Python类型提示（通过PEP 484在Python 3.5中引入，在后续版本中大幅扩展）已从可选的文档辅助工具转变为专业Python开发的核心部分。2025年，带类型的Python是专业环境中的默认期望。以下是如何有效使用类型系统。
基础知识和变化
基本目的：类型提示不改变Python的运行时行为——Python保持动态类型。它们是静态类型检查器（mypy、pyright、basedpyright）、IDE和其他工具在运行时之前捕获错误所使用的元数据。基本语法：`def greet(name: str) -> str: return f”Hello, {name}”`。注释变量：`x: int = 5`，`names: list[str] = []`。与早期相比发生了什么变化：PEP 585（Python 3.9）：现在可以直接写`list[str]`、`dict[str, int]`、`tuple[int, …]`——不再需要从`typing`导入`List`、`Dict`、`Tuple`。PEP 604（Python 3.10）：使用`|`的联合类型——`str | None`而不是`Optional[str]`，`int | str`而不是`Union[int, str]`。PEP 673（Python 3.11）：`Self`类型——用于返回与其类相同类型的方法。PEP 675（Python 3.11）：`LiteralString`——标记必须是字面量字符串的字符串参数（对SQL注入防范重要）。Python 3.12：用于类型别名的`type`语句——`type Vector = list[float]`而不是`Vector = list[float]`。Python 3.13：`TypeIs`（比`TypeGuard`更窄）。`from __future__ import annotations`技巧：在Python 3.7到3.9中，这使所有注释懒惰（视为字符串），允许前向引用和循环类型，无需引号。
生产代码的关键模式
TypedDict（用于类字典结构）：`from typing import TypedDict; class User(TypedDict): name: str; age: int`——创建可类型检查的字典类型。比原始`dict[str, Any]`更明确。适用于API响应类型、配置字典和JSON结构。Protocol（用于结构化类型/鸭子类型）：`from typing import Protocol; class Readable(Protocol): def read(self) -> str: …`——任何实现`read() -> str`方法的类都满足`Readable`，无需显式继承。这实现了带类型检查的鸭子类型——类似Go的方法。数据类vs NamedTuple vs TypedDict：当需要具有方法的可变对象时使用`@dataclass`；当需要带名称的元组语义（不可变、可迭代、可索引）时使用`NamedTuple`；当需要注释字典结构时使用`TypedDict`。泛型：`from typing import TypeVar; T = TypeVar(‘T’); def first(items: list[T]) -> T: return items[0]`——在Python 3.12+中，更简单的语法是`def first[T](items: list[T]) -> T: return items[0]`。`Annotated`：`from typing import Annotated; UserId = Annotated[int, “must be positive”]`——附加到类型的元数据，由FastAPI（用于请求验证）、Pydantic（用于字段约束）和Beartype（运行时检查）等框架使用。`overload`：用于返回不同类型的具有多个有效签名的函数：`@overload; def process(x: str) -> str: …; @overload; def process(x: int) -> int: …; def process(x): …`
类型检查器和配置
mypy：原始的、使用最广泛的类型检查器。严格模式（`–strict`）启用所有可选检查——对新项目的推荐设置。pyright（VS Code中Pylance使用）：比mypy更快，具有更好的泛型推断。VS Code的推荐选择。basedpyright：pyright的分支，有更多功能和更严格的默认设置——越来越多地被采用为整体最佳类型检查器。Pyrefly（Meta，2025年）：Meta用Rust编写的新检查器——极快，为大型代码库设计。早期采用阶段。mypy的配置（pyproject.toml）：
“`toml
[tool.mypy]
strict = true
python_version = “3.12”
“`
现有代码库的渐进式类型策略：从`–ignore-missing-imports`开始，避免因未类型化的第三方库而失败；早期启用`–check-untyped-defs`（标记未类型化的函数体）；在注释文件时逐步启用严格模式。文件级忽略：`# type: ignore[assignment]`在该行抑制特定错误类型。2025年的类型化Python：几乎所有主要库现在都附带类型存根或内联类型——numpy、pandas、requests、FastAPI、SQLAlchemy、Django（通过django-stubs）、Flask。`py.typed`标记文件表明包附带类型。没有类型的库：使用`pip install types-libraryname`从typeshed安装社区类型存根。
