如何让静态类型检查器识别自定义类型检查函数的类型断言？

我定义了联合类型和类型检查函数，代码如下：

from typing import TypeAlias
from datetime import datetime
import re

ExprType: TypeAlias = int | str | datetime

def check_type(value: ExprType, expected_type: type[ExprType]):
    if not isinstance(value, expected_type):
        raise TypeError(f"Expected {expected_type}, but got {type(value)}.")

value: ExprType = 0

# ... 其他处理逻辑 ...

text_var = "123"
if m := re.match("(\d+)", text_var):
    check_type(value, int)
    value += int(m.group(1))  # Pylance报错：Operator + is not supported for types ExprType and int.

尽管通过check_type已经确保value是int类型，但Pylance无法识别该函数的类型验证作用，依然将value视为ExprType（int | str | datetime），因此触发运算符不支持的错误。

类似下面的场景中，Pylance能自动识别条件判断后的类型窄化：

my_var: int | None = 5       # 初始类型为int | None

if my_var:                   # 条件判断后，分支内my_var类型自动窄化为int
    print("I'm not None")    
else:
    print("I'm None")        # 分支内my_var类型为NoneType

我需要让Pylance识别check_type函数也能实现同样的类型窄化效果。

方法1：用assert isinstance直接验证 #

直接替换自定义函数，使用assert isinstance做类型检查，Pylance原生支持识别这种写法的类型窄化：

if m := re.match("(\d+)", text_var):
    assert isinstance(value, int), f"Expected int, but got {type(value)}."
    value += int(m.group(1))  # 此时Pylance会自动将value类型窄化为int，不再报错

方法2：给check_type添加TypeGuard类型注解 #

如果要保留自定义的check_type函数，可以通过TypeGuard（Python 3.10+内置，旧版本需从typing_extensions导入）标记函数的类型验证能力：

from typing import TypeAlias, TypeGuard
from datetime import datetime
import re

ExprType: TypeAlias = int | str | datetime

def check_type[T](value: ExprType, expected_type: type[T]) -> TypeGuard[T]:
    if not isinstance(value, expected_type):
        raise TypeError(f"Expected {expected_type}, but got {type(value)}.")
    return True

value: ExprType = 0

text_var = "123"
if m := re.match("(\d+)", text_var):
    check_type(value, int)
    value += int(m.group(1))  # Pylance现在能识别value已被验证为int类型

TypeGuard[T]会告诉类型检查器：只要函数正常执行（未抛出异常且返回True），value的类型就为T（即传入的expected_type对应的类型）。

方法3：使用cast强制类型转换（不推荐） #

如果上述方法都不适用，可以用cast强制指定类型，但这种方式是绕过类型检查器，安全性较低，仅作为临时方案：

from typing import TypeAlias, cast
from datetime import datetime
import re

ExprType: TypeAlias = int | str | datetime

def check_type(value: ExprType, expected_type: type[ExprType]):
    if not isinstance(value, expected_type):
        raise TypeError(f"Expected {expected_type}, but got {type(value)}.")

value: ExprType = 0

text_var = "123"
if m := re.match("(\d+)", text_var):
    check_type(value, int)
    value = cast(int, value)
    value += int(m.group(1))  # 强制指定类型后不再报错

内容的提问来源于stack exchange，提问作者peter.slizik