国际访客建议访问 Primers 编程伙伴 国际版站点 > Python 教程 > typing 以获得更好的体验。

# Python 的内置模块 typing

typing 模块提供了对类型提示的运行时支持。

Python 运行时不强制要求类型标注,使用与标注不符的类型仍然可以运行。类型标注可被类型检查器、IDE、语法检查器等第三方工具使用。

# 类型

# typing.Any

特殊类型,表示没有约束的任意类型。

  • 所有类型都与 Any 兼容

  • Any 与所有类型都兼容

# typing.AnyStr

AnyStr 类型可接受 strbytes,但不允许两者混用。

例如:

def func(x: AnyStr, b:AnyStr):
    pass

func("hello", "world")      # 都是 str
func(b"hello", b"world")    # 都是 bytes
func("hello", b"world")     # 错误,str 和 bytes 混用

# typing.LiteralString

仅限字符串字面值的的特殊类型。

  • 任何字符串字面值或其他 LiteralString 都与 LiteralString 兼容

  • 组合 LiteralString 类型的对象产生的字符串也被认为是 LiteralString

  • str 类型的对象不与 LiteralString 兼容

LiteralString 对于会因用户可输入任意字符串而导致问题的敏感 API 很有用。例如,防止 SQL 注入攻击:

def query_student(name: LiteralString):
    sql_query("SELECT * FROM students WHERE name LIKE " + name) # name 必须是字符串字面量,不能是用户输入的 str

# typing.Never 和 typing.NoReturn

表示一个函数绝不会返回,例如 sys.exist

# typing.Self

表示当前闭包内的类。

# typing.TypeAlias

用于显式声明类型别名。

示例:

SQLStr: TypeAlias = LiteralString   # 定义类型别名

def query_student(name: SQLStr):    # 使用类型别名
    pass

# typing.Union

联合类型,Union[X, Y] 等价于 X | Y,表示类型是 XY 中任意一个。

  • 可以联合任意多个类型(至少一个)

Union[Union[int, str], float] == Union[int, str, float]
Union[int] == int
Union[int, str, int] == Union[int, str] == int | str
Union[int, str] == Union[str, int]

# typing.Optional

表示可选类型,Optional[X] 等价于 X | None

# typing.Concatenate

特殊形式,用于注解高阶函数。

例如:

P = ParamSpec('P')  # 用于捕获原始函数的参数类型
T = TypeVar('T')    # 用于捕获原始函数的返回类型
NewArgType = ...    # 新添加参数的类型

def wrap(fn: Callable[Concatenate[NewArgType, P], T]):
    pass

# typing.Literal

表示字面量。

# typing.ClassVar

特殊类型注解构造,用于标注类变量。

  • 类变量只能通过类名操作,不能通过实例操作

例如:

class Cat:
    kingdom: ClassVar[str]  # 类变量 
    name: str               # 实例变量

cat = Cat()
cat.kingdom = "animal"  # 错误,在实例上设置类变量
cat.name = "Tom"        # 正确
TODO:待更新

# 推荐阅读

本文 更新于: 2025-11-27 09:38:00 创建于: 2025-11-27 09:38:00