search

vacanza / holidays

Open World Holidays Framework
https://pypi.org/project/holidays
MIT License
1.49k stars 468 forks source link
calendar holiday holiday-api holiday-calculation python

readme

======== holidays

A fast, efficient Python library for generating country- and subdivision- (e.g. state or province) specific sets of government-designated holidays on the fly. It aims to make determining whether a specific date is a holiday as fast and flexible as possible.

.. |downloads| image:: https://img.shields.io/pypi/dm/holidays?color=41B5BE&style=flat :target: https://pypi.org/project/holidays :alt: PyPI downloads

.. |version| image:: https://img.shields.io/pypi/v/holidays?color=41B5BE&label=version&style=flat :target: https://pypi.org/project/holidays :alt: PyPI version

.. |release date| image:: https://img.shields.io/github/release-date/vacanza/holidays?color=41B5BE&style=flat :target: https://github.com/vacanza/holidays/releases :alt: PyPI release date

.. |status| image:: https://img.shields.io/github/actions/workflow/status/vacanza/holidays/ci-cd.yml?branch=dev&color=41BE4A&style=flat :target: https://github.com/vacanza/holidays/actions/workflows/ci-cd.yml?query=branch%3Adev :alt: CI/CD status

.. |documentation| image:: https://img.shields.io/readthedocs/holidays?color=41BE4A&style=flat :target: https://holidays.readthedocs.io/en/latest/?badge=latest :alt: Documentation status

.. |license| image:: https://img.shields.io/github/license/vacanza/holidays?color=41B5BE&style=flat :target: https://github.com/vacanza/holidays/blob/dev/LICENSE :alt: License

.. |python versions| image:: https://img.shields.io/pypi/pyversions/holidays?label=python&color=41B5BE&style=flat :target: https://pypi.org/project/holidays :alt: Python supported versions

.. |style| image:: https://img.shields.io/badge/style-ruff-41B5BE?style=flat :target: https://github.com/astral-sh/ruff :alt: Code style

.. |coverage| image:: https://img.shields.io/codecov/c/github/vacanza/holidays/dev?color=41B5BE&style=flat :target: https://app.codecov.io/gh/vacanza/holidays :alt: Code coverage

.. |stars| image:: https://img.shields.io/github/stars/vacanza/holidays?color=41BE4A&style=flat :target: https://github.com/vacanza/holidays/stargazers :alt: GitHub stars

.. |forks| image:: https://img.shields.io/github/forks/vacanza/holidays?color=41BE4A&style=flat :target: https://github.com/vacanza/holidays/forks :alt: GitHub forks

.. |contributors| image:: https://img.shields.io/github/contributors/vacanza/holidays?color=41BE4A&style=flat :target: https://github.com/vacanza/holidays/graphs/contributors :alt: GitHub contributors

.. |last commit| image:: https://img.shields.io/github/last-commit/vacanza/holidays/dev?color=41BE4A&style=flat :target: https://github.com/vacanza/holidays/commits/dev :alt: GitHub last commit

+--------+------------------------------------------------+ | PyPI | |downloads| |version| |release date| | +--------+------------------------------------------------+ | CI/CD | |status| |documentation| | +--------+------------------------------------------------+ | Code | |license| |python versions| |style| |coverage| | +--------+------------------------------------------------+ | GitHub | |stars| |forks| |contributors| |last commit| | +--------+------------------------------------------------+

Install

The latest stable version can always be installed or updated via pip:

.. code-block:: shell

$ pip install --upgrade holidays

The latest development (dev) version can be installed directly from GitHub:

.. code-block:: shell

$ pip install --upgrade https://github.com/vacanza/holidays/tarball/dev

All new features are always first pushed to dev branch, then released on main branch upon official version upgrades.

Documentation

.. _Read the Docs: https://holidays.readthedocs.io/

The documentation is hosted on Read the Docs_.

Quick Start

.. code-block:: python

from datetime import date
import holidays

us_holidays = holidays.US()  # this is a dict-like object
# the below is the same, but takes a string:
us_holidays = holidays.country_holidays('US')  # this is a dict-like object

nyse_holidays = holidays.NYSE()  # this is a dict-like object
# the below is the same, but takes a string:
nyse_holidays = holidays.financial_holidays('NYSE')  # this is a dict-like object

date(2015, 1, 1) in us_holidays  # True
date(2015, 1, 2) in us_holidays  # False
us_holidays.get('2014-01-01')  # "New Year's Day"

The HolidayBase dict-like class will also recognize date strings and Unix timestamps:

.. code-block:: python

'2014-01-01' in us_holidays  # True
'1/1/2014' in us_holidays    # True
1388597445 in us_holidays    # True

Some holidays may be only present in parts of a country:

.. code-block:: python

us_pr_holidays = holidays.country_holidays('US', subdiv='PR')
'2018-01-06' in us_holidays     # False
'2018-01-06' in us_pr_holidays  # True

.. _holidays documentation: https://holidays.readthedocs.io/

Please see the holidays documentation_ for additional examples and detailed information.

Available Countries

.. _ISO 3166-1 alpha-2 code: https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes .. _ISO 3166-2 code: https://en.wikipedia.org/wiki/ISO_3166-2 .. _ISO 639-1 code: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes .. _ISO 639-2 code: https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes

We currently support 155 country codes. The standard way to refer to a country is by using its ISO 3166-1 alpha-2 code, the same used for domain names, and for a subdivision its ISO 3166-2 code. Some countries have common or foreign names or abbreviations as aliases for their subdivisions. These are defined in the (optional) subdivisions_aliases attribute. Some of the countries support more than one language for holiday names output. A default language is defined by default_language (optional) attribute for each entity and is used as a fallback when neither user specified language nor user locale language available. The default language code is a ISO 639-1 code_. A list of all languages supported by country is defined by supported_languages (optional) attribute. If there is no designated ISO 639-1 code then ISO 639-2 code can be used.

Many countries have other categories of holidays in addition to common (national-wide) holidays: bank holidays, school holidays, additional (paid or non-paid) holidays, holidays of state or public employees, religious holidays (valid only for these religions followers). A list of all categories supported by country is defined by supported_categories (optional) attribute.

The following is a list of supported countries, their subdivisions followed by their aliases (if any) in brackets, available languages and additional holiday categories. All countries support PUBLIC holidays category by default. All other default values are highlighted with bold:

.. list-table:: :widths: 20 4 46 20 10 :header-rows: 1 :class: tight-table

Available Financial Markets

.. _ISO 10383 MIC: https://www.iso20022.org/market-identifier-codes

The standard way to refer to a financial market is to use its ISO 10383 MIC_ (Market Identifier Code) as a "country" code when available. The following financial markets are available:

.. list-table:: :widths: 23 4 83 20 :header-rows: 1 :class: tight-table

Contributions

.. _Issues: https://github.com/vacanza/holidays/issues .. _pull requests: https://github.com/vacanza/holidays/pulls .. _here: https://github.com/vacanza/holidays/blob/dev/CONTRIBUTING.rst

Issues and pull requests are always welcome. Please see here_ for more information.

License

.. __: https://github.com/vacanza/holidays/blob/dev/LICENSE

Code and documentation are available according to the MIT License (see LICENSE__).