1 / 4概念
Functions
函数是 Python 里最主要的抽象单位:它把参数、作用域、异常和资源边界收在一处。判断一个函数是否可靠,不看它跑通一次,而看签名是否说清输入输出、异常是否是契约的一部分、资源是否一定释放、类型注解是否真能被检查器接住。
1 概念
1.1 一句话定义
函数是一等对象:定义时求值默认参数并生成代码对象,调用时把实参绑定成局部名字并在新帧里执行;闭包捕获外层 cell,装饰器是高阶函数,生成器与上下文管理器都是可被 for、with、async with 驱动的协议实现。
1.2 它解决什么问题
- 接口与复用:签名描述输入输出,调用方不必知道实现。
- 作用域隔离:局部名字不污染模块,闭包表达稳定依赖。
- 横切复用:装饰器承载重试、缓存、鉴权、计时,而不改函数体。
- 确定释放:上下文管理器把打开与关闭写成一对,异常路径也执行清理。
- 惰性数据流:生成器按需产出,内存不随数据量线性增长。
- 可检查契约:类型注解、
Protocol与TypedDict让静态检查器在运行前发现错配。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 对象模型、引用、相等与哈希 | Interpreter and Objects |
GIL、线程、进程与 asyncio | Async and Concurrency |
导入系统、pyproject.toml、mypy/pyright 的安装配置 | Modules and Packaging |
JavaScript 的函数、闭包与 this | Functions and Scope |
| TypeScript 的类型收窄与泛型 | Types and Narrowing、Generics and Operators |
| 测试框架与夹具的完整用法 | Unit Testing |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| 位置参数 | 按顺序绑定的参数 | / 左边的参数不能按关键字传 |
| 关键字参数 | 按名字绑定的参数 | * 右边的参数必须按关键字传 |
| 默认值 | 定义时求值并保存的对象 | 可变默认值会被所有调用共享 |
| 闭包 | 引用外层局部变量的函数 | 捕获的是变量,不是当时的值 |
| 装饰器 | 接收函数并返回可调用对象的高阶函数 | 不加 wraps 会丢签名与文档 |
| 生成器 | 用 yield 产出值的函数 | 只能消费一次,且不立即执行 |
| 上下文管理器 | 实现 __enter__ / __exit__ 的对象 | 不是异常处理器本身 |
| 类型注解 | 运行时不强制、供检查器读取的标注 | 不是运行时校验 |
Protocol | 结构化子类型:看方法签名不看继承 | runtime_checkable 只查方法存在性 |
TypedDict | 描述字典键与值类型的类型 | 运行时不校验键 |
TypeVar | 泛型参数 | 约束与绑定方差影响推导 |
| EAFP | 先做再捕获异常 | 与 LBYL 的前提检查相对 |
| 异常链 | raise ... from 设置 __cause__ | 与隐式 __context__ 不同 |
2 机制
2.1 心智模型
调用一次函数等于三步:先把实参绑定到形参,再为新帧准备局部槽位,最后执行字节码。函数定义只创建代码对象与默认值,函数体一行都不执行;生成器函数连帧都只创建一次,再按 next() 逐步推进。
2.2 机制拆解
- 参数绑定:形参分位置-only(
/前)、位置或关键字、*args、关键字-only(*后)与**kwargs。默认值在def执行时求值一次并存进函数对象;需要每次新建时用None哨兵。 - 闭包:内层函数引用外层变量时,变量升级为 cell。循环里创建的闭包共享同一个 cell,所以
lambda在循环结束后看到的是最终值;需要绑定当前值就用默认参数或functools.partial。 - 装饰器:
@d等价于f = d(f)。带参数的装饰器是三层结构:先收配置,再收函数,再返回包装器。functools.wraps复制__name__、__doc__、__qualname__、__dict__并设置__wrapped__,让inspect.signature仍能读出原签名。 - 生成器:函数体含
yield时调用返回生成器对象。next()推进到下一个yield,send()把值送回yield表达式,throw()在挂起点抛异常,close()触发GeneratorExit。yield from把迭代委托给子生成器并透传send/throw,子生成器的返回值进入StopIteration.value。 - 上下文管理器:
with先调用__enter__,正常或异常退出时调用__exit__(exc_type, exc, tb);返回真值表示异常已被吞掉。contextlib.contextmanager把一个生成器转成上下文管理器,yield之前是进入、之后是退出,异常会在yield处抛出。 - 异常契约:函数应只抛自己能解释的异常,并把底层异常用
raise NewError(...) from err链起来;except只捕获具体类型,裸except会吞掉KeyboardInterrupt、CancelledError和真实 bug。 - 类型系统:注解是对象,默认在函数定义时求值;
from __future__ import annotations让它变成字符串,避免前向引用与导入环。检查器读取注解做静态检查;typing.get_type_hints在运行时解析,代价高且可能失败。Protocol是结构化子类型,TypedDict描述字典形状,overload只对检查器有效,运行时只有最后一个实现。
2.3 完整枚举
| 构造 | 用途 | 边界 |
|---|---|---|
| 位置-only 参数 | 锁定参数顺序,允许改名 | 调用方不能按关键字传 |
| 关键字-only 参数 | 强制可读的参数名 | 不能靠位置省略 |
*args / **kwargs | 透传与包装 | 丢失签名与类型,必须补注解 |
| 默认参数 | 可选配置 | 定义时求值,可变对象会共享 |
functools.wraps | 保留被包装函数的元数据 | 不改运行时行为 |
functools.lru_cache / cache | 记忆化纯函数 | 参数必须可哈希,缓存无界会涨内存 |
functools.singledispatch | 按第一个参数类型分派 | 不做多重分派 |
contextlib.contextmanager | 生成器写上下文管理器 | 异常在 yield 处抛出 |
contextlib.ExitStack | 动态数量的资源 | 容易忘记显式关闭 |
contextlib.suppress | 忽略指定异常 | 只应包住精确的一行 |
typing.Protocol | 结构化接口 | runtime_checkable 不检查签名 |
typing.TypedDict | 字典形状 | 运行时仍是普通 dict |
typing.overload | 多签名声明 | 运行时只保留实现 |
typing.ParamSpec | 保留被包装函数的签名 | 需要 3.10 及以上 |
typing.Self | 返回自身类型 | 需要 3.11 及以上 |
ExceptionGroup / except* | 承载多处并发失败 | 需要 3.11 及以上 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 函数调用开销 | 数十纳秒 | 3.11 起显著降低,但仍高于内联 |
| 递归深度上限 | 约 1000 层 | sys.getrecursionlimit() |
| 装饰器成本 | 每次调用多一层帧 | 嵌套装饰器层层叠加 |
| 缓存命中 | 一次字典查找 | lru_cache 命中约数十纳秒 |
| 生成器对象 | 约数百字节 | 远小于一次性列表 |
| 生成器切换 | 微秒级以下 | 比线程切换轻 |
| 类型注解求值 | 定义时一次 | 前向引用会让求值失败 |
get_type_hints | 毫秒级 | 运行时解析,不宜放热路径 |
3 实践
3.1 最小示例
from contextlib import contextmanager
from functools import wraps
from typing import Iterator, Protocol
class Store(Protocol):
def get(self, key: str) -> str | None: ...
def put(self, key: str, value: str) -> None: ...
@contextmanager
def session(store: Store) -> Iterator[Store]:
try:
yield store
finally:
store.put("closed", "1")
def traced(fn):
@wraps(fn)
def wrapper(*args, **kwargs):
try:
return fn(*args, **kwargs)
except ValueError as err:
raise RuntimeError("call failed") from err
return wrapper
@traced
def load(store: Store, key: str) -> str:
return store.get(key) or "missing"
追踪一次失败调用:load 抛 ValueError,traced 捕获后抛 RuntimeError 并保留 __cause__;调用方看到两层 traceback,第一层说明业务失败,第二层给出根因。with session(store) 退出时无论成功还是异常都会执行 finally,把关闭标记写入同一接口。
3.2 常用操作与参数
| 操作 | 写法 | 说明 |
|---|---|---|
| 看签名 | inspect.signature(f) | 加 wraps 后仍能看到原签名 |
| 部分应用 | functools.partial(f, x) | 固定前置参数,不复制函数体 |
| 记忆化 | @cache / @lru_cache(maxsize=128) | 纯函数与可哈希参数才适用 |
| 按类型分派 | @singledispatch | 注册函数用 @fn.register |
| 动态资源 | with ExitStack() as stack: | stack.enter_context(cm) |
| 忽略异常 | with suppress(FileNotFoundError): | 只包一行 |
| 迭代工具 | itertools.islice / chain | 惰性组合,不物化中间列表 |
| 参数校验 | 哨兵 _MISSING = object() | 区分“未传”与“传了 None” |
| 运行时取注解 | typing.get_type_hints(f) | 解析前向引用,注意导入环 |
| 判断可调用 | callable(x) | 不看签名 |
3.3 标准流程
- 先定签名:参数顺序、是否只读、哪些必须按关键字传,用默认值表达可选性。
- 默认值只用不可变对象;需要可变时用
None哨兵。 - 写清异常契约:函数抛什么、为什么抛、调用方该捕获还是让上层处理。
- 资源用
with;需要动态数量时用ExitStack,不要手写try/finally嵌套。 - 数据量大或可能无限时返回生成器;需要多次遍历就返回列表或
tuple。 - 用
Protocol描述依赖,用TypedDict描述外部字典,用overload描述重载;把检查器写进 CI。
3.4 与相邻技术的组合
- pytest:夹具就是生成器;
yield前准备、后清理,与contextmanager同一心智模型。 - FastAPI:依赖注入用可调用对象与生成器依赖,签名决定请求参数,
Protocol描述仓储。 - dataclasses:
__post_init__是构造期校验,field(default_factory=...)解决可变默认值。 - asyncio:
async with与async for是同一套协议的异步版本;阻塞调用要用to_thread桥接。 - functools 与装饰器链:鉴权、重试、计时、缓存可以叠加,但顺序决定语义,最外层最先执行。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 返回规模 | 小结果 / 大结果 / 无限流 | 决定返回列表、生成器还是迭代器 |
| 调用频率 | 偶发 / 热点 | 热点要评估装饰器与校验开销 |
| 依赖形态 | 具体类 / 结构化接口 | Protocol 降低耦合,但检查变弱 |
| 参数形态 | 固定 / 透传 | 透传要补签名,否则类型全丢 |
| 可选参数 | 少量 / 大量 | 大量可选参数应收进配置对象 |
| 失败语义 | 返回值 / 异常 | 异常用于例外,不用于常规分支 |
3.6 决策规则
- 可变默认值一律改成
None哨兵;这条没有例外。 - 装饰器必须加
wraps;带参数的装饰器用三层函数或functools.partial。 - 生成器只在一处消费;需要多处遍历时返回
tuple或重新调用工厂函数。 - 库代码用
Protocol描述入参,不用抽象基类强制继承。 except只捕获本层能处理的异常,其余raise原样上抛。- 类型注解要能被
pyright或mypy在严格模式下接受,否则注解只是注释。 - 参数超过五个且有多个可选时,改为一个 dataclass 或
TypedDict参数。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| 普通函数 | 最轻、最直观 | 组合靠装饰器 | 绝大多数逻辑 |
类 + __call__ | 有状态、可配置 | 多一层对象 | 需要保存配置的处理器 |
| 装饰器 | 横切复用不改函数体 | 调试栈变深、签名易丢 | 重试、缓存、鉴权 |
| 上下文管理器 | 确定释放 | 侵入调用点 | 文件、锁、事务 |
| 生成器 | 惰性、省内存 | 单次消费 | 大文件、流式管道 |
Protocol | 结构化、低耦合 | 运行时检查弱 | 跨模块接口 |
| 抽象基类 | 运行时可检查、可共享实现 | 强制继承 | 框架扩展点 |
3.8 何时不该用
- 简单的一行转换不需要装饰器;直接调用更易读。
- 返回值要跨进程或跨请求复用时不要返回生成器。
- 参数是动态键值对且无稳定形状时,
TypedDict只会制造维护负担。 - 装饰器会改变语义(如把同步函数包装成异步)时,优先显式重写。
- 异常用于控制正常流程会让性能与可读性同时变差。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 多次调用共享同一个列表 | 默认参数在定义时创建一次 | 用 None 哨兵在函数内创建 |
| 循环里的闭包都输出最后一个值 | 闭包捕获 cell 而非当前值 | 用默认参数绑定当前值 |
装饰后 inspect.signature 报错 | 未使用 wraps | 加 @functools.wraps(fn) |
| 生成器第二次遍历为空 | 生成器只能消费一次 | 返回 tuple 或重新创建 |
捕获了 CancelledError 导致取消失效 | 裸 except 或 except Exception 范围过大 | 只捕获具体异常并 raise |
| 递归深度溢出 | 递归未收敛或数据过深 | 改迭代或显式栈 |
类型检查器对 **kwargs 无反应 | 透传丢失签名 | 用 ParamSpec 或显式参数 |
Protocol 的 isinstance 通过但调用失败 | 运行时只查方法名,不查签名 | 用 typing.runtime_checkable 只做粗筛 |
| 缓存越用内存越大 | lru_cache(maxsize=None) 无界 | 设上限或用弱引用缓存 |
| 上下文管理器吞掉异常 | __exit__ 返回真值 | 只在确知已处理时返回真值 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
用 lambda 写多行逻辑 | 无法调试、无名字 | 定义普通函数 |
装饰器里不写 wraps | 文档、签名、类型全丢 | @wraps |
| 用异常做正常分支 | 性能差、调用方难读 | 返回哨兵或 Optional |
| 一个函数做参数校验、业务和 I/O | 无法单测、无法复用 | 拆成校验、纯函数、适配层 |
| 生成器里做资源申请却不清理 | 提前退出时泄漏 | try/finally 或上下文管理器 |
把所有异常转成 Exception | 丢失类型与处理能力 | 定义异常层次并链式抛出 |
用 assert 做外部输入校验 | -O 会移除断言 | 显式 if ... raise |
4.3 可观测信号
签名问题看 inspect.signature 与 help();装饰器是否保留元数据看 __wrapped__ 与 __qualname__;生成器是否泄漏看 gc.get_referrers 与生成器对象的 gi_frame;异常契约看 traceback 的链式段;类型覆盖看 pyright --verifytypes 与 mypy --strict 的报告;热点看 cProfile 里函数自身的 tottime,别把时间算在子调用上。
4.4 安全 / 性能 / 一致性边界
- 类型边界:注解只是静态信息,
typing.get_type_hints可能因导入环失败;外部输入仍要运行时校验。 - 异常边界:库不应抛出
SystemExit或KeyboardInterrupt之外的BaseException子类;捕获范围过宽会破坏调用方的取消与退出语义。 - 资源边界:生成器和上下文管理器都依赖调用方推进;生成器被丢弃时清理依赖 GC,关键资源应显式关闭。
- 性能边界:装饰器与逐元素校验是常数成本,数量级差异来自算法与数据结构;热点函数应先测量再拆装饰器。