Python / 知识点
Python 开发速查手册
手册条目
通过简洁表达式完成序列转换、过滤和组合。
使用列表推导式
列表推导式适合把“遍历、可选过滤、生成新值”合并为一个表达式,最终得到一个新列表。逻辑超过两层、包含副作用或需要逐步调试时,改用普通 for 循环更清楚。
基本语法
常用形式是 [表达式 for 变量 in 可迭代对象 if 条件]。执行顺序先遍历,再判断可选条件,最后计算表达式并收集结果;省略 if 时会转换全部元素。
高频用法
下面一次覆盖值转换、过滤后转换、条件表达式和二维列表展开:
numbers = [1, 2, 3, 4, 5]
matrix = [[1, 2], [3, 4]]
squares = [n * n for n in numbers]
even_times_ten = [n * 10 for n in numbers if n % 2 == 0]
labels = ["even" if n % 2 == 0 else "odd" for n in numbers]
flat = [item for row in matrix for item in row]
print(squares)
print(even_times_ten)
print(labels)
print(flat)预期输出:
[1, 4, 9, 16, 25]
[20, 40]
['odd', 'even', 'odd', 'even', 'odd']
[1, 2, 3, 4]读取时先看最右侧的数据来源。以展开表达式为例,顺序等价于先执行 for row in matrix,再执行 for item in row,最后把 item 放入结果列表。
风险与边界
列表推导式会立即创建完整列表。处理大文件、无限序列或只消费一次的数据时,可能占用过多内存,应改用生成器表达式 (表达式 for 变量 in 数据)。
不要在表达式中执行 print()、写文件或修改外部对象等副作用;这会让求值顺序难以检查。嵌套超过两层或条件较多时,普通循环通常更容易维护和设置断点。
排障清单
- 结果为空:先单独打印或测试
if条件,确认没有把全部元素过滤掉。 - 顺序不符:嵌套推导式中的多个
for必须与等价普通循环保持相同的从外到内顺序。 - 出现
NameError:推导式变量只在表达式内部有效,不能依赖它在推导式结束后继续存在。 - 只需迭代一次:优先使用生成器表达式,消费前不要误以为它已经生成列表。
在键可能不存在时读取默认值并避免 KeyError。
安全读取字典值
键可能缺失时使用 dict.get(),可以返回默认值而不触发 KeyError。它不会修改原字典,但默认值只在键不存在时生效;键存在且值为 None、0 或 False 时会原样返回。
基本语法
mapping.get(key) 在键缺失时返回 None;mapping.get(key, default) 在键缺失时返回指定默认值。需要区分“键不存在”和“键存在但值为 None”时,应先用 key in mapping 判断。
高频用法
下面演示缺失键、显式空值、保留合法假值,以及读取可能为空的嵌套对象:
config = {
"host": "127.0.0.1",
"port": 0,
"debug": False,
"owner": None,
}
payload = {"user": None}
host = config.get("host", "localhost")
timeout = config.get("timeout", 30)
owner = config.get("owner", "system")
wrong_port = config.get("port") or 8000
safe_port = config.get("port", 8000)
user_name = (payload.get("user") or {}).get("name", "anonymous")
print(host)
print(timeout)
print(owner)
print(wrong_port)
print(safe_port)
print(user_name)预期输出:
127.0.0.1
30
None
8000
0
anonymousowner 说明默认值不会替换已存在的 None;wrong_port 说明用 or 兜底会误伤合法的 0。只需处理键缺失时,直接给 get() 传默认值。
方法选择
读取但不修改字典时用 get();必须区分缺失与空值时用成员判断;需要在缺失时写入默认值时才用 setdefault()。大量同类键需要自动初始化时,可考虑 collections.defaultdict,但要注意读取缺失键会创建条目。
风险与边界
data.get("key", expensive()) 会先计算 expensive(),即使键已经存在。默认值创建成本高或带副作用时,先判断键是否存在,再按需计算。
链式写法 (data.get("user") or {}).get(...) 只适合中间值为字典或空值的场景;若中间值可能是字符串、列表等非字典对象,仍会触发 AttributeError,应先校验类型。
排障清单
- 仍出现
KeyError:检查后续代码是否又使用了mapping[key],异常不一定来自get()。 - 默认值没有生效:确认键是否存在但值为
None;需要替换空值时显式判断。 0、False或空字符串被替换:不要用get(...) or 默认值,除非所有假值都应视为缺失。- 嵌套读取报
AttributeError:检查中间节点类型,不要假定它一定是字典。
使用集合完成去重、交集、并集和差集计算。
集合去重与运算
需要从一批值中删除重复项、查找共同元素或计算两组数据的增减时,使用 set 最直接。集合只保留唯一且可哈希的元素,并提供 &、|、-、^ 等运算符;需要稳定输出或保留原顺序时,要额外排序或改用有序去重方案。
基本语法
set(iterable) 将可迭代对象转成集合。a & b 求交集,a | b 求并集,a - b 求只在左侧出现的元素,a ^ b 求只在一侧出现的元素。集合运算返回新集合,不会修改原集合;需要原地更新时才使用 intersection_update()、update() 等方法。
高频用法
下面示例同时演示无序去重、保序去重和四种常见集合运算。为避免集合遍历顺序影响结果,展示时统一使用 sorted()。
def main() -> None:
items = ["api", "db", "api", "cache", "db"]
left = {"api", "db", "cache"}
right = {"db", "mq", "cache"}
# set 适合只关心唯一值;dict.fromkeys 适合还要保留首次出现顺序
unique_unordered = sorted(set(items))
unique_ordered = list(dict.fromkeys(items))
print("无序去重:", unique_unordered)
print("保序去重:", unique_ordered)
print("交集:", sorted(left & right))
print("并集:", sorted(left | right))
print("左侧差集:", sorted(left - right))
print("对称差集:", sorted(left ^ right))
if __name__ == "__main__":
main()预期输出:
无序去重: ['api', 'cache', 'db']
保序去重: ['api', 'db', 'cache']
交集: ['cache', 'db']
并集: ['api', 'cache', 'db', 'mq']
左侧差集: ['api']
对称差集: ['api', 'mq']读取结果时,交集表示两边都存在;并集表示至少一边存在;left - right 只保留左侧独有值,方向不能写反;对称差集则用于找两边不一致的值。
选择合适的去重方式
只做成员判断或后续集合运算时,直接使用 set(items)。既要去重又要保持首次出现顺序时,使用 list(dict.fromkeys(items))。如果还要统计每个值出现次数,集合会丢失计数,应改用 collections.Counter。按对象某个字段去重时,不要直接把字典放进集合,可维护一个 seen 集合记录字段值。
风险与边界
集合元素必须可哈希。列表、字典和普通集合放入 set 会触发 TypeError: unhashable type;安全替代是将列表转成元组、将集合转成 frozenset,或只提取稳定主键去重。
不要依赖集合的遍历顺序。触发条件是直接把集合用于页面展示、序列化结果或测试断言;不同运行环境或数据变化可能造成顺序不稳定。安全替代是输出前使用 sorted(),或从一开始采用保序去重。
集合去重会永久丢失重复次数。若重复次数参与告警、计费或容量判断,结果可能被低估;应先用 Counter 保存计数,再按需要提取唯一键。
排障清单
- 出现
unhashable type:检查元素是否包含列表、字典或可变集合。 - 结果顺序偶尔变化:不要直接比较集合的字符串形式,先排序后再输出或断言。
- 差集结果与预期相反:确认业务含义是
left - right还是right - left。 - 去重后数量异常减少:确认业务是否需要保留重复次数或按复合字段去重。
速查:唯一值用 set,保序唯一值用 dict.fromkeys,共同项用 &,全集用 |,单侧增减用 -。
按字段、多个条件或自定义规则排序可迭代对象。
排序与自定义键
需要按对象字段、多个升降序条件或业务优先级重新排列数据时,使用 sorted() 或 list.sort()。核心是让 key 为每个元素生成一个可比较的排序键;排序键越小,元素越靠前。
基本语法
sorted(iterable, key=None, reverse=False) 返回新的列表,不修改原对象。list.sort(key=None, reverse=False) 原地修改列表并返回 None。两者都使用稳定排序:当排序键相同时,元素保留原有相对顺序。
单字段排序可返回一个值,多条件排序可返回元组。元组会从左到右逐项比较,因此应把优先级最高的条件放在最前面。
主示例
下面按分数、多个条件和业务状态分别排序。数字降序可在键中取负值,这样不必让 reverse=True 同时反转整个元组。
def main() -> None:
records = [
{"name": "alice", "score": 92, "age": 30, "status": "normal"},
{"name": "bob", "score": 92, "age": 25, "status": "urgent"},
{"name": "carol", "score": 88, "age": 27, "status": "normal"},
]
priority = {"urgent": 0, "normal": 1}
by_score = sorted(records, key=lambda row: row["score"], reverse=True)
# 分数降序、年龄升序、姓名升序;负数只反转分数这一项
by_multiple = sorted(
records,
key=lambda row: (-row["score"], row["age"], row["name"]),
)
# 未知状态排到最后,避免新增状态时直接抛 KeyError
by_priority = sorted(
records,
key=lambda row: (
priority.get(row["status"], 99),
-row["score"],
row["name"],
),
)
print("按分数:", [row["name"] for row in by_score])
print("多条件:", [row["name"] for row in by_multiple])
print("按优先级:", [row["name"] for row in by_priority])
if __name__ == "__main__":
main()预期输出:
按分数: ['alice', 'bob', 'carol']
多条件: ['bob', 'alice', 'carol']
按优先级: ['bob', 'alice', 'carol']第一行中 alice 与 bob 分数相同,稳定排序保留了输入顺序。第二行先比较分数,再比较年龄。第三行先按状态映射排序,状态相同时才继续比较分数和姓名。
常用排序规则
按字典字段排序时,键通常写为 lambda row: row["field"]。按多个条件排序时返回元组,例如 (-score, age, name) 表示分数降序、年龄升序、姓名升序。按固定业务顺序排序时,先建立映射表,如 {"urgent": 0, "normal": 1},并用 dict.get(value, default) 为未知值提供兜底位置。
字符串默认按 Unicode 码点比较,不等同于自然语言、拼音或“数字感知”排序。例如 "item10" 可能排在 "item2" 前面;需要自然排序时,应先把字符串拆成文本段和数字段,再作为复合键比较。
风险与边界
reverse=True 会反转整个排序结果。触发条件是复合键中既有升序又有降序字段;直接开启它会把所有字段方向一起反转。安全替代是对数值降序字段取负值,或利用稳定排序从次要条件到主要条件分多次排序。
排序键必须彼此可比较。字段同时包含 None、数字和字符串时,Python 3 可能抛出 TypeError;安全替代是先归一化,例如让键返回 (value is None, normalized_value),把空值稳定放到末尾。
list.sort() 会修改原列表且返回 None。若写成 result = records.sort(...),result 将是 None;需要保留原列表时使用 sorted(records, ...),需要节省额外列表内存时再选择原地排序。
自定义优先级映射若直接使用 priority[value],遇到新状态会触发 KeyError。生产代码应使用 priority.get(value, fallback),并同步记录未知值,避免静默掩盖数据质量问题。
排障清单
- 排序结果方向全反:检查是否误用
reverse=True处理混合升降序。 - 相同主键顺序异常:确认输入顺序是否已被上游修改,并利用稳定排序补充次级键。
- 出现不可比较类型错误:统一空值、数字和字符串的类型后再生成排序键。
result变成None:检查是否把list.sort()的返回值赋给变量。- 新状态排序失败:为优先级映射增加兜底值,并监控未知状态。
速查:保留原数据用 sorted(),原地修改用 list.sort();多条件用元组键,混合方向优先在键中单独转换字段。
使用 enumerate 和 zip 同时处理索引或多个序列。
遍历索引与多序列
需要在循环中同时取得元素位置时使用 enumerate();需要按位置并行读取多个序列时使用 zip()。两者可以组合,避免手动维护计数器或反复通过下标访问列表。
基本语法
enumerate(iterable, start=0) 依次产生 (索引, 元素);start 只改变索引的起始值,不会跳过元素。zip(a, b, ...) 依次产生由各序列同位置元素组成的元组,默认在最短序列耗尽时停止。
names = ['Alice', 'Bob', 'Carol']
scores = [92, 85, 88]
# enumerate 负责生成展示序号,zip 负责配对同位置数据
for index, (name, score) in enumerate(zip(names, scores), start=1):
print(f'{index}. {name}: {score}')预期输出:
1. Alice: 92
2. Bob: 85
3. Carol: 88每行开头是从 1 开始的索引,后面是 names 与 scores 中同一位置的两个元素。
高频用法
- 使用
for index, value in enumerate(values):替代range(len(values)),循环体可直接取得元素。 - 使用
for key, value in zip(keys, values):并行处理字段名和值、旧值和新值等成对数据。 - 使用
left, right = zip(*pairs)将二元组序列拆成两组数据;结果是元组。 - Python 3.10 及以上可使用
zip(a, b, strict=True),要求所有序列长度完全一致。
风险与边界
普通 zip() 遇到长度不一致时会静默丢弃较长序列末尾的数据,可能造成批量写入缺项或字段错配。数据必须一一对应时,优先使用 strict=True;旧版本可先比较各序列的 len()。
zip() 返回一次性迭代器。第一次循环或调用 list() 后再次遍历将没有结果;需要重复使用时,应先保存为列表。遍历期间也不要增删原列表,否则索引和配对关系可能失去业务含义。
排障清单
- 循环次数少于预期:检查各输入序列长度,普通
zip()以最短序列为准。 - 使用
strict=True出现ValueError:输入长度不同,应修正上游数据,而不是直接关闭严格检查。 - 第二次遍历没有输出:迭代器已被消费,重新创建
zip()或先执行rows = list(zip(...))。 - 只需要索引而不需要元素:通常说明循环设计可以简化,优先直接遍历元素。
兼容性
enumerate() 和普通 zip() 可用于常见 Python 3 环境。zip(..., strict=True) 从 Python 3.10 开始支持;兼容更早版本时需手动校验长度。
截取、复制、反转或按步长读取序列内容。
使用序列切片
切片用于从列表、元组、字符串等序列中截取区间、创建浅拷贝、反转顺序或按固定步长取值。切片通常不会因边界超出序列长度而报错,适合编写简洁的区间读取逻辑。
基本语法
基本形式为 sequence[start:stop:step]。范围采用左闭右开规则:包含 start,不包含 stop。三个位置都可以省略;step 为负数时从右向左读取。
numbers = list(range(10))
print(numbers[2:6]) # 索引 2 到 5
print(numbers[:3]) # 前 3 个元素
print(numbers[::2]) # 每隔一个元素读取
print(numbers[::-1]) # 反转序列
print(numbers[-3:]) # 最后 3 个元素预期输出:
[2, 3, 4, 5]
[0, 1, 2]
[0, 2, 4, 6, 8]
[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
[7, 8, 9]读取切片时先确定方向,再按 start 到 stop 之间的索引移动,每次移动 step 指定的距离。
高频用法
items[start:stop]:截取连续区间,常用于分页、批处理和窗口数据。items[:]:创建外层容器的浅拷贝,修改新列表的增删操作不会改变原列表。items[::-1]:返回反向排列的新序列,不修改原对象。items[::n]:每隔n个位置取一个元素;例如items[::10]可用于抽样查看长列表。
风险与边界
step 不能为 0,否则触发 ValueError: slice step cannot be zero。需要原顺序时使用正步长,需要反向读取时使用负步长,并同步调整起止方向。
对列表执行切片会创建新列表。处理超大序列时,大范围复制或反转可能显著增加内存占用,可改用迭代器、索引循环或 itertools.islice()。items[:] 只是浅拷贝,内部嵌套的列表、字典等对象仍与原容器共享。
只有可变序列支持切片赋值,例如 items[1:3] = replacements。替换元素数量可以与原区间不同,从而改变列表长度;生产代码中应避免在依赖固定索引的位置随意使用。字符串和元组不可修改,只能取得新的切片结果。
排障清单
- 结果为空:检查正步长时是否满足
start < stop,负步长时是否满足start > stop。 - 边界写得很大却未报错:这是正常行为,切片会自动限制在有效范围内。
- 修改副本中的嵌套对象后原数据也变化:当前是浅拷贝,需要使用
copy.deepcopy()或重新构造内部对象。 - 对生成器切片出现
TypeError:生成器不支持下标操作,可使用itertools.islice()。
兼容性
列表、元组、字符串、字节串和 range 等内置序列均支持切片,但返回类型及是否复制数据由具体对象决定。内置列表切片返回新列表,不能据此推断第三方数组类型也一定复制数据。
将序列或字典拆分到变量、函数参数和返回结果。
解包参数与返回值
在接收固定结构的数据、把集合传给函数,或一次接收多个返回值时使用解包。核心规则是:赋值左侧按位置接收元素,调用处用 * 展开可迭代对象、用 ** 展开映射,函数返回多个值本质上是返回一个元组。
基本语法
序列解包要求左右元素数量匹配;带星号的目标会收集剩余元素,且同一次赋值最多只能出现一个。字典直接迭代得到键,若要同时取得键和值,应解包 dict.items()。
first, second = (10, 20)
head, *middle, tail = [1, 2, 3, 4]
user = {'name': 'alice', 'age': 18}
name, age = user.values()
print(first, second)
print(head, middle, tail)
print(name, age)预期输出:
10 20
1 [2, 3] 4
alice 18读取方法:middle 始终是列表;user.values() 按字典当前迭代顺序返回值,生产代码更适合按键读取,避免字段顺序变化造成错配。
高频用法
下面的完整示例同时覆盖函数实参展开和返回值解包。*sizes 按位置传参,**options 按参数名传参,divmod() 返回的二元组可直接拆成两个变量。
def rectangle(width, height, unit='cm'):
area = width * height
perimeter = 2 * (width + height)
return area, perimeter, unit
sizes = (3, 4)
options = {'unit': 'm'}
area, perimeter, unit = rectangle(*sizes, **options)
quotient, remainder = divmod(11, 3)
print(f'area={area}{unit}²')
print(f'perimeter={perimeter}{unit}')
print(f'quotient={quotient}, remainder={remainder}')预期输出:
area=12m²
perimeter=14m
quotient=3, remainder=2函数调用中的 * 可展开列表、元组、生成器等可迭代对象;** 需要映射且键必须是字符串。返回值数量固定时直接解包最清晰;只关心部分结果时可用 _ 占位,但 _ 只是普通变量,不会自动忽略数据。
风险与边界
固定解包数量不匹配会触发 ValueError;安全替代是先校验长度,或用一个星号目标接收剩余项。对生成器解包会消耗其元素,后续再次读取可能为空;需要复用时先转成列表,或重新创建迭代器。
调用函数时,显式参数与 **mapping 提供同名参数会触发 TypeError。合并配置前应明确优先级,例如先构造新字典 {**defaults, **overrides},再只展开一次,避免重复传值。
排障清单
- 出现
not enough values to unpack:检查实际元素数是否少于左侧变量数。 - 出现
too many values to unpack:减少左侧变量,或加入一个*rest。 - 出现
got multiple values for argument:检查位置参数、关键字参数和**映射是否重复提供同一参数。 - 字典解包结果错位:不要依赖
values()的业务顺序,改为name = data['name']这类显式取值。
兼容性
赋值解包和调用解包适用于 Python 3;字典合并表达式 {**a, **b} 可用于 Python 3.5 及以上。生产接口返回字段数量可能变化时,优先返回具名对象、数据类或字典,避免调用方因元组长度变化整体报错。
设置位置参数、关键字参数、默认值和仅限参数。
定义函数参数
在设计稳定的函数调用接口时,需要明确哪些参数必须按位置传入、哪些允许关键字传入、哪些只能使用关键字,以及如何接收不定数量参数。合理的签名能让错误在调用入口直接暴露,而不是进入函数后才出现含糊异常。
基本语法
参数从左到右通常按以下顺序组织:仅位置参数、普通参数、可变位置参数、仅关键字参数、可变关键字参数。/ 左侧只能按位置传入,* 右侧只能按关键字传入。
def func(pos_only, /, normal, default=0, *args, required_kw, flag=True, **kwargs):
return pos_only, normal, default, args, required_kw, flag, kwargspos_only 是仅位置参数;normal 可按位置或关键字传入;default 有默认值;args 收集额外位置参数;required_kw 没有默认值,调用时必须写参数名;kwargs 收集未被前面参数接收的关键字参数。
高频用法
下面的完整示例把调用约束、默认值、*args、仅关键字参数和 **kwargs 放在同一个签名中,并用 inspect.signature() 验证最终接口。
from inspect import signature
def request(method, /, path, timeout=3, *tags, retries=2, verify=True, **headers):
return {
'method': method,
'path': path,
'timeout': timeout,
'tags': tags,
'retries': retries,
'verify': verify,
'headers': headers,
}
result = request(
'GET',
'/health',
5,
'internal',
retries=1,
Accept='application/json',
)
print(signature(request))
print(result)预期输出:
(method, /, path, timeout=3, *tags, retries=2, verify=True, **headers)
{'method': 'GET', 'path': '/health', 'timeout': 5, 'tags': ('internal',), 'retries': 1, 'verify': True, 'headers': {'Accept': 'application/json'}}读取方法:tags 始终是元组,headers 始终是字典。把控制行为的参数放到 * 之后,可强制调用方写成 retries=1,降低布尔值或整数因位置错位而被误传的风险。
默认值的安全写法
默认值在函数定义时只计算一次。列表、字典、集合等可变对象若直接作为默认值,会被多次调用共享;安全做法是使用 None,并在函数内部创建新对象。
def append_item(item, items=None):
if items is None:
items = []
items.append(item)
return items
print(append_item('a'))
print(append_item('b'))预期输出:
['a']
['b']每次调用都创建独立列表,因此第二次结果不会意外包含第一次加入的 'a'。不可变默认值,如数字、字符串、元组,通常可以直接使用。
风险与边界
调用时同时按位置和关键字给同一参数赋值,会触发 TypeError;安全替代是为每个参数选择一种传入方式。默认参数之前不能出现同一参数区间内的必填普通参数,否则函数定义阶段会触发 SyntaxError;必填的仅关键字参数可放在 * 之后且不设置默认值。
修改已有公共函数的 / 或 * 位置属于接口兼容性变更,旧调用可能立即失败。发布前应搜索调用点并运行测试;需要平滑迁移时,先保留旧签名并在函数内发出弃用警告,再在后续版本收紧约束。
排障清单
missing required positional argument:检查必填位置参数是否遗漏,或是否误写成仅位置参数的关键字调用。missing required keyword-only argument:检查*之后无默认值的参数是否显式传入。unexpected keyword argument:参数名拼写错误,或函数没有**kwargs接收额外字段。got multiple values for argument:同一参数被位置实参和关键字实参重复赋值。- 签名不确定:使用
inspect.signature(函数对象)查看真实参数顺序和约束。
兼容性
用户自定义函数中的 / 语法从 Python 3.8 开始支持;*、*args 和 **kwargs 在更早的 Python 3 版本已可用。若代码需要兼容 Python 3.7,不要在自定义函数签名中使用 /,并通过文档和测试约束调用方式。
接收和转发数量不固定的位置参数与关键字参数。
使用 *args 与 **kwargs
当函数需要接收数量不固定的参数,或包装器需要原样转发调用参数时,使用 *args 收集额外位置参数、使用 **kwargs 收集额外关键字参数。二者也可在调用端解包现有序列和字典。
基本语法
定义函数时,args 是元组,按调用顺序保存额外位置参数;kwargs 是字典,保存未被显式形参接收的关键字参数。名称可以更换,但保留 args、kwargs 便于阅读。
def collect(required, *args, enabled=True, **kwargs):
print(required)
print(args)
print(enabled)
print(kwargs)*args 之后的普通形参属于仅限关键字参数,调用时必须写出参数名。调用端的 *items 会展开序列,**options 会展开映射。
高频用法
下面示例同时演示收集、关键字专用参数和包装函数转发。包装层不解析业务参数,只记录后继续传给目标函数。
def request(method, base_url, *segments, timeout=3, **headers):
# 路径片段统一去除首尾斜杠,避免拼接出重复分隔符
path = '/'.join(str(item).strip('/') for item in segments)
target = f'{base_url.rstrip("/")}/{path}' if path else base_url
print(f'{method} {target} timeout={timeout}')
print(f'headers={headers}')
return 200
def traced_request(*args, **kwargs):
# 转发时必须同时保留位置参数与关键字参数
print(f'args={args}')
print(f'kwargs={kwargs}')
return request(*args, **kwargs)
def main():
status = traced_request(
'GET',
'https://api.example.com',
'users',
42,
timeout=5,
Authorization='Bearer demo',
)
print(f'status={status}')
if __name__ == '__main__':
main()预期输出
args=('GET', 'https://api.example.com', 'users', 42)
kwargs={'timeout': 5, 'Authorization': 'Bearer demo'}
GET https://api.example.com/users/42 timeout=5
headers={'Authorization': 'Bearer demo'}
status=200读取时先确认 args 的顺序,再检查 kwargs 是否包含目标函数需要的选项;最终两行说明转发后的路径、超时和请求头均已生效。
常见场景包括:为日志、重试、缓存等包装器透明转发参数;把列表作为多个位置参数传入 func(*items);把配置字典作为关键字参数传入 func(**options);为插件接口保留少量可扩展选项。
风险与边界
当函数大量依赖 *args、**kwargs 时,调用签名会变得不直观,拼写错误和参数类型问题通常推迟到运行时才暴露。公共 API 应优先声明明确形参,只把真正开放扩展的部分放入可变参数。
若函数接收 **kwargs 后忽略未知键,调用方的拼写错误可能被静默吞掉。安全做法是校验允许的键集合,发现未知键立即抛出 TypeError,或将扩展配置封装为明确的数据对象。
调用 func(value, name=value) 可能让同一形参同时收到位置值和关键字值,触发 TypeError: got multiple values for argument。转发前不要擅自重复补参数;需要覆盖配置时,先合并字典,再只展开一次。
排障清单
出现 unexpected keyword argument 时,检查目标函数是否声明了该关键字,或中间包装器是否把 **kwargs 完整转发。出现 missing required positional argument 时,检查 *args 的顺序和数量。
出现 multiple values for argument 时,搜索同一参数是否既通过位置传入,又存在于 kwargs。调试包装器时可临时打印 args 和 kwargs,确认问题发生在收集阶段还是目标函数调用阶段。
兼容性
*args、**kwargs 适用于所有主流 Python 3 版本。关键字参数保持调用顺序在 Python 3.7 起成为语言保证;依赖输出顺序的日志或测试应以 Python 3.7 及以上为基线。
为变量、参数和返回值补充静态类型信息。
添加类型注解
类型注解用于说明变量、参数和返回值的预期类型,便于 IDE 补全、静态检查和代码审查。注解默认不会转换数据,也不会阻止错误类型在运行时传入。
基本语法
变量使用 name: Type,函数参数使用 parameter: Type,返回值写在 -> Type 中。没有返回值的函数标注为 -> None;可能返回空值时使用 Optional[T]。
from typing import List, Optional, get_type_hints
def average(values: List[float], precision: int = 2) -> Optional[float]:
# 空集合没有可计算的平均值,用 None 明确表达缺少结果
if not values:
return None
return round(sum(values) / len(values), precision)
def main() -> None:
scores: List[float] = [89.5, 92.0, 84.2]
result: Optional[float] = average(scores)
print(f'result={result}')
# 运行时可读取注解,但读取不等于执行类型校验
hints = get_type_hints(average)
print(hints['values'])
print(hints['precision'])
print(hints['return'])
if __name__ == '__main__':
main()预期输出
result=88.57
typing.List[float]
<class 'int'>
typing.Optional[float]第一行是函数的实际计算结果,后三行来自函数注解。它们可供框架或检查工具读取,但 Python 调用函数时不会自动验证这些类型。
高频用法
容器应同时标注元素类型,例如 List[str]、Dict[str, int],避免只写宽泛的 list 或 dict。值可能不存在时使用 Optional[str],并在使用前处理 None 分支。
多个位置重复出现的复杂类型可定义别名,例如 UserId = int 或 Headers = Dict[str, str]。回调函数可使用 Callable[[str], bool] 描述参数和返回值,结构固定的字典可考虑 TypedDict,而不是长期依赖无约束的 Dict[str, object]。
公共函数优先补齐参数和返回值注解;局部变量只在类型不明显、初始值为空容器或后续会改变表示形式时补充,避免给每个简单赋值增加噪声。
风险与边界
类型注解不是运行时验证。触发条件是调用方传入错误类型但代码路径尚未使用相关操作;后果可能是在更深位置才出现 TypeError,甚至产生错误结果。需要外部输入校验时,应显式检查,或使用专门的数据校验库。
大量使用 Any 会让静态检查器停止追踪该值,错误可能沿调用链扩散。安全替代是使用具体联合类型、协议或结构化数据类型;只有边界无法建模时才局部使用 Any。
修改注解而不修改实现会制造错误契约。例如声明返回 str,实际返回 None,IDE 和调用方会基于错误假设继续编写代码。提交前应让静态检查器覆盖关键模块,并为边界分支保留测试。
排障清单
静态检查提示类型不兼容时,先确认是数据本身错误,还是注解写得过窄;不要直接用 Any 或强制转换压掉告警。对于可能为 None 的值,应先判空,再在非空分支使用。
出现注解名称未定义时,检查类型是否已导入。循环引用或前向引用可使用字符串注解,或在模块顶部启用 from __future__ import annotations;但调用 get_type_hints() 时,相关名称最终仍必须可解析。
兼容性
示例中的 typing.List、typing.Optional 适合 Python 3.8 及以上。Python 3.9 起可写 list[str],Python 3.10 起可写 str | None;若项目需要兼容旧版本,应统一采用 typing 中的写法并在持续集成中固定最低 Python 版本。
快速创建包含字段、默认值和比较能力的数据对象。
定义数据类
需要快速声明“以字段为核心”的数据对象时使用 @dataclass。它会按字段自动生成初始化、显示和比较方法,适合配置项、DTO、任务记录等轻量对象;需要复杂继承、持久化或大量自定义行为时,应改用普通类或专用模型库。
基本语法
@dataclass 默认生成 __init__()、__repr__() 和 __eq__()。字段按声明顺序进入构造函数;无默认值字段必须放在有默认值字段之前。
from dataclasses import dataclass, field
@dataclass(order=True, slots=True)
class Task:
priority: int
title: str
# 每个实例都创建独立列表,避免共享可变默认值
tags: list[str] = field(default_factory=list, compare=False)
done: bool = field(default=False, compare=False)
def __post_init__(self) -> None:
if self.priority < 0:
raise ValueError("priority must be >= 0")
def main() -> None:
deploy = Task(2, "deploy", ["prod"])
backup = Task(1, "backup")
print(deploy)
print(backup < deploy)
print(deploy == Task(2, "deploy"))
if __name__ == "__main__":
main()预期输出:
Task(priority=2, title='deploy', tags=['prod'], done=False)
True
True第一行来自自动生成的 __repr__();第二行按参与比较的字段依次排序;第三行说明 tags 和 done 因 compare=False 不参与相等性判断。
常用参数
| 写法 | 作用 | 适用场景 |
|---|---|---|
@dataclass(frozen=True) |
禁止重新给字段赋值 | 值对象、字典键候选 |
@dataclass(order=True) |
生成 <、<=、>、>= |
字段顺序可代表排序规则 |
@dataclass(slots=True) |
使用槽位,减少实例属性开销 | 实例量大且字段固定 |
@dataclass(kw_only=True) |
构造参数只能按名称传入 | 字段较多,避免位置参数错位 |
field(default_factory=list) |
为每个实例创建新对象 | 列表、字典、集合等可变默认值 |
需要把实例转成普通字典时使用 dataclasses.asdict();基于旧实例创建修改副本时使用 dataclasses.replace()。
风险与边界
不要写 tags: list[str] = []。触发条件是把列表、字典或集合直接作为默认值;后果是定义阶段报错,或在其他类写法中出现实例共享状态。安全替代是 field(default_factory=list)。
frozen=True 只阻止字段重新绑定,不会递归冻结字段内部对象。若字段仍是列表,列表内容依然可变;需要真正不可变时改用元组、frozenset 或不可变映射。
order=True 会按字段声明顺序比较。字段顺序不等于业务排序规则时,结果可能合法但错误;应使用专门的排序键字段,并对非排序字段设置 compare=False。
排障清单
- 出现
non-default argument ... follows default argument:把无默认值字段移到有默认值字段之前,或使用kw_only=True。 - 实例无法作为字典键:通常是类可变且未生成哈希;优先使用
frozen=True,不要为可变对象强行设置unsafe_hash=True。 __post_init__()未执行:确认对象通过数据类生成的__init__()创建,并检查自定义__init__()是否覆盖了自动生成逻辑。- 比较结果异常:检查字段顺序和每个
field(compare=...)设置。
兼容性
dataclasses 自 Python 3.7 起进入标准库;slots=True 和 kw_only=True 需要 Python 3.10+;list[str] 注解需要 Python 3.9+。较旧版本可改用 typing.List[str],或安装官方回移植包。
正确使用绝对导入、相对导入和模块别名。
导入模块与包
需要在多文件项目中复用函数、类或常量时使用导入。项目内跨包引用优先采用绝对导入;同一包内部的紧密协作可采用相对导入;别名用于缩短稳定且公认的长名称,不能用来掩盖名称冲突。
基本语法
片段示例(需替换包名和对象名,并放入实际包结构中):
import package.module
import package.module as alias
from package.module import name
from .module import name
from ..package import name绝对导入从解释器的模块搜索路径开始定位,例如 from app.services import greeting。相对导入中的一个点表示当前包,两个点表示上一级包;它依赖正确的包上下文,不能把包含相对导入的文件随意当作独立脚本运行。
可复制示例
下面的命令创建一个最小包:services.py 使用相对导入,main.py 使用绝对导入和模块别名,最后通过 -m 按模块方式启动。
tmp_dir="$(mktemp -d)"
cd "$tmp_dir"
mkdir -p app
cat > app/__init__.py <<'PY'
PY
cat > app/models.py <<'PY'
def format_name(name: str) -> str:
return name.strip().title()
PY
cat > app/services.py <<'PY'
from .models import format_name
def greeting(name: str) -> str:
return f"Hello, {format_name(name)}!"
PY
cat > app/main.py <<'PY'
import json as jsonlib
from app.services import greeting
print(greeting("ada"))
print(jsonlib.dumps({"module": __name__}))
PY
python -m app.main预期输出:
Hello, Ada!
{"module": "__main__"}python -m app.main 必须在 app 的父目录执行。解释器先把当前目录加入模块搜索路径,再建立 app 的包上下文,因此绝对导入和 .models 相对导入都能正常解析。入口模块运行时的 __name__ 为 __main__,所以第二行不是 app.main。
选择规则
绝对导入适合公开、稳定的项目路径,代码搜索和重构影响更清晰。相对导入适合同一包内部的实现细节,路径较短,但层级过深时可读性会迅速下降。别名应保持团队一致,例如 import numpy as np;不要为普通短模块创建个人化缩写。
只导入少量明确成员时可使用 from module import name。需要保留来源上下文或避免同名覆盖时,优先 import module 后通过 module.name 访问。
风险与边界
直接运行 python app/main.py 时,触发条件是入口文件位于包内且使用绝对或相对包导入;后果可能是 ModuleNotFoundError 或 attempted relative import with no known parent package。安全替代是在项目根目录运行 python -m app.main。
不要把本地文件命名为 json.py、typing.py、requests.py 等已使用模块名。触发后会优先导入本地文件,导致缺少属性、部分初始化或循环导入。安全替代是改名并删除同目录下旧的 __pycache__。
循环导入常见于两个模块在顶层互相引用。后果是模块只初始化一半,出现 cannot import name ... from partially initialized module。优先把共享类型或常量下沉到第三个模块;仅为打破环而把导入塞进函数,应作为临时方案并记录原因。
避免 from module import * 和手工修改 sys.path。前者会污染命名空间并隐藏依赖来源,后者让运行结果依赖启动目录;应使用明确导入,并通过可安装包、虚拟环境或 python -m 建立稳定路径。
排障清单
ModuleNotFoundError:确认当前解释器、工作目录、包名拼写和依赖安装位置;用python -c "import sys; print(sys.executable); print(sys.path)"查看实际搜索环境。- 相对导入报“no known parent package”:不要直接执行包内文件,改从项目根目录使用
python -m 包名。模块名。 - 导入到错误文件:打印
module.__file__,检查是否被同名本地文件或旧安装版本遮蔽。 - 修改代码后行为未更新:结束常驻进程并清理相关缓存;普通进程不会自动重新加载已导入模块。
兼容性
Python 3 默认使用绝对导入语义。目录含 __init__.py 时行为最直观;Python 3.3+ 也支持命名空间包,但跨环境发布时仍应通过 pyproject.toml 等标准打包配置明确包边界。
捕获预期异常并使用 else、finally 完成资源收尾。
处理异常
在输入解析、网络调用或文件操作可能失败时,用 try 捕获可预期异常;无异常时把后续逻辑放入 else,无论成功失败都必须执行的清理放入 finally。目标是只处理已知故障,同时保证资源状态可控。
基本语法
except 应指定尽可能具体的异常类型,并把 try 范围缩到真正可能失败的语句。else 只在 try 未抛出异常时执行,适合放成功路径;finally 总会执行,适合释放锁、关闭临时资源或恢复状态。
高频用法
下面同时演示正常分支、异常分支和资源收尾。示例使用内存流,复制后可直接运行。
from io import StringIO
def read_port(stream: StringIO) -> int | None:
try:
# try 只覆盖解析与校验,避免误捕获后续编程错误。
raw = stream.readline().strip()
port = int(raw)
if not 1 <= port <= 65535:
raise ValueError("端口必须在 1..65535")
except ValueError as exc:
print(f"配置错误: {exc}")
return None
else:
# 仅在解析和校验都成功时进入成功路径。
print(f"端口有效: {port}")
return port
finally:
# 即使前面已经 return,finally 仍会执行。
stream.close()
print(f"资源已关闭: {stream.closed}")
def main() -> None:
read_port(StringIO("8080\n"))
read_port(StringIO("abc\n"))
if __name__ == "__main__":
main()预期输出
端口有效: 8080
资源已关闭: True
配置错误: invalid literal for int() with base 10: 'abc'
资源已关闭: True前两行表示成功路径执行了 else 后仍进入 finally;后两行表示 ValueError 被捕获,随后同样完成资源关闭。
风险与边界
- 使用裸
except:时,会连KeyboardInterrupt、SystemExit等退出信号一起吞掉,程序可能无法正常停止。安全替代是捕获具体异常,确需兜底时使用except Exception并记录后重新抛出。 - 在
finally中执行return、break或抛出新异常时,原异常或原返回值可能被覆盖。安全替代是让finally只做幂等清理,并避免改变控制流。 - 清理代码自身失败时,可能掩盖最初故障。优先使用
with管理文件、锁和连接;必须手动清理时,单独记录清理异常并保留原始异常上下文。
排障清单
- 确认实际异常类型是否与
except声明一致,必要时打印type(exc).__name__。 - 检查
try是否包得过宽,导致无关代码错误被当作预期故障处理。 - 确认异常处理后是继续、返回还是重新抛出,避免程序带着不完整状态继续运行。
- 检查
finally或资源关闭逻辑是否再次抛错并覆盖原始堆栈。
兼容性
示例中的 int | None 类型标注需要 Python 3.10+;旧版本可改为 Optional[int],异常处理语义不受影响。
为业务错误建立明确的异常类型和错误上下文。
定义自定义异常
当调用方需要区分库存不足、参数无效、权限拒绝等业务失败,并据此决定提示、重试或告警时,应定义明确的异常类型。异常对象除错误消息外,还应携带稳定错误码和排障所需的结构化上下文。
定义方式
自定义异常通常继承 Exception,也可在语义完全匹配时继承 ValueError 等内置异常。构造函数必须调用 super().__init__(message),并把 code、业务标识和关键数值保存为属性,调用方无需解析错误字符串。
高频用法
下面定义通用业务异常和库存不足子类,并由调用方按类型捕获。
class BusinessError(Exception):
code = "BUSINESS_ERROR"
def __init__(self, message: str, *, context: dict[str, object] | None = None) -> None:
super().__init__(message)
self.context = context or {}
class InsufficientStockError(BusinessError):
code = "INSUFFICIENT_STOCK"
def __init__(self, sku: str, requested: int, available: int) -> None:
# 结构化字段便于日志、告警和接口层直接读取。
super().__init__(
"库存不足",
context={"sku": sku, "requested": requested, "available": available},
)
def reserve_stock(sku: str, requested: int, available: int) -> int:
if requested > available:
# 在最接近业务规则的位置抛出具体异常。
raise InsufficientStockError(sku, requested, available)
return available - requested
def main() -> None:
for requested in (2, 8):
try:
remaining = reserve_stock("SKU-42", requested, available=5)
except InsufficientStockError as exc:
# 调用方按类型处理,不依赖消息文本匹配。
print(f"{exc.code}: {exc}; context={exc.context}")
else:
print(f"预留成功: remaining={remaining}")
if __name__ == "__main__":
main()预期输出
预留成功: remaining=3
INSUFFICIENT_STOCK: 库存不足; context={'sku': 'SKU-42', 'requested': 8, 'available': 5}第一行是正常返回值;第二行可直接读取 exc.code 和 exc.context,用于日志字段、接口错误映射或告警聚合。
错误上下文与转换
底层异常需要转换为业务异常时,使用 raise 自定义异常(...) from exc 保留异常链。这样外层看到稳定业务语义,排障时仍能从 __cause__ 和堆栈定位原始数据库、网络或解析错误。
风险与边界
- 统一抛出普通
Exception时,调用方只能匹配文本,消息调整后处理逻辑可能失效。安全替代是为可恢复或需单独展示的业务失败建立具体类型。 - 把令牌、密码、完整身份证号等放入
context时,日志和接口响应可能泄露敏感数据。安全替代是只保存必要标识,并在记录前脱敏。 - 在底层捕获自定义异常后直接忽略时,事务可能在不完整状态下继续。安全替代是明确补偿并返回,或使用
raise原样重新抛出。 - 随意修改对外使用的
code时,告警规则和客户端映射可能失效。应把错误码视为稳定契约,新增类型优先于复用旧码改变含义。
排障清单
- 确认异常类继承自
Exception,且构造函数调用了父类初始化。 - 确认抛出位置靠近业务规则,捕获位置位于能真正决定恢复策略的边界层。
- 检查上下文字段是否齐全、可序列化且不含敏感信息。
- 转换底层异常时确认使用了
from exc,避免原始原因丢失。
兼容性
示例使用 Python 3.10+ 的联合类型标注;旧版本可改用 typing.Optional 和 typing.Dict,异常类设计与捕获方式保持不变。
确保文件、锁和连接在异常发生时仍能正确释放。
使用上下文管理器
打开文件、获取锁或启动事务时,用 with 管理资源生命周期。代码块无论正常结束还是抛出异常,退出逻辑都会执行,可避免文件未关闭、锁未释放和连接长期占用。
基本语法
with manager as resource: 先进入上下文,再执行缩进代码,最后退出并清理。多个资源可写成 with a as x, b as y:,退出时按进入的相反顺序释放。块外虽然可能仍能访问 resource 变量,但资源通常已经失效。
自定义管理器通过 __enter__() 返回资源,通过 __exit__(exc_type, exc, traceback) 清理。__exit__() 返回真值会抑制异常;返回 False 或 None 时,异常继续向外传播。
高频用法
- 文件:
with Path(...).open(...) as file,退出后自动关闭文件描述符。 - 锁:
with lock,异常发生时仍释放锁;临界区应尽量短。 - 事务:数据库管理器通常提交或回滚,但是否关闭连接要看具体库。
- 动态资源:数量运行时才确定时,用
contextlib.ExitStack统一登记和逆序释放。
可运行示例
下面同时获取锁和文件,并主动抛出异常,随后验证两个资源都已释放。
from pathlib import Path
from threading import Lock
path = Path("context-demo.txt")
lock = Lock()
try:
with lock, path.open("w", encoding="utf-8") as file:
file.write("ready\n")
# 模拟业务失败,验证异常路径仍会清理资源
raise RuntimeError("simulated failure")
except RuntimeError as exc:
print(f"caught: {exc}")
print(f"file_closed: {file.closed}")
# 非阻塞获取成功,说明原来的锁已经释放
acquired = lock.acquire(blocking=False)
print(f"lock_released: {acquired}")
if acquired:
lock.release()
print(f"content: {path.read_text(encoding='utf-8').strip()}")
path.unlink()预期输出
caught: simulated failure
file_closed: True
lock_released: True
content: readyfile_closed 和 lock_released 都为 True,说明异常未阻止清理;末尾删除测试文件,示例可重复运行。
风险与边界
使用过宽的 contextlib.suppress(Exception),或让 __exit__() 返回真值,会隐藏真实失败并继续处理不完整数据。只抑制明确且可恢复的异常,并保留必要日志。
事务管理器不一定关闭连接。若误把“提交或回滚”当成“归还连接”,可能耗尽连接池。应确认驱动约定,必要时分别管理事务和连接。
多线程以不同顺序获取多把锁可能死锁。统一加锁顺序、缩短临界区;需要超时时,使用支持 timeout 的显式 acquire(),并在 finally 中释放。
排障清单
ValueError: I/O operation on closed file:把文件读写移回with代码块。- 锁未释放:搜索手工
acquire(),确认所有退出路径都有finally。 generator didn't stop:@contextmanager生成器必须恰好执行一次yield,清理放在finally中。- 异常无故消失:检查
__exit__()返回值和contextlib.suppress()的范围。
速查原则:只要存在“获取后必须释放”的配对动作,优先找上下文管理器接口,再考虑手写 try/finally。
以跨平台方式拼接、检查、遍历和转换文件路径。
使用 pathlib 操作路径
拼接、检查、创建、遍历或转换路径时,优先使用 pathlib.Path。它把路径当作对象处理,避免手工拼接分隔符,并让同一份代码更容易跨 Windows、macOS 和 Linux 运行。
基本语法
用 Path("目录") / "子目录" / "文件.txt" 拼接路径;Path.cwd() 获取当前工作目录,Path.home() 获取用户主目录。相对路径基于进程工作目录解析,部署时不要假设它一定等于脚本目录。
查询方法通常返回布尔值或新路径对象;mkdir()、write_text()、rename()、unlink() 等会真实修改磁盘内容。
常用操作
| 目的 | 推荐写法 | 说明 |
|---|---|---|
| 拼接 | base / "config" / "app.toml" |
不手工处理分隔符 |
| 判断 | exists()、is_file()、is_dir() |
区分不存在、文件和目录 |
| 建目录 | mkdir(parents=True, exist_ok=True) |
自动补齐父目录 |
| 读写文本 | read_text()、write_text() |
显式指定编码 |
| 遍历 | glob("*.py")、rglob("*.py") |
后者递归 |
| 转换 | resolve()、relative_to()、as_posix() |
绝对化、求相对路径、统一展示 |
可运行示例
示例创建测试目录,写入并重命名文件,再递归查找 Python 文件;最后删除测试数据。
from pathlib import Path
import shutil
root = Path("demo-workspace")
if root.exists():
shutil.rmtree(root)
# 通过 / 运算符拼接路径,不写平台相关分隔符
src = root / "src"
config = root / "config"
src.mkdir(parents=True)
config.mkdir()
main = src / "main.py"
main.write_text("print('ok')\n", encoding="utf-8")
(src / "utils.py").write_text("VALUE = 1\n", encoding="utf-8")
(config / "app.toml").write_text("debug = true\n", encoding="utf-8")
# rename() 会真实移动文件,而不是仅生成新路径对象
renamed = main.rename(src / "cli.py")
python_files = sorted(
path.relative_to(root).as_posix()
for path in root.rglob("*.py")
)
print(f"config_is_file: {(config / 'app.toml').is_file()}")
print("python_files:")
for item in python_files:
print(f"- {item}")
print(f"renamed_to: {renamed.relative_to(root).as_posix()}")
# 清理示例目录,避免重复运行残留旧文件
shutil.rmtree(root)预期输出
config_is_file: True
python_files:
- src/cli.py
- src/utils.py
renamed_to: src/cli.pyrelative_to(root) 去掉测试根目录,as_posix() 仅用于稳定展示;内部仍应保留 Path 对象。
风险与边界
当右侧是绝对路径时,base / absolute_path 会丢弃左侧 base。用户输入还可能包含 .. 并越出预期目录。应先对基目录和候选路径调用 resolve(),再用 candidate.is_relative_to(base) 验证范围;该方法需要 Python 3.9 及以上。
先调用 exists() 再写入存在竞态条件,文件可能在两步之间被其他进程创建。需要“仅在不存在时创建”时,使用 open("x") 并处理 FileExistsError。
unlink()、rmdir()、rename() 和 replace() 会修改真实数据,replace() 还可能覆盖目标。批量操作先打印候选路径或在测试目录演练,重要文件先备份。
排障清单
FileNotFoundError:先执行path.parent.mkdir(parents=True, exist_ok=True)。relative_to()报ValueError:目标不在基目录下,先用is_relative_to()判断。- 平台间分隔符不同:不要比较路径字符串;日志需要统一格式时再用
as_posix()。 PermissionError:检查父目录权限、只读挂载和文件占用,不要直接放宽整个目录权限。- 文本乱码:显式传入正确编码,统一协议优先使用
encoding="utf-8"。
速查原则:路径运算始终保留为 Path,只有旧 API 或文本协议明确需要时才转换为字符串。
按指定编码读取、覆盖或追加文本文件内容。
读写文本文件
用于按明确编码读取文本,或以覆盖、追加方式写入内容。生产脚本应同时固定文件路径、编码和写入模式,避免因工作目录或系统默认编码不同而得到意外结果。
基本语法
open(path, mode, encoding=...) 返回文件对象,推荐配合 with 使用,退出代码块时会自动关闭文件。常用模式是 r 读取、w 覆盖写入、a 追加写入;文本文件通常显式指定 encoding="utf-8"。
高频用法
下面的示例先覆盖创建文件,再追加一行,最后完整读取。newline="\n" 让写入内容统一使用 LF,便于跨平台生成稳定文件。
from pathlib import Path
path = Path("notes.txt")
# w 会清空已有内容,确认目标路径后再写入
with path.open("w", encoding="utf-8", newline="\n") as file:
file.write("第一行\n")
# a 从文件末尾追加,不会覆盖已有内容
with path.open("a", encoding="utf-8", newline="\n") as file:
file.write("第二行\n")
with path.open("r", encoding="utf-8") as file:
content = file.read()
print(repr(content))
print(content, end="")预期输出
'第一行\n第二行\n'
第一行
第二行第一行用 repr 显示真实换行符,后两行是文件的可见内容。需要逐行处理大文件时,改用 for line in file,不要一次性调用 read()。
风险与边界
使用 w 且路径指向已有文件时,会在写入前截断原文件;进程随后异常退出,可能只留下半份内容。重要文件应先写入同目录临时文件,完成 flush 和必要校验后再用 os.replace() 原子替换,并保留备份。
读取时省略编码,或实际文件并非 UTF-8,可能触发 UnicodeDecodeError,也可能出现乱码。优先确认文件来源并固定编码;无法确定时先检测或要求上游声明编码,不要用 errors="ignore" 静默丢弃数据。
多个进程同时追加或覆盖同一文件时,内容可能交错、覆盖或丢失。应通过单写者、文件锁、队列或数据库协调写入,而不是依赖普通文本文件承担并发存储。
排障清单
FileNotFoundError:打印Path.cwd()和目标绝对路径,确认相对路径是否基于预期工作目录。PermissionError:检查目录写权限、文件只读属性,以及文件是否被其他程序独占。- 内容未追加:确认模式是
a,并检查是否在后续步骤又以w打开了同一路径。 - 读取内容过大:改为逐行迭代或分块读取,避免一次性占满内存。
兼容性
Python 3 在不同操作系统上的默认编码和换行规则可能不同。跨平台脚本应显式设置 encoding,生成协议文件时同时固定 newline;只读取普通文本时通常让 Python 自动处理平台换行即可。
在 Python 对象与 JSON 文本之间进行序列化和反序列化。
读写 JSON 文件
用于把 Python 的字典、列表等基础对象保存为 JSON,或从 JSON 文件恢复为 Python 对象。文件读写应固定 UTF-8 编码,并区分面向文件的 load、dump 与面向字符串的 loads、dumps。
基本语法
json.load(file) 从文件反序列化,json.dump(obj, file) 写入文件;json.loads(text) 解析字符串,json.dumps(obj) 返回字符串。读取结果通常是 dict、list、str、int、float、bool 或 None。
常用参数
ensure_ascii=False:直接保留中文字符;默认值会把非 ASCII 字符写成\uXXXX。indent=2:格式化缩进,便于人工审阅;省略时文件更紧凑。sort_keys=True:按键排序,适合生成稳定差异,但会改变原始键顺序。encoding="utf-8":这是open()的参数,不是json.dump()或json.load()的参数。
高频用法
下面的示例写入一个配置对象,再读回并访问字段。末尾补一个换行,便于命令行工具查看和版本控制比较。
import json
from pathlib import Path
path = Path("config.json")
data = {
"service": "api",
"enabled": True,
"ports": [8000, 8001],
}
# ensure_ascii=False 保留中文;indent 生成可审阅的文件
with path.open("w", encoding="utf-8", newline="\n") as file:
json.dump(data, file, ensure_ascii=False, indent=2)
file.write("\n")
with path.open("r", encoding="utf-8") as file:
loaded = json.load(file)
print(loaded["service"])
print(loaded["ports"])预期输出
api
[8000, 8001]输出表明 JSON 对象已恢复为字典,数组已恢复为列表。验证文件语法时,也可以运行 python -m json.tool config.json;命令成功会格式化输出,失败会给出错误位置。
风险与边界
对象包含 set、datetime、Decimal 或自定义类时,json.dump() 会触发 TypeError。应在写入前显式转换为约定的数据结构,或提供受控的 default 函数;涉及金额、时间或类型恢复时,不要用 default=str 掩盖语义。
JSON 不允许单引号、尾随逗号和注释。把 Python 字典文本直接当 JSON 读取会触发 JSONDecodeError;应由 json.dump() 生成,或修正上游格式,不要使用 eval() 解析不可信内容。
直接以 w 覆盖配置文件时,进程中断可能留下空文件或不完整 JSON。关键配置应先写临时文件,成功反序列化校验后再用 os.replace() 替换;存在并发写入时还需锁或单写者机制。
超大或不可信 JSON 会一次性占用大量内存和解析时间。应限制文件大小、来源和嵌套深度;需要流式处理的大数据优先使用逐行 JSON 等可增量格式。
排障清单
JSONDecodeError:查看异常中的行号、列号和字符位置,重点检查尾随逗号、单引号、截断文件与非法转义。TypeError: Object of type ... is not JSON serializable:定位非基础类型,明确转换规则后再写入。- 中文显示为
\u4e2d:写入时设置ensure_ascii=False,并确认查看工具按 UTF-8 打开文件。 - 字段不存在:先打印
loaded.keys()或检查数据版本,不要直接假设所有文件都有相同结构。
按列名或行结构读取和生成 CSV 数据文件。
读写 CSV 文件
使用标准库 csv 按列名读取、写入表格数据。优先使用 DictReader 和 DictWriter,可避免依赖列的位置;打开文件时固定传入 newline="",防止 Windows 出现空行。
基本语法
读取时,首行会作为字段名;写入时,fieldnames 决定列顺序,writeheader() 负责生成表头。
import csv
from pathlib import Path
def main() -> None:
path = Path("users.csv")
rows = [
{"id": "1", "name": "Alice", "active": "true"},
{"id": "2", "name": "Bob", "active": "false"},
]
# newline="" 交给 csv 模块处理换行,避免产生额外空白行。
with path.open("w", encoding="utf-8", newline="") as file:
writer = csv.DictWriter(file, fieldnames=["id", "name", "active"])
writer.writeheader()
writer.writerows(rows)
with path.open("r", encoding="utf-8", newline="") as file:
for row in csv.DictReader(file):
print(row["id"], row["name"], row["active"])
if __name__ == "__main__":
main()预期输出:
1 Alice true
2 Bob false生成的 users.csv 内容为:
id,name,active
1,Alice,true
2,Bob,false读取结果中的值默认都是字符串;需要整数、布尔值或日期时,应在业务校验通过后显式转换。
常用参数
| 参数 | 什么时候设置 | 说明 |
|---|---|---|
delimiter |
文件不是逗号分隔 | 例如制表符使用 delimiter="\t" |
quotechar |
字段可能包含分隔符 | 默认双引号,写入时会自动包裹必要字段 |
encoding |
文件来源明确 | 通常用 utf-8;Excel 中文文件常见 utf-8-sig |
extrasaction |
字典可能有多余键 | DictWriter(..., extrasaction="ignore") 可忽略未声明字段 |
restval |
某些行缺少字段 | 写入缺失列时使用该默认值 |
高频用法
按位置处理无表头文件时使用 csv.reader 和 csv.writer;按列名处理业务数据时使用字典版本。文件分隔符未知时,可先对小段样本调用 csv.Sniffer().sniff(sample),但生产任务应优先由配置明确指定格式,避免错误推断。
追加数据时用模式 "a",但不要再次调用 writeheader()。是否需要表头可先检查 path.exists() 和 path.stat().st_size,防止重复表头混入数据行。
风险与边界
触发条件:直接用 line.split(",") 解析包含引号、逗号或换行的字段。可能后果:列错位或数据截断。安全替代:始终交给 csv.reader 或 DictReader 处理转义规则。
触发条件:读取不可信的大文件且一次性调用 list(reader)。可能后果:内存快速增长,进程被系统终止。安全替代:逐行迭代并分批写入下游。
触发条件:编码选错或未限制字段长度。可能后果:出现乱码、UnicodeDecodeError,或超长字段触发异常。安全替代:确认来源编码;必要时调用 csv.field_size_limit() 设置经过评估的上限。
排障清单
- 出现空白行:确认打开文件时使用了
newline=""。 - 中文乱码:核对实际编码;Excel 导出文件可尝试
utf-8-sig,不要盲目忽略解码错误。 KeyError:打印reader.fieldnames,检查表头空格、大小写和 BOM。- 列数不一致:记录原始行号,并检查引号是否闭合、分隔符是否正确。
速查:列名稳定时用 DictReader/DictWriter,数据量大时保持逐行流式处理。
搜索、提取、替换和验证符合模式的文本。
匹配正则表达式
使用 re 对文本执行搜索、提取、替换和格式校验。模式会重复使用时先 re.compile();正则字符串优先写成原始字符串 r"...",避免反斜杠被 Python 字符串再次解释。
基本语法
下面一次演示完整校验、命名分组提取、批量搜索和替换:
import re
ORDER_RE = re.compile(r"^(?P<prefix>[A-Z]{2})-(?P<number>\d{4})$")
TEXT_RE = re.compile(r"订单\s+(?P<order>[A-Z]{2}-\d{4})")
def main() -> None:
order_id = "CN-2048"
match = ORDER_RE.fullmatch(order_id)
print(match.groupdict() if match else "invalid")
text = "订单 CN-2048 已创建,订单 US-1024 待审核"
print([item.group("order") for item in TEXT_RE.finditer(text)])
masked = re.sub(r"\d", "*", order_id)
print(masked)
if __name__ == "__main__":
main()预期输出:
{'prefix': 'CN', 'number': '2048'}
['CN-2048', 'US-1024']
CN-****fullmatch() 要求整个字符串符合模式,适合字段校验;finditer() 返回迭代器,适合逐个读取匹配及其位置;sub() 返回替换后的新字符串,不会修改原值。
常用接口
| 接口 | 适用场景 | 关键区别 |
|---|---|---|
re.search() |
任意位置寻找首个匹配 | 不要求从开头匹配 |
re.match() |
只检查字符串开头 | 容易被误当作完整校验 |
re.fullmatch() |
验证整个字段 | 校验输入时优先使用 |
re.findall() |
提取全部匹配值 | 存在捕获组时返回组内容或元组 |
re.finditer() |
需要值、位置或流式遍历 | 返回匹配对象迭代器 |
re.sub() |
替换或脱敏 | 替换参数可传函数 |
常用标志包括 re.IGNORECASE、re.MULTILINE 和 re.DOTALL。多标志可用 | 组合,例如 re.IGNORECASE | re.MULTILINE;应只开启确实需要的标志,避免扩大匹配范围。
模式读取
() 创建捕获组,(?:...) 只分组但不捕获,(?P<name>...) 创建命名组。数量约束常用 ?、*、+、{m,n};字符集合用 [];特殊字符如 .、+、( 需要转义,或对普通文本调用 re.escape()。
边界应写明确。例如验证四位数字使用 r"\d{4}" 仍可能匹配部分文本,配合 fullmatch() 才能保证没有前后多余字符。
风险与边界
触发条件:对不可信长文本使用含嵌套量词的模式,例如 (a+)+$。可能后果:灾难性回溯导致 CPU 长时间占满。安全替代:消除嵌套量词、限定输入长度,并用线性扫描或专用解析器替代复杂模式。
触发条件:把用户输入直接拼接进正则。可能后果:输入被当作元字符,造成误匹配或性能问题。安全替代:普通文本先经过 re.escape(user_input)。
触发条件:用正则解析完整 HTML、JSON 或编程语言。可能后果:嵌套结构、转义和边界处理错误。安全替代:使用对应解析器,正则只处理局部、结构简单的文本。
排障清单
- 总是匹配失败:检查是否误用了双反斜杠,打印
pattern.pattern查看实际模式。 - 只得到分组内容:
findall()遇到捕获组会改变返回形状;改用非捕获组或finditer()。 ^、$行为异常:确认是否开启re.MULTILINE;严格结尾校验可优先配合fullmatch()。- 匹配范围过大:检查贪婪量词,必要时改为
*?、+?,并增加明确边界。 - 替换结果异常:替换字符串中的反斜杠也有特殊含义;复杂替换改用函数返回值。
速查:字段校验用 fullmatch(),首次搜索用 search(),批量提取且需要位置用 finditer()。