类型系统前沿（PEP 695、Self、Protocol 进阶）

# ① 新泛型语法（PEP 695，3.12+）：类型变量就地声明
def first[T](xs: list[T]) -> T:
    return xs[0]

class Stack[T]:
    def push(self, item: T) -> None: ...
    def pop(self) -> T: ...

# ② 带约束/上界的类型变量
def clamp[T: (int, float)](v: T, lo: T, hi: T) -> T: ...
def scale[T: Number](x: T) -> T: ...            # 上界（协议/类）

# ③ Self（PEP 673）：返回"自己的类型"，子类调用也正确
from typing import Self

class Builder:
    def set_name(self, name: str) -> Self:      # 旧写法会退化为 Builder
        self.name = name
        return self

class FastBuilder(Builder): ...
b = FastBuilder().set_name("x")                 # 推断为 FastBuilder ✓

# ④ 类型别名新写法（3.12+，惰性求值）
type Vector = list[float]
type Matrix = list[Vector]

# ⑤ 泛型默认值（PEP 696，3.13）
class Result[T = str]: ...

旧：T = TypeVar("T")
    def first(xs: list[T]) -> T: ...        （声明与使用分离）
新：def first[T](xs: list[T]) -> T: ...     （声明即使用，作用域限定在函数内）

收益：
  ① 少两行样板，作用域自动收敛（不会误用别处的 T）
  ② 约束/上界直接写在 [T: ...] 括号里
  ③ 别名 type X = ... 支持前向引用，不再需要字符串引号

迁移指引：
  旧代码          → 新写法（3.12+）
  TypeVar(...)    → def f[T](...)
  TypeAlias 注解  → type X = ...
  -> "ClassName"  → -> Self（方法链场景）
  旧约束 TypeVar 约束元组 → [T: (A, B)]
不变：运行时依然不强制；检查器才是裁判

# Builder 模式的正确类型化（Self 的杀手场景）
type JSON = dict[str, "JSON"] | list["JSON"] | str | int | float | bool | None

def flatten(obj: JSON) -> list[str]: ...