dates.bank-holidays

def bank_holidays(region: UkRegion, year: int) -> List[BankHoliday]

UkRegion = Literal["england-and-wales", "scotland", "northern-ireland"]

@dataclass(frozen=True)
class BankHoliday:
    """One day off, as gov.uk lists it."""

    date: str
    #: gov.uk's own wording, e.g. "Boxing Day"
    title: str
    #: true when this is a substitute weekday for a holiday that fell at a weekend
    substitute: bool

from fune.dates.bank_holidays import bank_holidays  # dates.bank-holidays@^1

from typing import List, Optional

from .dates_bank_holidays_data import BANK_HOLIDAYS  ← this capability’s own data, compiled from data/bank-holidays.json into the same file by fune build
from .dates_bank_holidays_types import BankHoliday, UkRegion


def bank_holidays(region: UkRegion, year: int) -> List[BankHoliday]:
    """The bank holidays for a UK region and year, in date order, as gov.uk
    publishes them.

    A year the data does not cover is an error rather than an empty list,
    because an empty list reads as "no holidays" and a deadline calculation
    would then count Christmas Day as a working day.
    """
    if isinstance(year, bool) or not isinstance(year, int):
        raise TypeError("year must be an integer, received %r" % (year,))
    first: Optional[int] = None
    last: Optional[int] = None
    found: List[BankHoliday] = []
    prefix = "%04d-" % (year,)
    for row in BANK_HOLIDAYS:
        if row.region != region:
            continue
        row_year = int(row.date[0:4])
        if first is None or row_year < first:
            first = row_year
        if last is None or row_year > last:
            last = row_year
        if row.date.startswith(prefix):
            found.append(BankHoliday(date=row.date, title=row.title, substitute=row.substitute))
    if first is None or last is None:
        raise ValueError(
            'unknown region "%s": expected england-and-wales, scotland or northern-ireland' % (region,)
        )
    if year < first or year > last:
        raise ValueError(
            "no bank holiday data for %s in %s: the published calendar covers %s to %s" % (region, year, first, last)
        )
    # ISO dates sort correctly as strings.
    return sorted(found, key=lambda holiday: holiday.date)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add dates.bank-holidays

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./dates.bank-holidays-1.0.1-python.fune, or fetch it from a terminal with fune pull dates.bank-holidays@1.0.1:python.

The whole function, every language, is one file too: dates.bank-holidays-1.0.1.fune, 59,839 bytes, sha256 0b3290c1a820afe756b41df29850449ee4c8ae1ddc5834ea7012cf5f094edaf1. It installs into a project of any language.

# fune: before dates.bank-holidays

# fune: after dates.bank-holidays

# fune: step dates.bank-holidays after <n|label>

More from the author

The holidays are data, not rules in code. Easter moves, holidays falling on a weekend are substituted by proclamation, and one-off holidays are added at a few months' notice: the Platinum Jubilee (3 June 2022, which also moved the spring holiday to 2 June), the State Funeral of Queen Elizabeth II (19 September 2022), the coronation of King Charles III (8 May 2023), the VE day move of the early May holiday (8 May 2020) and Scotland's World Cup bank holiday (15 June 2026). No formula produces those, which is why this is a table. When gov.uk publishes another year or another one-off holiday, that is a new version of this capability, not a code change.

A year outside the published range is an error, not an empty list. An empty list would read as "no holidays that year", and a deadline calculation would silently count Christmas Day as a working day.

The data deliberately has no `effective` columns. A bank holiday is an event on a date, not a rule that stays in force until superseded, so there is nothing for `history=current` to keep; declaring the columns would let a project-wide history setting prune the whole calendar away.

This lists days, it does not count them. To skip holidays in working-day arithmetic, pass the dates to dates.add-business-days or dates.business-days-between, which take an explicit holiday list so they work for any country and any employer's closure days.

## Notices

Contains public sector information licensed under the Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

1.0.1 adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files