Scaffold: préparation du projet pronote-sync
- Guide de développement (GUIDE_DEV_PYTHON.md) : spécification complète - TODO.md : 15 jalons de développement (M1-M15) avec étapes et critères d'acceptation - AGENTS.md : guide de contribution pour agents et développeurs - pyproject.toml : configuration projet (dépendances, ruff, mypy strict, pytest) - .gitignore : exclusion venv, bytecode, .env, caches, state files - .env.example : template des variables d'environnement (placeholders) - Structure du package pronote_sync/ (14 sous-packages avec __init__.py) - tests/ avec conftest.py et fixtures/ - Environnement virtuel .venv/ (Python 3.14)
This commit is contained in:
158
AGENTS.md
Normal file
158
AGENTS.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# Guide pour les agents et contributeurs — `pronote-sync`
|
||||
|
||||
> **Langue de travail** : Français (ce fichier et toute la documentation projet).
|
||||
|
||||
---
|
||||
|
||||
## 1. Description du projet
|
||||
`pronote-sync` est un pipeline Python qui synchronise les données de **Pronote** (système de gestion scolaire) vers **CalDAV** (agendas) et **XMPP** (notifications).
|
||||
|
||||
> **Spécification complète** : Voir [`GUIDE_DEV_PYTHON.md`](./GUIDE_DEV_PYTHON.md).
|
||||
|
||||
---
|
||||
|
||||
## 2. Stack technique
|
||||
|
||||
### Langage et dépendances
|
||||
- **Python** : ≥ 3.13 (actuellement 3.14 dans `.venv/`)
|
||||
- **Dépendances principales** :
|
||||
`pydantic>=2.0`, `pydantic-settings`, `icalendar`, `caldav`, `slixmpp`, `pronotepy`, `feedparser`, `requests`, `httpx`
|
||||
|
||||
### Outils de développement
|
||||
- **Linter** : `ruff` (longueur de ligne : 100)
|
||||
- **Typage** : `mypy` (mode `strict=true`)
|
||||
- **Tests** : `pytest` (couverture ≥ 90%), `pytest-mock`, `responses`, `aioresponses`
|
||||
- **Sécurité** : `bandit`
|
||||
- **Pre-commit** : hooks configurés pour `ruff`, `mypy`, `bandit`
|
||||
|
||||
### Environnement
|
||||
- **Virtualenv** : `.venv/` (à activer avant toute opération)
|
||||
- **Fichier de configuration** : `.env` (à partir de `.env.example`)
|
||||
|
||||
---
|
||||
|
||||
## 3. Structure du projet
|
||||
|
||||
```
|
||||
pronote_sync/
|
||||
├── config/ # Configuration et paramètres
|
||||
├── models/ # Modèles de données (Pydantic v2)
|
||||
├── sources/ # Connecteurs (Pronote, iCal, etc.)
|
||||
├── sync/ # Logique de synchronisation
|
||||
├── synthesis/ # Génération de synthèses (IA)
|
||||
├── channels/ # Canaux de sortie (CalDAV, XMPP)
|
||||
├── pipeline/ # Orchestration du pipeline
|
||||
├── utils/ # Utilitaires (redaction, logging, etc.)
|
||||
├── cli/ # Interface en ligne de commande
|
||||
└── __init__.py
|
||||
|
||||
tests/
|
||||
├── fixtures/ # Données de test anonymisées
|
||||
├── unit/ # Tests unitaires
|
||||
└── integration/ # Tests d'intégration
|
||||
```
|
||||
|
||||
> **Plan de développement** : Voir [`TODO.md`](./TODO.md) pour les 15 jalons (M1-M15).
|
||||
|
||||
---
|
||||
|
||||
## 4. Commandes essentielles
|
||||
|
||||
### Environnement
|
||||
```bash
|
||||
# Activer le virtualenv
|
||||
source .venv/bin/activate
|
||||
|
||||
# Installer les dépendances de développement
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
### Qualité de code
|
||||
```bash
|
||||
# Linter (ruff)
|
||||
ruff check .
|
||||
|
||||
# Formattage (ruff)
|
||||
ruff format .
|
||||
|
||||
# Vérification des types (mypy)
|
||||
mypy .
|
||||
|
||||
# Analyse de sécurité (bandit)
|
||||
bandit -r pronote_sync/
|
||||
|
||||
# Pre-commit (tous les hooks)
|
||||
pre-commit run --all-files
|
||||
```
|
||||
|
||||
### Tests
|
||||
```bash
|
||||
# Exécuter les tests
|
||||
pytest
|
||||
|
||||
# Exécuter les tests avec couverture
|
||||
pytest --cov
|
||||
```
|
||||
|
||||
### CLI
|
||||
```bash
|
||||
# Exécuter en mode dry-run (simulation)
|
||||
pronote-sync --dry-run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Conventions de code
|
||||
|
||||
### Typage
|
||||
- **Strict** : `mypy` en mode `strict=true`. **Tous** les paramètres, retours et variables locales doivent être typés.
|
||||
- **Pydantic v2** : Tous les modèles de données héritent de `BaseModel`. Les modèles de contrat utilisent `frozen=True`.
|
||||
|
||||
### Architecture
|
||||
- **Injection de dépendances** : Utiliser `typing.Protocol` et une **composition root** dans `pipeline/run.py`. **Interdiction** des singletons globaux.
|
||||
|
||||
### Style
|
||||
- **Longueur de ligne** : 100 caractères maximum (configuré dans `ruff`).
|
||||
- **Imports** : Triés automatiquement par `ruff` (intègre `isort`).
|
||||
|
||||
### Tests
|
||||
- **Sans réseau** : Utiliser **uniquement** des mocks (`pytest-mock`, `responses`, `aioresponses`).
|
||||
- **Fixtures** : Les données de test doivent être anonymisées et stockées dans `tests/fixtures/`.
|
||||
|
||||
### Comportement
|
||||
- **Idempotence** : Deux exécutions identiques sans changement externe doivent produire le **même résultat**.
|
||||
- **Mode dégradé** :
|
||||
- Si l'IA échoue → retourner un message **sans synthèse**.
|
||||
- Si `pronotepy` échoue → fallback vers le parsing **iCal**.
|
||||
- Si tout échoue → lever une **erreur explicite**.
|
||||
|
||||
---
|
||||
|
||||
## 6. Sécurité et secrets
|
||||
|
||||
### Règles absolues
|
||||
- **Aucun secret en clair** : Ni dans le code, ni dans les logs, ni dans les erreurs, ni dans les fixtures.
|
||||
- **Masquage** : Utiliser systématiquement `redact_url()`, `redact_secrets()`, et `redact_exception()` depuis `utils/redaction.py`.
|
||||
|
||||
### Bonnes pratiques
|
||||
- **Types sécurisés** : Les mots de passe et clés API doivent utiliser `pydantic.SecretStr`.
|
||||
- **Fichier `.env`** : **Jamais** committé (couvert par `.gitignore`). Utiliser `.env.example` comme template.
|
||||
|
||||
---
|
||||
|
||||
## 7. Plan de développement
|
||||
|
||||
Le projet suit un plan séquentiel en **15 jalons** (M1-M15) décrits dans [`TODO.md`](./TODO.md).
|
||||
|
||||
- Chaque jalon a des **critères d'acceptation** à valider avant de passer au suivant.
|
||||
- Ordre logique :
|
||||
**scaffolding → config → modèles → sources → sync → synthèse → canaux → pipeline → CLI → tests → déploiement → docs**
|
||||
|
||||
---
|
||||
|
||||
## 8. Référence
|
||||
|
||||
| Document | Rôle |
|
||||
|----------|------|
|
||||
| [`GUIDE_DEV_PYTHON.md`](./GUIDE_DEV_PYTHON.md) | Spécification complète (architecture, modèles, parsing, déploiement) |
|
||||
| [`TODO.md`](./TODO.md) | Plan de développement détaillé (15 jalons) |
|
||||
Reference in New Issue
Block a user