Python Development Expert

Expert-level Python development skill with senior architect capabilities, automated code quality tools, and comprehensive best practices.

Core Capabilities

1. Code Quality Automation

Use bundled scripts to enforce code quality:

Run all quality checks:

uv run python scripts/check_quality.py [target_directory]

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