python

Python Proximity Pattern Examples

Python examples demonstrating aggressive proximity patterns for AI-generated code.

📁 Examples

rate_limiter.py

Complete rate limiting implementation showing:

• 🧠 Decision documentation for algorithm choices
• ⚡ Performance benchmarks and measurements
• 🛡️ Security considerations for privacy
• 🎯 Tests colocated in same file
• 📊 Metrics and monitoring considerations

Key Pattern:

# 🧠 DECISION: Token bucket algorithm over fixed window
# Why: Handles burst traffic better than fixed windows
# Measurement: 30% fewer false positives in production testing
# Alternative: Fixed window (rejected: thundering herd at boundaries)

cache_manager.py

LRU cache with proximity patterns:

• TTL decisions with calculations
• Memory usage documentation
• Eviction strategy reasoning
• Performance benchmarks

auth_system.py

Authentication with security markers:

• Password hashing decisions
• Session management reasoning
• Security threat documentation
• Rate limiting integration

🎯 Python-Specific Patterns

1. Docstring Decisions

def process_data(data: List[Dict]) -> Result:
    """
    Process data with rate limiting.
    
    🧠 DECISION: Batch size of 100 for processing
    Why: Optimal for memory/speed balance
    Benchmark: 50 items = 45/s, 100 = 89/s, 200 = 92/s
    Memory: 100 items = 10MB (fits in Lambda)
    """

2. Type Hints with Reasoning

# 🧠 DECISION: TypedDict over dataclass for API responses
# Why: JSON serialization without custom encoder
# Alternative: Dataclass (needs encoder)
from typing import TypedDict

class ApiResponse(TypedDict):
    status: int
    data: Dict[str, Any]

3. Test Colocation

# Production code
class Cache:
    def get(self, key: str) -> Optional[Any]:
        # Implementation

# Tests in same file
class TestCache:
    def test_get_returns_none_for_missing(self):
        cache = Cache()
        assert cache.get("missing") is None

🚀 Running Examples

# Run rate limiter example
python rate_limiter.py

# Run tests (colocated)
python -m pytest rate_limiter.py

# Run with performance profiling
python -m cProfile rate_limiter.py

📊 Proximity Score: 93/100

These examples achieve high proximity scores:

• ✅ All constants documented with reasoning
• ✅ Tests in same file or adjacent file
• ✅ Security decisions marked and explained
• ✅ Performance choices include measurements
• ✅ Error handling with recovery strategies

💡 Learning Points

1. Constants Documentation: Every magic number explained
2. Algorithm Choices: Document why specific approach chosen
3. Memory Calculations: Show the math for limits
4. Security Markers: Threats and mitigations explicit
5. Test Proximity: Tests as documentation