📦 Python — Python 脚本执行

代码风格（PEP 8）

• 缩进使用 4 个空格（绝不使用 Tab）
• 最大行长度：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+（3.9 于 2025 年 10 月 EOL）
• 目标版本： 新项目使用 Python 3.11-3.13
• 绝不使用 Python 2 语法或模式
• 使用现代特性：match 语句、海象运算符、类型提示

依赖管理

优先检查 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

Pythonic 模式

# ✅ 列表/字典推导式优于循环
squares = [x2 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"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=[]):  # Bug：跨调用共享
    ...
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 获取用户。
    
    Args:
        user_id: 唯一用户标识符。
        include_deleted: 如果为 True，包含软删除的用户。
    
    Returns:
        找到则返回 User 对象，否则返回 None。
    
    Raises:
        DatabaseError: 如果连接失败。
    """

快速检查清单

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