类型系统进阶

Python 3.10+ 的类型注解已足够表达大多数 API 契约；配合 mypy / pyright 可在运行前发现错误。基础见 python-fundamentals；Pydantic 与 Agent schema 见 ai-agents-essentials；/roadmaps/python。

学习目标

使用 X | Y、list[str]、TypedDict、Protocol
编写泛型函数与 TypeVar 约束
配置 mypy 并对模块做静态检查

现代注解语法

from typing import TypedDict, Protocol, TypeVar

class LessonMeta(TypedDict):
    slug: str
    title: str
    published: bool

def slugify(title: str) -> str:
    return title.lower().replace(" ", "-")

T = TypeVar("T")

def first(items: list[T]) -> T | None:
    return items[0] if items else None

Protocol（结构化子类型）

class SupportsRender(Protocol):
    def render(self, source: str) -> str: ...

def publish(renderer: SupportsRender, md: str) -> str:
    return renderer.render(md)

class Plain:
    def render(self, source: str) -> str:
        return source.strip()

# Plain 无需继承 SupportsRender，只要有 render 方法即可
publish(Plain(), "# Hello")

mypy 配置片段

# pyproject.toml
[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true

mypy src/

常见修复：# type: ignore[code] 仅作最后手段，优先改类型或重构。

与运行时校验

工具	阶段	用途
mypy	静态	开发期类型错误
Pydantic	运行时	HTTP/API 边界校验
isinstance	运行时	窄化 Union

FastAPI 的 response_model 同时受益于两者。

练习

为 count_chars 函数（packaging 课）补全返回类型 dict[str, int]
定义 LessonRepo Protocol，含 get(slug: str) -> LessonMeta | None
对一个小模块运行 mypy，修复至少一处报错

静态类型与校验