Workalendar

Warnings

• breaking Compatibility with Python 3.6 was removed in version 17.0.0. Users running Python 3.6 or older must upgrade their Python environment to version 3.7 or newer to use workalendar 17.0.0 and subsequent releases.
  Fix: Upgrade your Python installation to version 3.7 or newer.
• breaking The `skyfield` dependency was transitioned from a core requirement to an optional extra (`workalendar[astronomy]`) in version 16.0.0. Additionally, `pyCalverter` was replaced by `convertdate`. Users relying on astronomical calculations (e.g., for certain Asian calendars) should install the library with the astronomy extra: `pip install workalendar[astronomy]`. It is also recommended to uninstall any previously installed `skyfield` or `skyfield-data` packages to benefit from workalendar's pre-computed astronomical data and performance improvements.
  Fix: If astronomical calculations are needed, install with `pip install workalendar[astronomy]`. Consider `pip uninstall skyfield skyfield-data` if these were previously installed as core dependencies.
• gotcha Some calendars, particularly the Islamic calendar, may not perfectly align with officially declared holidays due to variations in religious authority decisions. Workalendar's computations are based on algorithms, which may sometimes differ from actual observations.
  Fix: For applications requiring absolute precision (e.g., financial systems), always cross-reference computed holidays with official local declarations, especially for culturally sensitive calendars.
• gotcha The library strictly expects standard Python `datetime.date` or `datetime.datetime` objects (or their subclasses from the standard library) as inputs for its core functions. Attempting to pass date-like objects from external, non-standard libraries will raise an `UnsupportedDateType` error.
  Fix: Ensure all date and datetime objects passed to `workalendar` functions are instances of `datetime.date` or `datetime.datetime`.

Install

• pip install workalendar

Imports

• France

  from workalendar.europe import France

  Older versions of workalendar (e.g., pre-1.0) often used class names ending in `Calendar` (e.g., `FranceCalendar`). The modern and recommended pattern is to import the country name directly (e.g., `France`).
• date

  from datetime import date

  The library's functions typically expect standard Python `datetime.date` or `datetime.datetime` objects for date inputs.

Quickstart

This quickstart demonstrates how to instantiate a country-specific calendar, retrieve a list of holidays for a particular year, and check whether a given date is considered a working day.

from datetime import date
from workalendar.europe import France

# Initialize a calendar for a specific country
cal = France()

year = 2024

# Get all holidays for a given year
holidays_2024 = cal.holidays(year)
print(f"Holidays in France for {year}:")
for hol_date, hol_name in holidays_2024:
    print(f"  {hol_date}: {hol_name}")

# Check if a specific day is a working day
test_date_christmas = date(2024, 12, 25) # Christmas Day
test_date_weekday = date(2024, 1, 10) # A Wednesday

print(f"\nIs {test_date_christmas} a working day in France? {cal.is_working_day(test_date_christmas)}")
print(f"Is {test_date_weekday} a working day in France? {cal.is_working_day(test_date_weekday)}")