ECC 的 /python-review 命令指南：PEP 8、类型安全与 Pythonic 惯用法的全量代码审查

ECC 的 /python-review 命令指南PEP 8、类型安全与 Pythonic 惯用法的全量代码审查【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本指南围绕 ECC 项目中的/python-review命令展开介绍如何通过调用python-reviewer代理对 Python 变更执行涵盖 PEP 8 合规、类型提示、安全性、性能与 Pythonic 惯用法的综合性代码审查。读完本文你将掌握该命令的触发时机、CRITICAL / HIGH / MEDIUM 三级问题分类标准、自动执行的静态分析工具链ruff、mypy、black、bandit 等、报告输出格式与合并门禁判定并能用仓库源码与规则文件佐证每一条审查结论。命令定位python-reviewer 代理的调用入口/python-review是 ECC 命令体系中面向 Python 专项审查的入口。它的核心动作是调用 python-reviewer 代理python-reviewer该代理在agents/python-reviewer.md中被定义为Expert Python code reviewer specializing in PEP 8 compliance, Pythonic idioms, type hints, security, and performance并被标记为MUST BE USED for Python projects默认模型为sonnet工具能力包含 Read、Grep、Glob、Bash——这意味着它既能静态阅读代码也能在仓库中实际运行诊断命令。代理被调用后的执行序列定义在 agents/python-reviewer.md运行git diff -- *.py查看最近的 Python 文件变更在可用时运行静态分析工具ruff、mypy、pylint、black --check聚焦于被修改的.py文件立即开始审查。从源码结构看命令文档与代理定义构成命令 → 代理的一层委托关系命令负责声明审查范围与流程代理负责实际执行。命令本身不重复实现分析逻辑而是通过代理的能力边界Bash 工具去驱动真实的工具链。何时使用 /python-review根据命令文档以下场景应当使用/python-review编写或修改 Python 代码之后提交 Python 变更之前审查包含 Python 代码的 Pull Request 时新 Python 代码库的 onboarding入职熟悉阶段学习 Pythonic 模式与惯用语时。该命令与仓库中其他命令的定位互补/code-review面向非 Python 专项问题/python-test先行验证测试是否通过/build-fix在静态分析工具失败时兜底修复。这种分工使/python-review能专注于 Python 语义、类型与惯用法层面的深度检查。审查分类CRITICAL / HIGH / MEDIUM 三级问题体系审查结果按严重程度分为三档全部继承自命令文档并可在 agents/python-reviewer.md 中找到代理侧的完整优先级清单。CRITICAL必须修复安全问题与吞掉错误的模式属于最高优先级SQL / 命令注入漏洞不安全的eval/exec使用Pickle 的不安全反序列化硬编码的凭据凭据应走环境变量见 rules/python/security.md 中os.environ的加载方式YAML 的不安全load掩盖错误的裸except子句。代理侧进一步明确了这些条目的判定细节SQL 注入重点关注 f-string 拼接查询应改用参数化查询命令注入关注 shell 命令中的未校验输入应改用subprocess列表参数形式路径穿越关注用户可控路径应以normpath校验并拒绝..弱加密为安全目的使用 MD5/SHA1同样属于该级别。HIGH建议修复公开函数缺少类型提示可变的默认参数def f(x[])应改为def f(xNone)静默吞掉异常未使用上下文管理器管理资源用 C 风格循环代替列表推导式用type()而非isinstance()无锁的竞态条件共享状态应使用threading.Lock。代理清单还补充了代码质量维度超过 50 行的函数、超过 5 个参数应改用 dataclass、超过 4 层嵌套、重复代码模式、无命名常量的魔法数字以及并发维度错误混用 sync/async、循环内 N1 查询应批量查询。MEDIUM考虑改进PEP 8 格式违规公开函数缺少 docstring用print而非logging低效的字符串操作循环内拼接应改用.join()无命名常量的魔法数字格式化未使用 f-strings不必要的列表创建可用生成器表达式做惰性求值。代理清单补充了 MEDIUM 层的惯用法条目from module import *命名空间污染、value None应使用value is None、遮蔽内建名list、dict、str。自动执行的检查工具链命令文档列出审查时会运行的自动化检查全部以 Bash 命令形式给出# 类型检查 mypy . # リンティングとフォーマットlint 与格式 ruff check . black --check . isort --check-only . # セキュリティスキャン安全扫描 bandit -r . # 依存関係監査依赖审计 pip-audit safety check # テスト测试与覆盖率 pytest --covapp --cov-reportterm-missing这套工具链与仓库的工程实践完全一致pyproject.toml 实际配置了[tool.ruff]target-version py311、select [E, F, I, N, W, UP]与[tool.mypy]warn_return_any true、warn_unused_ignores true证明 ruff 与 mypy 是本仓库的正式质量门禁rules/python/coding-style.md 明确规定 black 负责代码格式化、isort 负责 import 排序、ruff 负责 lintrules/python/security.md 指定 bandit 做静态安全分析bandit -r src/rules/python/testing.md 指定 pytest 为测试框架并给出覆盖率命令pyproject.toml 中[tool.pytest.ini_options]配置了testpaths [tests]与asyncio_mode auto而仓库 tests/ 目录下也确实存在test_claude_provider.py、test_executor.py、test_resolver.py等 pytest 测试文件源码结构佐证。需要注意pytest --covapp中的app是文档示例包名实际项目中应替换为自身包名本仓库的 coverage 配置位于 pyproject.tomlsource [src/llm]。审查报告的输出格式命令文档给出了完整的交互示例用户输入/python-review后代理输出一份结构化报告包含被审查文件清单、静态分析结果✓通过 /WARNING警告、按严重度分类的问题列表每条含文件与行号、问题描述、坏示例与好示例代码、问题统计摘要、合并建议、以及需要格式化时的black file命令。代理侧的输出契约定义在 agents/python-reviewer.md[SEVERITY] Issue title File: path/to/file.py:42 Issue: Description Fix: What to change报告中每个问题都遵循严重度 → 位置 → 问题 → 修复的四要素结构便于直接落入工单或 PR 评论。文档示例中的典型修复对包括SQL 注入CRITICALquery fSELECT * FROM users WHERE id {user_id} # 坏直接拼接用户输入 query SELECT * FROM users WHERE id %s # 好参数化查询 cursor.execute(query, (user_id,))可变默认参数HIGHdef process_items(items[]): # 坏默认列表被所有调用共享 items.append(new) return items def process_items(itemsNone): # 好None 哨兵 每次新建 if items is None: items [] items.append(new) return items缺失类型提示MEDIUMdef get_user(user_id): # 坏 return db.find(user_id) def get_user(user_id: str) - Optional[User]: # 好 return db.find(user_id)未使用上下文管理器MEDIUMf open(config.json) # 坏异常时文件不会关闭 data f.read() f.close() with open(config.json) as f: # 好with 保证资源释放 data f.read()批准标准与合并门禁命令文档以表格形式定义了三种判定状态这也与代理定义中的 Approval Criteria 一致状态条件PASS批准无 CRITICAL 或 HIGH 问题WARNING警告仅有 MEDIUM 问题谨慎合并FAIL阻塞发现 CRITICAL 或 HIGH 问题判定逻辑是任何 CRITICAL 或 HIGH 问题都直接阻塞合并只有 MEDIUM 问题时允许带警告合并。示例报告末尾的Recommendation: FAIL: Block merge until CRITICAL issue is fixed演示了该规则的实际应用。常见修复模式速查命令文档附带了六组可直接套用的常见修复全部与 skills/python-patterns/ 中的惯用法互为印证添加类型提示# 变更前 def calculate(x, y): return x y # 变更后 from typing import Union def calculate(x: Union[int, float], y: Union[int, float]) - Union[int, float]: return x y使用上下文管理器# 变更前 f open(file.txt) data f.read() f.close() # 变更后 with open(file.txt) as f: data f.read()使用列表推导式# 变更前 result [] for item in items: if item.active: result.append(item.name) # 变更后 result [item.name for item in items if item.active]修正可变默认值# 变更前 def append(value, items[]): items.append(value) return items # 变更后 def append(value, itemsNone): if items is None: items [] items.append(value) return items使用 f-stringsPython 3.6# 变更前 name Alice greeting Hello, name ! greeting2 Hello, {}.format(name) # 变更后 greeting fHello, {name}!修复循环内字符串拼接# 变更前O(n²)字符串不可变导致反复拷贝 result for item in items: result str(item) # 变更后O(n) result .join(str(item) for item in items)后两条修复的原理细节字符串不可变导致的 O(n²) 复杂度、join的线性复杂度在 skills/python-patterns/ 中有更充分的展开rules/python/patterns.md 则补充了 Protocol 鸭子类型、dataclass 作为 DTO、上下文管理器与生成器惰性求值等模式规范。框架特定审查命令文档对主流 Python Web 框架给出了专项检查清单Django 项目N1 查询问题使用select_related与prefetch_related模型变更缺少迁移能用 ORM 时却使用裸 SQL多步骤操作缺少transaction.atomic()。FastAPI 项目CORS 误配置使用 Pydantic 模型做请求校验响应模型的正确性async/await 的恰当使用依赖注入模式。Flask 项目上下文管理app context、request context恰当的错误处理Blueprint 的组织方式配置管理。代理侧还额外标注了 FastAPI 审查要关注异步中是否存在阻塞调用No blocking in async以及 Flask 需要关注 CSRF 防护。Python 版本兼容性提示审查器会对使用了较新版本特性的代码给出提示确保项目声明的requires-python与代码实际用到的语法匹配特性最低 Python类型提示3.5f-strings3.6海象运算符:3.8位置专用参数3.8Match 语句3.10类型联合x | None3.10文档要求确认项目的pyproject.toml或setup.py指定了正确的最低 Python 版本。以本仓库为例pyproject.toml 声明requires-python 3.11ruff 的target-version py311与之对齐这正是一个声明版本与工具目标版本一致的良好范本。与其他命令及技能的集成命令文档给出了推荐的使用编排先使用/python-test确认测试通过对应 python-testing skill 的 pytest 与 TDD 方法论/code-review负责 Python 之外的非专项问题提交前使用/python-review静态分析工具失败时使用/build-fix。底层依赖为 python-patterns skill提供惯用法、类型提示、上下文管理器、推导式、dataclass、装饰器、并发模式等完整参考与 python-testing skill提供 pytest fixtures、参数化、mock、覆盖率与 TDD 流程审查时的判定标准也可对照 rules/python/ 目录下的 coding-style、security、testing、patterns 规则文件。总结/python-review是 ECC 为 Python 项目提供的一条完整质量门禁命令它通过git diff定位变更、借助 ruff / mypy / black / isort / bandit / pytest 等真实工具链做自动检查、按 CRITICAL / HIGH / MEDIUM 三级组织问题报告、以无 CRITICAL/HIGH 即批准的规则输出合并决策并对 Django、FastAPI、Flask 提供框架专项检查。在 ECC 仓库中这条命令与 python-reviewer 代理、python-patterns / python-testing 技能以及 rules/python 规则体系共同构成了从写出代码到安全合入的完整审查链路同时 pyproject.toml 中的实际工具配置为其可行性提供了仓库级证据。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考