API Reference

holidays.utils.country_holidays(country, subdiv=None, years=None, expand=True, observed=True, prov=None, state=None, language=None, categories=None)

Returns a new dictionary-like HolidayBase object for the public holidays of the country matching country and other keyword arguments.

Parameters:
  • country (str) – An ISO 3166-1 Alpha-2 country code.

  • subdiv (str | None) – The subdivision (e.g. state or province) as a ISO 3166-2 code or its alias; not implemented for all countries (see documentation).

  • years (int | Iterable[int] | None) – The year(s) to pre-calculate public holidays for at instantiation.

  • expand (bool) – Whether the entire year is calculated when one date from that year is requested.

  • observed (bool) – Whether to include the dates of when public holiday are observed (e.g. a holiday falling on a Sunday being observed the following Monday). False may not work for all countries.

  • prov (str | None) – deprecated use subdiv instead.

  • state (str | None) – deprecated use subdiv instead.

  • language (str | None) – The language which the returned holiday names will be translated into. It must be an ISO 639-1 (2-letter) language code. If the language translation is not supported the original holiday names will be used.

  • categories (Tuple[str] | None) – Requested holiday categories.

Returns:

A HolidayBase object matching the country.

Return type:

HolidayBase

The key of the dict-like HolidayBase object is the date of the holiday, and the value is the name of the holiday itself. Dates where a key is not present are not public holidays (or, if observed is False, days when a public holiday is observed).

When passing the date as a key, the date can be expressed in one of the following types:

  • datetime.date,

  • datetime.datetime,

  • a str of any format recognized by dateutil.parser.parse(),

  • or a float or int representing a POSIX timestamp.

The key is always returned as a datetime.date object.

To maximize speed, the list of public holidays is built on the fly as needed, one calendar year at a time. When the object is instantiated without a years parameter, it is empty, but, unless expand is set to False, as soon as a key is accessed the class will calculate that entire year’s list of holidays and set the keys with them.

If you need to list the holidays as opposed to querying individual dates, instantiate the class with the years parameter.

Example usage:

>>> from holidays import country_holidays
>>> us_holidays = country_holidays('US')
# For a specific subdivision (e.g. state or province):
>>> calif_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 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, 4), 'Independence Day')
(datetime.date(2020, 7, 3), 'Independence Day (observed)')
(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')
(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:

  • a dict with date/name key/value pairs (e.g. {'2010-07-10': 'My birthday!'}),

  • a list of dates (as a datetime.date, datetime.datetime, str, int, or float); 'Holiday' will be used as a description,

  • or a single date item (of one of the types above); 'Holiday' will be used as a description:

>>> 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 more complex logic, like 4th Monday of January, you can inherit the HolidayBase class and define your own _populate() method. See documentation for examples.

holidays.utils.financial_holidays(market, subdiv=None, years=None, expand=True, observed=True, language=None)

Returns a new dictionary-like HolidayBase object for the public holidays of the financial market matching market and other keyword arguments.

Parameters:
  • market (str) – An ISO 3166-1 Alpha-2 market code.

  • subdiv (str | None) – Currently not implemented for markets (see documentation).

  • years (int | Iterable[int] | None) – The year(s) to pre-calculate public holidays for at instantiation.

  • expand (bool) – Whether the entire year is calculated when one date from that year is requested.

  • observed (bool) – Whether to include the dates of when public holiday are observed (e.g. a holiday falling on a Sunday being observed the following Monday). False may not work for all countries.

  • language (str | None) – The language which the returned holiday names will be translated into. It must be an ISO 639-1 (2-letter) language code. If the language translation is not supported the original holiday names will be used.

Returns:

A HolidayBase object matching the market.

Return type:

HolidayBase

Example usage:

>>> from holidays import financial_holidays
>>> nyse_holidays = financial_holidays('NYSE')

See country_holidays() documentation for further details and examples.

holidays.utils.list_localized_countries(include_aliases=True)

Get all localized countries and languages they support.

Parameters:

include_aliases – Whether to include entity aliases (e.g. UK for GB).

Returns:

A dictionary where key is an ISO 3166-1 alpha-2 country code and value is a list of supported languages (either ISO 639-1 or a combination of ISO 639-1 and ISO 3166-1 codes joined with “_”).

Return type:

Dict[str, List[str]]

holidays.utils.list_localized_financial(include_aliases=True)

Get all localized financial markets and languages they support.

Parameters:

include_aliases – Whether to include entity aliases(e.g. TAR for ECB, XNYS for NYSE).

Returns:

A dictionary where key is a market code and value is a list of supported subdivision codes.

Return type:

Dict[str, List[str]]

holidays.utils.list_supported_countries(include_aliases=True)

Get all supported countries and their subdivisions.

Parameters:

include_aliases – Whether to include entity aliases (e.g. UK for GB).

Returns:

A dictionary where key is an ISO 3166-1 alpha-2 country code and value is a list of supported subdivision codes.

Return type:

Dict[str, List[str]]

holidays.utils.list_supported_financial(include_aliases=True)

Get all supported financial markets and their subdivisions.

Parameters:

include_aliases – Whether to include entity aliases(e.g. TAR for ECB, XNYS for NYSE).

Returns:

A dictionary where key is a market code and value is a list of supported subdivision codes.

Return type:

Dict[str, List[str]]

class holidays.holiday_base.HolidayBase(years=None, expand=True, observed=True, subdiv=None, prov=None, state=None, language=None, categories=None)

Bases: Dict[date, str]

A dict-like object containing the holidays for a specific country (and province or state if so initiated); inherits the dict class (so behaves similarly to a dict). Dates without a key in the Holiday object are not holidays.

The key of the object is the date of the holiday and the value is the name of the holiday itself. When passing the date as a key, the date can be expressed as one of the following formats:

  • datetime.datetime type;

  • datetime.date types;

  • a float representing a Unix timestamp;

  • or a string of any format (recognized by datetime.parse).

The key is always returned as a datetime.date object.

To maximize speed, the list of holidays is built as needed on the fly, one calendar year at a time. When you instantiate the object, it is empty, but the moment a key is accessed it will build that entire year’s list of holidays. To pre-populate holidays, instantiate the class with the years argument:

us_holidays = holidays.US(years=2020)

It is generally instantiated using the country_holidays() function.

The key of the dict-like HolidayBase object is the date of the holiday, and the value is the name of the holiday itself. Dates where a key is not present are not public holidays (or, if observed is False, days when a public holiday is observed).

When passing the date as a key, the date can be expressed in one of the following types:

  • datetime.date,

  • datetime.datetime,

  • a str of any format recognized by dateutil.parser.parse(),

  • or a float or int representing a POSIX timestamp.

The key is always returned as a datetime.date object.

To maximize speed, the list of public holidays is built on the fly as needed, one calendar year at a time. When the object is instantiated without a years parameter, it is empty, but, unless expand is set to False, as soon as a key is accessed the class will calculate that entire year’s list of holidays and set the keys with them.

If you need to list the holidays as opposed to querying individual dates, instantiate the class with the years parameter.

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 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, 4), 'Independence Day')
(datetime.date(2020, 7, 3), 'Independence Day (observed)')
(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')
(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:

  • a dict with date/name key/value pairs (e.g. {'2010-07-10': 'My birthday!'}),

  • a list of dates (as a datetime.date, datetime.datetime, str, int, or float); 'Holiday' will be used as a description,

  • or a single date item (of one of the types above); 'Holiday' will be used as a description:

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

Parameters:
  • years (Set[int]) – The year(s) to pre-calculate public holidays for at instantiation.

  • expand (bool) – Whether the entire year is calculated when one date from that year is requested.

  • observed (bool) – Whether to include the dates when public holiday are observed (e.g. a holiday falling on a Sunday being observed the following Monday). This doesn’t work for all countries.

  • subdiv (str | None) – The subdivision (e.g. state or province) as a ISO 3166-2 code or its alias; not implemented for all countries (see documentation).

  • prov (str | None) – deprecated use subdiv instead.

  • state (str | None) – deprecated use subdiv instead.

  • language (str | None) – The language which the returned holiday names will be translated into. It must be an ISO 639-1 (2-letter) language code. If the language translation is not supported the original holiday names will be used.

  • categories (Set[str]) – Requested holiday categories.

Returns:

A HolidayBase object matching the country.

country: str

The country’s ISO 3166-1 alpha-2 code.

market: str

The market’s ISO 3166-1 alpha-2 code.

subdivisions: Tuple[str, ...] = ()

The subdivisions supported for this country (see documentation).

subdivisions_aliases: Dict[str, str] = {}

Aliases for the ISO 3166-2 subdivision codes with the key as alias and the value the ISO 3166-2 subdivision code.

special_holidays: Dict[int, Tuple[int, int, str] | Tuple[Tuple[int, int, str], ...] | Tuple[int, int, int, int] | Tuple[int, int, int, int, int] | Tuple[Tuple[int, int, int, int] | Tuple[int, int, int, int, int], ...]] = {}

A list of the country-wide special (as opposite to regular) holidays for a specific year.

weekend: Set[int] = {5, 6}

Country weekend days.

default_category: str = 'public'

The entity category used by default.

default_language: str | None = None

The entity language used by default.

supported_categories: Tuple[str, ...] = ('public',)

All holiday categories supported by this entity.

supported_languages: Tuple[str, ...] = ()

All languages supported by this entity.

categories: Set[str] = {}

Requested holiday categories.

expand: bool

Whether the entire year is calculated when one date from that year is requested.

observed: bool

Whether dates when public holiday are observed are included.

subdiv: str | None = None

The subdiv requested as ISO 3166-2 code or one of the aliases.

years: Set[int]

The years calculated.

classmethod get_subdivision_aliases()

Get subdivision aliases.

Return type:

Dict[str, List]

append(*args)

Alias for update() to mimic list type.

Parameters:

args (Dict[date | datetime | str | float | int, str] | List[date | datetime | str | float | int] | date | datetime | str | float | int) –

Return type:

None

copy()

Return a copy of the object.

get(key, default=None)

Return the holiday name for a date if date is a holiday, else default. If default is not given, it defaults to None, so that this method never raises a KeyError. If more than one holiday is present, they are separated by a comma.

Parameters:
  • key (date | datetime | str | float | int) –

    The date expressed in one of the following types:

    • datetime.date,

    • datetime.datetime,

    • a str of any format recognized by dateutil.parser.parse(),

    • or a float or int representing a POSIX timestamp.

  • default (str | Any) – The default value to return if no value is found.

Return type:

str | Any

get_list(key)

Return a list of all holiday names for a date if date is a holiday, else empty string.

Parameters:

key (date | datetime | str | float | int) –

The date expressed in one of the following types:

  • datetime.date,

  • datetime.datetime,

  • a str of any format recognized by dateutil.parser.parse(),

  • or a float or int representing a POSIX timestamp.

Return type:

List[str]

get_named(holiday_name, lookup='icontains', split_multiple_names=True)

Return a list of all holiday dates matching the provided holiday name. The match will be made case insensitively and partial matches will be included by default.

Parameters:
  • holiday_name (str) – The holiday’s name to try to match.

  • lookup

    The holiday name lookup type:

    contains - case sensitive contains match; exact - case sensitive exact match; startswith - case sensitive starts with match; icontains - case insensitive contains match; iexact - case insensitive exact match; istartswith - case insensitive starts with match;

  • split_multiple_names – Either use the exact name for each date or split it by holiday name delimiter.

Returns:

A list of all holiday dates matching the provided holiday name.

Return type:

List[date]

pop(key, default=None)

If date is a holiday, remove it and return its date, else return default.

Parameters:
  • key (date | datetime | str | float | int) –

    The date expressed in one of the following types:

    • datetime.date,

    • datetime.datetime,

    • a str of any format recognized by dateutil.parser.parse(),

    • or a float or int representing a POSIX timestamp.

  • default (str | Any) – The default value to return if no match is found.

Returns:

The date removed.

Raise:

KeyError if date is not a holiday and default is not given.

Return type:

str | Any

pop_named(name)

Remove (no longer treat at as holiday) all dates matching the provided holiday name. The match will be made case insensitively and partial matches will be removed.

Parameters:
  • name (str) – The holiday’s name to try to match.

  • default – The default value to return if no match is found.

Returns:

A list of dates removed.

Raise:

KeyError if date is not a holiday and default is not given.

Return type:

List[date]

update(*args)

Update the object, overwriting existing dates.

Param:

Either another dictionary object where keys are dates and values are holiday names, or a single date (or a list of dates) for which the value will be set to “Holiday”.

Dates can be expressed in one or more of the following types:

  • datetime.date,

  • datetime.datetime,

  • a str of any format recognized by dateutil.parser.parse(),

  • or a float or int representing a POSIX timestamp.

Parameters:

args (Dict[date | datetime | str | float | int, str] | List[date | datetime | str | float | int] | date | datetime | str | float | int) –

Return type:

None

class holidays.holiday_base.HolidaySum(h1, h2)

Bases: HolidayBase

Returns a dict-like object resulting from the addition of two or more individual dictionaries of public holidays. The original dictionaries are available as a list in the attribute holidays, and country and subdiv attributes are added together and could become list s. Holiday names, when different, are merged. All years are calculated (expanded) for all operands.

Parameters:

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"),
 (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, Family Day"),
 (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, 18), 'Victoria Day')]
country: str | List[str]

Countries included in the addition.

market: str | List[str]

Markets included in the addition.

years: Set[int]

The years calculated.

holidays: List[HolidayBase]

The original HolidayBase objects included in the addition.