backend-python

backend-python

The non-negotiable standard for any Python backend work. Treat this as a senior engineer's review bar: code does not ship unless it meets every section below.

When to use (MANDATORY)

Invoke this skill before writing code whenever you:

• Create a new Python project or service.
• Add or change backend code: APIs, business logic, data models, persistence, CLIs, workers, jobs.
• Set up tooling, config, tests, or CI for a Python repo.

If the user types /backend-python, follow this skill from the top.

---

0. Non-negotiable principles

1. uv only. All Python/env/dependency/run/tooling operations go through uv. Never use raw pip, pip-tools, poetry, pipenv, conda, virtualenv, or a hand-rolled venv.
2. Latest stable Python installed on the machine. Detect and pin it (see §1). Never use alpha/rc/dev builds for a project unless the user explicitly asks.
3. Typed everywhere. Full type hints on every function signature and dataclass/model. Code must pass a type checker (ty / pyright / mypy).
4. Pydantic v2 for all external data. Request/response/DTO models and all config use Pydantic v2; config uses pydantic-settings. No bare dicts crossing a boundary.
5. Ruff is the gate. ruff check and ruff format must pass clean before "done".
6. Tests are part of the feature. New behavior ships with pytest tests. No "I'll add tests later".
7. Robust & optimized. Explicit error handling, no silent excepts, no N+1 / needless work, async I/O where it pays off, resources closed via context managers.
8. Well-organized & documented. src/ layout, clear layering, docstrings, README, and design notes in Docs/.
9. Secrets: follow the global secret-handling rules — gitignored .env (+ .env.example) via pydantic-settings for local, secret manager for cloud. Never hardcode or print secrets.

---

1. Toolchain — uv + latest stable Python

Run these at project start. Commands are identical across OSes (only .env loading differs).

# 1. Ensure uv exists
uv --version
# If missing (Windows): winget install astral-sh.uv   |   or: pip install uv (last resort)

# 2. See installed Pythons, pick the highest STABLE (ignore a*/rc/dev, pypy, graalpy, freethreaded)
uv python list --only-installed

# 3. If the latest stable isn't present, install it (example pins the line, not a patch)
uv python install 3.14

Pin the version so the project is reproducible:

• requires-python = ">=3.14" in pyproject.toml.
• A .python-version file containing the chosen version (uv writes it on uv init --python).

Rule of thumb for "latest stable": the highest cpython-X.Y.Z with no a/b/rc/+freethreaded suffix from uv python list. Today that is the 3.14 line.

---

2. Scaffold the project

# Application (service/API/worker). Creates pyproject.toml, .python-version, src/ layout.
uv init <project-name> --package --python 3.14
# Reusable library instead:  uv init <name> --lib --python 3.14

Then shape it into this layered src/ layout (FastAPI shown as the default web framework; keep the layering for any backend):

<project>/
├── pyproject.toml          # single source of config: deps, ruff, pytest, coverage, type-checker
├── uv.lock                 # committed — reproducible installs
├── .python-version         # pinned interpreter
├── .env.example            # documented, committed (NO real values)
├── .gitignore              # ignores .env, .venv, __pycache__, .ruff_cache, .pytest_cache, etc.
├── README.md               # run/dev/test instructions
├── Docs/                   # architecture & design notes (per global rule: all .md live here)
├── scripts/                # one-off utilities & migration scripts (per global rule)
├── src/
│   └── <package>/
│       ├── __init__.py
│       ├── main.py             # app/entrypoint wiring only
│       ├── core/
│       │   ├── config.py       # pydantic-settings Settings
│       │   ├── logging.py      # structured logging setup
│       │   └── exceptions.py   # domain exception hierarchy
│       ├── api/                # transport layer (routers/controllers); thin
│       │   ├── deps.py
│       │   └── v1/
│       │       ├── router.py
│       │       └── routes/
│       ├── schemas/            # Pydantic v2 I/O models (DTOs) — never leak ORM models
│       ├── models/             # ORM / persistence models
│       ├── services/           # business logic (pure, testable, framework-agnostic)
│       ├── repositories/       # data access; isolates DB from services
│       └── db/
│           └── session.py
└── tests/
    ├── conftest.py
    ├── unit/                   # fast, no I/O — mirrors src/ structure
    └── integration/            # DB/HTTP/external boundaries

Layering rule (dependency direction): api → services → repositories → db. Services hold business logic and never import the web framework. Schemas (Pydantic) are the boundary between layers — ORM models never cross into the API response directly.

---

3. Dependencies (uv)

# Runtime deps
uv add fastapi "uvicorn[standard]" pydantic pydantic-settings

# Dev deps (grouped — not shipped to prod)
uv add --dev pytest pytest-cov pytest-asyncio ruff ty pre-commit

# Run anything inside the project env (NEVER activate the venv manually)
uv run <cmd>            # e.g. uv run pytest, uv run ruff check, uv run python -m <package>

# Sync / lock
uv sync                 # install from uv.lock
uv lock --upgrade       # refresh the lockfile deliberately

Swap FastAPI for the framework the project needs, but keep pydantic + pydantic-settings and the dev toolchain. ty is Astral's type checker; use pyright or mypy if preferred.

---

4. Configuration — pydantic-settings + secrets

src/<package>/core/config.py:

from functools import lru_cache
from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    """Application configuration, loaded from environment / .env."""

    model_config = SettingsConfigDict(
        env_file=".env", env_file_encoding="utf-8", extra="ignore", frozen=True
    )

    app_name: str = "service"
    debug: bool = False
    database_url: str = Field(..., description="DB DSN; injected via env/secret manager")


@lru_cache
def get_settings() -> Settings:
    return Settings()  # type: ignore[call-arg]

• Local: gitignored .env (+ a committed .env.example with placeholders like <DB_URL>).
• Cloud/prod: inject via the platform secret manager / env — never bake values into the image.
• Never log or print secret values; mask to last ~4 chars if a value must be shown.

---

5. Code best practices (the review bar)

Typing & models

• Every public function is fully type-annotated. Prefer precise types over Any.
• All data crossing a boundary (HTTP, queue, file, DB row → response) is a Pydantic v2 model.
• Separate input, output, and DB schemas (e.g. UserCreate, UserRead, User). Use model_config = ConfigDict(from_attributes=True) to build read-models from ORM objects.
• Validate at the edge with validators (@field_validator / @model_validator); keep the core logic working on trusted, typed objects.

Structure & robustness

• Keep transport thin: routers parse/validate input and call a service; no business logic in routes.
• Raise a domain exception hierarchy (in core/exceptions.py); translate to HTTP/transport errors in one place (exception handlers / middleware). Never except Exception: pass.
• Use with / async with for all resources (DB sessions, files, clients). No leaks.
• Make functions small, pure where possible, and dependency-injected (pass collaborators in) so they are unit-testable without monkeypatching the world.

Performance & async

• Use async def for I/O-bound paths end-to-end; never block the event loop with sync I/O.
• Avoid N+1 queries (eager-load / batch). Stream large payloads. Cache only with a clear invalidation story. Measure before micro-optimizing.

Logging

• Structured logging via core/logging.py; log decisions and errors with context, not secrets.
• No print() in library/app code.

---

6. Testing (pytest)

• Tests live in tests/, mirroring src/; unit/ is fast and I/O-free, integration/ covers boundaries.
• Use fixtures in conftest.py; parametrize edge cases; assert on behavior, not internals.
• Cover the happy path and failure/validation paths for every feature.
• Async tests use pytest-asyncio. Aim for meaningful coverage (target ≥ 85% on core logic).

uv run pytest                      # run all
uv run pytest --cov=src --cov-report=term-missing
uv run pytest tests/unit -q        # fast loop

---

7. Lint & format — Ruff (the gate)

Both must pass clean before any task is "done":

uv run ruff format .       # format (also: --check in CI)
uv run ruff check . --fix  # lint + autofix

Config in pyproject.toml (see §9 template). Treat Ruff lint failures as build failures.

---

8. Documentation

• Docstrings on every public module, class, and function (PEP 257; Google or NumPy style, consistent across the repo). Explain why, not just what.
• README.md: what it is, prerequisites, uv sync, how to run, test, and lint.
• Docs/: architecture decisions, data model, API overview, runbooks (all .md go here per the global file-placement rule).
• Keep docs in sync with code in the same change.

---

9. Quality gate — pyproject.toml + pre-commit

Consolidate tool config in pyproject.toml:

[project]
name = "<package>"
requires-python = ">=3.14"
dependencies = [
    "fastapi",
    "uvicorn[standard]",
    "pydantic",
    "pydantic-settings",
]

[dependency-groups]
dev = ["pytest", "pytest-cov", "pytest-asyncio", "ruff", "ty", "pre-commit"]

[tool.ruff]
target-version = "py314"
line-length = 100
src = ["src", "tests"]

[tool.ruff.lint]
# sensible strong default; expand as needed
select = ["E", "F", "I", "UP", "B", "SIM", "C4", "ASYNC", "RUF"]

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S101"]  # asserts allowed in tests

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra --strict-markers"
asyncio_mode = "auto"

[tool.coverage.run]
source = ["src"]
branch = true

.pre-commit-config.yaml (run uv run pre-commit install once):

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.15.14
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format

CI (and local "done" check) should run, in order: uv sync → uv run ruff format --check . → uv run ruff check . → uv run ty check (or pyright/mypy) → uv run pytest --cov=src.

---

Definition of Done (checklist)

• Created/run via uv only; .python-version pins latest stable Python; uv.lock committed.
• src/ layered layout; transport thin; services framework-agnostic; ORM models don't leak into responses.
• All boundary data is Pydantic v2; config via pydantic-settings; secrets via .env/secret manager (never hardcoded/printed).
• Fully typed; passes the type checker.
• Robust: domain exceptions, no silent excepts, resources via context managers; no obvious N+1/blocking-in-async.
• Ruff format + check pass clean.
• pytest covers happy + failure paths; meaningful coverage.
• Docstrings + README + relevant Docs/ notes updated in the same change.