python-code-review

Python 代码审查

快速参考

问题类型	参考文档
缩进、行长度、空白、命名	references/pep8-style.md
缺少或错误的类型提示、Any 的使用	references/type-safety.md
异步函数中的阻塞调用、缺少 await	references/async-patterns.md
裸 except、缺少上下文、日志记录	references/error-handling.md
可变默认值、print 语句	references/common-mistakes.md

审查清单

PEP8 风格

• 使用 4 个空格缩进（不使用制表符）
• 行长度 ≤79 个字符（文档字符串和注释 ≤72 个字符）
• 顶层定义前后各空两行，类中空一行
• 按以下顺序对导入分组：标准库 → 第三方库 → 本地模块（组间空一行）
• 括号内或冒号、逗号前没有空白
• 命名：函数和变量使用 snake_case，类使用 CamelCase，常量使用 UPPER_CASE
• 行内注释前至少留两个空格

类型安全

• 所有函数参数和返回值都添加类型提示
• 除非必要，否则不使用 Any（并添加注释说明原因）
• 使用正确的 T | None 语法（Python 3.10+）

异步模式

• 异步函数中没有阻塞调用（time.sleep、requests）
• 所有协程都正确使用 await

错误处理

• 没有裸 except: 子句
• 使用具体的异常类型并附带上下文
• 使用 raise ... from 保留堆栈跟踪

常见错误

• 没有可变默认参数
• 使用 logger 而非 print() 输出
• 优先使用 f-string，而非 .format() 或 %

有效模式（不要标记）

以下模式是有意采用且正确的，不要将其报告为问题：

• 类型注解与类型断言 —— 注解声明类型，但不是运行时断言；不要将其与缺少验证混淆
• 与无类型库交互时使用 Any —— 外部库缺少类型存根时必须使用
• 空的 __init__.py 文件 —— 对包结构而言有效，无需包含代码
• noqa 注释 —— 当特定情况不适用检查器规则时，有效
• 运行时类型检查后使用 cast() —— 这是告知类型检查器类型已收窄的正确模式

依情境适用的规则

仅在满足特定条件时标记以下问题：

问题	仅当以下条件成立时才标记
泛化的异常处理	存在具体且有意义的异常类型
未使用的变量	变量没有 _ 前缀，且未用于 f-string、日志记录或调试

关卡（报告工作流）

按顺序完成。在满足每个通过条件前，不要进入下一项。

1. 范围 —— **通过：**列出本次检查的每个 .py 路径（或明确的 glob）。
2. 误报筛查 —— 通过：对于计划报告的每个问题，都检查了上述有效模式和依情境适用的规则；如果这些部分说明不要标记，则删除或缩小问题范围。
3. 证据 —— **通过：**每个剩余问题都包含 [FILE:LINE]（或有界的行号范围）。符号或简短的逐字片段可以补充位置锚点，但不能取代它。
4. 验证流程 —— 通过：加载 review-verification-protocol，并在面向用户撰写报告前，针对每个报告的问题完成其中的强制步骤。
5. 交付 —— **通过：**面向用户的输出符合该流程要求的结构（不得跳过检查，只输出问题列表）。

何时加载参考文档

• 审查代码格式或风格 → pep8-style.md
• 审查函数签名 → type-safety.md
• 审查 async def 函数 → async-patterns.md
• 审查 try/except 代码块 → error-handling.md
• 常规 Python 审查 → common-mistakes.md

审查问题

1. 代码是否遵循 PEP8 格式规范（缩进、行宽、空白）？
2. 导入项是否按正确顺序分组（标准库 → 第三方库 → 本地模块）？
3. 命名是否遵循约定（snake_case、CamelCase、UPPER_CASE）？
4. 所有函数签名是否都标注了完整类型？
5. 异步函数是否真正实现了非阻塞？
6. 异常是否包含有意义的上下文信息？
7. 是否存在可变默认参数？

报告前：请先完成上方的门禁（报告工作流）（尤其是第 4 道门禁）。