1. 概述#

Python 的 typing 模块是用于类型提示（Type Hints）的标准库，自 Python 3.5 起引入。它不会在运行时强制类型检查，但可以配合工具（如 mypy、IDE 等）提升代码可读性、健壮性和开发效率。

从 Python 3.9 开始，标准库对内置容器类型（如 list、dict、set、tuple 等）进行了增强，使其原生支持泛型语法（即可以直接写成 dict[str, int] 这样的形式），而不再需要从 typing 模块导入对应的 Dict、List、Set、Tuple 等。

2. 快速查阅#

推荐语法	是否可直接用内置名？	替代方案（新语法）	说明
容器类型（Collections）
`list[T]`	✅ 是（≥3.9）	无	内置泛型，无需导入 `typing.List`
`dict[K, V]`	✅ 是（≥3.9）	无	内置泛型，替代 `typing.Dict`
`set[T]`	✅ 是（≥3.9）	无	内置泛型，替代 `typing.Set`
`tuple[T, ...]` 或 `tuple[A, B, C]`	✅ 是（≥3.9）	无	内置泛型，替代 `typing.Tuple`
`frozenset[T]`	✅ 是（≥3.9）	无	内置泛型
联合与可选类型
`T \| None`	✅ 是（≥3.10）	—	推荐替代 `Optional[T]`
`Optional[T]`	❌ 否	`T \| None`	Python 3.10+ 起建议用 `
`A \| B`	✅ 是（≥3.10）	—	推荐替代 `Union[A, B]`
`Union[A, B, C]`	❌ 否	`A \| B \| C`	旧写法，兼容性好但冗长
通用类型
`Any`	❌ 否	无	表示任意类型，需 `from typing import Any`
`Callable[[A, B], R]`	❌ 否	无	描述函数签名，仍需从 `typing` 导入
泛型与类型变量
`TypeVar('T')`	❌ 否	无	需 `from typing import TypeVar`，用于泛型函数/类
`Generic[T]`	❌ 否	无	需 `from typing import Generic`（但 `typing.Generic` 在 ≥3.9 可配合内置泛型使用）
字面量与结构化类型
`Literal['read', 'write']`	❌ 否	无	需 `from typing import Literal`（或 `typing_extensions` for <3.8）
`TypedDict`	❌ 否	无	需 `from typing import TypedDict`，用于带键类型约束的字典
新类型与协议
`NewType('UserId', int)`	❌ 否	无	需 `from typing import NewType`，创建语义不同的类型别名
`Protocol`	❌ 否	无	需 `from typing import Protocol`（≥3.8），用于结构子类型（鸭子类型）
其他
`Iterable[T]`, `Iterator[T]` 等	❌ 否	无	抽象基类（如 `collections.abc` 中的类型）仍需从 `typing` 导入（尽管部分在 ≥3.9 可用 `collections.abc` 直接泛型化，但 `typing` 版本更常用）

2.1. 基本容器类型#

用于标注列表、字典、元组等容器中元素的类型。

1
from typing import List, Dict, Tuple, Set
2

3
# 列表：元素必须是 int
4
def process_numbers(nums: List[int]) -> None:
5
    for n in nums:
6
        print(n)
7

8
# 字典：键为 str，值为 int
9
scores: Dict[str, int] = {"Alice": 95, "Bob": 87}
10

11
# 元组：固定长度和类型
12
point: Tuple[float, float] = (3.14, 2.71)
13

14
# 集合
15
unique_ids: Set[int] = {1, 2, 3}

⚠️ 注意：从 Python 3.9+ 开始，可以直接使用内置类型如 list[int]，无需导入 List。

2.2. Optional（可选类型）#

表示“可能是某类型，也可能是 None”。

1
from typing import Optional
2

3
def find_user(user_id: int) -> Optional[str]:
4
    if user_id == 1:
5
        return "Alice"
6
    return None  # 可返回 None

等价于 Union[str, None]。

2.3. Union（联合类型）#

表示“可以是多种类型之一”。

1
from typing import Union
2

3
def parse_value(value: Union[int, str]) -> str:
4
    return str(value)
5

6
# Python 3.10+ 可简写为 value: int | str

2.4. Any（任意类型）#

关闭类型检查，适用于不确定类型的场景（不推荐滥用）。

1
from typing import Any
2

3
def log_anything(data: Any) -> None:
4
    print("Received:", data)

2.5. Callable（函数类型）#

用于标注接受或返回函数的参数/返回值。

1
from typing import Callable
2

3
def apply_operation(x: int, func: Callable[[int], int]) -> int:
4
    return func(x)
5

6
double = lambda n: n * 2
7
print(apply_operation(5, double))  # 输出 10

2.6. TypeVar（泛型）#

定义泛型函数或类，保持类型一致性。

1
from typing import TypeVar
2

3
T = TypeVar('T')
4

5
def first_element(items: List[T]) -> T:
6
    return items[0]
7

8
# 推断出返回类型与输入列表元素类型一致
9
names: List[str] = ["Alice", "Bob"]
10
first: str = first_element(names)

2.7. Literal（字面量类型）#

限制变量只能取特定值。

1
from typing import Literal
2

3
FileMode = Literal['r', 'w', 'a', 'rb']
4
def open_file(mode: FileMode) -> None: ...

2.8. NewType（创建新类型）#

创建语义上不同的类型（即使底层相同），增强类型安全。

1
from typing import NewType
2

3
UserId = NewType('UserId', int)
4
BookId = NewType('BookId', int)
5

6
def get_user(user_id: UserId) -> str:
7
    return f"User {user_id}"
8

9
uid = UserId(123)
10
bid = BookId(456)
11

12
get_user(uid)   # ✅ 正确
13
get_user(bid)   # ❌ 类型检查器会报错（虽然运行时是 int）

2.9. TypedDict（结构化字典）#

为字典指定每个键的类型（类似接口）。

1
from typing import TypedDict
2

3
class Person(TypedDict):
4
    name: str
5
    age: int
6
    email: str
7

8
p: Person = {"name": "Alice", "age": 30, "email": "alice@example.com"}

音乐

音乐

1. 概述#

2. 快速查阅#

2.1. 基本容器类型#

2.2. Optional（可选类型）#

2.3. Union（联合类型）#

2.4. Any（任意类型）#

2.5. Callable（函数类型）#

2.6. TypeVar（泛型）#

2.7. Literal（字面量类型）#

2.8. NewType（创建新类型）#

2.9. TypedDict（结构化字典）#

支持与分享

音乐

目录

音乐

音乐

Typing 模块

1. 概述#

2. 快速查阅#

2.1. 基本容器类型#

2.2. Optional（可选类型）#

2.3. Union（联合类型）#

2.4. Any（任意类型）#

2.5. Callable（函数类型）#

2.6. TypeVar（泛型）#

2.7. Literal（字面量类型）#

2.8. NewType（创建新类型）#

2.9. TypedDict（结构化字典）#

支持与分享

音乐

目录