Python 教程 / 类型提示与 mypy 静态检查

类型提示说明变量、函数参数与返回值预期使用什么类型,供读者、编辑器和静态检查工具理解。Python 普通执行不会仅凭注解拒绝错误输入,因此仍要明确编写运行时验证。

理解类型契约与实际检查的区别

参数上的 amount: int 表示调用者应提供整数,不会自动把字符串转换成整数;返回位置的 -> str 表示预期返回字符串。list[int] 描述整数列表,str | None 则允许字符串或缺失值 None。本课示例以 Python 3.12 以上版本为基础。

注解让接口意图更容易检查,但不能取代业务规则。例如负整数仍属于 int,静态检查通常无法据此知道金额不应为负。另一方面,输入是否允许字符串“8000”并转换,属于应用自己决定的输入政策,不能从注解推断。相关定义见Python 官方类型提示文档。

本例使用 type(amount) is int,而不是只检查 isinstance(amount, int),以拒绝 bool。错误处理沿用try、except 与 raise的规则。动态读取注解的工具还应核对所用 Python 版本的求值规则,不要把不同版本的内部表示视为固定不变。

执行完整示例并解释输出

在独立练习目录中,把下面完整代码保存为 UTF-8 的 hints.py。选择项目虚拟环境,在该目录执行 python hints.py;如果核对后的解释器命令是 python3,则使用 python3。普通执行只需要标准库,不必先安装 mypy。

def format_amount(amount: int) -> str:
    if type(amount) is not int or amount < 0:
        raise ValueError("invalid amount")
    return f"{amount:,} KRW"

def find_name(names: dict[str, str], key: str) -> str | None:
    return names.get(key)

print(format_amount(8000))
print(find_name({"e1": "lunch"}, "missing"))
try:
    format_amount("8000")
except ValueError:
    print("rejected")

预期输出:

8,000 KRW
None
rejected

format_amount(8000) 返回带千位分隔符的字符串;KRW 是本例保留的韩元单位,并不执行汇率转换。find_name 用字典 get 查询不存在的键,返回 None。最后一次调用故意传入字符串,函数中手写的条件抛出 ValueError,再由 except 打印 rejected;不是注解自动抛出的异常。

比较时先把 8000 改成 0,输出应变成 0 KRW。将最后的错误参数改为 -1,尽管它是整数,运行验证仍会拒绝。完成比较后恢复原文件,确保预期输出又与上方一致。

用 mypy 独立进行静态检查

确认虚拟环境已选中,再在同一目录运行以下两条命令。安装需要访问包源;第二条只分析 hints.py,不会先执行其中的 print。工具版本、设置和诊断文字可能变化,操作说明见mypy 官方入门指南。

python -m pip install mypy
python -m mypy hints.py

当前文件本来就包含 format_amount("8000"),所以 mypy 报告参数类型错误是预期结果,不代表安装失败。不要用 Any 或随意忽略错误来掩盖这次练习。创建 hints_valid.py 副本,删除最后整个 try/except 代码段,再运行 python -m mypy hints_valid.py;应不再报告这处故意错误。只删 try 内的一行会留下空代码块,造成语法错误。

检查方式 本例检查什么 不能据此保证什么
mypy 静态分析 参数、返回值与注解之间的类型关系 金额范围、文件存在或网络可用
运行时验证 实际值是否为非负的纯 int 其他函数或其他输入路径都有同样验证

静态工具也可能按 int 的类型关系接受 True,但本例的运行条件明确拒绝它。这说明“静态检查成功”和“所有输入符合业务规定”是不同结论。修复类型错误后仍应运行测试,特别是零、负值、布尔值和外部输入的边界。

处理可能缺失的返回值

find_name 的返回类型包含 None,所以调用 upper 等字符串方法前,先用 if result is not None 判断。拿到缺失值后直接执行 result.upper() 会产生 AttributeError。静态工具能够提醒这种未缩小类型的调用,实际执行仍要遵守同一个分支规则。

还要注意,dict[str, str] 并不会在运行时逐项验证字典。若外部解析结果带来整数值,find_name 仍可能直接返回整数。进入应用边界时应检查键和值的类型,把经过验证的数据交给带类型提示的内部函数,而不是把任意解析结果标为字典后便假定安全。

核对函数的每一个返回路径、缺失值分支和输入拒绝规则。类型提示提供可读的契约,静态检查帮助找出契约之间的矛盾,运行验证则负责真实输入与值范围;三者配合才能减少错误。