Mypy 类型收窄（Type Narrowing）完全指南：从 isinstance 到 TypeGuard 与 TypeIs 的进阶实战

Mypy 类型收窄（Type Narrowing）完全指南：从 isinstance 到 TypeGuard 与 TypeIs 的进阶实战

【免费下载链接】mypyOptional static typing for Python项目地址: https://gitcode.com/GitHub_Trending/my/mypy

类型收窄（Type narrowing）是让类型检查器相信一个宽泛类型实际上更具体的技术——例如把Shape收窄为Square。本文以 mypy 官方文档 type_narrowing.rst 为主线，系统讲解 mypy 支持的四大类收窄手段：内建收窄表达式（isinstance/issubclass/type/callable/None判断）、cast强制转换、PEP 647 的用户自定义TypeGuard，以及 PEP 742 的TypeIs，并深入 mypy 源码揭示其底层实现原理（控制流分析器binder与checker的配合），帮助读者写出类型更安全、更精确的 Python 代码。

什么是类型收窄

类型收窄是指：让类型检查器相信一个更宽泛的类型实际上更加具体。例如，一个类型为Shape的对象，实际上可能是更窄的类型Square。mypy 提供了以下四类类型收窄手段：

• 类型收窄表达式（type narrowing expressions）：基于isinstance、issubclass、type、callable、is not None等内建判断进行收窄；
• 强制转换（casts）：通过typing.cast告诉检查器某个值的类型；
• 用户自定义类型守卫（User-Defined Type Guards，PEP 647）：通过TypeGuard让自定义函数参与条件收窄；
• TypeIs（PEP 742）：通过TypeIs让自定义函数同时在if与else两个分支收窄，行为更接近内建的isinstance。

类型收窄表达式

最简单的收窄方式是使用下列受支持的内建表达式：

• isinstance(obj, float)—— 将obj收窄为float类型；
• issubclass(cls, MyClass)—— 将cls收窄为Type[MyClass]；
• type(obj) is int—— 将obj收窄为int类型；
• callable(obj)—— 将对象收窄为可调用类型；
• obj is not None—— 将对象收窄为其非可选形式。

收窄是上下文相关的

类型收窄是上下文相关的。例如，基于条件的不同，mypy 只会在if分支内部收窄表达式：

def function(arg: object): if isinstance(arg, int): # Type is narrowed within the ``if`` branch only reveal_type(arg) # Revealed type: "builtins.int" elif isinstance(arg, str) or isinstance(arg, bool): # Type is narrowed differently within this ``elif`` branch: reveal_type(arg) # Revealed type: "builtins.str | builtins.bool" # Subsequent narrowing operations will narrow the type further if isinstance(arg, bool): reveal_type(arg) # Revealed type: "builtins.bool" # Back outside of the ``if`` statement, the type isn't narrowed: reveal_type(arg) # Revealed type: "builtins.object"

注意最后一处reveal_type：一旦离开if语句块，类型就恢复为原始声明object，不再保留分支内的收窄结果。

return 与异常：提前退出也参与收窄

mypy 能理解return或抛出异常对类型可能性的影响。如果某个分支提前返回，那么后续代码中该类型就会被排除：

def function(arg: int | str): if isinstance(arg, int): return # `arg` can't be `int` at this point: reveal_type(arg) # Revealed type: "builtins.str"

assert 收窄

我们同样可以用assert在同一上下文中收窄类型：

def function(arg: Any): assert isinstance(arg, int) reveal_type(arg) # Revealed type: "builtins.int"

注意：--warn-unreachable与不可达代码

开启--warn-unreachable后，将类型收窄到某种不可能的状态会被视为错误：

def function(arg: int): # error: Subclass of "int" and "str" cannot exist: # would have incompatible method signatures assert isinstance(arg, str) # error: Statement is unreachable print("so mypy concludes the assert will always trigger")

如果不开启--warn-unreachable，mypy 只会简单地不去检查它判定为不可达的代码：

x: int = 1 assert isinstance(x, str) reveal_type(x) # Revealed type is "builtins.int" print(x + '!') # Typechecks with `mypy`, but fails in runtime.

上面的例子中，assert isinstance(x, str)在int上永远失败，但 mypy 没有报错，只是不再收窄x；print(x + '!')虽然类型检查通过，但在运行时必然失败——这正是"收窄到不可能状态"的典型陷阱。

关于不可达代码的更多细节，可参阅官方文档 unreachable 相关章节（--warn-unreachable的完整行为说明）。

收窄的源码实现：binder 与控制流分析

从源码结构看，mypy 的收窄能力由两大组件协作完成：

• mypy/binder.py 中的ConditionalTypeBinder与Frame类负责记录"在当前代码点，某个表达式（以字面量哈希literal_hash为键）应该具有什么类型"。Frame的类注释明确指出：每个新的作用域或控制流分支都会压入一个新的Frame，赋值与isinstance检查等收窄操作都会更新帧内的类型信息（Frame.types），离开分支弹出帧后类型自然"恢复原状"——这正是文档中"分支内收窄、分支外恢复"现象的实现基础。
• mypy/checker.py 的find_isinstance_check_helper（mypy/checker.py第 6632 行起）负责识别收窄表达式并计算"条件为真 / 条件为假"两张类型映射表（TypeMap）。该函数依次处理：
  • builtins.isinstance：调用conditional_types_with_intersection求交集（第 6642-6651 行）；
  • builtins.issubclass：调用infer_issubclass_maps（第 6652-6656 行）；
  • builtins.callable：调用conditional_callable_type_map（第 6657-6662 行）；
  • builtins.hasattr：调用hasattr_type_maps（第 6663-6668 行）；
  • 其他调用表达式：尝试从可调用类型或RefExpr中提取TypeGuard/TypeIs信息（第 6669-6724 行）。

也就是说，isinstance、issubclass、callable等并非语法层面的魔法，而是 mypy 检查器在 AST 层面对这些内建函数调用做的专门识别与映射。

issubclass：在类型与元类层面的更优推断

mypy 还可以利用issubclass在与类型、元类打交道时做出更好的类型推断：

class MyCalcMeta(type): @classmethod def calc(cls) -> int: ... def f(o: object) -> None: t = type(o) # We must use a variable here reveal_type(t) # Revealed type is "builtins.type" if issubclass(t, MyCalcMeta): # `issubclass(type(o), MyCalcMeta)` won't work reveal_type(t) # Revealed type is "Type[MyCalcMeta]" t.calc() # Okay

这里有两个值得注意的细节：

1. 必须先赋值给变量再调用issubclass：直接写issubclass(type(o), MyCalcMeta)无法触发收窄。原因在于 mypy 只对可绑定（bindable）的表达式（变量、属性访问、索引）做收窄记录——从binder.py中BindableExpression的类型别名（IndexExpr | MemberExpr | NameExpr）可以看出，只有这类表达式才会被存入Frame.types。
2. 收窄目标是Type[MyCalcMeta]：issubclass判断的是"类对象之间的继承关系"，因此收窄后的类型是类类型Type[MyCalcMeta]，从而可以安全地调用元类上的类方法calc()。

mypy 在 test-data/unit/check-isinstance.test 中为issubclass收窄准备了大量用例（如第 1846 行起的Type[Goblin]系列测试），覆盖了TypeVar、多重issubclass链、以及issubclass(cls, (A, B))元组形式等场景。

callable：把联合类型拆成可调用与非可调用两部分

mypy 在类型检查阶段就能判断哪些类型可调用、哪些不可调用，因此它知道callable()的返回值。例如：

from collections.abc import Callable x: Callable[[], int] if callable(x): reveal_type(x) # N: Revealed type is "def () -> builtins.int" else: ... # Will never be executed and will raise error with `--warn-unreachable`

callable函数甚至可以把联合类型拆分为可调用与非可调用两部分：

from collections.abc import Callable x: int | Callable[[], int] if callable(x): reveal_type(x) # N: Revealed type is "def () -> builtins.int" else: reveal_type(x) # N: Revealed type is "builtins.int"

从源码看，这一行为由checker.py中的conditional_callable_type_map（mypy/checker.py第 6455 行起）实现：它调用partition_by_callable将当前类型按可调用性分区，若两部分都存在则分别生成if与else的类型映射；若类型全部可调用，则else分支映射为UninhabitedType（不可达类型），这正是上述示例中--warn-unreachable会报错的根源。

Casts：只影响类型检查的"提示"

mypy 支持类型强制转换（cast），通常用于把一个静态类型值强转为它的子类型。与 Java、C# 等语言不同，mypy 的 cast只作为类型检查器的提示，不会在运行时执行任何类型检查。使用typing.cast进行转换：

from typing import cast o: object = [1] x = cast(list[int], o) # OK y = cast(list[str], o) # OK (cast performs no actual runtime check)

为什么要设计成这样？若要支持cast(list[str], o)这样的运行时检查，就必须检查列表中所有元素的类型，对于大型列表来说代价极高。因此 cast 的定位是：

• 消除误报：压制类型检查器给出的虚假警告；
• 辅助推断：在类型检查器无法完全理解代码意图时提供一点帮助。

注意：需要运行时检查时请使用断言

def foo(o: object) -> None: print(o + 5) # Error: can't add 'object' and 'int' assert isinstance(o, int) print(o + 5) # OK: type of 'o' is 'int' here

assert isinstance(...)既收窄了类型（通过前面介绍的 assert 收窄机制），又在运行时真正执行检查，是"运行时安全 + 类型精确"两全的做法。

与 Any 的交互

• 类型为Any的表达式不需要cast；
• 赋给类型为Any的变量也不需要cast；
• 你也可以把Any作为 cast 的目标类型——这样就能对结果执行任意操作：

from typing import cast, Any x = 1 x.whatever() # Type check error y = cast(Any, x) y.whatever() # Type check OK (runtime error)

上面的y.whatever()虽然类型检查通过，但运行时必然抛AttributeError——cast 到Any是把"类型安全"完全交给开发者的一种逃生舱，应谨慎使用。

User-Defined Type Guards：用户自定义类型守卫（PEP 647）

mypy 支持 PEP 647 定义的User-Defined Type Guards。

类型守卫（type guard）是程序基于运行时检查、影响类型检查器条件收窄行为的一种机制。本质上，TypeGuard是bool类型的一个"智能别名"。

先看一个普通bool返回函数的例子：

def is_str_list(val: list[object]) -> bool: """Determines whether all objects in the list are strings""" return all(isinstance(x, str) for x in val) def func1(val: list[object]) -> None: if is_str_list(val): reveal_type(val) # Reveals list[object] print(" ".join(val)) # Error: incompatible type

返回bool时，mypy无法从is_str_list的返回值推断出任何类型信息，val仍是list[object]，" ".join(val)报错。

同样的例子改用TypeGuard：

from typing import TypeGuard def is_str_list(val: list[object]) -> TypeGuard[list[str]]: """Determines whether all objects in the list are strings""" return all(isinstance(x, str) for x in val) def func1(val: list[object]) -> None: if is_str_list(val): reveal_type(val) # list[str] print(" ".join(val)) # ok

工作原理：TypeGuard把函数的第一个参数（这里是val）收窄为第一个类型参数（这里是list[str]）指定的类型。

注意：收窄不是严格的（non-strict narrowing）

PEP 647 并不强制"严格收窄"。例如，你可以把str收窄为int：

def f(value: str) -> TypeGuard[int]: return True

由于不强制严格收窄，很容易破坏类型安全。不过 mypy 文档同时指出：破坏类型安全的方式其实很多（最常见的是 cast 和Any）；如果一个 Python 开发者愿意花时间学习并实现用户自定义类型守卫，可以合理假定他们关心类型安全，不会写出破坏类型安全或产生荒谬结果的守卫函数。

泛型 TypeGuard

TypeGuard可以与泛型类型一起使用（Python 3.12 语法）：

from typing import TypeGuard # use `typing_extensions` for `python<3.10` def is_two_element_tupleT -> TypeGuard[tuple[T, T]]: return len(val) == 2 def func(names: tuple[str, ...]): if is_two_element_tuple(names): reveal_type(names) # tuple[str, str] else: reveal_type(names) # tuple[str, ...]

注意这里的类型变量T在收窄时会被绑定：当传入tuple[str, ...]时，TypeGuard[tuple[T, T]]实例化为tuple[str, str]。

带额外参数的 TypeGuard

类型守卫函数可以接收额外参数（Python 3.12 语法）：

from typing import TypeGuard # use `typing_extensions` for `python<3.10` def is_set_ofT -> TypeGuard[set[T]]: return all(isinstance(x, type) for x in val) items: set[Any] if is_set_of(items, str): reveal_type(items) # set[str]

收窄仍然只作用于第一个参数（val），额外参数（type）只参与泛型实例化，不影响收窄目标的选择。

方法作为 TypeGuard

方法同样可以作为TypeGuard使用：

class StrValidator: def is_valid(self, instance: object) -> TypeGuard[str]: return isinstance(instance, str) def func(to_validate: object) -> None: if StrValidator().is_valid(to_validate): reveal_type(to_validate) # Revealed type is "builtins.str"

注意：TypeGuard不会收窄self/cls隐式参数

PEP 647 规定TypeGuard不会收窄self或cls隐式参数的类型。如果确实需要收窄self/cls，可以把该值作为显式参数传给类型守卫函数：

class Parent: def method(self) -> None: reveal_type(self) # Revealed type is "Parent" if is_child(self): reveal_type(self) # Revealed type is "Child" class Child(Parent): ... def is_child(instance: Parent) -> TypeGuard[Child]: return isinstance(instance, Child)

在这里self被当作显式实参传入is_child，因此可以被收窄为Child。

赋值表达式作为 TypeGuard

有时你可能想"创建新变量"与"把它收窄到某个具体类型"同时完成。这可以通过TypeGuard与海象运算符:=（赋值表达式）组合实现：

from typing import TypeGuard # use `typing_extensions` for `python<3.10` def is_float(a: object) -> TypeGuard[float]: return isinstance(a, float) def main(a: object) -> None: if is_float(x := a): reveal_type(x) # N: Revealed type is 'builtins.float' reveal_type(a) # N: Revealed type is 'builtins.object' reveal_type(x) # N: Revealed type is 'builtins.object' reveal_type(a) # N: Revealed type is 'builtins.object'

这里发生了什么？

1. 创建新变量x，并把a的值赋给它；
2. 对x执行is_float()类型守卫；
3. 在if上下文中把x收窄为float，不影响a。

注意：同样的写法对isinstance(x := a, float)同样有效。

从源码实现看，checker.py的find_isinstance_check_helper中对AssignmentExpr（第 6727-6739 行）的处理，正是分别对node.target与node.value递归查找收窄检查，再把两张映射合并——海象表达式场景由此得到支持。

TypeIs：更精确的双分支收窄（PEP 742）

mypy 支持 PEP 742 定义的TypeIs。

TypeIs收窄函数允许你定义自定义类型检查，它可以像内建isinstance()一样，在条件判断的if与else两个分支中同时收窄变量的类型。TypeIs是 Python 3.13 新增的——在旧版 Python 中请使用typing_extensions提供的反向移植（backport）版本。

看一个使用TypeIs的完整示例：

from typing import TypeIs def is_str(x: object) -> TypeIs[str]: return isinstance(x, str) def process(x: int | str) -> None: if is_str(x): reveal_type(x) # Revealed type is 'str' print(x.upper()) # Valid: x is str else: reveal_type(x) # Revealed type is 'int' print(x + 1) # Valid: x is int

在这个例子中，is_str是一个返回TypeIs[str]的收窄函数：在if分支中x被收窄为str，在else分支中x被收窄为int——两个分支都收窄了，这正是与TypeGuard最核心的差异。

关键要点：

• 函数必须至少接受一个位置参数；
• 返回类型标注为TypeIs[T]，其中T是希望收窄到的类型；
• 函数必须返回bool值；
• 在if分支（函数返回True时），参数类型被收窄为其原始类型与T的交集；
• 在else分支（函数返回False时），参数类型被收窄为其原始类型与T的补集的交集。

TypeIs vs TypeGuard

两者都允许定义自定义类型收窄函数，但在关键行为上存在重要差异：

下面是用TypeGuard重写同一逻辑的对比示例：

from typing import TypeGuard, reveal_type def is_str(x: object) -> TypeGuard[str]: return isinstance(x, str) def process(x: int | str) -> None: if is_str(x): reveal_type(x) # Revealed type is "builtins.str" print(x.upper()) # ok: x is str else: reveal_type(x) # Revealed type is "Union[builtins.int, builtins.str]" print(x + 1) # ERROR: Unsupported operand types for + ("str" and "int") [operator]

注意else分支的差别：TypeGuard下x仍保持int | str，因此print(x + 1)会报operator错误；而TypeIs下else分支的x已是int，可以直接做加法运算。

泛型 TypeIs

TypeIs函数同样可以配合泛型类型使用：

from typing import TypeVar, TypeIs T = TypeVar('T') def is_two_element_tuple(val: tuple[T, ...]) -> TypeIs[tuple[T, T]]: return len(val) == 2 def process(names: tuple[str, ...]) -> None: if is_two_element_tuple(names): reveal_type(names) # Revealed type is 'tuple[str, str]' else: reveal_type(names) # Revealed type is 'tuple[str, ...]'

带额外参数的 TypeIs

TypeIs函数可以接受除第一个参数之外的额外参数，类型收窄只作用于第一个参数：

from typing import Any, TypeVar, reveal_type, TypeIs T = TypeVar('T') def is_instance_of(val: Any, typ: type[T]) -> TypeIs[T]: return isinstance(val, typ) def process(x: Any) -> None: if is_instance_of(x, int): reveal_type(x) # Revealed type is 'int' print(x + 1) # ok else: reveal_type(x) # Revealed type is 'Any'

方法中的 TypeIs

方法同样可以作为TypeIs函数。注意：在实例方法或类方法中，类型收窄作用于第二个参数（即self/cls之后的那个参数）：

class Validator: def is_valid(self, instance: object) -> TypeIs[str]: return isinstance(instance, str) def process(self, to_validate: object) -> None: if Validator().is_valid(to_validate): reveal_type(to_validate) # Revealed type is 'str' print(to_validate.upper()) # ok: to_validate is str

这与TypeGuard方法示例形成对照：TypeGuard方法收窄的也是self之后的第一个显式参数（instance），只是TypeGuard明确不作用于self/cls本身。

赋值表达式与 TypeIs

你也可以把海象运算符:=与TypeIs组合使用，在创建新变量的同时收窄其类型：

from typing import TypeIs, reveal_type def is_float(x: object) -> TypeIs[float]: return isinstance(x, float) def main(a: object) -> None: if is_float(x := a): reveal_type(x) # Revealed type is 'float' # x is narrowed to float in this block print(x + 1.0)

TypeIs / TypeGuard 的源码级实现

从 mypy 源码看，TypeGuard与TypeIs的差别被编码在类型系统的两个字段上：

• mypy/types.py 中CallableType定义了type_guard与type_is两个属性（第 2178-2244 行），注释明确写着："type_guard：T，若 ->TypeGuard[T]（此时ret_type是bool）；type_is：T，若 ->TypeIs[T]（此时ret_type是bool）"。二者与ret_type并存，表示函数表面返回bool、实际携带收窄目标类型。
• mypy/types.py 第 480 行定义了专门的TypeGuardedType包装类型，用于在类型映射中标记"被TypeGuard收窄的目标"。
• mypy/nodes.py 的RefExpr（第 2406-2430 行）同样缓存了type_guard与type_is字段，使函数引用的收窄信息可以在 AST 层直接读取。
• mypy/checker.py 第 6669-6724 行的关键分支展示了两者的行为分叉：当检查到TypeGuard时，直接返回{expr: TypeGuardedType(type_guard)}（"总是正确"，即使类型不重叠也照单全收——对应 PEP 647 的非严格收窄）；当检查到TypeIs时，则走conditional_types_with_intersection求交集（consider_runtime_isinstance=False），产生if/else两张映射——这正是TypeIs能在else分支也收窄的机制来源。

局限性：mypy 不做跨符号关系追踪

mypy 的分析局限于单个符号（symbol），不会追踪符号之间的关系。例如下面的代码，人类很容易推断出"如果a是None，那么b必然不是None，因此a or b永远是C的实例"，但 mypy 做不到：

class C: pass def f(a: C | None, b: C | None) -> C: if a is not None or b is not None: return a or b # Incompatible return value type (got "C | None", expected "C") return C()

在类型检查器中追踪这种跨变量条件会带来显著的复杂性与性能开销（从binder.py的Frame设计可以看出，mypy 按帧存储的是"表达式 → 类型"的单向映射，天然不维护变量之间的约束关系）。

三个绕行方案

面对这种场景，可以用以下任一方式绕过：

1. 用assert说服类型检查器；
2. 用cast覆盖推断（见上文 Casts 一节）；
3. 把函数重写得稍显冗长，让每个变量单独收窄：

def f(a: C | None, b: C | None) -> C: if a is not None: return a elif b is not None: return b return C()

总结：如何选择收窄手段

值得强调的是，TypeGuard与TypeIs都属于"程序主动影响类型检查器"的高级手段，使用它们意味着你承担了保证守卫函数正确性的责任——就像 PEP 647 文档中所说，破坏类型安全的方式（cast、Any）始终存在，守卫函数的价值恰恰建立在使用者对类型安全的重视之上。

延伸阅读

• 类型收窄的完整官方说明见 docs/source/type_narrowing.rst；
• 收窄相关的大规模回归测试见 test-data/unit/check-isinstance.test（isinstance、issubclass、callable、TypeGuard等用例）与 test-data/unit/check-typeguard.test；
• --warn-unreachable的完整语义见 docs/source/command_line.rst 与 docs/source/common_issues.rst；
• 严格可选类型（strict optional，即obj is not None收窄到非可选形式）的背景见 docs/source/kinds_of_types.rst。

【免费下载链接】mypyOptional static typing for Python项目地址: https://gitcode.com/GitHub_Trending/my/mypy