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 仍可能直接返回整数。进入应用边界时应检查键和值的类型,把经过验证的数据交给带类型提示的内部函数,而不是把任意解析结果标为字典后便假定安全。
核对函数的每一个返回路径、缺失值分支和输入拒绝规则。类型提示提供可读的契约,静态检查帮助找出契约之间的矛盾,运行验证则负责真实输入与值范围;三者配合才能减少错误。




