549 lines
24 KiB
Plaintext
549 lines
24 KiB
Plaintext
Metadata-Version: 1.2
|
|
Name: holidays
|
|
Version: 0.10.4
|
|
Summary: Generate and work with holidays in Python
|
|
Home-page: https://github.com/dr-prodigy/python-holidays
|
|
Author: ryanss
|
|
Author-email: ryanssdev@icloud.com
|
|
Maintainer: dr-prodigy
|
|
Maintainer-email: maurizio.montel@gmail.com
|
|
License: MIT
|
|
Description: ===============
|
|
python-holidays
|
|
===============
|
|
|
|
A fast, efficient Python library for generating country, province and state
|
|
specific sets of holidays on the fly. It aims to make determining whether a
|
|
specific date is a holiday as fast and flexible as possible.
|
|
|
|
.. image:: http://img.shields.io/travis/dr-prodigy/python-holidays/master
|
|
:target: https://travis-ci.org/dr-prodigy/python-holidays
|
|
|
|
.. image:: http://img.shields.io/coveralls/dr-prodigy/python-holidays/master
|
|
:target: https://coveralls.io/r/dr-prodigy/python-holidays
|
|
|
|
.. image:: http://img.shields.io/pypi/v/holidays.svg
|
|
:target: https://pypi.python.org/pypi/holidays
|
|
|
|
.. image:: http://img.shields.io/pypi/l/holidays.svg
|
|
:target: https://github.com/dr-prodigy/python-holidays/blob/master/LICENSE
|
|
|
|
|
|
Example Usage
|
|
-------------
|
|
|
|
.. code-block:: python
|
|
|
|
from datetime import date
|
|
|
|
import holidays
|
|
|
|
us_holidays = holidays.UnitedStates()
|
|
# or:
|
|
# us_holidays = holidays.US()
|
|
# or:
|
|
# us_holidays = holidays.CountryHoliday('US')
|
|
# or, for specific prov / states:
|
|
# us_holidays = holidays.CountryHoliday('US', prov=None, state='CA')
|
|
|
|
date(2015, 1, 1) in us_holidays # True
|
|
date(2015, 1, 2) in us_holidays # False
|
|
|
|
# The Holiday class will also recognize strings of any format
|
|
# and int/float representing a Unix timestamp
|
|
'2014-01-01' in us_holidays # True
|
|
'1/1/2014' in us_holidays # True
|
|
1388597445 in us_holidays # True
|
|
|
|
us_holidays.get('2014-01-01') # "New Year's Day"
|
|
|
|
us_holidays['2014-01-01': '2014-01-03'] # [date(2014, 1, 1)]
|
|
|
|
us_pr_holidays = holidays.UnitedStates(state='PR') # or holidays.US(...), or holidays.CountryHoliday('US', state='PR')
|
|
|
|
# some holidays are only present in parts of a country
|
|
'2018-01-06' in us_holidays # False
|
|
'2018-01-06' in us_pr_holidays # True
|
|
|
|
# Easily create custom Holiday objects with your own dates instead
|
|
# of using the pre-defined countries/states/provinces available
|
|
custom_holidays = holidays.HolidayBase()
|
|
# Append custom holiday dates by passing:
|
|
# 1) a dict with date/name key/value pairs,
|
|
custom_holidays.append({"2015-01-01": "New Year's Day"})
|
|
# 2) a list of dates (in any format: date, datetime, string, integer),
|
|
custom_holidays.append(['2015-07-01', '07/04/2015'])
|
|
# 3) a single date item
|
|
custom_holidays.append(date(2015, 12, 25))
|
|
|
|
date(2015, 1, 1) in custom_holidays # True
|
|
date(2015, 1, 2) in custom_holidays # False
|
|
'12/25/2015' in custom_holidays # True
|
|
|
|
# For more complex logic like 4th Monday of January, you can inherit the
|
|
# HolidayBase class and define your own _populate(year) method. See below
|
|
# documentation for examples.
|
|
|
|
|
|
Install
|
|
-------
|
|
|
|
The latest stable version can always be installed or updated via pip:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ pip install holidays
|
|
|
|
If the above fails, please use easy_install instead:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ easy_install holidays
|
|
|
|
|
|
Available Countries
|
|
-------------------
|
|
|
|
=================== ========= =============================================================
|
|
Country ISO code Provinces/States Available
|
|
=================== ========= =============================================================
|
|
Angola AO/AGO None
|
|
Argentina AR/ARG None
|
|
Aruba AW/ABW None
|
|
Australia AU/AUS prov = **ACT** (default), NSW, NT, QLD, SA, TAS, VIC, WA
|
|
Austria AT/AUT prov = 1, 2, 3, 4, 5, 6, 7, 8, **9** (default)
|
|
Bangladesh BD/BDG None
|
|
Belarus BY/BLR None
|
|
Belgium BE/BEL None
|
|
Brazil BR/BRA state = AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG,
|
|
PA, PB, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO
|
|
Bulgaria BG/BLG None
|
|
Burundi BI/BDI None
|
|
Canada CA/CAN prov = AB, BC, MB, NB, NL, NS, NT, NU, **ON** (default),
|
|
PE, QC, SK, YU
|
|
Chile CL/CHL state = AI, AN, AP, AR, AT, BI, CO, LI, LL, LR, MA, ML, NB,
|
|
RM, TA, VS
|
|
Colombia CO/COL None
|
|
Croatia HR/HRV None
|
|
Czechia CZ/CZE None
|
|
Denmark DK/DNK None
|
|
Djibouti DJ/DJI None
|
|
DominicanRepublic DO/DOM None
|
|
Egypt EG/EGY None
|
|
England None
|
|
Estonia EE/EST None
|
|
EuropeanCentralBank ECB/TAR Trans-European Automated Real-time Gross Settlement (TARGET2)
|
|
Finland FI/FIN None
|
|
France FR/FRA **Métropole** (default), Alsace-Moselle, Guadeloupe, Guyane,
|
|
Martinique, Mayotte, Nouvelle-Calédonie, La Réunion,
|
|
Polynésie Française, Saint-Barthélémy, Saint-Martin,
|
|
Wallis-et-Futuna
|
|
Germany DE/DEU prov = BW, BY, BYP, BE, BB, HB, HH, HE, MV, NI, NW, RP, SL,
|
|
SN, ST, SH, TH
|
|
Greece GR/GRC None
|
|
Honduras HN/HND None
|
|
HongKong HK/HKG None
|
|
Hungary HU/HUN None
|
|
Iceland IS/ISL None
|
|
India IN/IND prov = AS, SK, CG, KA, GJ, BR, RJ, OD, TN, AP, WB, KL, HR,
|
|
MH, MP, UP, UK, TN
|
|
Ireland IE/IRL None
|
|
IsleOfMan None
|
|
Israel IL/ISR None
|
|
Italy IT/ITA prov = AN, AO, BA, BL, BO, BS, BZ, CB, Cesena, CH, CS, CT,
|
|
EN, FC, FE, FI, Forlì, FR, GE, GO, IS, KR, LT, MB, MI, MO,
|
|
MN, MS, NA, PA, PC, PD, PG, PR, RM, SP, TS, VI
|
|
Japan JP/JPN None
|
|
Kenya KE/KEN None
|
|
Korea KR/KOR None
|
|
Latvia LV/LVA None
|
|
Lithuania LT/LTU None
|
|
Luxembourg LU/LUX None
|
|
Malawi MW/MWI None
|
|
Mexico MX/MEX None
|
|
Morocco MA/MOR None
|
|
Netherlands NL/NLD None
|
|
NewZealand NZ/NZL prov = NTL, AUK, TKI, HKB, WGN, MBH, NSN, CAN, STC, WTL,
|
|
OTA, STL, CIT
|
|
Nicaragua NI/NIC prov = MN
|
|
Nigeria NG/NGA None
|
|
NorthernIreland None
|
|
Norway NO/NOR None
|
|
Paraguay PY/PRY None
|
|
Peru PE/PER None
|
|
Poland PL/POL None
|
|
Portugal PT/PRT None
|
|
PortugalExt PTE/PRTE *Portugal plus extended days most people have off*
|
|
Romania RO/ROU None
|
|
Russia RU/RUS None
|
|
Scotland None
|
|
Serbia RS/SRB None
|
|
Singapore SG/SGP None
|
|
Slovakia SK/SVK None
|
|
Slovenia SI/SVN None
|
|
SouthAfrica ZA/ZAF None
|
|
Spain ES/ESP prov = AN, AR, AS, CB, CL, CM, CN, CT, EX, GA, IB, MC,
|
|
MD, NC, PV, RI, VC
|
|
Sweden SE/SWE None
|
|
Switzerland CH/CHE prov = AG, AR, AI, BL, BS, BE, FR, GE, GL, GR, JU, LU,
|
|
NE, NW, OW, SG, SH, SZ, SO, TG, TI, UR, VD, VS, ZG, ZH
|
|
Turkey TR/TUR None
|
|
Ukraine UA/UKR None
|
|
UnitedArabEmirates AE/ARE None
|
|
UnitedKingdom GB/GBR/UK None
|
|
UnitedStates US/USA state = AL, AK, AS, AZ, AR, CA, CO, CT, DE, DC, FL, GA,
|
|
GU, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MH, MA, MI,
|
|
FM, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, MP,
|
|
OH, OK, OR, PW, PA, PR, RI, SC, SD, TN, TX, UT, VT, VA,
|
|
VI, WA, WV, WI, WY
|
|
Vietnam VN/VNM
|
|
Wales None
|
|
=================== ========= =============================================================
|
|
|
|
|
|
API
|
|
---
|
|
|
|
class holidays.HolidayBase(years=[], expand=True, observed=True, prov=None, state=None)
|
|
The base class used to create holiday country classes.
|
|
|
|
Parameters:
|
|
|
|
years
|
|
An iterable list of integers specifying the years that the Holiday object
|
|
should pre-generate. This would generally only be used if setting *expand*
|
|
to False. (Default: [])
|
|
|
|
expand
|
|
A boolean value which specifies whether or not to append holidays in new
|
|
years to the holidays object. (Default: True)
|
|
|
|
observed
|
|
A boolean value which when set to True will include the observed day of a
|
|
holiday that falls on a weekend, when appropriate. (Default: True)
|
|
|
|
prov
|
|
A string specifying a province that has unique statutory holidays.
|
|
(Default: Australia='ACT', Canada='ON', NewZealand=None)
|
|
|
|
state
|
|
A string specifying a state that has unique statutory holidays.
|
|
(Default: UnitedStates=None)
|
|
|
|
Methods:
|
|
|
|
get(key, default=None)
|
|
Returns a string containing the name of the holiday(s) in date `key`, which
|
|
can be of date, datetime, string, unicode, bytes, integer or float type. If
|
|
multiple holidays fall on the same date the names will be separated by
|
|
commas
|
|
|
|
get(key, default=None)
|
|
Returns a string containing the name of the holiday(s) in date `key`, which
|
|
can be of date, datetime, string, unicode, bytes, integer or float type. If
|
|
multiple holidays fall on the same date the names will be separated by
|
|
commas
|
|
|
|
get_list(key)
|
|
Same as `get` except returns a `list` of holiday names instead of a comma
|
|
separated string
|
|
|
|
get_named(name)
|
|
Returns a `list` of holidays matching (even partially) the provided name
|
|
(case insensitive check)
|
|
|
|
pop(key, default=None)
|
|
Same as `get` except the key is removed from the holiday object
|
|
|
|
pop_named(name)
|
|
Same as `pop` but takes the name of the holiday (or part of it) rather than
|
|
the date
|
|
|
|
update/append
|
|
Accepts dictionary of {date: name} pairs, a list of dates, or even singular
|
|
date/string/timestamp objects and adds them to the list of holidays
|
|
|
|
|
|
More Examples
|
|
-------------
|
|
|
|
.. code-block:: python
|
|
|
|
# Simplest example possible
|
|
|
|
>>> from datetime import date
|
|
>>> import holidays
|
|
>>> date(2014, 1, 1) in holidays.US()
|
|
True
|
|
>> date(2014, 1, 2) in holidays.US()
|
|
False
|
|
|
|
# But this is not efficient because it is initializing a new Holiday object
|
|
# and generating a list of all the holidays in 2014 during each comparison
|
|
|
|
# It is more efficient to create the object only once
|
|
|
|
>>> us_holidays = holidays.US()
|
|
>>> date(2014, 1, 1) in us_holidays
|
|
True
|
|
>> date(2014, 1, 2) in us_holidays
|
|
False
|
|
|
|
# Each country has three class names that can be called--a full name
|
|
# and the 2 and 3-digit ISO codes. Use whichever you prefer.
|
|
|
|
>>> holidays.UnitedStates() == holidays.US()
|
|
True
|
|
>>> holidays.Canada() == holidays.CA()
|
|
True
|
|
>>> holidays.US() == holidays.CA()
|
|
False
|
|
|
|
# Let's print out the holidays in 2014 specific to California, USA
|
|
|
|
>>> for date, name in sorted(holidays.US(state='CA', years=2014).items()):
|
|
>>> print(date, name)
|
|
2014-01-01 New Year's Day
|
|
2014-01-20 Martin Luther King Jr. Day
|
|
2014-02-15 Susan B. Anthony Day
|
|
2014-02-17 Washington's Birthday
|
|
2014-03-31 César Chávez Day
|
|
2014-05-26 Memorial Day
|
|
2014-07-04 Independence Day
|
|
2014-09-01 Labor Day
|
|
2014-10-13 Columbus Day
|
|
2014-11-11 Veterans Day
|
|
2014-11-27 Thanksgiving
|
|
2014-12-25 Christmas Day
|
|
|
|
# So far we've only checked holidays in 2014 so that's the only year the
|
|
# Holidays object has generated
|
|
|
|
>>> us_holidays.years
|
|
set([2014])
|
|
>>> len(us_holidays)
|
|
10
|
|
|
|
# Because by default the `expand` param is True the Holiday object will add
|
|
# holidays from other years as they are required.
|
|
|
|
>>> date(2013, 1, 1) in us_holidays
|
|
True
|
|
>>> us_holidays.years
|
|
set([2013, 2014])
|
|
>>> len(us_holidays)
|
|
20
|
|
|
|
# If we change the `expand` param to False the Holiday object will no longer
|
|
# add holidays from new years
|
|
|
|
>>> us_holidays.expand = False
|
|
>>> date(2012, 1, 1) in us_holidays
|
|
False
|
|
>>> us.holidays.expand = True
|
|
>>> date(2012, 1, 1) in us_holidays
|
|
True
|
|
|
|
# January 1st, 2012 fell on a Sunday so the statutory holiday was observed
|
|
# on the 2nd. By default the `observed` param is True so the holiday list
|
|
# will include January 2nd, 2012 as a holiday.
|
|
|
|
>>> date(2012, 1, 1) in us_holidays
|
|
True
|
|
>>> us_holidays[date(2012, 1, 1)]
|
|
"New Year's Day"
|
|
>>> date(2012, 1, 2) in us_holidays
|
|
True
|
|
>>> us_holidays.get(date(2012 ,1, 2))
|
|
"New Year's Day (Observed)"
|
|
|
|
# The `observed` and `expand` values can both be changed on the fly and the
|
|
# holiday list will be adjusted accordingly
|
|
|
|
>>> us_holidays.observed = False
|
|
>>> date(2012, 1, 2) in us_holidays
|
|
False
|
|
us_holidays.observed = True
|
|
>> date(2012, 1, 2) in us_holidays
|
|
True
|
|
|
|
# Holiday objects can be added together and the resulting object will
|
|
# generate the holidays from all of the initial objects
|
|
|
|
>>> north_america = holidays.CA() + holidays.US() + holidays.MX()
|
|
>>> north_america.get('2014-07-01')
|
|
"Canada Day"
|
|
>>> north_america.get('2014-07-04')
|
|
"Independence Day"
|
|
|
|
# The other form of addition is also available
|
|
|
|
>>> north_america = holidays.Canada()
|
|
>>> north_america += holidays.UnitedStates()
|
|
>>> north_america += holidays.Mexico()
|
|
>>> north_america.country
|
|
['CA', 'US', 'MX']
|
|
|
|
# We can even get a set of holidays that include all the province- or
|
|
# state-specific holidays using the built-in sum() function
|
|
>>> a = sum([holidays.CA(prov=x) for x in holidays.CA.PROVINCES])
|
|
>>> a.prov
|
|
PROVINCES = ['AB', 'BC', 'MB', 'NB', 'NL', 'NS', 'NT', 'NU', 'ON', 'PE',
|
|
'QC', 'SK', 'YU']
|
|
|
|
# Holidays can be retrieved using their name too.
|
|
# `get_named(key)` receives a string and returns a list of holidays
|
|
# matching it (even partially, with case insensitive check)
|
|
|
|
>>> us_holidays = holidays.UnitedStates(years=2020)
|
|
>>> us_holidays.get_named('day')
|
|
[datetime.date(2020, 1, 1), datetime.date(2020, 1, 20),
|
|
datetime.date(2020, 2, 17), datetime.date(2020, 5, 25),
|
|
datetime.date(2020, 7, 4), datetime.date(2020, 7, 3),
|
|
datetime.date(2020, 9, 7), datetime.date(2020, 10, 12),
|
|
datetime.date(2020, 11, 11), datetime.date(2020, 12, 25)]
|
|
|
|
# Sometimes we may not be able to use the official federal statutory
|
|
# holiday list in our code. Let's pretend we work for a company that
|
|
# does not include Columbus Day as a statutory holiday but does include
|
|
# "Ninja Turtle Day" on July 13th. We can create a new class that inherits
|
|
# the UnitedStates class and the only method we need to override is _populate()
|
|
|
|
>>> class CorporateHolidays(holidays.UnitedStates):
|
|
>>> def _populate(self, year):
|
|
>>> # Populate the holiday list with the default US holidays
|
|
>>> holidays.UnitedStates._populate(self, year)
|
|
>>> # Remove Columbus Day
|
|
>>> self.pop_named("Columbus Day")
|
|
>>> # Add Ninja Turtle Day
|
|
>>> self[date(year, 7, 13)] = "Ninja Turtle Day"
|
|
>>> date(2014, 10, 14) in Holidays(country="US")
|
|
True
|
|
>>> date(2014, 10, 14) in CorporateHolidays(country="US")
|
|
False
|
|
>>> date(2014, 7, 13) in Holidays(country="US")
|
|
False
|
|
>>> date(2014 ,7, 13) in CorporateHolidays(country="US")
|
|
True
|
|
|
|
# We can also inherit from the HolidayBase class which has an empty
|
|
# _populate method so we start with no holidays and must define them
|
|
# all ourselves. This is how we would create a holidays class for a country
|
|
# that is not supported yet.
|
|
|
|
>>> class NewCountryHolidays(holidays.HolidayBase):
|
|
>>> def _populate(self, year):
|
|
>>> self[date(year, 1, 2)] = "Some Federal Holiday"
|
|
>>> self[date(year, 2, 3)] = "Another Federal Holiday"
|
|
>>> hdays = NewCountryHolidays()
|
|
|
|
# We can also include prov/state specific holidays in our new class.
|
|
|
|
>>> class NewCountryHolidays(holidays.HolidayBase):
|
|
>>> def _populate(self, year):
|
|
>>> # Set default prov if not provided
|
|
>>> if self.prov == None:
|
|
>>> self.prov = 'XX'
|
|
>>> self[date(year, 1, 2)] = "Some Federal Holiday"
|
|
>>> if self.prov == 'XX':
|
|
>>> self[date(year, 2, 3)] = "Special XX province-only holiday"
|
|
>>> if self.prov == 'YY':
|
|
>>> self[date(year, 3, 4)] = "Special YY province-only holiday"
|
|
>>> hdays = NewCountryHolidays()
|
|
>>> hdays = NewCountryHolidays(prov='XX')
|
|
|
|
# If you write the code necessary to create a holiday class for a country
|
|
# not currently supported please contribute your code to the project!
|
|
|
|
# Perhaps you just have a list of dates that are holidays and want to turn
|
|
# them into a Holiday class to access all the useful functionality. You can
|
|
# use the append() method which accepts a dictionary of {date: name} pairs,
|
|
# a list of dates, or even singular date/string/timestamp objects.
|
|
|
|
>>> custom_holidays = holidays.HolidayBase()
|
|
>>> custom_holidays.append(['2015-01-01', '07/04/2015'])
|
|
>>> custom_holidays.append(date(2015, 12, 25))
|
|
|
|
|
|
>>> from datetime import date
|
|
>>> holidays.US()[date(2013, 12, 31): date(2014, 1, 2)]
|
|
|
|
# Intermediate years are only shown if they are listed in the years parameter.
|
|
|
|
>>> holidays.US(years=[2014])[datetime.date(2013, 1, 1): datetime.date(2015, 12, 31)]
|
|
|
|
Development Version
|
|
-------------------
|
|
|
|
The latest development (beta) version can be installed directly from GitHub:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ pip install --upgrade https://github.com/dr-prodigy/python-holidays/tarball/beta
|
|
|
|
All new features are always first pushed to beta branch, then released on
|
|
master branch upon official version upgrades.
|
|
|
|
Running Tests
|
|
-------------
|
|
|
|
.. code-block:: bash
|
|
|
|
$ pip install flake8
|
|
$ flake8
|
|
$ python tests.py
|
|
|
|
|
|
Coverage
|
|
--------
|
|
|
|
.. code-block:: bash
|
|
|
|
$ pip install coverage
|
|
$ coverage run --omit=*site-packages* tests.py
|
|
$ coverage report -m
|
|
|
|
|
|
Contributions
|
|
-------------
|
|
|
|
.. _issues: https://github.com/dr-prodigy/python-holidays/issues
|
|
.. __: https://github.com/dr-prodigy/python-holidays/pulls
|
|
.. _`beta branch`: https://github.com/dr-prodigy/python-holidays/tree/beta
|
|
|
|
Issues_ and `Pull Requests`__ are always welcome.
|
|
|
|
When contributing with fixes and new features, please start forking/branching
|
|
from `beta branch`_, to work on latest code and reduce merging issues.
|
|
|
|
Also, whenever possible, please provide 100% test coverage for your new code.
|
|
|
|
Thanks a lot for your support.
|
|
|
|
License
|
|
-------
|
|
|
|
.. __: https://github.com/dr-prodigy/python-holidays/raw/master/LICENSE
|
|
|
|
Code and documentation are available according to the MIT License
|
|
(see LICENSE__).
|
|
|
|
Platform: any
|
|
Classifier: Development Status :: 4 - Beta
|
|
Classifier: Intended Audience :: Developers
|
|
Classifier: License :: OSI Approved :: MIT License
|
|
Classifier: Operating System :: OS Independent
|
|
Classifier: Programming Language :: Python
|
|
Classifier: Programming Language :: Python :: 2
|
|
Classifier: Programming Language :: Python :: 2.7
|
|
Classifier: Programming Language :: Python :: 3
|
|
Classifier: Programming Language :: Python :: 3.6
|
|
Classifier: Programming Language :: Python :: 3.7
|
|
Classifier: Programming Language :: Python :: 3.8
|
|
Classifier: Programming Language :: Python :: 3.9
|
|
Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
Classifier: Programming Language :: Python :: Implementation :: PyPy
|
|
Classifier: Topic :: Office/Business :: Scheduling
|
|
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
Classifier: Topic :: Software Development :: Localization
|