Add SCHOOL category and subdivision hooks for Belgium

docs/holiday_categories.md

@@ -299,6 +299,29 @@ for date, name in sorted(germany_catholic.items()):
     print(f"{date}: {name}")
 ```
 
+### School Holidays Example (Belgium)
+
+Belgium provides school holidays that depend on the educational community.  
+Currently supported subdivisions are:
+
+- `VLG` → Flemish Community  
+- `WBR` → French Community (Wallonia + Brussels French schools)  
+- `GER` → German-speaking Community  
+
+To retrieve only school holidays, use the `SCHOOL` category.
+
+#### Basic Example
+
+```python
+import holidays
+from holidays.constants import SCHOOL
+
+# Flemish Community school holidays
+be_flemish_schools = holidays.Belgium(subdiv="VLG", categories=SCHOOL, years=2026)
+for date, name in sorted(be_flemish_schools.items()):
+    print(date, name)
+```
+
 ### Unofficial Holidays Example
 
 Get unofficial holidays in the United States:
@@ -307,7 +330,7 @@ Get unofficial holidays in the United States:
 import holidays
 from holidays.constants import UNOFFICIAL
 
-us_unofficial = holidays.UnitedStates(categories=UNOFFICIAL, years=2024)
+us_unofficial = holidays.UnitedStates(categories=UNOFFICIAL, years=2022)
 for date, name in sorted(us_unofficial.items()):
     print(f"{date}: {name}")
 ```

holidays/countries/belgium.py

@@ -10,28 +10,65 @@
 #  Website: https://github.com/vacanza/holidays
 #  License: MIT (see LICENSE file)
 
+from datetime import date
 from gettext import gettext as tr
 
-from holidays.constants import BANK, PUBLIC
+from holidays.calendars.gregorian import (
+    APR,
+    AUG,
+    JUL,
+    JUN,
+    SEP,
+    OCT,
+    NOV,
+    DEC,
+    MON,
+    SAT,
+    _timedelta,
+    _get_nth_weekday_from,
+    _get_nth_weekday_of_month,
+)
+from holidays.constants import BANK, PUBLIC, SCHOOL
 from holidays.groups import ChristianHolidays, InternationalHolidays
 from holidays.holiday_base import HolidayBase
 
 
 class Belgium(HolidayBase, ChristianHolidays, InternationalHolidays):
-    """Belgium holidays.
+    """
+    Belgium holidays.
 
     References:
         * <https://en.wikipedia.org/wiki/Public_holidays_in_Belgium>
         * <https://web.archive.org/web/20250331001402/https://www.belgium.be/nl/over_belgie/land/belgie_in_een_notendop/feestdagen>
         * <https://nl.wikipedia.org/wiki/Feestdagen_in_België>
         * <https://web.archive.org/web/20240816004739/https://www.nbb.be/en/about-national-bank/national-bank-belgium/public-holidays>
+        * Official education calendars:
+            - Flemish Community (Vlaanderen)
+            <https://www.vlaanderen.be/onderwijs-en-vorming/wat-mag-en-moet-op-school/schoolvakanties-vrije-dagen-en-afwezigheden/schoolvakanties>
+            - French Community (Fédération Wallonie-Bruxelles)
+            <http://www.enseignement.be/index.php?page=23953>
+            - German-speaking Community (Deutschsprachige Gemeinschaft)
+            <https://ostbelgienbildung.be/desktopdefault.aspx/tabid-2212/4397_read-31727/>
+
+    Notes:
+        * Belgium has three school systems with different vacation rules:
+            - VLG: Flemish Community
+            - WBR: French Community (Wallonia + Brussels French schools)
+            - GER: German-speaking Community (Ostbelgien)
+        * School holiday rules are based on official education calendars.
     """
 
     country = "BE"
     default_language = "nl"
-    supported_categories = (BANK, PUBLIC)
+    supported_categories = (BANK, PUBLIC, SCHOOL)
     supported_languages = ("de", "en_US", "fr", "nl", "uk")
 
+    subdivisions = (
+        "VLG",  # Flemish Community.
+        "WBR",  # French Community (Wallonia + Brussels French schools)
+        "GER",  # German-speaking Community.
+    )
+
     def __init__(self, *args, **kwargs):
         ChristianHolidays.__init__(self)
         InternationalHolidays.__init__(self)
@@ -48,7 +85,7 @@
         self._add_easter_monday(tr("Paasmaandag"))
 
         # Labor Day.
         self._add_labor_day(tr("Dag van de Arbeid"))
 
         # Ascension Day.
         self._add_ascension_thursday(tr("O. L. H. Hemelvaart"))
@@ -84,6 +121,225 @@
         # Bank Holiday.
         self._add_christmas_day_two(tr("Banksluitingsdag"))
 
+    def _add_multiday_holiday(
+        self, start_date: date, duration_days: int, *, name: str | None = None
+    ) -> set[date]:
+        """Override to start adding holidays directly from start_date."""
+        return super()._add_multiday_holiday(
+            _timedelta(start_date, -1),
+            duration_days=duration_days,
+            name=name,
+        )
+
+    def _populate_subdiv_vlg_school_holidays(self):
+        """
+        School holidays for the Flemish Community (Vlaamse Gemeenschap).
+
+        Most vacation periods are rule-based and can be calculated
+        algorithmically, therefore they are implemented here.
+        """
+        year = self._year
+        easter = self._easter_sunday
+
+        # Christmas holidays (week of 25 December).
+        christmas = date(year, DEC, 25)
+        start = _get_nth_weekday_from(-1 if christmas.weekday() <= 4 else 1, 0, christmas)
+        self._add_multiday_holiday(start, 13, name=tr("Kerstvakantie"))
+
+        # Previous year's Christmas (for January spillover).
+        prev_christmas = date(year - 1, DEC, 25)
+        prev_start = _get_nth_weekday_from(
+            -1 if prev_christmas.weekday() <= 4 else 1,
+            0,
+            prev_christmas,
+        )
+        self._add_multiday_holiday(prev_start, 14, name=tr("Kerstvakantie"))
+
+        # Carnival holidays.
+        krokus_raw = _timedelta(easter, days=-47)
+        krokus_start = _get_nth_weekday_from(-1, MON, krokus_raw)
+        self._add_multiday_holiday(krokus_start, 7, name=tr("Krokusvakantie"))
+
+        # Easter holidays.
+        # - March Easter → week before Easter.
+        # - Easter after 15 April → second Monday before Easter.
+        # - Otherwise → first Monday of April.
+        easter_start = _get_nth_weekday_of_month(1, MON, APR, self._year)
+        easter_duration = 14
+
+        if easter.month == 3:
+            easter_start = _timedelta(easter, -6)
+        elif easter.day >= 16:
+            easter_start = _timedelta(easter, -13)
+            easter_duration = 15
+        self._add_multiday_holiday(easter_start, easter_duration, name=tr("Paasvakantie"))
+
+        # Labour Day.
+        self._add_labor_day(tr("Dag van de Arbeid"))
+
+        # Ascension Day.
+        self._add_ascension_thursday(tr("Hemelvaart"))
+
+        # Friday after Ascension.
+        ascension_friday = _timedelta(easter, days=40)
+        self._add_holiday(tr("Vrijdag na O. L. H. Hemelvaart"), ascension_friday)
+
+        # Whit Monday / Pentecost Monday.
+        self._add_whit_monday(tr("Pinkstermaandag"))
+
+        # Summer holidays.
+        start = date(year, JUL, 1)
+        end = date(year, SEP, 1)
+        self._add_multiday_holiday(start, (end - start).days, name=tr("Zomervakantie"))
+
+        # Autumn holidays (week of 1 November).
+        nov_1 = date(year, NOV, 1)
+        start = _get_nth_weekday_from(-1 if nov_1.weekday() <= 5 else 1, 0, nov_1)
+        self._add_multiday_holiday(start, 7, name=tr("Herfstvakantie"))
+
+        # Armistice Day (End of World War I).
+        self._add_remembrance_day(tr("Wapenstilstand"))
+
+    def _populate_subdiv_wbr_school_holidays(self):
+        """
+        School holidays for the French Community (Wallonie-Bruxelles).
+        Based on the official compulsory education calendar.
+        """
+        year = self._year
+        easter = self._easter_sunday
+
+        # Autumn holidays.
+        herfst_start = _get_nth_weekday_of_month(3, MON, OCT, year)
+        self._add_multiday_holiday(herfst_start, 14, name=tr("Herfstvakantie"))
+
+        # current year's Christmas.
+        christmas = date(year, DEC, 25)
+        kerst_start = _get_nth_weekday_from(-1 if christmas.weekday() <= 4 else 1, 0, christmas)
+        self._add_multiday_holiday(kerst_start, 14, name=tr("Kerstvakantie"))
+
+        # Previous year's Christmas (for January spillover).
+        prev_christmas = date(year - 1, DEC, 25)
+        prev_start = _get_nth_weekday_from(
+            -1 if prev_christmas.weekday() <= 4 else 1,
+            0,
+            prev_christmas,
+        )
+        self._add_multiday_holiday(prev_start, 14, name=tr("Kerstvakantie"))
+
+        # Carnival holidays.
+        krokus_raw = _timedelta(easter, days=-49)
+        krokus_start = _get_nth_weekday_from(1, MON, krokus_raw)
+        self._add_multiday_holiday(krokus_start, 14, name=tr("Krokusvakantie"))
+
+        # Spring Holidays.
+        paas_start = _get_nth_weekday_of_month(4, MON, APR, year)
+        self._add_multiday_holiday(paas_start, 14, name=tr("Paasvakantie"))
+
+        # Summer holidays.
+        zomer_start = _get_nth_weekday_of_month(1, SAT, JUL, year)
+
+        # School restart.
+        school_restart = _get_nth_weekday_of_month(4, MON, AUG, year)
+
+        # Summer ends day before school restart.
+        zomer_end = _timedelta(school_restart, -1)
+
+        duration = (zomer_end - zomer_start).days + 1
+
+        self._add_multiday_holiday(
+            zomer_start,
+            duration,
+            name=tr("Zomervakantie"),
+        )
+        # Armistice Day.
+        self._add_remembrance_day(tr("Wapenstilstand"))
+
+        # Labour Day.
+        self._add_labor_day(tr("Dag van de Arbeid"))
+
+        # French Community Day.
+        self._add_holiday(tr("Feestdag van de Franse Gemeenschap"), date(year, SEP, 27))
+
+        # Easter Monday.
+        self._add_easter_monday(tr("Paasmaandag"))
+
+        # Ascension Day.
+        self._add_ascension_thursday(tr("Hemelvaart"))
+
+        # Whit Monday.
+        self._add_whit_monday(tr("Pinkstermaandag"))
+
+    def _populate_subdiv_ger_school_holidays(self):
+        """
+        School holidays for the German-speaking Community (Deutschsprachige Gemeinschaft).
+
+        Based on official education calendar structure.
+        Most vacation periods follow the same framework as other Belgian communities,
+        with Easter holidays starting on the Monday after Easter.
+        """
+        year = self._year
+        easter = self._easter_sunday
+
+        # Christmas holidays (week of 25 December).
+        christmas = date(year, DEC, 25)
+        # if Christmas is on Monday, holiday will start that day.
+        # if Christmas is on Tue-Fri, start the previous Monday.
+        # if Christmas is a Sat/Sun, start the following Monday.
+        start = _get_nth_weekday_from(-1 if christmas.weekday() <= 4 else 1, 0, christmas)
+        self._add_multiday_holiday(start, 13, name=tr("Kerstvakantie"))
+
+        # Previous year's Christmas (for January spillover).
+        prev_christmas = date(year - 1, DEC, 25)
+        prev_start = _get_nth_weekday_from(
+            -1 if prev_christmas.weekday() <= 4 else 1,
+            0,
+            prev_christmas,
+        )
+        self._add_multiday_holiday(prev_start, 13, name=tr("Kerstvakantie"))
+
+        # Carnival holidays.
+        krokus_raw = _timedelta(easter, days=-47)
+        krokus_start = _get_nth_weekday_from(-1, MON, krokus_raw)
+        self._add_multiday_holiday(krokus_start, 6, name=tr("Krokusvakantie"))
+
+        # Easter holidays.
+        # - March Easter → week before Easter.
+        # - Easter after 15 April → second Monday before Easter.
+        # - Otherwise → first Monday of April.
+        paas_start = _timedelta(easter, 1)  # Monday after Easter
+        self._add_multiday_holiday(paas_start, 13, name=tr("Paasvakantie"))
+
+        # Summer holidays.
+        start = date(year, JUN, 30)
+        end = date(year, SEP, 1)
+        self._add_multiday_holiday(start, (end - start).days, name=tr("Zomervakantie"))
+
+        # Autumn holidays (week of 1 November).
+        nov_1 = date(year, NOV, 1)
+        start = _get_nth_weekday_from(-1 if nov_1.weekday() <= 5 else 1, 0, nov_1)
+        self._add_multiday_holiday(start, 6, name=tr("Herfstvakantie"))
+
+        # Armistice Day.
+        self._add_remembrance_day(tr("Wapenstilstand"))
+
+        # Labour Day.
+        self._add_labor_day(tr("Dag van de Arbeid"))
+
+        # German Community Day.
+        self._add_holiday(tr("Feestdag van de Duitstalige Gemeenschap"), date(year, NOV, 15))
+
+        # Easter Monday.
+        self._add_easter_monday(tr("Paasmaandag"))
+
+        # Ascension Day.
+        self._add_ascension_thursday(tr("Hemelvaart"))
+
+        # Whit Monday.
+        self._add_whit_monday(tr("Pinkstermaandag"))
+
+        # Christmas Eve (observed in German-speaking schools).
+        self._add_holiday(tr("Heiligavond"), date(year, DEC, 24))
+
 
 class BE(Belgium):
     pass

holidays/locale/de/LC_MESSAGES/BE.po

@@ -87,3 +87,35 @@ msgstr "Freitag nach Christi Himmelfahrt"
 #. Bank Holiday.
 msgid "Banksluitingsdag"
 msgstr "Bankschlusstag"
+
+#. Christmas Holidays.
+msgid "Kerstvakantie"
+msgstr "Weihnachtsferien"
+
+#. Carnival Holidays.
+msgid "Krokusvakantie"
+msgstr "Karnevalsferien"
+
+#. Easter Holidays.
+msgid "Paasvakantie"
+msgstr "Osterferien"
+
+#. Summer Holidays.
+msgid "Zomervakantie"
+msgstr "Sommerferien"
+
+#. Autumn Holidays.
+msgid "Herfstvakantie"
+msgstr "Herbstferien"
+
+#. French Community Day.
+msgid "Feestdag van de Franse Gemeenschap"
+msgstr "Feiertag der Französischen Gemeinschaft"
+
+#. German-speaking Community Day.
+msgid "Feestdag van de Duitstalige Gemeenschap"
+msgstr "Feiertag der Deutschsprachigen Gemeinschaft"
+
+#. Christmas Eve.
+msgid "Heiligavond"
+msgstr "Heiligabend"