Python类型提示如何实现自定义函数的isinstance式类型收窄

可以，通过TypeGuard类型标注就能实现和isinstance完全一致的分支类型收窄效果。

isinstance之所以能触发类型解释器的自动类型推断，本质是它是Python类型系统内置识别的原生类型守卫：当判断结果为True时，类型解释器会自动将被判断的变量收窄到指定类型。自定义校验函数只要通过TypeGuard显式声明函数返回True时对应的参数类型，就能让类型解释器获得完全一致的推断能力。

具体实现 #

Python 3.10+ 版本 #

TypeGuard在Python 3.10正式纳入标准库typing模块，直接导入即可使用，修改示例代码如下：

from typing import Any, TypeGuard

def is_positive_int(value: Any) -> TypeGuard[int]:
    return isinstance(value, int) and value >= 0

if is_positive_int(value):
    value += 1  # 此处类型解释器可正确识别value为int类型，不会报类型错误

Python 3.9 适配 #

Python 3.9标准库的typing模块尚未内置TypeGuard，可以安装官方兼容包typing_extensions后使用，语法和3.10+完全一致：

from typing import Any
# 先执行 pip install typing_extensions 安装依赖
from typing_extensions import TypeGuard

def is_positive_int(value: Any) -> TypeGuard[int]:
    return isinstance(value, int) and value >= 0

目前mypy、Pyright（VS Code Pylance扩展的底层类型检查器）等所有主流Python类型检查工具都完整支持TypeGuard语法，不需要额外配置。

注意事项 #

• TypeGuard本质是开发者向类型解释器做出的类型承诺：当函数返回True时，传入的第一个位置参数一定符合TypeGuard中声明的类型。类型解释器不会逐行校验函数内部的逻辑是否真的满足这个承诺，你需要自行保证校验逻辑的正确性，否则可能出现类型提示正常但运行时报错的问题。
• TypeGuard支持任意复杂度的类型收窄场景，除了int、str这类基础类型，也可以用来判断TypedDict结构、泛型容器类型、联合类型中的特定成员等，用法和基础类型没有区别。

内容的提问来源于stack exchange，提问作者Severin