Python typing 模块【全面指南】与【类型注解】一文详解!

Python typing 模块全面指南与类型注解详解

前言

Python 的 typing 模块是现代 Python 开发（尤其是大型项目）中不可或缺的神器。它能极大地提高代码的可读性，并配合 IDE（如 VS Code、PyCharm）和静态类型检查工具（如 mypy）进行类型检查，减少运行时 Bug。

以下内容整理了所有类型注解补全，并额外补充了其他高频常用类型，分为四大类进行详细说明，帮助你一次性全面掌握。

导入部分（已补全常用类型）

from typing import (

TYPE_CHECKING,

Literal,

Optional,

Callable,

Generator,

Dict,

List, # 补充：列表

Tuple, # 补充：元组

Set, # 补充：集合

Any,

Awaitable,

Union,

Iterable, # 补充：可迭代对象

Iterator, # 补充：迭代器

Sequence, # 补充：序列（更宽泛的列表/元组/字符串）

TypeVar, # 补充：泛型变量

Protocol, # 补充：协议（结构化类型/鸭子类型）

TypedDict, # 补充：类型化字典（固定键）

Final, # 补充：最终变量（不可重新赋值）

Annotated, # 补充：带元数据的类型（Python 3.9+）

cast, # 补充：类型转换工具（运行时不检查）

overload, # 补充：函数重载

)

注意：Python 3.9+ 后，内置容器（如 list, dict, tuple, set）可以直接小写使用，无需从 typing 导入。但为了兼容旧版本和统一风格，很多项目仍从 typing 导入。

第一类：基础容器与数据结构 (Basic Containers)

1. Dict[K, V]、List[T]、Tuple[... ]、Set[T]

用法：泛型容器，指定内部元素的类型。

场景：明确数据结构的内容，提高可读性和检查严谨性。

from typing import Dict, List, Tuple, Set

user_info: Dict[str, int] = {"age": 18, "id": 1001}

scores: List[float] = [98.5, 88.0, 100.0]

point: Tuple[int, int, int] = (10, 20, 30) # 定长定类型

flexible_tuple: Tuple[int, ...] = (1, 2, 3, 4) # 变长同类型（Python 3.11+ 更优雅）

unique_ids: Set[str] = {"id1", "id2"}

2. Any

用法：表示任意类型，类型检查器对此变量完全放行。

注意：慎用！相当于关闭类型检查，失去 typing 的意义。

from typing import Any

def print_anything(data: Any) -> None:

print(data) # 可以传任何类型

3. Sequence[T]（补充）

含义：比 List 更宽泛，包括 list、tuple、str、bytes 等所有支持索引、len()、切片的序列。

优势：函数参数更通用，兼容性更好。

from typing import Sequence

def print_reverse(seq: Sequence[int]) -> None:

print(seq[::-1]) # 接受 list、tuple、range 等

第二类：逻辑控制与组合 (Logic & Composition)

4. Union[A, B, ...]

含义：联合类型，“A 或 B 或 …”。

新语法（Python 3.10+）：直接用 A | B。

from typing import Union

def get_user(user_id: Union[int, str]) -> None: ...

# 等价于 Python 3.10+

# def get_user(user_id: int | str) -> None: ...

5. Optional[T]

含义：等价于 T | None，表示可以为 None。

常见场景：函数参数默认值为 None。

from typing import Optional

def greet(name: Optional[str] = None) -> None:

print(f"Hello, {name or 'Guest'}")

6. Literal['a', 'b', 42]

含义：字面量类型，变量值必须是指定的常量之一。

场景：模式选择、状态码、配置开关，非常适合代替枚举的轻量场景。

from typing import Literal

FileMode = Literal['r', 'w', 'a', 'rb']

def open_file(mode: FileMode) -> None: ...

第三类：函数、生成器与异步 (Functions & Async)

7. Callable[[Arg1, Arg2, ...], ReturnType]

含义：表示一个可调用对象（函数、lambda、类实例带 call）。

用法：常用于回调函数参数。

from typing import Callable

def calculate(a: int, b: int, op: Callable[[int, int], int]) -> int:

return op(a, b)

calculate(3, 4, lambda x, y: x * y)

8. Generator[YieldType, SendType, ReturnType]

含义：标注 yield 生成器的三种类型。

YieldType：yield 出的值类型（最常用）。

SendType：通过 .send() 传入的值类型（常用 None）。

ReturnType：生成器结束时的返回值（通常 None）。

from typing import Generator

def count_down(n: int) -> Generator[int, None, None]:

while n > 0:

yield n

n -= 1

9. Iterable[T] 与 Iterator[T]（补充）

Iterable：可被 for 循环遍历的对象。

Iterator：支持 next() 的对象（通常是 Iterable 的迭代器）。

建议：参数只需遍历时用 Iterable 更宽松。

from typing import Iterable

def process_items(items: Iterable[str]) -> None:

for item in items:

print(item)

10. Awaitable[T]

含义：可以被 await 的对象（通常是协程）。

场景：高级异步框架中传递任务。

from typing import Awaitable

async def run_task(task: Awaitable[int]) -> None:

result = await task

print(result)

第四类：特殊工具与高级用法 (Special Tools)

11. TYPE_CHECKING

含义：运行时为 False，类型检查时为 True。

核心用途：解决循环导入问题，只在静态检查时导入类。

from typing import TYPE_CHECKING

if TYPE_CHECKING:

from .models import User # 只在 mypy 检查时导入

def process_user(user: "User") -> None: ... # 字符串引用避免运行时导入

12. TypeVar、Generic（补充泛型）

用途：实现类型一致的泛型函数/类。

from typing import TypeVar, List

T = TypeVar('T')

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

return items[0]

# 调用时自动推断：first_item([1, 2]) -> int

13. Final[T]（补充）

含义：标记变量/属性不可重新赋值（类型检查器会报错）。

from typing import Final

API_KEY: Final[str] = "abc123"

# API_KEY = "new" # mypy 会报错

14. Annotated[T, ...]（补充，Python 3.9+）

含义：为类型附加元数据，常用于第三方库（如 pydantic、fastapi）的验证。

from typing import Annotated

PositiveInt = Annotated[int, lambda x: x > 0]

def set_age(age: PositiveInt) -> None: ...

15. TypedDict（补充）

含义：为字典指定固定键和对应类型（结构化 dict）。

from typing import TypedDict

class Movie(TypedDict):

title: str

year: int

movie: Movie = {"title": "Inception", "year": 2010}

总结速查表 (Cheatsheet)

类型注解

简单解释

典型场景

Dict[K, V]

字典，指定键值类型

配置、JSON 数据

List[T]

列表

集合数据

Tuple[A, B, ...]

定长元组

坐标、固定字段

Set[T]

集合

去重 ID

Sequence[T]

通用序列（list/tuple/str 等）

参数只需索引访问

Any

任意类型（慎用）

动态数据、第三方库回调

Union[A, B] 或 A | B

多选一

ID 可为 int 或 str

Optional[T]

T 或 None

可选参数、可能缺失字段

Literal['a', 42]

固定字面值

模式、状态码

Callable[[...], R]

函数/回调

高阶函数、策略模式

Generator[Y, S, R]

生成器

yield 迭代器

Iterable[T]

可遍历对象

for 循环参数

Awaitable[T]

可 await 的协程

异步任务调度

TYPE_CHECKING

类型检查开关

解决循环导入

TypeVar('T')

泛型占位符

通用函数/类

Final[T]

不可变常量

配置常量、魔法值

Annotated[T, ...]

带元数据类型

验证、依赖注入

TypedDict

固定键类型的字典

API 返回结构、配置

！