Antoine Van Elstraete
a2efd61c4e
- 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)
159 lines
4.9 KiB
Markdown
159 lines
4.9 KiB
Markdown
# 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) |
|