Python Code Review 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 Review Checklist PEP8 Style 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 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+) Async Patterns No blocking calls (time.sleep, requests) in async functions Proper await on all coroutines Error Handling No bare except: clauses Specific exception types with context raise ... from to preserve stack traces Common Mistakes No mutable default arguments Using logger not print() for output f-strings preferred over .format() or % 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 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 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 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? Before Submitting Findings
Load and follow review-verification-protocol before reporting any issue.