名称： python
描述： Python 编码规范与最佳实践。适用于编写、审查或重构 Python 代码。强制执行 PEP 8 风格，通过 py_compile 进行语法验证，执行单元测试，仅支持现代 Python 版本（无 EOL 版本），优先使用 uv 进行依赖管理，并遵循地道的 Pythonic 模式。

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 "未找到测试"

# 格式检查（如果工具可用）
ruff check . --fix 2>/dev/null || python -m black --check . 2>/dev/null

Python 版本

• 最低版本： Python 3.10+（3.9 已于 2025 年 10 月终止支持）
• 目标版本： 新项目建议使用 Python 3.11-3.13
• 禁止使用 Python 2 语法或模式
• 善用现代特性：match 语句、海象运算符、类型提示

依赖管理

优先使用 uv，其次使用 pip：

# 优先使用 uv（如果已安装）
if command -v uv &>/dev/null; then
    uv pip install <package>
    uv pip compile requirements.in -o requirements.txt
else
    pip install <package>
fi

新项目使用 uv 初始化：uv init 或 uv venv && source .venv/bin/activate

Pythonic 模式

# ✅ 优先使用列表/字典推导式而非循环
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()

# ✅ 解包操作
first, *rest = items
a, b = b, a  # 交换变量

# ✅ 遵循 EAFP 而非 LBYL
try:
    value = d[key]
except KeyError:
    value = default

# ✅ 使用 f-string 进行格式化
msg = f"你好 {name}，你有 {count} 个物品"

# ✅ 使用类型提示
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
try:
    ...
except:  # 会捕获 SystemExit、KeyboardInterrupt 等
    ...
except Exception:  # 更合适
    ...

# ❌ 全局状态
# ❌ from module import *
# ❌ 在循环中进行字符串拼接（应使用 join）
# ❌ 使用 == None（应使用 `is None`）
# ❌ 使用 len(x) == 0（应使用 `not x`）

测试

• 优先使用 pytest，其次 unittest
• 测试文件命名为 test_*.py，测试函数命名为 test_*
• 编写聚焦的单元测试，对外部依赖进行模拟
• 每次提交前运行：python -m pytest -v

文档字符串

def fetch_user(user_id: int, include_deleted: bool = False) -> User | None:
    """根据 ID 从数据库获取用户。

    参数：
        user_id: 用户的唯一标识符。
        include_deleted: 如果为 True，则包含已软删除的用户。

    返回：
        如果找到则返回 User 对象，否则返回 None。

    抛出：
        DatabaseError: 数据库连接失败时抛出。
    """

快速检查清单

• [ ] 语法有效（py_compile）
• [ ] 测试通过（pytest）
• [ ] 公共函数有类型提示
• [ ] 无硬编码的敏感信息
• [ ] 使用 f-string，而非 .format() 或 %
• [ ] 文件路径使用 pathlib
• [ ] I/O 操作使用上下文管理器
• [ ] 无可变默认参数