This runs:

Ruff lint: Fast linting for code quality issues
Ruff format: Code formatting checks
MyPy: Static type checking
Pytest: Test execution with coverage
Bandit: Security vulnerability scanning

Auto-fix common issues:

uv run python scripts/autofix.py [target_directory]

Auto-fixes:

Code formatting (line length, indentation, quotes)
Import sorting
Common linting issues (unused imports, etc.)

2. Project Initialization

Create new Python projects with best practices:

uv run python scripts/init_project.py <project-name> [path]

Creates:

Modern project structure (src/ layout)
Configured pyproject.toml with Ruff, MyPy, Pytest
Git ignore file
Test structure
README template

3. Code Quality Standards

See code_quality.md for detailed standards on:

Linting and formatting configuration
Type hints and annotations
Modern Python patterns (match statements, walrus operator, etc.)
Error handling best practices
Documentation with comprehensive docstrings
Testing with pytest
Dependencies management with uv

4. Architecture Patterns

See architecture_patterns.md for:

Project organization (feature-based structure)
Dependency injection with protocols
Design patterns (Factory, Strategy, Repository, Unit of Work)
API design with FastAPI
Async patterns
Error handling architecture
Performance optimization

Development Workflow

When Writing New Code

Use type hints everywhere:

def process_data(
    items: Sequence[dict[str, Any]],
    max_count: int = 100,
) -> list[ProcessedItem]:
    ...

Follow modern Python idioms:

# Use match statements (3.10+)
match status:
    case 200:
        return response.json()
    case 404:
        raise NotFoundError()
    case _:
        raise APIError(status)

Add comprehensive docstrings:

def calculate_metrics(data: pd.DataFrame) -> dict[str, float]:
    """Calculate statistical metrics from data.
    
    Args:
        data: Input DataFrame with numeric columns
    
    Returns:
        Dictionary mapping metric names to values
    
    Raises:
        ValueError: If data is empty
    """

Before Committing

Run auto-fix: uv run python scripts/autofix.py
Run quality checks: uv run python scripts/check_quality.py
Ensure all checks pass before committing

Code Review Checklist

✅ All functions have type hints
✅ Docstrings follow Google style
✅ No lint warnings from Ruff
✅ MyPy type checking passes
✅ No security issues from Bandit
✅ Test coverage > 80%
✅ Code follows architecture patterns

Tool Configuration

All tools are configured via pyproject.toml:

Ruff: Line length 100, Python 3.12+, comprehensive rule set MyPy: Strict mode with no untyped definitions Pytest: Coverage reporting with missing lines Coverage: Excludes test files and common patterns

Common Patterns

Dependency Injection

from typing import Protocol

class Repository(Protocol):
    def save(self, item: Item) -> None: ...

class Service:
    def __init__(self, repo: Repository) -> None:
        self.repo = repo

Configuration with Pydantic

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    api_key: str
    
    model_config = {"env_file": ".env"}

Error Handling

class DomainError(Exception):
    """Base for all domain errors."""
    pass

class ValidationError(DomainError):
    """Invalid input data."""
    pass

Async Operations

async def fetch_all(urls: list[str]) -> list[Response]:
    async with aiohttp.ClientSession() as session:
        tasks = [fetch_one(session, url) for url in urls]
        return await asyncio.gather(*tasks)

Quick Reference

Install dev dependencies:

uv add --dev ruff mypy pytest pytest-cov bandit

Run single tool:

uv run ruff check .
uv run mypy .
uv run pytest
uv run bandit -r .

Format code:

uv run ruff format .

Type check:

uv run mypy --strict .

Best Practices Summary

Always use type hints for function signatures and class attributes
Run quality checks before committing code
Follow modern Python patterns (match, protocols, dataclasses)
Use dependency injection for testability
Write comprehensive docstrings with examples
Organize by feature not by layer
Prefer composition over inheritance
Use async for I/O-bound operations
Cache expensive computations
Test with pytest and maintain >80% coverage

python

Python Development Expert

Core Capabilities

1. Code Quality Automation