python-code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Code Review

Python代码审查

Quick Reference

快速参考

Issue Type	Reference
Indentation, line length, whitespace, naming	references/pep8-style.md
Missing/wrong type hints, Any usage	references/type-safety.md
Blocking calls in async, missing await	references/async-patterns.md
Bare except, missing context, logging	references/error-handling.md
Mutable defaults, print statements	references/common-mistakes.md

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

Review Checklist

审查检查清单

PEP8 Style

PEP8 编码风格

4-space indentation (no tabs)
Line length ≤79 characters (≤72 for docstrings/comments)
Two blank lines around top-level definitions, one within classes
Imports grouped: stdlib → third-party → local (blank line between groups)
No whitespace inside brackets or before colons/commas
Naming:
```
snake_case
```
for functions/variables,
```
CamelCase
```
for classes,
```
UPPER_CASE
```
for constants
Inline comments separated by at least two spaces

使用4空格缩进（禁止使用制表符）
行长度≤79个字符（文档字符串/注释≤72个字符）
顶级定义前后保留两个空行，类内部定义之间保留一个空行
导入分组：标准库 → 第三方库 → 本地库（组之间保留一个空行）
括号内部、冒号/逗号前无空白字符
命名规范：函数/变量使用
```
snake_case
```
，类使用
```
CamelCase
```
，常量使用
```
UPPER_CASE
```
行内注释与代码之间至少保留两个空格

Type Safety

类型安全性

Type hints on all function parameters and return types
No
```
Any
```
unless necessary (with comment explaining why)
Proper
```
T | None
```
syntax (Python 3.10+)

所有函数参数和返回值都添加类型提示
非必要情况不使用
```
Any
```
类型（必要时需添加注释说明原因）
正确使用
```
T | None
```
语法（Python 3.10+）

Async Patterns

异步模式

No blocking calls (
```
time.sleep
```
,
```
requests
```
) in async functions
Proper
```
await
```
on all coroutines

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

Error Handling

错误处理

No bare
```
except:
```
clauses
Specific exception types with context
```
raise ... from
```
to preserve stack traces

禁止使用裸
```
except:
```
语句
使用具体的异常类型并添加上下文信息
使用
```
raise ... from
```
保留堆栈跟踪信息

Common Mistakes

常见问题

No mutable default arguments
Using
```
logger
```
not
```
print()
```
for output
f-strings preferred over
```
.format()
```
or
```
%
```

禁止使用可变默认参数
使用
```
logger
```
而非
```
print()
```
输出日志
优先使用f-strings而非
```
.format()
```
或
```
%
```
格式化字符串

Valid Patterns (Do NOT Flag)

无需标记的有效模式

These patterns are intentional and correct - do not report as issues:

Type annotation vs type assertion - Annotations declare types but are not runtime assertions; don't confuse with missing validation
Using
Any
when interacting with untyped libraries - Required when external libraries lack type stubs
Empty
__init__.py
files - Valid for package structure, no code required
noqa
comments - Valid when linter rule doesn't apply to specific case
Using
cast()
after runtime type check - Correct pattern to inform type checker of narrowed type

以下模式是有意设计的正确写法 - 不要将其报告为问题：

类型注解 vs 类型断言 - 注解用于声明类型但不做运行时断言；不要将其与缺失验证混淆
与无类型库交互时使用
Any
- 当外部库缺少类型存根时，这是必要的做法
空的
__init__.py
文件 - 这是合法的包结构，无需编写代码
noqa
注释 - 当检查器规则不适用于特定场景时，使用该注释是合法的
运行时类型检查后使用
cast()
- 这是告知类型检查器已缩小类型范围的正确模式

Context-Sensitive Rules

上下文敏感规则

Only flag these issues when the specific conditions apply:

Issue	Flag ONLY IF
Generic exception handling	Specific exception types are available and meaningful
Unused variables	Variable lacks `_` prefix AND isn't used in f-strings, logging, or debugging

仅在满足特定条件时才标记这些问题：

问题	仅在以下情况标记
通用异常处理	存在可用且有意义的具体异常类型时
未使用的变量	变量没有 `_` 前缀，且未在f-strings、日志记录或调试中使用时

When to Load References

何时加载参考文档

Reviewing code formatting/style → pep8-style.md
Reviewing function signatures → type-safety.md
Reviewing
```
async def
```
functions → async-patterns.md
Reviewing try/except blocks → error-handling.md
General Python review → common-mistakes.md

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

Review Questions

审查问题

Does the code follow PEP8 formatting (indentation, line length, whitespace)?
Are imports properly grouped (stdlib → third-party → local)?
Do names follow conventions (snake_case, CamelCase, UPPER_CASE)?
Are all function signatures fully typed?
Are async functions truly non-blocking?
Do exceptions include meaningful context?
Are there any mutable default arguments?

代码是否遵循PEP8格式规范（缩进、行长度、空白字符）？
导入是否按标准库→第三方库→本地库正确分组？
命名是否符合规范（snake_case、CamelCase、UPPER_CASE）？
所有函数签名是否都完整添加了类型注解？
异步函数是否真正实现了非阻塞？
异常是否包含有意义的上下文信息？
是否存在可变默认参数？

Before Submitting Findings

提交检查结果前的步骤

Load and follow review-verification-protocol before reporting any issue.

在报告任何问题之前，请加载并遵循审查验证协议。