Python 编码规范

代码风格（PEP 8）

• 使用 4 个空格进行缩进（禁止使用制表符）
• 单行最大长度：88 个字符（Black 默认值）或 79 个字符（严格遵循 PEP 8）
• 顶层定义前空两行，类内部方法间空一行
• 导入顺序：标准库 → 第三方库 → 本地模块；各组内按字母顺序排列
• 函数/变量名使用 snake_case，类名使用 PascalCase，常量名使用 UPPER_CASE

提交前检查

# 语法检查（必须执行）
python -m py_compile *.py

# 运行测试（若存在）
python -m pytest tests/ -v 2>/dev/null || python -m unittest discover -v 2>/dev/null || echo "No tests found"

# 格式检查（若已配置）
ruff check . --fix 2>/dev/null || python -m black --check . 2>/dev/null

Python 版本要求

• 最低要求： Python 3.10+（Python 3.9 于 2025 年 10 月结束支持）
• 推荐目标： 新项目应面向 Python 3.11–3.13
• 禁止使用 Python 2 的语法或模式
• 应使用现代特性：match 语句、海象操作符（walrus operator）、类型提示（type hints）

依赖管理

优先检查并使用 uv，不可用时回退至 pip：

# 若 uv 可用则优先使用
if command -v uv &>/dev/null; then
    uv pip install 
    uv pip compile requirements.in -o requirements.txt
else
    pip install 
fi

新项目若使用 uv：运行 uv init 或 uv venv && source .venv/bin/activate

Python 风格惯用法

# ✅ 使用列表/字典推导式替代显式循环
squares = [x**2 for x in range(10)]
lookup = {item.id: item for item in items}

# ✅ 使用上下文管理器处理资源
with open("file.txt") as f:
    data = f.read()

# ✅ 使用解包（unpacking）
first, *rest = items
a, b = b, a  # 交换变量值

# ✅ EAFP 原则（Easier to Ask for Forgiveness than Permission），而非 LBYL（Look Before You Leap）
try:
    value = d[key]
except KeyError:
    value = default

# ✅ 使用 f-string 进行字符串格式化
msg = f"Hello {name}, you have {count} items"

# ✅ 添加类型提示
def process(items: list[str]) -> dict[str, int]:
    ...

# ✅ 使用 dataclasses 或 attrs 定义数据容器
from dataclasses import dataclass

@dataclass
class User:
    name: str
    email: str
    active: bool = True

# ✅ 使用 pathlib 替代 os.path
from pathlib import Path
config = Path.home() / ".config" / "app.json"

# ✅ 合理使用 enumerate、zip 和 itertools
for i, item in enumerate(items):
    ...
for a, b in zip(list1, list2, strict=True):
    ...

应避免的反模式

# ❌ 禁止使用可变对象作为默认参数
def bad(items=[]):  # 错误：该列表在多次调用间共享
    ...
def good(items=None):
    items = items or []

# ❌ 禁止裸 except（bare except）
try:
    ...
except:  # 会捕获 SystemExit、KeyboardInterrupt 等不应捕获的异常
    ...
except Exception:  # 更安全的做法
    ...

# ❌ 避免全局状态
# ❌ 禁止使用 from module import *
# ❌ 避免在循环中拼接字符串（应使用 ''.join()）
# ❌ 禁止使用 == None（应使用 is None）
# ❌ 禁止使用 len(x) == 0（应使用 not x）

测试

• 优先使用 pytest，也可使用 unittest
• 测试文件命名应为 test_*.py，测试函数命名应为 test_*
• 应编写聚焦的单元测试，并对所有外部依赖进行 mock
• 每次提交前必须运行：python -m pytest -v

文档字符串（Docstrings）

def fetch_user(user_id: int, include_deleted: bool = False) -> User | None:
    """从数据库中根据 ID 获取用户。
    
    Args:
        user_id: 用户唯一标识符。
        include_deleted: 若为 True，则包含已被软删除的用户。
    
    Returns:
        若找到则返回 User 对象，否则返回 None。
    
    Raises:
        DatabaseError: 若数据库连接失败。
    """

快速检查清单

• 语法有效（py_compile）
• 测试全部通过（pytest）
• 公共函数已添加类型提示
• 无硬编码的密钥（secrets）
• 使用 f-string，而非 .format() 或 % 格式化
• 使用 pathlib 处理文件路径
• I/O 操作使用上下文管理器
• 无可变默认参数