Python 类型注解完全指南 2026：mypy 静态检查 + Pydantic 数据验证 + 泛型实战

1
# ── 变量注解 ──────────────────────────────────────────────────
2
name: str = "Alice"
3
age: int = 30
4

5
# 3.10+ 新语法：| 代替 Union，更简洁
6
def greet(name: str | None = None) -> str:
7
    return f"Hello, {name or 'World'}"
8

9
# 3.9+ 内置容器直接用小写（无需 from typing import List）
10
def process(items: list[int], config: dict[str, str]) -> tuple[int, str]:
11
    return items[0], config.get("key", "")
12

13
# 3.12+ type 别名语法
14
type Vector = list[float]
15
type Matrix = list[list[float]]
16

17
# ── 函数注解 ──────────────────────────────────────────────────
18
from collections.abc import Callable, Sequence, Iterator
19

20
def apply(func: Callable[[int], str], value: int) -> str:
21
    return func(value)
22

23
def first(items: Sequence[int]) -> int | None:
24
    return items[0] if items else None
25

26
# *args 和 **kwargs
27
def log(*messages: str, level: str = "INFO") -> None:
28
    pass
29

30
def create(**kwargs: str | int) -> dict[str, str | int]:
31
    return kwargs

1
from typing import Protocol, runtime_checkable
2

3
# 定义协议接口（不需要显式继承，鸭子类型）
4
@runtime_checkable
5
class Drawable(Protocol):
6
    def draw(self) -> None: ...
7
    def resize(self, factor: float) -> None: ...
8

9
class Circle:
10
    def draw(self) -> None:
11
        print("Drawing circle")
12
    def resize(self, factor: float) -> None:
13
        self.radius *= factor
14

15
class Square:
16
    def draw(self) -> None:
17
        print("Drawing square")
18
    def resize(self, factor: float) -> None:
19
        self.side *= factor
20

21
# Circle / Square 无需继承 Drawable，mypy 自动识别
22
def render_all(shapes: list[Drawable]) -> None:
23
    for shape in shapes:
24
        shape.draw()
25

26
render_all([Circle(), Square()])         # mypy ✅
27
print(isinstance(Circle(), Drawable))    # True（@runtime_checkable）

1
from typing import TypedDict, NotRequired, Literal, Final, TypeGuard
2

3
# ── TypedDict ─────────────────────────────────────────────────
4
class UserDict(TypedDict):
5
    id: int
6
    name: str
7
    email: str
8
    age: NotRequired[int]   # 可选字段
9

10
user: UserDict = {"id": 1, "name": "Alice", "email": "a@b.com"}   # ✅
11
# user = {"id": "1", ...}                                           # ❌ mypy
12

13
# ── Literal：限制值域 ─────────────────────────────────────────
14
LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR"]
15

16
def log(message: str, level: LogLevel = "INFO") -> None:
17
    pass
18

19
log("msg", "INFO")      # ✅
20
# log("msg", "VERBOSE") # ❌ mypy 报错
21

22
# ── Final：常量 ───────────────────────────────────────────────
23
MAX_RETRIES: Final = 3
24
API_BASE: Final[str] = "https://api.example.com"
25

26
# ── TypeGuard：自定义类型收窄 ─────────────────────────────────
27
def is_string_list(val: list[object]) -> TypeGuard[list[str]]:
28
    return all(isinstance(item, str) for item in val)
29

30
def process(items: list[str] | list[int]) -> None:
31
    if is_string_list(items):
32
        joined = ", ".join(items)   # mypy 收窄为 list[str]，✅

1
from typing import Self
2

3
class Builder:
4
    def __init__(self) -> None:
5
        self._config: dict[str, str] = {}
6

7
    def set(self, key: str, value: str) -> Self:   # Self 指向实际类型
8
        self._config[key] = value
9
        return self
10

11
    def build(self) -> dict[str, str]:
12
        return self._config
13

14
class AdvancedBuilder(Builder):
15
    def validate(self) -> Self:
16
        return self
17

18
# 子类继承时，Self 自动指向 AdvancedBuilder，链式调用类型正确
19
result = AdvancedBuilder().set("k", "v").validate().build()   # ✅

1
from pydantic import BaseModel, Field, field_validator, model_validator
2
from pydantic import ConfigDict
3

4
class User(BaseModel):
5
    model_config = ConfigDict(strict=True, frozen=True)
6

7
    id: int
8
    name: str = Field(min_length=1, max_length=100)
9
    email: str
10
    age: int | None = Field(default=None, ge=0, le=150)
11
    tags: list[str] = Field(default_factory=list)
12

13
# 创建 & 序列化
14
user = User(id=1, name="Alice", email="alice@example.com")
15
user.model_dump()           # → dict（v2 写法，v1 是 .dict()）
16
user.model_dump_json()      # → JSON 字符串
17
User.model_validate({"id": 1, "name": "Alice", "email": "a@b.com"})
18

19

20
# ── 字段验证器 ────────────────────────────────────────────────
21
class Article(BaseModel):
22
    title: str
23
    tags: list[str]
24

25
    @field_validator("title")
26
    @classmethod
27
    def strip_title(cls, v: str) -> str:
28
        if not v.strip():
29
            raise ValueError("title cannot be empty")
30
        return v.strip()
31

32
    @field_validator("tags", mode="before")   # 预处理阶段
33
    @classmethod
34
    def parse_tags(cls, v: str | list[str]) -> list[str]:
35
        if isinstance(v, str):
36
            return [t.strip() for t in v.split(",") if t.strip()]
37
        return v
38

39

40
# ── 模型级验证器 ──────────────────────────────────────────────
41
class DateRange(BaseModel):
42
    start: str
43
    end: str
44

45
    @model_validator(mode="after")
46
    def check_order(self) -> "DateRange":
47
        if self.start >= self.end:
48
            raise ValueError("end must be after start")
49
        return self
50

51

52
# ── 嵌套模型 ──────────────────────────────────────────────────
53
class Address(BaseModel):
54
    city: str
55
    country: str = "CN"
56

57
class Company(BaseModel):
58
    name: str
59
    address: Address          # 嵌套模型自动转换
60
    employees: list[User]
61

62
company = Company(
63
    name="Example Corp",
64
    address={"city": "Beijing"},      # dict 自动转 Address ✅
65
    employees=[{"id": 1, "name": "Alice", "email": "a@b.com"}],
66
)