python-typing-ops

用途

python-typing-ops 是一个关于 Python 类型提示（type hints）与类型安全模式的技能，用于帮助编写类型安全、带有类型文档说明的 Python 代码。其触发关键词包括：type hints、typing、TypeVar、Generic、Protocol、mypy、pyright、type annotation、overload、TypedDict。

该技能自述为「基础技能（foundation skill），无前置要求」。

主要能力

技能内容按类型标注主题组织，涵盖以下方面：

基础注解：变量注解（如 name: str = "Alice"、count: int = 42、items: list[str]、mapping: dict[str, int]），函数签名注解（参数类型与返回类型），以及 None 处理（如 def find(id: int) -> str | None）。

集合类型：建议使用 collections.abc 中的 Sequence、Mapping、Iterable 等集合抽象基类以提升灵活性，例如接受 list、tuple 或任意 sequence；同时介绍嵌套类型别名，如 Matrix = list[list[float]]、Config = dict[str, str | int | bool]。

Optional 与 Union：介绍 3.10+ 的现代联合语法 User | None、str | int | float，以及带默认 None 的参数写法 timeout: float | None = None。

TypedDict：使用 typing.TypedDict 定义固定键的字典结构，支持 total=False（全部可选）、Required、NotRequired，以实现类型安全的键访问。

Callable：使用 collections.abc.Callable 表示函数类型（如 Handler = Callable[[str, int], bool]）；当需要关键字参数时，示例建议改用 Protocol 定义可调用协议。

泛型（Generics）：使用 TypeVar 定义泛型参数（如 first(items: list[T]) -> T | None），并支持带 bound 的 TypeVar（如 TypeVar("N", bound=SupportsFloat)）。

Protocol（结构化类型）：通过定义具有 read 方法的 Readable 协议，使函数可接受任何具备该方法的对象，示例中 file、BytesIO、自定义类均可传入。

TypeGuard 类型守卫：通过 TypeGuard[list[str]] 让检查函数在条件分支内收窄变量类型。

Literal 与 Final：Literal["read", "write", "append"] 限定取值，Final 标记不可重新赋值的常量（如 MAX_SIZE: Final = 1024、API_VERSION: Final[str] = "v2"）。

速查表：给出类型与用例的对应关系，包括 X | None（可选值）、list[T]（同构列表）、dict[K, V]（字典）、Callable[[Args], Ret]（函数类型）、TypeVar("T")（泛型参数）、Protocol（结构化类型）、TypedDict（固定键字典）、Literal["a", "b"]（限定取值）、Final（不可重新赋值）。

使用方式

技能提供类型检查器命令示例：

mypy：uv run mypy src/ --strict
pyright：uv run pyright src/

pyproject.toml 配置示例：

[tool.mypy]
strict = true
python_version = "3.11"

技能还说明了新兴工具 ty——Astral 基于 Rust 的类型检查器（与 uv、ruff 同一工具链），速度显著快于 mypy，但仍处于预览阶段（pre-1.0），因此 mypy 或 pyright 仍是生产默认选择；可通过 uvx ty check 试用，待其稳定后在新项目中采用。

附带资源

references 目录包含以下参考文档：generics-advanced.md（TypeVar、ParamSpec、TypeVarTuple）、protocols-patterns.md（结构化类型、运行时协议）、type-narrowing.md（守卫、isinstance、assert）、mypy-config.md（mypy/pyright 配置）、runtime-validation.md（Pydantic v2、typeguard、beartype）、overloads.md（@overload 装饰器模式）。

scripts 目录包含 check-types.sh（以常见选项运行类型检查器）。

assets 目录包含 pyproject-typing.toml（推荐的 mypy/pyright 配置）。

适用场景

适用于为 Python 代码添加类型提示、配置类型检查器、需要类型安全的字典结构、泛型函数、结构化类型或类型收窄等场景。

限制

该技能定位为基础技能，无前置要求；未提供关于收费、价格、平台或具体效果的信息；ty 工具仍为预览阶段（pre-1.0），生产环境默认仍建议使用 mypy 或 pyright。

技能介绍

用途

主要能力

使用方式

附带资源

适用场景

相关技能

限制