用途:指导编写符合 Python 3.14+ 惯用风格的代码、CLI 工具、脚本与服务。
核心原则:优先使用标准库,仅在合理时引入外部依赖;所有函数与参数都加类型标注;显式优于隐式;尽早抛出信息明确的错误。
工具链:uv 用于包管理(非 pip/poetry),ruff 用于检查与格式化(非 flake8/black),pytest 用于测试,mypy 用于类型检查。常用命令:uv sync、ruff check --fix .、ruff format .、pytest -v、mypy .。
常见模式:类型标注如 def process_users(users: list[User], limit: int | None = None) -> list[Result];异步函数如 async def fetch_data(url: str, timeout: float = 30.0) -> dict[str, Any];dataclass 配合 field(default_factory=list);结构化模式匹配 match/case。
Python 3.14 特性:延迟注解(无需 from future import annotations)、模板字符串 t"Hello {name}" 返回 Template 对象、except 可省略括号、concurrent.interpreters 子解释器并行、标准库 compression.zstd、可选无 GIL 的自由线程构建。
参考文档:PATTERNS.md(代码模式与风格)、CLI.md(CLI 应用模式)、TESTING.md(pytest 测试)。该技能已合并原 python-code-style 与 python-type-safety,内容保留在 References/code-style.md 与 References/type-safety.md。系统可靠性(后台任务、重试、可观测性)见 python-infrastructure;依赖管理与项目脚手架见 uv。
注意事项:from future import annotations 会让所有注解变为字符串,运行时内省需实际类型可用;f-string 调试语法 f"{var=}" 需 3.8+;dataclass(slots=True) 需 3.10+;PEP 604 联合语法 int | None 运行时需 3.10+;FastAPI 依赖中 async def 与 def 的执行位置不同,混用需谨慎。