Template: Python Project

Prerequisites: Complete the Interactive Guide (steps 1-5) and read The CLAUDE.md Guide first. You need Claude Code installed and understand how CLAUDE.md works before customizing a template.

Left to its own devices, Claude Code will default to whatever Python patterns it saw most during training. A lot of that is pip install, requirements.txt, os.path, and bare except:. None of that is what you want in 2025.

This template steers it toward modern tooling: uv or poetry for dependency management, pytest for testing, mypy for type checking. If you use Django or FastAPI, add framework-specific conventions after the base template.

# CLAUDE.md

## Project Overview

Python 3.12+ project. Uses `uv` for dependency management and virtual environments.
All dependencies declared in `pyproject.toml`.

Directory layout:
- `src/` - Application source code (importable package)
- `tests/` - Test files mirroring src/ structure
- `scripts/` - CLI scripts and one-off utilities
- `pyproject.toml` - Project metadata, dependencies, tool config

## Build and Run Commands

```bash
uv sync                # Install dependencies into .venv
uv run python -m src.main  # Run the application
uv run pytest          # Run all tests
uv run pytest -x       # Stop on first failure
uv run mypy src/       # Type check source code
uv run ruff check .    # Lint
uv run ruff format .   # Format

If using Poetry instead of uv:

poetry install
poetry run pytest
poetry run mypy src/

Code Style

• Follow PEP 8. Use Ruff for linting and formatting (configured in pyproject.toml).
• Type hints on all public functions and methods. No untyped public APIs.
• Use from __future__ import annotations at the top of every module for modern syntax.
• Prefer dataclasses or Pydantic models over plain dicts for structured data.
• No bare except:. Always catch specific exceptions. At minimum: except Exception as e:.
• Prefer returning new values over mutating arguments. Functions should be pure when possible.
• Docstrings on all public classes and functions. Use Google-style format.

def calculate_total(items: list[LineItem], tax_rate: float) -> Money:
    """Calculate the total cost including tax.

    Args:
        items: Line items to sum.
        tax_rate: Tax rate as a decimal (0.08 for 8%).

    Returns:
        Total cost with tax applied.
    """

Testing

pytest with fixtures. Test files mirror the source structure:

src/services/billing.py
tests/services/test_billing.py

Rules:

• Use fixtures over mocks. Create real objects when possible.
• Use pytest.mark.parametrize for testing multiple inputs.
• Factory functions for building test data, not raw dicts.
• Target 80% coverage minimum: uv run pytest --cov=src --cov-report=term-missing
• Separate slow tests with @pytest.mark.slow and skip in fast runs.

Virtual Environment

• Always use .venv in the project root. Never install packages globally.
• The .venv/ directory is in .gitignore. Do not commit it.
• If .venv does not exist, run uv sync before doing anything else.
• Never use pip install directly. Use uv add <package> to add dependencies.

Common Pitfalls (Do Not)

• Do not create or modify requirements.txt. All dependencies live in pyproject.toml.
• Do not use os.path for path manipulation. Use pathlib.Path.
• Do not use print() for logging. Use the logging module or structlog.
• Do not use mutable default arguments (def f(items=[])). Use None and create inside.
• Do not catch and silently swallow exceptions. Log them or re-raise.
• Do not use requests for new code. Use httpx (async support, better defaults).

Communication Style

Be concise. Show the code change, not a tutorial about how Python works. When adding dependencies, run uv add instead of telling me to do it.

### How to Use

1. Copy the code block above into a `CLAUDE.md` file at your project root
2. Switch the `uv` commands to `poetry` commands if that's your package manager
3. Update the directory layout if your project doesn't use a `src/` structure
4. Add framework-specific sections for Django, FastAPI, Flask, or whatever you're building on