python

Python 指南

Python 开发的标准和最佳实践。编写或修改 Python 代码时，请遵循以下指南。

设计原则

始终贯彻 DRY、KISS 和 SOLID 原则。在适当情况下优先使用函数式方法；对于有状态行为，使用类。使用 Protocol 类进行组合以定义接口，而非继承。每个模块应只负责一项职责。使用依赖注入管理类的依赖项。

代码风格

• 命名：变量、方法和类的名称应具有描述性且简洁
• 文档：为所有类、函数、枚举及枚举值编写文档字符串
• 类型提示：保持一致使用；除非必要，避免使用 Any
• 导入：避免在 __init__.py 中使用聚合导出；优先使用空文件

类型注解

• 使用 dict、list，而非 typing.Dict、typing.List
• 使用 str | None，而非 Optional[str]
• 在包含类型提示的文件顶部添加 from __future__ import annotations
• 优先使用内置类型，而非 typing 模块中的对应类型

架构

依赖注入

• 使用类时，始终通过构造函数或方法注入依赖项
• 每个模块只放置一个服务类（此外可以包含接口和类模型）
• 使用 Protocol 类定义接口，以便进行依赖注入和测试

模块组织

• 每个模块专注于一个关注点，并明确划分边界
• 提取可复用的方法，避免重复
• 设计时考虑在不同上下文中的复用性

环境变量

• 使用 environment.py 文件，并为每个变量单独提供方法（例如，为 API_KEY 提供 api_key()，为 DATABASE_URL 提供 database_url()）
• 将每个包中的所有环境访问操作集中在一处，以便在测试中轻松模拟

数据模型

• 使用 Pydantic v2 定义模式、验证和数据模型
• 利用 Pydantic 的类型验证、序列化和配置管理功能
• 使用 Pydantic 模型定义 API 请求／响应模式、配置对象和数据传输对象

测试

结构

• 测试目录结构应与 src/ 镜像对应
• 测试方法以 test_ 开头
• 使用测试类套件：对于 def foo()，创建 class TestFoo
• 名称应简洁，方法名中省略测试类套件名称
• 修改代码时，始终检查是否需要添加相应的单元测试

质量

• 使用 AAA（Arrange、Act、Assert）模式
• 测试应实用、易读、简洁且易于维护
• 避免编写会产生大量差异或变得难以维护的测试

工具

• 优先使用 pytest，而非 unittest
• 使用 pytest-mock 进行模拟
• 使用 conftest.py 存放共享的 fixture
• 使用 tests/__test_<package_name>__ 存放共享测试代码

实现

实现 Python 代码时：

• 确保代码通过类型检查和测试后再提交
• 将相关更改与测试组合成原子提交
• 检查现有工作流模式（先编写规范、TDD 等）并遵循它们

参考资料

• 关于由 uv 管理的项目中的临时 Python 脚本，请参阅 references/uv-scripts.md。
• 关于使用 uv 和 Hatch 的 monorepo 专属模式，请参阅 references/uv-monorepo.md。