API Reference

Bases: dict[date, str]

Represent a dictionary-like collection of holidays for a specific country or region.

This class inherits from dict and maps holiday dates to their names. It supports customization by country and, optionally, by province or state (subdivision). A date not present as a key is not considered a holiday (or, if observed is False, not considered an observed holiday).

Keys are holiday dates, and values are corresponding holiday names. When accessing or assigning holidays by date, the following input formats are accepted:

• datetime.date
• datetime.datetime
• float or int (Unix timestamp)
• str of any format recognized by dateutil.parser.parse()

Keys are always returned as datetime.date objects.

To maximize performance, the holiday list is lazily populated one year at a time. On instantiation, the object is empty. Once a date is accessed, the full calendar year for that date is generated, unless expand is set to False. To pre-populate holidays, instantiate the class with the years argument:

us_holidays = holidays.US(years=2020)

It is recommended to use the country_holidays() function for instantiation.

Example usage:

>>> from holidays import country_holidays
>>> us_holidays = country_holidays('US')
# For a specific subdivisions (e.g. state or province):
>>> california_holidays = country_holidays('US', subdiv='CA')

The below will cause 2015 holidays to be calculated on the fly:

>>> from datetime import date
>>> assert date(2015, 1, 1) in us_holidays

This will be faster because 2015 holidays are already calculated:

>>> assert date(2015, 1, 2) not in us_holidays

The HolidayBase class also recognizes strings of many formats and numbers representing a POSIX timestamp:

>>> assert '2014-01-01' in us_holidays
>>> assert '1/1/2014' in us_holidays
>>> assert 1388597445 in us_holidays

Show the holiday's name:

>>> us_holidays.get('2014-01-01')
"New Year's Day"

Check a range:

>>> us_holidays['2014-01-01': '2014-01-03']
[datetime.date(2014, 1, 1)]

List all 2020 holidays:

>>> us_holidays = country_holidays('US', years=2020)
>>> for day in sorted(us_holidays.items()):
...     print(day)
(datetime.date(2020, 1, 1), "New Year's Day")
(datetime.date(2020, 1, 20), 'Martin Luther King Jr. Day')
(datetime.date(2020, 2, 17), "Washington's Birthday")
(datetime.date(2020, 5, 25), 'Memorial Day')
(datetime.date(2020, 7, 3), 'Independence Day (observed)')
(datetime.date(2020, 7, 4), 'Independence Day')
(datetime.date(2020, 9, 7), 'Labor Day')
(datetime.date(2020, 10, 12), 'Columbus Day')
(datetime.date(2020, 11, 11), 'Veterans Day')
(datetime.date(2020, 11, 26), 'Thanksgiving Day')
(datetime.date(2020, 12, 25), 'Christmas Day')

Some holidays are only present in parts of a country:

>>> us_pr_holidays = country_holidays('US', subdiv='PR')
>>> assert '2018-01-06' not in us_holidays
>>> assert '2018-01-06' in us_pr_holidays

Append custom holiday dates by passing one of the following:

• A dict mapping date values to holiday names (e.g. {'2010-07-10': 'My birthday!'}).
• A list of date values (datetime.date, datetime.datetime, str, int, or float); each will be added with 'Holiday' as the default name.
• A single date value of any of the supported types above; 'Holiday' will be used as the default name.

>>> custom_holidays = country_holidays('US', years=2015)
>>> custom_holidays.update({'2015-01-01': "New Year's Day"})
>>> custom_holidays.update(['2015-07-01', '07/04/2015'])
>>> custom_holidays.update(date(2015, 12, 25))
>>> assert date(2015, 1, 1) in custom_holidays
>>> assert date(2015, 1, 2) not in custom_holidays
>>> assert '12/25/2015' in custom_holidays

For special (one-off) country-wide holidays handling use special_public_holidays:

special_public_holidays = {
    1977: ((JUN, 7, "Silver Jubilee of Elizabeth II"),),
    1981: ((JUL, 29, "Wedding of Charles and Diana"),),
    1999: ((DEC, 31, "Millennium Celebrations"),),
    2002: ((JUN, 3, "Golden Jubilee of Elizabeth II"),),
    2011: ((APR, 29, "Wedding of William and Catherine"),),
    2012: ((JUN, 5, "Diamond Jubilee of Elizabeth II"),),
    2022: (
        (JUN, 3, "Platinum Jubilee of Elizabeth II"),
        (SEP, 19, "State Funeral of Queen Elizabeth II"),
    ),
}

def _populate(self, year):
    super()._populate(year)

    ...

For more complex logic, like 4th Monday of January, you can inherit the HolidayBase class and define your own _populate() method. See documentation for examples.

Bases: HolidayBase

Combine multiple holiday collections into a single dictionary-like object.

This class represents the sum of two or more HolidayBase instances. The resulting object behaves like a dictionary mapping dates to holiday names, with the following behaviors:

• The holidays attribute stores the original holiday collections as a list.
• The country and subdiv attributes are combined from all operands and may become lists.
• If multiple holidays fall on the same date, their names are merged.
• Holidays are generated (expanded) for all years included in the operands.

Example:

>>> from holidays import country_holidays
>>> nafta_holidays = country_holidays('US', years=2020) +     country_holidays('CA') + country_holidays('MX')
>>> dates = sorted(nafta_holidays.items(), key=lambda x: x[0])
>>> from pprint import pprint
>>> pprint(dates[:10], width=72)
[(datetime.date(2020, 1, 1), "Año Nuevo; New Year's Day"),
 (datetime.date(2020, 1, 20), 'Martin Luther King Jr. Day'),
 (datetime.date(2020, 2, 3), 'Día de la Constitución'),
 (datetime.date(2020, 2, 17), "Washington's Birthday"),
 (datetime.date(2020, 3, 16), 'Natalicio de Benito Juárez'),
 (datetime.date(2020, 4, 10), 'Good Friday'),
 (datetime.date(2020, 5, 1), 'Día del Trabajo'),
 (datetime.date(2020, 5, 25), 'Memorial Day'),
 (datetime.date(2020, 7, 1), 'Canada Day'),
 (datetime.date(2020, 7, 3), 'Independence Day (observed)')]

Initialize iCalendar exporter.