CLAUDE.md

Python Project Guidelines

Overview

Python application following modern best practices with type hints, comprehensive testing, and clean architecture.

Tech Stack

  • Language: Python 3.11+
  • Package Manager: uv (or pip + venv)
  • Testing: pytest
  • Linting: ruff
  • Type Checking: mypy
  • Formatting: ruff format

Development Commands

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run tests
pytest

# Run tests with coverage
pytest --cov=src

# Linting
ruff check .

# Formatting
ruff format .

# Type checking
mypy src

Project Structure

src/
├── __init__.py
├── main.py           # Application entry point
├── config.py         # Configuration management
├── models/           # Data models (Pydantic, dataclasses)
├── services/         # Business logic
├── repositories/     # Data access layer
└── utils/            # Helper functions
tests/
├── conftest.py       # Shared fixtures
├── unit/             # Unit tests
└── integration/      # Integration tests

Code Style

  • Use type hints for all function signatures
  • Follow PEP 8 naming conventions
  • Use dataclasses or Pydantic for data structures
  • Prefer explicit over implicit
  • Keep functions under 20 lines when possible
# Good example
from dataclasses import dataclass
from typing import Optional

@dataclass
class User:
    id: int
    name: str
    email: Optional[str] = None

def get_user_by_id(user_id: int) -> Optional[User]:
    """Retrieve a user by their ID."""
    # Implementation
    pass

Error Handling

  • Use specific exception types
  • Don't catch broad exceptions unless re-raising
  • Log errors with context
  • Return meaningful error messages

Testing

  • Write tests for all public functions
  • Use fixtures for shared test data
  • Mock external dependencies
  • Test edge cases and error conditions

Dependencies

  • Pin exact versions in requirements.txt
  • Keep development dependencies separate
  • Regularly update and audit dependencies
  • Document why each dependency is needed