Python 类型提示完全实战指南：从「动态一时爽」到「重构火葬场」的救赎之路

1
from typing import Optional, Union
2

3
# 可能为 None 的值
4
def find_user(user_id: int) -> Optional[str]:
5
    """找到返回用户名，找不到返回 None"""
6
    users = {1: "Alice", 2: "Bob"}
7
    return users.get(user_id)
8

9
# Python 3.10+ 可以用 | 语法（更爽）
10
def find_user(user_id: int) -> str | None:
11
    ...
12

13
# 多种类型
14
def parse_input(value: str | int | float) -> str:
15
    return str(value)

1
from typing import TypedDict
2

3
class UserInfo(TypedDict):
4
    name: str
5
    age: int
6
    email: str
7
    is_vip: bool
8

9
def display_user(user: UserInfo) -> str:
10
    # IDE 会自动补全 user["name"]、user["age"] 等
11
    return f"{user['name']} ({user['age']}岁) - {'VIP' if user['is_vip'] else '普通用户'}"
12

13
# 使用
14
user: UserInfo = {
15
    "name": "王大锤",
16
    "age": 25,
17
    "email": "wang@example.com",
18
    "is_vip": True
19
}
20
display_user(user)  # ✅ 类型安全

1
from typing import TypeVar, Generic
2

3
T = TypeVar("T")
4

5
class Stack(Generic[T]):
6
    def __init__(self) -> None:
7
        self._items: list[T] = []
8

9
    def push(self, item: T) -> None:
10
        self._items.append(item)
11

12
    def pop(self) -> T:
13
        if not self._items:
14
            raise IndexError("Stack is empty")
15
        return self._items.pop()
16

17
    def peek(self) -> T:
18
        if not self._items:
19
            raise IndexError("Stack is empty")
20
        return self._items[-1]
21

22
# 使用时指定类型
23
int_stack: Stack[int] = Stack()
24
int_stack.push(42)
25
int_stack.push("hello")  # ❌ mypy 报错：期望 int，得到 str
26

27
str_stack: Stack[str] = Stack()
28
str_stack.push("world")  # ✅

1
from typing import Protocol, runtime_checkable
2

3
@runtime_checkable
4
class Renderable(Protocol):
5
    def render(self) -> str:
6
        ...
7

8
class HTMLComponent:
9
    def render(self) -> str:
10
        return "<div>Hello</div>"
11

12
class MarkdownDoc:
13
    def render(self) -> str:
14
        return "# Hello"
15

16
class PlainText:
17
    def to_string(self) -> str:  # 没有 render 方法
18
        return "Hello"
19

20
def display(item: Renderable) -> None:
21
    print(item.render())
22

23
display(HTMLComponent())  # ✅ 有 render 方法
24
display(MarkdownDoc())    # ✅ 有 render 方法
25
display(PlainText())      # ❌ mypy 报错：PlainText 没有 render 方法

1
from dataclasses import dataclass, field
2
from datetime import datetime
3

4
@dataclass
5
class Article:
6
    title: str
7
    content: str
8
    author: str
9
    tags: list[str] = field(default_factory=list)
10
    published_at: datetime | None = None
11
    view_count: int = 0
12

13
    def summary(self, max_length: int = 100) -> str:
14
        text = self.content[:max_length]
15
        return f"{text}..." if len(self.content) > max_length else text
16

17
    def publish(self) -> None:
18
        self.published_at = datetime.now()
19

20
# 使用
21
article = Article(
22
    title="Python 类型提示指南",
23
    content="这是一篇很长的文章...",
24
    author="王大锤",
25
    tags=["Python", "Type Hints"]
26
)
27
article.publish()
28
print(article.summary(50))

1
from typing import Callable
2

3
# 基础用法
4
def apply_twice(func: Callable[[int], int], value: int) -> int:
5
    return func(func(value))
6

7
def double(x: int) -> int:
8
    return x * 2
9

10
result = apply_twice(double, 5)  # 20
11

12
# 复杂回调
13
EventHandler = Callable[[str, dict[str, object]], None]
14

15
def register_handler(event: str, handler: EventHandler) -> None:
16
    print(f"Registered handler for {event}")
17

18
def on_click(event_name: str, data: dict[str, object]) -> None:
19
    print(f"Clicked: {event_name}")
20

21
register_handler("click", on_click)  # ✅

1
# 复杂类型用别名
2
from typing import TypeAlias
3

4
# Python 3.10+
5
UserID: TypeAlias = int
6
Username: TypeAlias = str
7
UserMap: TypeAlias = dict[UserID, Username]
8
APIResponse: TypeAlias = dict[str, list[dict[str, str | int | None]]]
9

10
def get_users() -> UserMap:
11
    return {1: "Alice", 2: "Bob"}
12

13
def parse_response(resp: APIResponse) -> list[str]:
14
    # 比写一长串 dict[str, list[dict[str, str | int | None]]] 清晰多了
15
    ...

1
from typing import overload
2

3
@overload
4
def process(value: str) -> list[str]: ...
5
@overload
6
def process(value: int) -> list[int]: ...
7

8
def process(value: str | int) -> list[str] | list[int]:
9
    if isinstance(value, str):
10
        return value.split(",")
11
    return list(range(value))
12

13
# mypy 知道：
14
result1 = process("a,b,c")  # 类型是 list[str]
15
result2 = process(5)         # 类型是 list[int]

1
from pydantic import BaseModel, EmailStr, field_validator
2

3
class CreateUserRequest(BaseModel):
4
    username: str
5
    email: EmailStr
6
    age: int
7
    tags: list[str] = []
8

9
    @field_validator("age")
10
    @classmethod
11
    def validate_age(cls, v: int) -> int:
12
        if v < 0 or v > 150:
13
            raise ValueError("年龄不合理")
14
        return v
15

16
# 自动验证 + 类型转换
17
user = CreateUserRequest(
18
    username="wang",
19
    email="wang@example.com",
20
    age="25",  # 字符串自动转 int
21
    tags=["python", "dev"]
22
)
23
print(user.age)  # 25（int 类型）

1
# ❌ 类还没定义就引用了
2
class TreeNode:
3
    def __init__(self, children: list[TreeNode]):  # 报错！
4
        ...
5

6
# ✅ 方案1：字符串引用
7
class TreeNode:
8
    def __init__(self, children: list["TreeNode"]):
9
        self.children = children
10

11
# ✅ 方案2：Python 3.10+ 用 from __future__
12
from __future__ import annotations
13

14
class TreeNode:
15
    def __init__(self, children: list[TreeNode]):  # 现在可以了
16
        self.children = children