python-best-practices

name	python_best_practices
description	Python 代码审查规则。当审查 .py 文件时套用。检查类型注解、异常处理、命名规范、函数复杂度、安全漏洞（eval/exec/pickle/yaml.load/os.system）。
category	style
reviewer_type	style
languages	["python"]

Python Best Practices Review

When to Apply

• 审查 .py 文件（非测试文件）
• 审查 Python 项目的安全性、可读性、惯用性

When NOT to Apply

• 测试文件（test_*.py, *_test.py, tests/）→ 测试中的 # noqa、bare except、mock 模式是合理惯用法
• 生成的代码（protobuf stubs, gRPC stubs, migration files）→ 不审查
• Jupyter notebooks → 探索性代码，规则放宽
• __init__.py → 仅包含导入的包文件
• setup.py / conftest.py → 配置/构建文件
• Django/Flask 迁移文件 → 自动生成的
• __main__.py → CLI 入口点

Key Areas

Type Hints

• Public functions should have type hints (parameters and return)
• Use from __future__ import annotations for forward refs
• Don't flag: Any in highly dynamic code, callback-heavy code

Error Handling

• Bare except: or except Exception: pass → error (检查是否故意)
• Errors should be logged or re-raised, never silently swallowed
• Use specific exception types (ValueError, KeyError) not Exception

Naming

• Functions: snake_case; Classes: PascalCase; Constants: UPPER_SNAKE_CASE
• Private: leading underscore _name; Internal: double underscore __name

Function Complexity

• Functions > 30 lines should be split
• Nesting > 3 levels is a warning
• Too many parameters (> 5) is a design smell

Imports

• Unused imports → warning
• Circular imports → error
• Wildcard imports (from module import *) → warning

Security

• os.system() / os.popen() with user input → error
• pickle.loads() on untrusted data → error
• yaml.load() without SafeLoader → error
• eval() / exec() with user input → error
• SQL queries via f-strings or % formatting → error
• Hardcoded API keys/tokens → error

Validation Criteria

True Positive: The issue makes the code harder to maintain, understand, or is a security risk. Confidence > 0.7.

False Positive:

• A broad except in a top-level error handler (e.g., main(), web framework middleware)
• # type: ignore or # noqa comments indicating intentional deviation
• Generated or auto-formatted code
• Any type usage in highly dynamic or callback-heavy code
• Long function that is a well-structured state machine or dispatcher