Python 库手册：typing 类型注解模块

Python 的 typing 模块提供了类型提示（Type Hinting）的支持，允许开发者在代码中使用静态类型标注。它是可选的类型检查机制，目的是提高代码的可读性、可维护性，并借助静态分析工具（如 mypy、pyright）在运行前发现潜在错误。

虽然 Python 是动态类型语言，typing 提供了一种轻量方式将静态类型特性引入代码开发过程，特别适用于大型项目或多人协作。

常见应用场景：

（1）编写清晰、可维护的函数接口和类定义。

（2）借助 IDE 自动补全、跳转与类型检查。

（3）为第三方库或老代码添加类型注释。

（4）配合 mypy、pyright 等工具进行静态分析。

◆ ◆ ◆

核心概念

1、类型提示工具箱

typing 提供一整套类型注解构造器，用于为函数参数、返回值、变量等添加类型提示。

2、支持泛型编程

通过 Generic、TypeVar 实现通用类型设计，增强类型灵活性与重用性。

3、支持嵌套和组合

类型构造器可嵌套使用，如 List[Dict[str, Tuple[int, int]]]。

4、静态类型检查而非运行约束

类型提示不会影响程序运行，主要供编辑器、IDE 和类型检查工具（如 mypy）使用。

◆ ◆ ◆

应用举例

例 1：使用 Union 与 Optional

from typing import Union, Optional

def parse_age(value: Union[str, int]) -> Optional[int]:
    try:
        return int(value)
    except ValueError:
        return None

例 2：定义泛型函数

from typing import TypeVar, List

T = TypeVar('T')

def first_item(items: List[T]) -> T:
    return items[0]

例 3：使用 Callable 表示函数类型

from typing import Callable

def execute_twice(func: Callable[[int], int], x: int) -> int:
    return func(func(x))

例 4：使用 TypedDict 表示结构化字典

from typing import TypedDict

class User(TypedDict):
    name: str
    age: int

def get_user_info() -> User:
    return {"name": "Alice", "age": 30}

例 5：使用 Final 定义不可变常量

from typing import Final

PI: Final = 3.14159
# PI = 3.15  # mypy 或 pyright 将报错

◆ ◆ ◆

常用类型与工具

Any

任意类型，跳过类型检查。

Callable

可调用对象（如函数）。

Dict[K, V]

键值对字典。

Final

声明不可被重定义的变量。

Iterable[T] / Iterator[T]

可迭代对象 / 迭代器。

List[T]

列表。

Literal

精确值限制，如 Literal["a", "b"]。

Optional[T]

可为 T 或 None，即 Union[T, None]。

Tuple[...]

元组类型，支持固定长度与可变长度。

TypedDict

类型明确的字典结构（类似数据类）。

Union[T1, T2, ...]

联合类型，可为其中任一类型。

TypeVar

泛型类型变量。

Protocol

结构子类型（鸭子类型）定义接口。

NoReturn

表示永远不会返回（如死循环或抛异常）。

函数类型注解语法示例：

from typing import List, Dict, Optional, Union

def greet(name: str, age: Optional[int] = None) -> str:
    if age:
        return f"Hello, {name}, age {age}"
    return f"Hello, {name}"

def sum_list(numbers: List[int]) -> int:
    return sum(numbers)

def get_config() -> Dict[str, Union[str, int]]:
    return {"version": 1, "mode": "debug"}

◆ ◆ ◆

补充说明

1、Python 3.9+ 原生支持 list[int], dict[str, int] 等简洁语法，推荐优先使用。

2、Python 3.10+ 引入 X | Y 表示联合类型，等价于 Union[X, Y]。

3、使用 typing.get_type_hints() 可在运行时获取类型注解。

4、类型提示不会影响程序运行，但可极大提升 IDE 智能补全与静态检查能力。

5、推荐结合 mypy 工具进行项目级别的类型检查。

“点赞有美意，赞赏是鼓励”