跳到主要内容

类型提示

类型提示不改变运行时行为,但能显著提升可读性与可维护性,也是静态检查工具的基础。

基本类型标注​

内置类型可直接使用;容器需从 typing 或内置泛型导入。

from typing import Optional

def greet(name: str) -> str:
    return f"hi, {name}"

nums: list[int] = [1, 2, 3]
kv: dict[str, int] = {"a": 1}
pt: tuple[int, int] = (0, 0)
maybe: Optional[int] = None

3.9+ 可直接用 list[int]、dict[str, int] 而不必写 List、Dict;3.10+ 可用 int | None 替代 Optional[int]。

Union​

Union[A, B] 表示参数可为 A 或 B,3.10+ 可用 A | B。多类型联合适合输入校验,内部再窄化类型。

TypeVar 泛型​

TypeVar 让函数或类与具体类型解耦,常用于容器与工具函数。

from typing import TypeVar

T = TypeVar("T")

def first(items: list[T]) -> T:
    return items[0]

调用 first([1, 2]) 推断为 int,first(["a"]) 推断为 str。

Protocol​

Protocol 用于结构化子类型(鸭子类型的静态表达):只要对象具备指定方法,即可被接受。

from typing import Protocol

class Closeable(Protocol):
    def close(self) -> None: ...

def shutdown(c: Closeable) -> None:
    c.close()

无需显式继承,适合解耦测试与扩展点。

mypy 与运行时检查​

  • mypy:主流静态检查器,通过 mypy src 集成进 CI
  • Pyright / pyrefly:由编辑器与 LSP 驱动的更快检查器
  • 运行时检查:工具如 pydantic、beartype 可在执行期强制类型,适合外部输入

静态检查是首选,运行时校验作为外部数据边界补充。