{"id":9023,"library":"govuk-bank-holidays","title":"GOV.UK Bank Holidays","description":"This library provides a convenient way to load the official list of bank holidays in the United Kingdom directly from GOV.UK. Currently at version 0.19, it is actively maintained with frequent updates to include new holiday data as published by GOV.UK, alongside regular maintenance for Python version compatibility.","status":"active","version":"0.19","language":"en","source_language":"en","source_url":"https://github.com/ministryofjustice/govuk-bank-holidays","tags":["bank holidays","UK","GOV.UK","dates","public holidays","schedule"],"install":[{"cmd":"pip install govuk-bank-holidays","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"BankHolidays","correct":"from govuk_bank_holidays.bank_holidays import BankHolidays"}],"quickstart":{"code":"from govuk_bank_holidays.bank_holidays import BankHolidays\n\n# Initialize the BankHolidays object (fetches data from GOV.UK by default)\nbank_holidays = BankHolidays()\n\n# Get all bank holidays for England and Wales\nprint(\"Bank holidays for England and Wales:\")\nfor holiday in bank_holidays.get_holidays(division=BankHolidays.ENGLAND_AND_WALES):\n    print(f\"  {holiday['title']} on {holiday['date']}\")\n\n# Get the next upcoming bank holiday for Scotland\nnext_scottish_holiday = bank_holidays.get_next_holiday(division=BankHolidays.SCOTLAND)\nif next_scottish_holiday:\n    print(f\"\\nNext Scottish bank holiday: {next_scottish_holiday['title']} on {next_scottish_holiday['date']}\")\n\n# Use cached holidays only (no internet connection required)\ncached_holidays = BankHolidays(use_cached_holidays=True)\nprint(f\"\\nTotal cached holidays: {len(cached_holidays.get_holidays())}\")","lang":"python","description":"Initializes the `BankHolidays` class, demonstrating how to fetch all holidays for a specific division and retrieve the next upcoming holiday. It also shows how to use the cached holiday data offline."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or newer. Check the library's release notes for the exact supported Python versions for your `govuk-bank-holidays` library version.","message":"Python version compatibility has changed across releases. For example, version 0.12 dropped support for Python versions older than 3.7, version 0.16 dropped support for versions older than 3.9, and version 0.18 removed Python 3.9 support. Ensure your environment uses a currently supported Python version (e.g., 3.10-3.14 for v0.18+).","severity":"breaking","affected_versions":"0.12, 0.16, 0.18"},{"fix":"Always specify a `division` (e.g., `BankHolidays.ENGLAND_AND_WALES`, `BankHolidays.SCOTLAND`, `BankHolidays.NORTHERN_IRELAND`) when calling methods like `get_holidays()` or `get_next_holiday()` to ensure all relevant holidays for that region are included.","message":"When fetching holidays, if no `division` parameter is specified, only holidays common to all UK divisions (England/Wales, Scotland, Northern Ireland) are returned. This will omit division-specific bank holidays.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware that very far-future holiday data might be missing or incomplete. For critical planning, always cross-reference with official GOV.UK sources.","message":"GOV.UK only provides bank holiday data for a year or two into the future. While the library includes a cached backup, it may not be as frequently updated or as comprehensive for distant future dates as the live GOV.UK source.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to version 0.17 or newer to benefit from the built-in download timeout and fallback to cached data.","message":"Version 0.17 introduced a timeout for downloading bank holiday data from GOV.UK. Older versions might hang indefinitely if the GOV.UK source is unavailable or slow.","severity":"gotcha","affected_versions":"<0.17"},{"fix":"Exercise caution when using the Welsh locale (`BankHolidays(locale='cy')`) and verify the accuracy of the holiday titles and notes if relied upon for official purposes.","message":"The Welsh localization (`locale='cy'`) may contain errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Use the constants provided by the `BankHolidays` class for divisions (e.g., `BankHolidays.ENGLAND_AND_WALES`). If parsing raw JSON, ensure you understand its nested structure.","cause":"Attempting to access a bank holiday division using an incorrect or non-existent key, or trying to access specific event properties directly from the raw GOV.UK JSON structure instead of using the library's methods.","error":"KeyError: 'some-division-name'"},{"fix":"The correct import statement is `from govuk_bank_holidays.bank_holidays import BankHolidays`.","cause":"Incorrect import path for the `BankHolidays` class.","error":"AttributeError: module 'govuk_bank_holidays' has no attribute 'BankHolidays'"},{"fix":"Always pass the appropriate division constant to the method, e.g., `bank_holidays.get_holidays(division=BankHolidays.SCOTLAND)` to get holidays specific to Scotland.","cause":"The `division` parameter was not specified when calling methods like `get_holidays()`, leading to only common UK holidays being returned.","error":"No bank holidays returned for a specific region, even though holidays are expected."},{"fix":"Ensure stable internet connectivity. Upgrade the library to version 0.17 or newer for robust timeout handling. Alternatively, initialize with `BankHolidays(use_cached_holidays=True)` to use the locally cached data, bypassing live download.","cause":"Network problems preventing the library from downloading the latest bank holiday data from GOV.UK. This can be exacerbated in older versions (pre-0.17) that lack download timeouts.","error":"requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer')) or similar connection issues."}]}