typing 模块

from typing import Any

# 没有类型注解：签名模糊，靠文档和记忆
def process_data(data):
    ...

# 有类型注解：签名即文档，IDE 和静态检查器都能理解
def process_data(data: dict[str, Any]) -> list[dict[str, Any]]:
    ...

# Python 3.12+ 推荐写法：直接使用内置类型
name: str = "Alice"
age: int = 30
price: float = 99.99
is_active: bool = True
nothing: None = None

# 函数签名中的类型注解
def create_user(
    username: str,
    age: int,
    email: str | None = None,
) -> int:
    """创建用户并返回用户 ID。"""
    return 1001

from typing import Any

# 场景1：处理动态数据（如 JSON 反序列化）
def parse_json_response(data: str) -> Any:
    import json
    return json.loads(data)

# 场景2：与不受控制的外部代码交互
def call_external_api(endpoint: str, **params: Any) -> Any:
    ...

# 场景3：渐进式类型化——后续会替换为具体类型
def legacy_handler(request: Any) -> Any:
    ...

# === 列表 ===
scores: list[int] = [95, 87, 92]
users: list[dict[str, object]] = [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
]

# === 字典 ===
config: dict[str, int] = {"timeout": 30, "retries": 3}
# 复杂嵌套：键是字符串，值是字符串或整数
settings: dict[str, str | int] = {"host": "localhost", "port": 5432}

# === 元组 ===
# 固定长度、不同类型
record: tuple[int, str, bool] = (1, "Alice", True)
# 可变长度、同一类型（基本用法）
coordinates: tuple[int, ...] = (1, 2, 3, 4, 5)
# 空元组
empty: tuple[()] = ()

# === 集合 ===
tags: set[str] = {"python", "typing", "tutorial"}
# 不可变集合
constants: frozenset[int] = frozenset({1, 2, 3})

# === 嵌套容器 ===
matrix: list[list[float]] = [
    [1.0, 2.0, 3.0],
    [4.0, 5.0, 6.0],
]
# 现实中的复杂类型：API 响应
ApiResponse: type[dict[str, list[dict[str, str | int]]]] = list

def parse_value(value: str | int | float) -> float:
    """接受多种输入类型，统一转换为 float。"""
    return float(value)

# 返回值联合
def find_user(user_id: int) -> dict[str, str] | None:
    """找到返回用户字典，未找到返回 None。"""
    return None  # 或 return {"name": "Alice", "role": "admin"}

# 复杂联合
StatusCode = int | str  # 类型别名
def handle_response(code: StatusCode) -> None:
    match code:
        case int():
            print(f"HTTP 状态码: {code}")
        case str():
            print(f"自定义状态: {code}")

# 完全等价的三行写法
def f1(x: int | None = None) -> str: ...
def f2(x: None | int = None) -> str: ...  # 顺序无关
from typing import Optional
def f3(x: Optional[int] = None) -> str: ...

# 推荐：Python 3.10+ 使用 | None 语法
def get_config(key: str) -> str | None:
    return {"host": "localhost"}.get(key)

from typing import Literal

# 模式选择
def set_mode(mode: Literal["read", "write", "append"]) -> None:
    match mode:
        case "read":
            print("以只读模式打开")
        case "write":
            print("以写入模式打开")
        case "append":
            print("以追加模式打开")

# 多类型字面量
Alignment = Literal["left", "center", "right", 0, 1, 2]

def align_text(text: str, align: Alignment) -> str:
    match align:
        case "left" | 0:
            return f"{text:<20}"
        case "center" | 1:
            return f"{text:^20}"
        case "right" | 2:
            return f"{text:>20}"

# HTTP 方法限制
HttpMethod = Literal["GET", "POST", "PUT", "DELETE", "PATCH"]
def api_call(url: str, method: HttpMethod) -> dict[str, object]:
    ...

from typing import Final

# 常量声明：不能被重新赋值
MAX_CONNECTIONS: Final = 100
CONFIG_PATH: Final[str] = "/etc/app/config.toml"

# Final 方法：子类不能覆盖
from typing import final

class BaseHandler:
    @final
    def handle(self) -> None:
        """核心处理逻辑，子类禁止覆盖。"""
        self._pre_process()
        self._execute()
        self._post_process()

    def _pre_process(self) -> None: ...
    def _execute(self) -> None: ...
    def _post_process(self) -> None: ...

# Final 类：不能被继承
@final
class ImmutableConfig:
    """此类的设计不允许子类化。"""
    host: str
    port: int

from typing import ClassVar

class DatabaseConnection:
    # 类变量：所有实例共享
    pool_size: ClassVar[int] = 20
    _connections: ClassVar[list["DatabaseConnection"]] = []

    # 实例变量：每个实例独立
    host: str
    port: int

    def __init__(self, host: str, port: int) -> None:
        self.host = host
        self.port = port

# 静态检查器会将此标记为错误：pool_size 不应通过实例赋值
conn = DatabaseConnection("localhost", 5432)
# conn.pool_size = 30  # mypy 会报错

from typing import NoReturn, Never

# NoReturn：函数不会正常返回（抛异常或无限循环）
def raise_error(message: str) -> NoReturn:
    raise ValueError(message)

def loop_forever() -> NoReturn:
    while True:
        ...

# Never (Python 3.11+)："底部类型"，是 NoReturn 的超集
# 表示一个值"永远不可能被构造出来"
from typing import assert_never

def handle_status(status: Literal["success", "error", "pending"]) -> str:
    if status == "success":
        return "OK"
    elif status == "error":
        return "FAIL"
    elif status == "pending":
        return "WAITING"
    else:
        # assert_never 保证穷尽性检查
        assert_never(status)

from typing import TypeVar

T = TypeVar("T")  # 无约束：可以是任意类型
K = TypeVar("K")
V = TypeVar("V")

def first(items: list[T]) -> T:
    """返回列表的第一个元素，保持原类型。"""
    return items[0]

# 类型推断：
# first([1, 2, 3])       -> int
# first(["a", "b", "c"])  -> str
# first([1.0, 2.0])       -> float

def get_key_value_pair(d: dict[K, V], key: K) -> tuple[K, V]:
    """从字典取出键值对。"""
    return key, d[key]

from collections.abc import Sized

# 约束：T 必须支持 len()
S = TypeVar("S", bound=Sized)

def double_length(obj: S) -> int:
    """返回对象长度的两倍。适用于任何 Sized 类型。"""
    return len(obj) * 2

# double_length("hello")     -> 10 ✅
# double_length([1, 2, 3])  -> 6  ✅
# double_length(42)          -> ❌ mypy 报错：int 不支持 len()

# 约束为特定类型的子类
from typing import TypeVar
NumberT = TypeVar("NumberT", bound=int | float)

def add(a: NumberT, b: NumberT) -> NumberT:
    return a + b

from typing import Generic, TypeVar

T = TypeVar("T")

class Stack(Generic[T]):
    """类型安全的泛型栈。"""
    def __init__(self) -> None:
        self._items: list[T] = []

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

    def pop(self) -> T | None:
        if self._items:
            return self._items.pop()
        return None

    def peek(self) -> T | None:
        if self._items:
            return self._items[-1]
        return None

# 使用
int_stack = Stack[int]()
int_stack.push(1)
int_stack.push(2)
top: int | None = int_stack.pop()  # mypy 知道是 int

str_stack = Stack[str]()
str_stack.push("hello")
# str_stack.push(42)  # mypy 报错：int 不能传入 str 的 Stack

from typing import Protocol

class SupportsClose(Protocol):
    """任何有 close() 方法的对象都满足此协议。"""
    def close(self) -> None: ...

class Flyable(Protocol):
    def fly(self) -> str: ...

class Bird:
    def fly(self) -> str:
        return "翅膀飞行"

class Airplane:
    def fly(self) -> str:
        return "引擎飞行"
    def land(self) -> None: ...

def takeoff(obj: Flyable) -> str:
    return obj.fly()

# 两者都能通过类型检查，无需继承自 Flyable
print(takeoff(Bird()))       # 翅膀飞行
print(takeoff(Airplane()))   # 引擎飞行

from typing import TypedDict

class UserProfile(TypedDict):
    """描述用户配置文件的字典结构。"""
    user_id: int
    username: str
    email: str
    is_active: bool

# 类型安全的数据解析
def parse_user(data: dict[str, object]) -> UserProfile | None:
    """从原始字典解析用户信息。"""
    if not isinstance(data.get("user_id"), int):
        return None
    if not isinstance(data.get("username"), str):
        return None
    # 运行时不做类型验证，但 mypy 认为这里类型已正确
    return data  # type: ignore[return-value]

# TypedDict 的可选字段与只读字段
from typing import NotRequired, Required

class ConfigV2(TypedDict, total=False):
    """total=False 表示所有字段默认可选。"""
    host: Required[str]   # 必填
    port: int             # 可选（total=False）
    debug: bool           # 可选

config: ConfigV2 = {"host": "localhost"}  # 合法

from typing import NamedTuple

class Point(NamedTuple):
    """二维坐标点，不可变，字段可通过名称访问。"""
    x: float
    y: float

    def distance_to_origin(self) -> float:
        return (self.x ** 2 + self.y ** 2) ** 0.5

    def __str__(self) -> str:
        return f"Point({self.x}, {self.y})"

p = Point(3.0, 4.0)
print(p.x, p.y)            # 3.0 4.0
print(p.distance_to_origin())  # 5.0
# p.x = 5.0  # AttributeError: can't set attribute

# 与 dataclass 的对比
from dataclasses import dataclass

@dataclass(frozen=True)
class PointDC:
    x: float
    y: float

# NamedTuple: 轻量、快速、继承自 tuple（支持解包、索引）
# dataclass(frozen=True): 功能更多（field()、__post_init__ 等）

from collections.abc import Callable

# Callable[[参数类型列表], 返回值类型]
Callback = Callable[[str, int], bool]

def register_handler(name: str, handler: Callback) -> None:
    """注册一个事件处理器。"""
    print(f"已注册处理器: {handler.__name__}")

def my_handler(event_type: str, priority: int) -> bool:
    return priority > 5

register_handler("click", my_handler)  # ✅

# 无参数、无返回值的回调
NoArgCallback = Callable[[], None]

# 任意参数
AnyCallback = Callable[..., object]

from typing import Callable, TypeVar
from typing import ParamSpec  # Python 3.10+
from collections.abc import Callable

P = ParamSpec("P")
R = TypeVar("R")

def logged(func: Callable[P, R]) -> Callable[P, R]:
    """一个保留原函数签名的装饰器。"""
    from functools import wraps

    @wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        print(f"调用 {func.__name__}")
        result = func(*args, **kwargs)
        print(f"{func.__name__} 返回 {result}")
        return result
    return wrapper

@logged
def add(a: int, b: int) -> int:
    return a + b

# mypy 知道 result 是 int，且知道参数类型
result = add(3, 5)  # 类型检查通过
# add("x", "y")  # mypy 报错

from typing import TypeGuard

def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    """类型守卫：运行时检查后告诉静态检查器这个 list 里全是 str。"""
    return all(isinstance(x, str) for x in val)

def process(items: list[object]) -> str:
    if is_str_list(items):
        # 在这个分支里，mypy 知道 items 是 list[str]
        return ", ".join(items)  # ✅
    return "非字符串列表"

from typing import TypeIs  # Python 3.12+

def is_int_list(val: list[object]) -> TypeIs[list[int]]:
    """TypeIs 守卫：两种分支都有精确的类型信息。"""
    return all(isinstance(x, int) for x in val)

def process_numbers(items: list[object]) -> int:
    if is_int_list(items):
        # True 分支：items 是 list[int]
        return sum(items)
    else:
        # False 分支：mypy 知道 items 是 `list[object]` 减去 `list[int]`
        # 即"非 list[int]"
        return len(items)

# TypeIs 对 None 检查也很实用
def is_present(val: object | None) -> TypeIs[object]:
    return val is not None

# 陷阱1：tuple 泛型混淆
# ❌ 错误：单元素可变元组的正确写法必须有 ...
scores: tuple[int] = (1, 2, 3)  # TypeError!

# ✅ 正确：可变长度同类型元组
scores: tuple[int, ...] = (1, 2, 3)

# ✅ 正确：固定长度不同类型元组
pair: tuple[int, str] = (1, "hello")


# 陷阱2：Any 的传染性
from typing import Any

def get_data() -> Any:
    return {"name": "Alice"}  # 返回类型被标记为 Any

def process(user: dict[str, str]) -> str:
    return user["name"].upper()

data = get_data()       # data 的类型是 Any
# result = process(data)  # mypy 不报错，因为 Any 兼容一切！
# result 的类型也是 Any！传染了。

# ✅ 解决方案：尽早收窄
data = get_data()
if isinstance(data, dict):
    result = process(data)  # mypy 能正确检查


# 陷阱3：循环导入
# ✅ 解决方案：延迟求值注解
from __future__ import annotations  # 文件第一行

class TreeNode:
    """二叉树节点——类型注解延迟求值避免循环引用。"""
    value: int
    left: TreeNode | None   # 无需字符串包装
    right: TreeNode | None   # 无需字符串包装

    def __init__(self, value: int) -> None:
        self.value = value
        self.left = None
        self.right = None

# 阶段1：为公共 API 添加注解（最小成本，最大收益）
def calculate_total(items: list[dict[str, float]], tax_rate: float) -> float:
    total = sum(item["price"] * item["quantity"] for item in items)
    return total * (1 + tax_rate)

# 阶段2：为内部关键路径添加注解
def _validate_input(data: str, schema: dict[str, object]) -> bool:
    ...

# 阶段3：逐步启用严格模式
# mypy.ini:
# [mypy]
# strict = True
# disallow_untyped_defs = True
# disallow_incomplete_defs = True
# warn_return_any = True
# warn_unused_ignores = True

[tool.pyright]
typeCheckingMode = "strict"
reportMissingTypeStubs = true
reportUnknownVariableType = false  # 逐步开启
reportUnknownParameterType = true
reportUnknownArgumentType = true
reportUnknownMemberType = true
reportMissingParameterType = true
reportUnnecessaryTypeIgnoreComment = true

# ✅ 良好的类型别名组织
# types.py（项目中的类型定义文件）
from collections.abc import Callable, Mapping, Sequence

# 业务类型别名——提高可读性
UserId = int
JsonDict = dict[str, object]
ApiHandler = Callable[[JsonDict], JsonDict]
ConfigMap = dict[str, str | int | bool]

# 使用类型别名
def get_user(user_id: UserId) -> JsonDict | None:
    return {"id": user_id, "name": "Alice"}

# ✅ 公共 API 总是注解（库/大型项目）
__all__ = [
    "UserId",
    "JsonDict",
    "ApiHandler",
    "ConfigMap",
]