---

name: python-development description: Python development standards for code review and generation. Covers Python 3.12+ patterns, type hints, async/await, testing with pytest, package management with uv, AWS Lambda/boto3 patterns, and Pydantic validation. Use when working with .py files, pyproject.toml, requirements.txt, Lambda functions, or when asking about Python best practices, code review, or generation.

Python Development

Guiding Principle

Apply features only when they add clarity, correctness, performance, or security. Prefer simple, intentional solutions (DRY, KISS, YAGNI, Fail Fast).

AI Assistant Guidelines

• Avoid Over-Engineering: Don't recommend boto3 client caching, async/await, or concurrency patterns unless explicitly requested or bottlenecks are evident
• Keep It Simple: Prefer stdlib over complex architectures
• Respect Context: Don't transform a 20-line script into a 200-line framework

Standards Quick Reference

Type Hints (Python 3.12+)

Use built-in types instead of typing module:

Copy# Modern Python 3.12+
def process(items: list[str], config: dict[str, int] | None = None) -> tuple[str, int]:
    ...

# Avoid (old style)
from typing import List, Dict, Optional, Tuple
def process(items: List[str], config: Optional[Dict[str, int]] = None) -> Tuple[str, int]:
    ...

Code Structure

Copy#!/usr/bin/env -S uv run
"""
Module purpose and overview.

Workflow:
1. Load configuration
2. Validate inputs
3. Process data
"""

# Standard library
import logging

# Third-party
import requests

# Local
from utils import helper


def helper_function() -> None:
    """Helper functions first."""
    pass


def main() -> int:
    """Main function last."""
    return 0


if __name__ == "__main__":
    sys.exit(main())

Key Patterns

Defensive Programming

Copy# Validate inputs early (fail-fast)
def process_user(user_id: str | None) -> User:
    if user_id is None:
        raise ValueError("user_id is required")
    # Continue processing...

No Mutable Defaults

Copy# BAD
def foo(items: list[str] = []):
    ...

# GOOD
def foo(items: list[str] | None = None):
    items = items or []
    ...

Error Handling

Copy# Re-raise with context at boundaries
try:
    data = load_database()
except Exception as e:
    raise RuntimeError(f"Failed to load database: {e}") from e

Logging Setup

Copyimport logging
import time

def setup_logger(name: str) -> logging.Logger:
    logger = logging.getLogger(name)
    logger.setLevel(logging.INFO)
    
    class UTCFormatter(logging.Formatter):
        converter = time.gmtime
    
    handler = logging.StreamHandler()
    handler.setFormatter(UTCFormatter("%(asctime)s - %(levelname)s - %(message)s"))
    logger.addHandler(handler)
    return logger

logger = setup_logger(__name__)

Package Management (uv)

Copy# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Project setup
uv init my-project
uv add boto3 pydantic
uv add --dev pytest black ruff
uv sync

# Run script
uv run python main.py

Pydantic Validation

Copyfrom pydantic import BaseModel, field_validator

class User(BaseModel):
    name: str
    age: int
    
    @field_validator("age")
    @classmethod
    def valid_age(cls, v: int) -> int:
        if v < 0 or v > 150:
            raise ValueError("Invalid age")
        return v

Quick Checklist

• Shebang line with uv
• Type hints on all functions
• Google-style docstrings
• Imports grouped and sorted
• if __name__ == "__main__": guard
• Logging configured
• Input validation
• Specific exception handling
• black and ruff pass
• pylint score ≥ 9.0

Detailed References

• Modern Python Features: See references/modern-python.md for match-case, walrus operator, dataclasses, functional patterns
• Async & Concurrency: See references/async-concurrency.md for asyncio, threading, multiprocessing
• Testing Patterns: See references/testing-patterns.md for pytest, mocking, fixtures
• AWS Lambda: See references/aws-lambda.md for boto3 patterns, Lambda best practices