Python中如何断言变量类型？确认类型后的类型窄化方法

问题场景 #

编程里常遇到这种情况：

if (未初始化) {
    执行初始化
}
使用已初始化的对象

在Python中，假设变量类型是A | B，经过初始化操作后能100%确定它是A，但Pyright这类类型检查器没法自动识别这一点，导致访问A的成员时触发类型错误。比如这段代码：

import random

# 变量类型为 str | None
value: str | None = None if random.random() > 0.5 else "goodbye"

def set_value():
    global value
    value = "hello"

# 初始化后，我们知道value是str，但类型检查器不知情
if value is None:
    set_value()

# Pyright报错：None类型没有capitalize属性
result = value.capitalize()
print(result)

代码运行正常，但类型检查器会提示错误——就像TypeScript里需要用value as string来断言类型一样，Python也有对应的惯用手段。

常用解决方法 #

1. 用typing.cast做静态类型断言 #

cast是专门给类型检查器用的工具，运行时不会做任何类型验证，只是明确告诉检查器“这个变量的类型是X”：

from typing import cast

# 保持前面的代码不变

# 断言value是str类型
result = cast(str, value).capitalize()

这个操作完全不影响代码运行逻辑，只解决类型检查的报错问题。

2. 用assert语句（兼顾运行时校验） #

如果想同时在运行时确保变量不会是None，避免潜在的bug，可以用assert：

# 保持前面的代码不变

# 断言value不是None，类型检查器会自动窄化类型为str
assert value is not None, "value必须被初始化为字符串"
result = value.capitalize()

这样一来，类型检查器会认可value是str；而且如果运行时value意外为None，会直接抛出AssertionError，提前暴露问题。

3. 局部变量重绑定（非全局场景） #

如果变量是局部变量而非全局变量，可以通过重新赋值让类型检查器自动窄化类型：

# 局部变量示例
value: str | None = None if random.random() > 0.5 else "goodbye"

if value is None:
    # 直接赋值，类型检查器会自动识别value现在是str
    value = "hello"

result = value.capitalize()  # 无类型错误

不过这种方法不适用于全局变量，因为类型检查器无法跟踪全局变量的外部修改。

4. 自定义类型守卫（复杂类型场景） #

如果是自定义的A和B类型，可以写一个类型守卫函数，让类型检查器理解你的判断逻辑：

from typing import TypeGuard

class A:
    def a_method(self):
        pass

class B:
    def b_method(self):
        pass

def is_a(obj: A | B) -> TypeGuard[A]:
    return isinstance(obj, A)

# 使用守卫函数
value: A | B = B() if random.random() > 0.5 else A()

if not is_a(value):
    value = A()

# 类型检查器认定value是A，可以安全调用a_method
value.a_method()

总结 #

• 仅需消除类型检查报错：用cast(目标类型, 变量)
• 同时需要运行时校验：用assert 变量 is not None（针对None场景）
• 局部变量优先通过赋值让类型自动窄化

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