python-code-review
Reviews Python code for type safety, async patterns, error handling, and common mistakes. Use when reviewing .py files, checking type hints, async/await usage, or exception handling.
When & Why to Use This Skill
This Claude skill provides a comprehensive automated review for Python code, focusing on type safety, PEP8 style compliance, asynchronous patterns, and robust error handling. It streamlines the development workflow by identifying common mistakes like mutable default arguments and blocking calls in async functions, ensuring code is efficient, readable, and maintainable.
Use Cases
- Automated Pull Request Audits: Perform initial checks on Python PRs to catch PEP8 violations and missing type hints before a human reviewer steps in.
- Optimizing Asynchronous Code: Identify blocking calls such as time.sleep or synchronous requests within async functions to prevent performance bottlenecks.
- Enhancing Type Safety: Scan existing codebases to find missing or incorrect type annotations, facilitating better IDE support and reducing runtime type errors.
- Standardizing Error Handling: Detect bare 'except:' clauses and ensure exceptions are raised with proper context to improve system observability and debugging.
| name | python-code-review |
|---|---|
| description | Reviews Python code for type safety, async patterns, error handling, and common mistakes. Use when reviewing .py files, checking type hints, async/await usage, or exception handling. |
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_casefor functions/variables,CamelCasefor classes,UPPER_CASEfor constants - Inline comments separated by at least two spaces
Type Safety
- Type hints on all function parameters and return types
- No
Anyunless necessary (with comment explaining why) - Proper
T | Nonesyntax (Python 3.10+)
Async Patterns
- No blocking calls (
time.sleep,requests) in async functions - Proper
awaiton all coroutines
Error Handling
- No bare
except:clauses - Specific exception types with context
-
raise ... fromto preserve stack traces
Common Mistakes
- No mutable default arguments
- Using
loggernotprint()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
Anywhen interacting with untyped libraries - Required when external libraries lack type stubs - Empty
__init__.pyfiles - Valid for package structure, no code required noqacomments - 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 deffunctions → 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.