Python 开发规范
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/siviter-xyz-dot-agent-python。
技能介绍
何时需要这套约束
团队里的 Python 服务越写越长时,常见问题不是语法错误,而是类型注解风格不统一、__init__.py 被当成 barrel export、环境变量散落在各模块里导致测试难以 mock,以及改业务代码时没人对照 pytest 目录结构补测试。本技能不是语法速查表,而是一套可执行的工程约定,覆盖从命名、文档字符串到架构分层与提交流程。
技能如何约束你的实现
设计与代码风格方面强调 DRY、KISS、SOLID;有状态时优先类,可组合处用 Protocol 定义接口而非深层继承;模块保持单一职责,类依赖通过构造函数或方法注入。
类型注解要求用内置泛型(dict、list)、str | None 替代旧式 Optional,并在含注解文件顶部加入 from __future__ import annotations。
架构与数据约定每包用 environment.py 集中读取环境变量(如 api_key() 对应 API_KEY);数据模型统一走 Pydantic v2,用于 API schema、配置与 DTO。
测试侧要求目录镜像 src/,方法以 test_ 开头,套件命名为 TestFoo;执行 AAA 模式,工具链偏向 pytest、pytest-mock 与 conftest.py。实现改动前需通过类型检查与测试,相关逻辑与测试尽量同次原子提交。
边界与注意点
技能侧重「怎么写、怎么测、怎么组织模块」,不替代具体业务领域设计。附带的 references/uv-scripts.md 与 references/uv-monorepo.md 只针对 uv / Hatch 单体仓库场景;若项目仍大量用 unittest 或 Pydantic v1,需要先与团队对齐迁移范围再机械套用全文。
使用场景
- 在现有 FastAPI 服务里新增模块时,需要按单模块单服务与 Protocol 接口拆分依赖注入。
- 重构遗留代码时,要把 `typing.List` 和 `Optional` 统一成内置泛型与 `str | None` 写法。
- 为微服务封装第三方 API 时,用 Pydantic v2 定义请求响应 schema 并补镜像 src 的单元测试。
- 多人协作提交前,按 AAA 用 pytest 补用例并确认类型检查与测试在同一原子提交里通过。
适合人员
- 维护内部 Python 微服务的后端工程师,希望新 PR 默认带类型注解与 pytest 目录约定。
- 负责单体仓库拆模块的技术负责人,需要 environment.py 集中读配置以便测试 mock。
- 从 Pydantic v1 升级的库维护者,要对齐 v2 模型与序列化写法并收紧提交前检查。
- 在 uv 管理的多包仓库里写脚本的同学,需要对照 references 里的 monorepo 与脚本约定。