Guide-Agenda-Vacances-Scolaires

Introduction

Le fichier des vacances scolaires permet de filtrer l'agenda théorique afin qu'aucun cours ne soit attendu pendant les périodes de vacances. Ce fichier est optionnel : s'il n'est pas configuré (SCHOOL_HOLIDAYS_PATH absent), le pipeline fonctionne normalement mais ne filtre pas les cours en fonction des vacances. Si l'agenda théorique n'est pas configuré (THEORETICAL_AGENDA_PATH absent), le fichier des vacances scolaires seul n'a aucun effet.

Principe

Les périodes de vacances scolaires sont décrites dans un fichier JSON local. Pendant ces périodes, l'agenda théorique ne retourne aucun cours. Si un cours réel Pronote apparaît pendant une période de vacances, il sera signalé comme un cours ajouté dans la détection des changements.

Variable de configuration

Variable	Description	Obligatoire
`SCHOOL_HOLIDAYS_PATH`	Chemin vers le fichier JSON des vacances scolaires	Non — pas de filtrage si absent

Cette variable est utilisée conjointement avec THEORETICAL_AGENDA_PATH — voir Guide Agenda Théorique.

Format JSON

Voici la structure JSON, illustrée avec l'académie de Bordeaux (zone A, année scolaire 2026-2027) :

{
  "zone": "A",
  "school_year": "2026-2027",
  "periods": [
    { "start_date": "2026-10-17", "end_date": "2026-11-02", "label": "Toussaint" },
    { "start_date": "2026-12-19", "end_date": "2027-01-04", "label": "Noël" },
    { "start_date": "2027-02-13", "end_date": "2027-03-01", "label": "Hiver" },
    { "start_date": "2027-04-10", "end_date": "2027-04-26", "label": "Printemps" },
    { "start_date": "2027-07-03", "end_date": "2027-09-01", "label": "Été" }
  ]
}

Description des champs

Niveau racine

Champ	Type	Description
`zone`	chaîne	Zone académique (ex. `A`, `B`, `C`). Informatif.
`school_year`	chaîne	Année scolaire (ex. `2026-2027`). Informatif.
`periods`	tableau	Liste des périodes de vacances. Peut être vide ou absent.

Chaque période (`periods[]`)

Champ	Type	Description
`start_date`	chaîne `YYYY-MM-DD`	Date de début (incluse)
`end_date`	chaîne `YYYY-MM-DD`	Date de fin (incluse). Doit être ≥ `start_date`.
`label`	chaîne	Nom de la période (ex. `Toussaint`, `Noël`)

Comportement

La fonction is_holiday(date) retourne True si la date tombe dans une période (start_date <= date <= end_date), bornes incluses. Pendant les vacances, l'agenda théorique ne retourne aucun cours. Un cours réel apparaissant pendant les vacances sera signalé comme ajouté dans la détection des changements.

Zones académiques

La France est divisée en 3 zones : A, B, C. Bordeaux fait partie de la zone A. Les zones diffèrent pour les vacances d'hiver et de printemps ; les vacances de la Toussaint, de Noël et d'été sont identiques pour toutes les zones. Le champ zone dans le JSON est purement informatif — il n'a pas d'impact sur le comportement du pipeline. Vous pouvez trouver votre zone sur le calendrier officiel du ministère à l'adresse education.gouv.fr.

Où trouver les dates officielles

Le calendrier scolaire officiel est publié par le ministère de l'Éducation nationale sur education.gouv.fr (rechercher « calendrier scolaire »). Les données sont également disponibles sur data.education.gouv.fr. Les dates sont publiées par académie et par zone.

Créer le fichier

mkdir -p data

Créez le fichier data/school_holidays.json en vous basant sur le format ci-dessus, en utilisant les dates officielles de votre zone.

Exemple de configuration dans `.env`

# --- Agenda théorique ---
THEORETICAL_AGENDA_PATH=./data/theoretical.json
SCHOOL_HOLIDAYS_PATH=./data/school_holidays.json

Sans vacances scolaires (par défaut)

Si vous ne souhaitez pas de filtrage par vacances scolaires, laissez SCHOOL_HOLIDAYS_PATH vide ou absent :

# SCHOOL_HOLIDAYS_PATH=

Cas particuliers

Week-ends : Le calendrier officiel commence les vacances le samedi. Si votre établissement n'a pas cours le samedi, vous pouvez indiquer le lundi suivant comme start_date sans altérer le comportement. Les bornes incluses signifient que le samedi est déjà considéré comme un jour de vacances.
Vacances d'été : L'inclusion des grandes vacances est optionnelle. Si elles sont omises, le calendrier ne filtrera simplement pas les dates pendant l'été — ce qui est généralement acceptable, le pipeline ne synchronisant qu'une fenêtre configurable (SYNC_PAST_DAYS / SYNC_FUTURE_DAYS).

→ Guide Agenda Théorique — configuration complète de l'agenda théorique → Configuration — tableau des variables