SuperAPI AI Directory

python-code-review

Coding & development

View repository

Updated 10-16 09:44

About this skill

Python Code Review Standards

Review Goals

Evaluate code quality against the following standards established by this repository:

  • [python-code-quality] — code style, type annotations, naming conventions, docstrings
  • [python-pytest] — test structure, coverage, test maintainability
  • [python-simplifier] — complexity, duplicated code, logical redundancy
  • [python-best-practices] — data structure selection, performance, concurrency models, common pitfalls

Review Dimensions and Checklist Items

1. Code Style (against python-code-quality)

Type Annotations

  • All function parameters and return values have type annotations
  • Use X | None instead of Optional[X]
  • Use built-in generics (list[X]、dict[K, V]) instead of typing.List、typing.Dict
  • The top of the file has from __future__ import annotations(depending on project configuration)

Naming Conventions

  • Class names use PascalCase
  • Functions and variables use snake_case
  • Constants use UPPER_SNAKE_CASE
  • Private members start with _ Start
  • No shadowing of built-in names (list、type、next , etc.)

Docstrings

  • All public functions and classes have Google-style docstrings
  • They describe parameters, return values, and possible exceptions raised
  • Docstrings are consistent with the actual implementation

Tool Checks

  • ruff check . No errors
  • ruff format --check . No formatting issues
  • basedpyright No type errors

2. Test Quality (against python-pytest)

Coverage and Completeness

  • Core logic test coverage ≥ 80%
  • Normal paths, exception paths, and boundary values are all tested
  • Each test verifies only one behavior

Readability

  • Test names clearly describe the scenario under test and the expected result
  • Follow the Arrange-Act-Assert (AAA) pattern
  • No leftover debugging print statements

Maintainability

  • Shared fixtures are placed in conftest.py
  • Mocks only target external dependencies (databases, HTTP, filesystems)
  • No hardcoded paths or environment-specific dependencies

3. Code Simplicity (against python-simplifier)

Complexity

  • Functions do not exceed 30 lines
  • Nesting levels do not exceed 3 levels
  • Functions have no more than 5 parameters (otherwise consider encapsulating with a dataclass)

Duplicated Code

  • No obvious duplicated logic (identical code blocks appearing 2 or more times should be extracted)
  • Similar functions have been merged through parameterization

Readability

  • No magic numbers or magic strings (use constants or enums)
  • Long chains of if-elif(≥4 branches) have been replaced with dictionary mappings or match-case
  • Use early returns (Guard Clauses) instead of deep nesting

4. Best Practices (against python-best-practices)

Data Structures

  • Membership tests use set instead of list
  • Frequency counting uses Counter
  • Queue operations use deque instead of list

Performance

  • Use generators instead of lists for large datasets
  • Repeated computation results are cached (lru_cache / cache)
  • String concatenation uses join instead of +=

Common pitfalls

  • No mutable default arguments (def f(x=[]):)
  • No incorrect references to loop variables in closures
  • and None comparisons use is/is not

Review conclusion format

At the end of the review, provide the conclusion in the following format:

## 代码审查结论

### ✅ 符合标准的方面
- 类型注解完整,使用了 Python 3.10+ 语法
- 测试遵循 AAA 模式,命名清晰
- ...

### ⚠️ 需要改进的方面
1. `process_data()` 函数缺少返回值类型注解
   - 位置:`src/processor.py:42`
   - 建议:添加 `-> list[Result]`

2. 测试覆盖率不足
   - 位置:`tests/test_processor.py`
   - 建议:补充异常路径测试(当输入为空列表时)

3. 魔法数字
   - 位置:`src/config.py:15`:`if retries > 3:`
   - 建议:提取为常量 `MAX_RETRIES = 3`

### 🚫 必须修复的问题(阻断合并)
- `basedpyright` 报告 2 个类型错误(见下方详情)
- `ruff` 报告 1 个 B006 错误(可变默认参数)

### 总体评分
- 代码风格:⭐⭐⭐⭐☆
- 测试质量:⭐⭐⭐☆☆
- 代码简洁性:⭐⭐⭐⭐⭐
- 最佳实践:⭐⭐⭐⭐☆

Quick check commands

Run the following commands before committing or merging to ensure basic quality:

# 格式化 + lint
ruff format .
ruff check . --fix

# 类型检查
basedpyright

# 运行相关测试(只跑本次修改涉及的模块)
pytest tests/test_affected_module.py -v

# 带覆盖率
pytest tests/test_affected_module.py --cov=src/affected_module --cov-report=term-missing