# CLAUDE.md — API Python

<!-- Adaptez les commandes à votre outillage (uv, pip + venv, poetry…).
     Supprimez les lignes qui ne s'appliquent pas à votre projet. -->

## Aperçu

API HTTP en Python (FastAPI ou framework équivalent), typée, testée avec pytest.

## Environnement et commandes

- Installer les dépendances : `uv sync` (ou `pip install -r requirements.txt`
  dans un environnement virtuel activé)
- Lancer l'API en local : `uv run uvicorn app.main:app --reload`
- Tests : `uv run pytest` ; un seul test : `uv run pytest tests/test_users.py::test_create`
- Lint et format : `uv run ruff check .` et `uv run ruff format .`
- Typage : `uv run mypy app`

Toujours lancer les tests du module modifié avant de conclure.

## Arborescence

- `app/main.py` : création de l'application et montage des routeurs
- `app/routers/` : un fichier par ressource (endpoints uniquement)
- `app/services/` : logique métier, sans dépendance au framework HTTP
- `app/schemas/` : modèles de validation des entrées et sorties
- `app/db/` : accès aux données et migrations
- `tests/` : miroir de `app/`, fixtures partagées dans `tests/conftest.py`

## Conventions

- Annotations de type obligatoires sur les fonctions publiques.
- Les routeurs valident et délèguent ; aucune requête SQL dans un routeur.
- Erreurs métier : exceptions dédiées, converties en réponses HTTP à un seul endroit.
- Tout nouvel endpoint s'accompagne d'au moins un test de succès et un test d'erreur.
- Configuration lue depuis les variables d'environnement, jamais codée en dur.

## À ne pas faire

- Ne pas modifier les migrations déjà appliquées : en créer une nouvelle.
- Ne pas lire ni afficher le contenu de `.env`.
- Ne pas désactiver un test qui échoue pour « faire passer » la suite.
- Ne pas ajouter de dépendance sans l'indiquer explicitement dans la réponse.