GOV.UK Bank Holidays

Common errors

• KeyError: 'some-division-name'

  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.
  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.

• AttributeError: module 'govuk_bank_holidays' has no attribute 'BankHolidays'

  cause Incorrect import path for the `BankHolidays` class.
  fix The correct import statement is `from govuk_bank_holidays.bank_holidays import BankHolidays`.

• No bank holidays returned for a specific region, even though holidays are expected.

  cause The `division` parameter was not specified when calling methods like `get_holidays()`, leading to only common UK holidays being returned.
  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.

• requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer')) or similar connection issues.

  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.
  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.

Warnings

• breaking 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+).
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Upgrade to version 0.17 or newer to benefit from the built-in download timeout and fallback to cached data.
• gotcha The Welsh localization (`locale='cy'`) may contain errors.
  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.

Install

• pip install govuk-bank-holidays Install latest version

Imports

• BankHolidays

  from govuk_bank_holidays.bank_holidays import BankHolidays

Quickstart

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.

from govuk_bank_holidays.bank_holidays import BankHolidays

# Initialize the BankHolidays object (fetches data from GOV.UK by default)
bank_holidays = BankHolidays()

# Get all bank holidays for England and Wales
print("Bank holidays for England and Wales:")
for holiday in bank_holidays.get_holidays(division=BankHolidays.ENGLAND_AND_WALES):
    print(f"  {holiday['title']} on {holiday['date']}")

# Get the next upcoming bank holiday for Scotland
next_scottish_holiday = bank_holidays.get_next_holiday(division=BankHolidays.SCOTLAND)
if next_scottish_holiday:
    print(f"\nNext Scottish bank holiday: {next_scottish_holiday['title']} on {next_scottish_holiday['date']}")

# Use cached holidays only (no internet connection required)
cached_holidays = BankHolidays(use_cached_holidays=True)
print(f"\nTotal cached holidays: {len(cached_holidays.get_holidays())}")