college-infos/AGENTS.md

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.

---

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 pour les 15 jalons (M1-M15).

---

4. Commandes essentielles

Environnement

# Activer le virtualenv
source .venv/bin/activate

# Installer les dépendances de développement
pip install -e ".[dev]"

Qualité de code

# 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

# Exécuter les tests
pytest

# Exécuter les tests avec couverture
pytest --cov

CLI

# 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.

• 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	Spécification complète (architecture, modèles, parsing, déploiement)
TODO.md	Plan de développement détaillé (15 jalons)