python

Critical Patterns

Type Hints (REQUIRED)

# ✅ ALWAYS: Use type hints for all function signatures
def calculate_total(items: list[dict], tax_rate: float = 0.1) -> float:
    """Calculate total with tax."""
    subtotal = sum(item["price"] for item in items)
    return subtotal * (1 + tax_rate)

# ❌ NEVER: Untyped functions
def calculate_total(items, tax_rate=0.1):
    return sum(i["price"] for i in items) * (1 + tax_rate)

Docstrings (REQUIRED)

# ✅ ALWAYS: Google-style docstrings
def process_order(order_id: str, validate: bool = True) -> Order:
    """Process an order by ID.
    
    Args:
        order_id: Unique order identifier.
        validate: Whether to validate before processing.
        
    Returns:
        Processed Order object.
        
    Raises:
        OrderNotFoundError: If order doesn't exist.
    """

Custom Exceptions (REQUIRED)

# ✅ ALWAYS: Custom exceptions over generic
class OrderNotFoundError(Exception):
    """Raised when order is not found."""
    pass

# ❌ NEVER: Generic exceptions
raise Exception("Order not found")

---

Decision Tree

Need formatting?       → Use f-strings
Need async?            → Use asyncio with async/await
Need data class?       → Use @dataclass or Pydantic
Need env management?   → Use poetry or uv
Need type checking?    → Run mypy in CI

---

Code Examples

Modern Python Features

# Pattern matching (3.10+)
match status:
    case "pending":
        process_pending()
    case "completed":
        finalize()
    case _:
        raise ValueError(f"Unknown status: {status}")

# Dataclasses
from dataclasses import dataclass

@dataclass
class User:
    id: str
    name: str
    email: str
    active: bool = True

Context Managers

# ✅ Good: Use context managers for resources
with open("file.txt", "r") as f:
    content = f.read()

# Async context manager
async with aiohttp.ClientSession() as session:
    async with session.get(url) as response:
        data = await response.json()

---

Commands

python -m venv .venv         # Create virtual environment
source .venv/bin/activate    # Activate (Unix)
pip install -r requirements.txt
mypy src/                    # Type checking
ruff check src/              # Linting
pytest tests/                # Run tests

---

Resources

Additional specialized documentation:

• PEP 8 Standards: pep8-standards.md
• FastAPI: fastapi.md
• FastAPI Async: fastapi-async.md
• Django: django.md
• Deep Learning: deep-learning.md
• Web Scraping: web-scraping.md