Python Backend Reviewer

Python Backend Code Reviewer

Expert analysis and refactoring of Python backend code to eliminate duplication, reduce complexity, and enforce best practices.

Overview

This skill helps identify and fix common issues in Python backend code, particularly problems introduced by AI code generation:

• Duplicate code across multiple files
• Recreated utilities instead of imports
• Over-engineered solutions
• High complexity functions and classes
• Anti-patterns and code smells
• Concurrency issues in async code (shared state mutation)

The skill provides automated analysis tools and comprehensive refactoring guidance.

⚠️ Architecture-Aware Prioritization

Static analysis finds issues, but architectural context determines priority.

Before prioritizing fixes, identify:

1. Critical paths: Which code runs on every request?

   • WebSocket/HTTP handlers
   • Main workflow orchestration
   • Shared services/middleware

2. Secondary paths: Less critical code

   • CLI tools
   • Scripts
   • Dev-only utilities
   • One-time migrations

3. Concurrency model: How is state shared?

   • Are handlers concurrent?
   • Are instances shared across requests?
   • Is there mutable singleton state?

Prioritization rule: Correctness in critical paths > Complexity in secondary paths

Pragmatic Thresholds

For orchestration/workflow code, use realistic thresholds:

Hard limits (always fix):

• No functions > 300 lines
• No nesting > 7 levels
• No shared-state mutation without synchronization guard

Quick Start

1. Run Automated Analysis

Start with automated tools to identify issues:

# Detect duplicate code blocks
uv run python scripts/detect_duplicates.py <path>

# Analyze imports and utility reimplementation
uv run python scripts/analyze_imports.py <path>

# Check code complexity
uv run python scripts/complexity_analyzer.py <path>

# Check for concurrency issues (shared state mutation)
uv run python scripts/concurrency_analyzer.py <path>

2. Review Analysis Results

Each tool outputs:

• Severity levels: Warnings (must fix) vs Info (should review)
• File locations: Exact line numbers for each issue
• Specific recommendations: What to change and why

3. Apply Fixes

Use the reference guides to refactor issues:

• See refactoring_patterns.md for step-by-step fixes
• See python_antipatterns.md for anti-pattern examples
• See best_practices.md for Python conventions

Main Workflows

Review a Python File

When a user asks to review a specific file:

1. Run all analysis tools on the file:

   python scripts/detect_duplicates.py path/to/file.py
   python scripts/analyze_imports.py path/to/file.py
   python scripts/complexity_analyzer.py path/to/file.py

2. Analyze results and categorize issues:

   • Critical: Duplicates, high complexity, security issues
   • Important: Utility reimplementation, deep nesting
   • Minor: Style issues, minor inefficiencies

3. Provide specific fixes:

   • Quote exact code locations with line numbers
   • Show before/after examples
   • Explain why the change improves the code

4. Offer to implement fixes if requested

Check Backend for Duplicates

When a user asks to check a project/module for duplicates:

1. Run duplicate detection on the entire directory:

   python scripts/detect_duplicates.py src/

2. Group duplicates by severity:

   • High: 10+ lines duplicated, 3+ occurrences
   • Medium: 5-10 lines, 2+ occurrences
   • Low: Helper functions that could be extracted

3. Recommend consolidation strategy:

   • Extract to shared utilities for cross-cutting concerns
   • Create base classes for inherited behavior
   • Use decorators for repeated patterns

Analyze Module Over-Engineering

When code appears over-engineered:

1. Run complexity analysis:

   python scripts/complexity_analyzer.py --max-complexity 10 --max-length 50 path/

2. Identify over-engineering patterns:

   • Premature abstractions (base classes with one implementation)
   • Excessive configuration options
   • God classes (20+ methods)
   • Deep inheritance hierarchies

3. Suggest simplifications:

   • Replace abstractions with simple functions
   • Remove unused configuration
   • Split god classes by responsibility
   • Flatten inheritance

4. Reference specific patterns from python_antipatterns.md

Optimize Following Best Practices

When asked to optimize code or ensure best practices:

1. Run all analysis tools to get baseline metrics

2. Check against best practices:

   • DRY principle violations
   • SOLID principle violations
   • Type hint coverage
   • Error handling patterns
   • Async/await consistency

3. Prioritize optimizations:

   • First: Correctness (bugs, security)
   • Second: Maintainability (duplicates, complexity)
   • Third: Performance (N+1 queries, inefficiencies)
   • Fourth: Style (naming, imports)

4. Reference best_practices.md for specific guidelines

Analyze Concurrency Safety

When reviewing async code that handles concurrent requests:

1. Run concurrency analysis:

   uv run python scripts/concurrency_analyzer.py services/ workflows/

2. Prioritize by severity:

   • Critical: Fix before production deployment
   • Warning: Review for actual sharing patterns
   • Info: Consider but often acceptable

3. Common fixes for shared state mutation:

   # ❌ Before: Mutating shared instance state
   class Workflow:
       async def run(self, task):
           self.current_task = task  # Race condition!
   
   # ✅ After: Request-scoped state
   class Workflow:
       async def run(self, task):
           execution = ExecutionContext(task=task)
           return await self._execute(execution)

4. Alternative patterns:

   • Pass state through parameters (preferred)
   • Use contextvars for request-scoped data
   • Use asyncio.Lock for truly shared state
   • Create new instances per request

Analysis Tools