# 代码还没跑，Pyright 已找出客户仓库的 None 漏洞

> Python 运行时不管类型提示，接手陌生仓库时，告诉你函数真实返回值的是检查器，不是解释器。

原文: https://fdetimes.net/zh/guides/python-type-hints-pyright-none-errors/

驻场第二天，你拿到了一个已有好几年历史的 Python 仓库的权限。写计费代码的工程师已经离职，每个函数都有参数名，却没有一处注解。周五之前，你要把自己的数据管道接到这段代码上。

常见做法是一个文件接一个文件地读，到处加 `print`，再用样例数据跑一遍。这样很慢，而且会漏掉最常拖垮真实部署的那类 bug：某个函数在样例数据下总能返回值，但客户数据缺了一行时就返回 `None`。

类型提示配合 pyright 这样的类型检查器，可以同时解决这两个问题。知道每个函数接收什么、返回什么，读陌生代码就更快；错误也能在任何代码运行之前被发现。前线部署工程师（FDE）几乎总在处理别人写的代码，这项技能很快就能回本。

## Python 不检查类型，那谁来检查？

这一点搞错，后面就全错，所以值得一开始就讲清楚。`typing` 模块的官方文档写明：Python 运行时不强制检查函数和变量的类型注解。注解是给第三方工具读的，比如类型检查器、IDE 和 linter。

这从一开始就是有意设计的。PEP 3107 引入了函数注解的语法，却刻意没有规定它的含义。直到 PEP 484，注解才被用来表示类型。PEP 484 本身也写明，Python 仍将是动态类型语言，作者无意让类型提示成为强制要求。

这对你有两层意义。写了 `def f(x: int)`，并不能阻止别人传入字符串。反过来，给客户代码加类型提示也不会改变代码的运行方式，所以这项工作几乎没有风险。类型提示只有在工具读取时才有用。

## 为什么 pyright 适合没有类型提示的代码

Pyright 是一个静态类型检查器，可以作为语言服务器装进编辑器，也可以用命令行版本。根据 pyright 的文档，使用它并不需要完整的注解：类型信息越多，它能帮的忙越多。

对遗留代码来说，关键在于 pyright 不会等你先写好类型提示。根据其文档，默认配置下它会检查所有代码，无论有没有注解。

它根据赋给变量的值推断变量类型。函数的返回类型取所有 `return` 语句类型的并集。无法推断时，pyright 把类型视为 `Unknown`，这是 `Any` 的一种形式。

Mypy 的默认行为不同。根据 pyright 的同一份对比文档，mypy 会跳过所有没有类型注解的函数和方法。

这是个陷阱。在没有类型提示的仓库上，mypy 检查通过并不说明代码没问题，只说明 mypy 没读大部分代码。

Pyright 的文档还提到，在大型代码库上，pyright 比 mypy 快 3 到 5 倍是常见情况。

## 一个 None bug 的完整过程

设想下面这段按地区计费的代码。它在作者的机器上运行正常，因为测试数据里总有 EU 地区。

```python
def load_rate(rows, region):
    for row in rows:
        if row["region"] == region:
            return float(row["rate"])
    return None

def price_with_tax(rows, region, price):
    rate = load_rate(rows, region)
    return rate * price
```

这里没有一处注解。不做任何修改，直接在这个目录上运行 `pyright`。`rows` 没有类型，所以 pyright 把 `row` 视为 Unknown。但仅凭两条 `return` 语句，它就能推断出 `load_rate` 返回 `float | None`。

问题出在最后一行。这里 `rate` 的类型是 `float | None`，用 `None` 乘以一个数会让程序中断。这条类型信息在运行前就已经有了，所以读 pyright 输出时，应该先看这一行。它直指导致发票出错的场景：客户有一个费率表里还没有的地区。

换成默认配置的 mypy，这两个函数都没有注解，会被直接跳过。

修复分两步。第一步，用类型提示写明意图。Mypy 的速查表建议，可能为 `None` 的值写成 `X | None`；`Optional[X]` 的含义完全相同：

```python
def load_rate(rows: list[dict[str, str]], region: str) -> float | None:
    for row in rows:
        if row["region"] == region:
            return float(row["rate"])
    return None

def price_with_tax(rows: list[dict[str, str]], region: str, price: float) -> float:
    rate = load_rate(rows, region)
    if rate is None:
        raise ValueError(f"地区 {region} 没有税率")
    return rate * price
```

第二步是 `if rate is None` 这个判断。过了这一行，类型检查器会把 `rate` 的类型收窄为 `float`。代码依然很短，但已经清楚写明数据缺失时怎么处理。这也正是要拿去问客户的问题：某个地区没有税率时，代码应该报错，还是使用默认税率？

**要点:** 类型检查器不会替你理解代码，它告诉你该问客户什么。

## 处理客户仓库的顺序

第一步，在改动任何代码之前，用默认配置运行 pyright。根据其文档，pyright 的 `typeCheckingMode` 有四个级别：off、basic、standard 和 strict，默认是 standard。第一次运行会给你一张地图：哪些文件错误最多，哪些函数可能返回 `None`，哪里全是 Unknown。

第二步，先在数据进入的地方加类型提示：读文件、调用 API、查询数据库，或者接收客户系统输入的函数。

原因在 mypy 的速查表里：没有类型的参数会被视为 `Any`，而遇到 `Any`，工具一个错误也查不出来。

第三步，把配置写进你分支上的 `pyrightconfig.json`，客户同意的话，再把 `pyright` 命令加进 CI。旧代码保持 standard。自己新写的模块可以设为 strict，因为没有历史包袱要清理。

## 常见错误

第一个错误是以为类型提示能在运行时保护代码。并不能。如果客户 API 返回的数据可能类型不对，你仍然要在数据进入的地方自己检查。

第二个是相信无注解仓库上 mypy 的检查通过，就像上面的例子。第三个是到处塞 `Any` 来消掉红色报错。错误数看起来好了，工具却什么也检查不了。

最后一个是第一天就对整个遗留仓库开启 strict。你会得到一长串错误，客户会看到一个改动几百个文件的 pull request，真正要紧的 `None` 错误则被埋在里面。

想把这项技能写进简历，就记下接手仓库时 pyright 报了多少错误，以及你在哪些 bug 碰上真实数据之前拦住了它们。这样一句话能让招聘经理看到你上手陌生代码库有多快，泛泛的一句“熟悉 Python”做不到这一点。

下次再拿到没有文档的仓库，先运行 pyright，再写第一个 `print`。第一份错误列表通常就能相当清楚地告诉你，客户的数据会在哪里让代码出错。

**本周动手试试:**

- 安装 pyright 命令行版本，在你正在接手的 Python 仓库上运行，代码和默认配置都不改。记下与 None 相关的错误。
- 挑一个读取外部数据的函数，用 X | None 加上类型提示，在调用处处理 None 的情况，然后重新运行 pyright，直到错误消失。

## 信源

- [typing — Support for type hints — Python 3.15.1 documentation](https://docs.python.org/3/library/typing.html)

- [PEP 484 – Type Hints](https://peps.python.org/pep-0484/)

- [Pyright docs: Getting Started](https://raw.githubusercontent.com/microsoft/pyright/main/docs/getting-started.md)

- [Pyright docs: Configuration](https://raw.githubusercontent.com/microsoft/pyright/main/docs/configuration.md)

- [Pyright docs: Type Inference](https://raw.githubusercontent.com/microsoft/pyright/main/docs/type-inference.md)

- [Pyright docs: Mypy Comparison](https://raw.githubusercontent.com/microsoft/pyright/main/docs/mypy-comparison.md)

- [Type hints cheat sheet](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html)
