Python Sensei — 最佳实践执行器

版本: 1.1.0 | 作者: Shadows Company | 许可证: MIT

触发时机

• 编写新的 Python 代码时
• 审查现有 Python 代码时
• 用户输入 “python review”、“best practices” 或 “clean up this python” 等指令时
• 重构 Python 模块时
• 新建 Python 项目时

不触发时机

• 质量无关紧要的快速脚本
• 用户明确要求 “just make it work”
• 非 Python 代码

前置依赖

需确保系统 PATH 中存在 python 或 python3，用于语法检查（python -m py_compile）和测试执行（python -m pytest）。

可选工具（自动检测，建议将据此动态调整）：

• pytest — 测试执行（pip install pytest）
• mypy 或 pyright — 静态类型检查
• ruff — 快速 linting 与格式化（pip install ruff）

该能力会检测用户环境中已安装的工具，并据此定制化推荐方案。

代码规范

1. 模块结构

"""模块文档字符串 — 一行描述其用途。"""

# 标准库导入
import os
from pathlib import Path

# 第三方库导入
import httpx
from pydantic import BaseModel

# 本地导入
from .config import Settings

# 常量
MAX_RETRIES = 3
DEFAULT_TIMEOUT = 30

# 模块主体代码...

规则：

• 单个模块最多 500 行 — 超出则拆分为多个专注功能的子模块
• 导入分组：标准库 → 第三方库 → 本地模块（各组之间用空行分隔）
• 常量置于模块顶部，命名使用 ALL_CAPS 格式
• 复杂类应单独存放于一个文件中（即一文件一类）

2. 函数

async def fetch_user(user_id: str, *, include_profile: bool = False) -> User | None:
    """根据 ID 获取用户。

    Args:
        user_id: 用户唯一标识符。
        include_profile: 是否包含完整档案数据。

    Returns:
        若找到则返回 User 对象；否则返回 None。

    Raises:
        ConnectionError: 当 API 不可达时抛出。
    """

规则：

• 所有公开函数必须带完整类型提示（参数 + 返回值）
• 为提升可读性，显式使用关键字参数（* 后的参数）
• 当失败属于正常流程（而非异常情形）时，返回类型应包含 None
• 仅对公开函数编写文档字符串（docstring）
• 单个函数最多 30 行 — 超出则提取为辅助函数

3. 数据模型

from dataclasses import dataclass, field
from enum import StrEnum

class Status(StrEnum):
    ACTIVE = "active"
    INACTIVE = "inactive"
    PENDING = "pending"

@dataclass
class User:
    id: str
    name: str
    status: Status = Status.ACTIVE
    tags: list[str] = field(default_factory=list)

    def to_dict(self) -> dict:
        return {
            "id": self.id,
            "name": self.name,
            "status": self.status.value,
            "tags": self.tags,
        }

规则：

• 简单模型使用 @dataclass；验证逻辑繁重的模型优先选用 Pydantic
• 状态枚举统一使用 StrEnum（支持 JSON 序列化）
• 所有模型均须提供 to_dict() 方法以支持序列化
• 默认设为不可变（必要时添加 frozen=True）

4. 错误处理

# 推荐：捕获具体异常，try 块尽量精简
try:
    response = await client.get(url)
    response.raise_for_status()
except httpx.TimeoutException:
    logger.warning("Request timed out: %s", url)
    return None
except httpx.HTTPStatusError as e:
    logger.error("HTTP %d: %s", e.response.status_code, url)
    raise

# 禁止：捕获全部异常
try:
    do_everything()
except Exception:
    pass  # 切勿如此操作

规则：

• 必须捕获具体异常类型，禁止使用裸 except:
• 仅在系统边界处进行校验（如用户输入、外部 API 响应）
• 信任内部代码逻辑 — 不应在各处添加防御性检查
• 错误输出统一使用 logging 模块，禁止使用 print()

5. 异步模式

import asyncio
import httpx

async def fetch_all(urls: list[str]) -> list[dict]:
    async with httpx.AsyncClient() as client:
        tasks = [client.get(url) for url in urls]
        responses = await asyncio.gather(*tasks, return_exceptions=True)
        return [r.json() for r in responses if not isinstance(r, Exception)]

规则：

• 资源管理统一使用 async with
• I/O 并行操作统一使用 asyncio.gather()
• 部分失败场景下应启用 return_exceptions=True
• 禁止在同一函数内混用同步与异步 I/O

6. 测试

import pytest

class TestUserService:
    def test_create_user_with_valid_data(self):
        user = create_user(name="Alice", email="alice@example.com")
        assert user.name == "Alice"
        assert user.status == Status.ACTIVE

    def test_create_user_rejects_empty_name(self):
        with pytest.raises(ValueError, match="name cannot be empty"):
            create_user(name="", email="alice@example.com")

    @pytest.mark.asyncio
    async def test_fetch_user_returns_none_for_missing(self):
        result = await fetch_user("nonexistent-id")
        assert result is None

规则：

• 测试文件路径： tests/test_{module}.py
• 测试方法名需清晰描述场景：test_[action]_[condition]_[expected]
• 单个测试方法中建议只含一条断言（preferred）
• 预期异常统一使用 pytest.raises
• 共享初始化逻辑统一使用 fixture

7. 项目结构

project/
  src/
    project_name/
      __init__.py
      main.py
      config.py
      models.py
  tests/
    test_main.py
    test_models.py
  pyproject.toml
  requirements.txt
  .gitignore

使用 pyproject.toml 替代 setup.py；requirements.txt 中固定主版本号。

需标记的反模式

安全注意事项

本能力仅读写工作目录内的 Python 源文件，不会访问项目范围以外的任何文件。

• 执行的命令：使用 python -m py_compile 进行语法检查，python -m pytest 执行测试。这些命令运行的是本地项目代码 —— 仅应在可信仓库或沙箱环境中使用。
• 读取的数据：仅限工作目录下的源文件。不访问密钥、凭据或系统文件。
• 网络访问：无需网络连接，全程离线运行。
• 凭据：不存储、不访问任何凭据信息。
• 持久化：所有修改仅作用于工作目录中的源文件，不更改任何全局配置。
• 沙箱化：建议在虚拟环境（venv）中运行，以隔离依赖。

输出格式

代码审查结果与生成的代码均严格遵循上述规范。每次审查均需指出具体反模式及其所在行号，并附上修正后的代码块。

核心规则

1. 全面启用类型提示 — 所有公开函数必须具备完整的类型注解
2. 单模块上限 500 行 — 大型模块须拆分为职责更聚焦的子模块
3. 每个模块必须配备测试 — 文件路径为 tests/test_{module}.py，测试名称需具描述性
4. 默认采用异步 — 所有 I/O 操作均应使用异步实现
5. 优先使用 pathlib — 使用 pathlib.Path 替代 os.path
6. 禁用 print 调试 — 统一通过 logging 模块配合恰当日志级别进行调试输出

发布方：Shadows Company — “We work in the shadows to serve the Light.”