{"id":4326,"library":"workalendar","title":"Workalendar","description":"Workalendar is a Python library providing a comprehensive toolkit for calculating holidays and working days across various countries and regions worldwide. It's currently at version 17.0.0 and sees regular releases, often driven by updates to national holidays and the addition of new calendars.","status":"active","version":"17.0.0","language":"en","source_language":"en","source_url":"https://github.com/workalendar/workalendar","tags":["holidays","calendar","date calculation","working days","public holidays","business days"],"install":[{"cmd":"pip install workalendar","lang":"bash"}],"dependencies":[{"reason":"Core dependency for date conversions, replaced pyCalverter in v16.0.0.","package":"convertdate"},{"reason":"Optional dependency for astronomy-based calculations (e.g., lunar holidays), moved to an extra ('astronomy') in v16.0.0. If previously installed as a core dependency, it should be uninstalled to benefit from performance gains from pre-computed files.","package":"skyfield","optional":true}],"imports":[{"note":"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`).","wrong":"from workalendar.europe import FranceCalendar","symbol":"France","correct":"from workalendar.europe import France"},{"note":"The library's functions typically expect standard Python `datetime.date` or `datetime.datetime` objects for date inputs.","symbol":"date","correct":"from datetime import date"}],"quickstart":{"code":"from datetime import date\nfrom workalendar.europe import France\n\n# Initialize a calendar for a specific country\ncal = France()\n\nyear = 2024\n\n# Get all holidays for a given year\nholidays_2024 = cal.holidays(year)\nprint(f\"Holidays in France for {year}:\")\nfor hol_date, hol_name in holidays_2024:\n    print(f\"  {hol_date}: {hol_name}\")\n\n# Check if a specific day is a working day\ntest_date_christmas = date(2024, 12, 25) # Christmas Day\ntest_date_weekday = date(2024, 1, 10) # A Wednesday\n\nprint(f\"\\nIs {test_date_christmas} a working day in France? {cal.is_working_day(test_date_christmas)}\")\nprint(f\"Is {test_date_weekday} a working day in France? {cal.is_working_day(test_date_weekday)}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python installation to version 3.7 or newer.","message":"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.","severity":"breaking","affected_versions":">=17.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=16.0.0"},{"fix":"For applications requiring absolute precision (e.g., financial systems), always cross-reference computed holidays with official local declarations, especially for culturally sensitive calendars.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure all date and datetime objects passed to `workalendar` functions are instances of `datetime.date` or `datetime.datetime`.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}