Generate and work with holidays in Python
Project description
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.
Install
The latest stable version can always be installed or updated via pip:
$ pip install --upgrade holidays
Documentation
The documentation is hosted on Read the Docs.
Quick Start
from datetime import date
import holidays
us_holidays = holidays.US() # this is a dict
# the below is the same, but takes a string:
us_holidays = holidays.country_holidays('US') # this is a dict
nyse_holidays = holidays.NYSE() # this is a dict
# the below is the same, but takes a string:
nyse_holidays = holidays.financial_holidays('NYSE') # this is a dict
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:
'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:
us_pr_holidays = holidays.country_holidays('US', subdiv='PR')
'2018-01-06' in us_holidays # False
'2018-01-06' in us_pr_holidays # True
Please see the documentation for additional examples and detailed information.
Available Countries
We currently support 96 countries. The standard way to refer to a country is by using its ISO 3166-1 alpha-2 code, the same used for domain names. The following countries and their subdivisions are available:
Country |
Code |
Subdivisions Available |
---|---|---|
Angola |
AO |
None |
Argentina |
AR |
None |
Aruba |
AW |
None |
Australia |
AU |
States and territories: ACT (default), NSW, NT, QLD, SA, TAS, VIC, WA |
Austria |
AT |
States: 1, 2, 3, 4, 5, 6, 7, 8, 9 (default) |
Azerbaijan |
AZ |
None |
Bangladesh |
BD |
None |
Belarus |
BY |
None |
Belgium |
BE |
None |
Bolivia |
BO |
Departments: B, C, H, L, N, O, P, S, T |
Bosnia and Herzegovina |
BA |
Departments: FBiH, RS, BD |
Botswana |
BW |
None |
Brazil |
BR |
States: AC, AL, AM, AP, BA, CE, DF, ES, GO, MA, MG, MS, MT, PA, PB, PE, PI, RJ, RN, RO, RR, RS, SC, SE, SP, TO |
Bulgaria |
BG |
None |
Burundi |
BI |
None |
Canada |
CA |
Provinces and territories: AB, BC, MB, NB, NL, NS NT, NU, ON (default), PE, QC, SK, YT |
Chile |
CL |
Regions: AI, AN, AP, AR, AT, BI, CO, LI, LL, LR, MA, ML, NB, RM, TA, VS |
China |
CN |
None |
Colombia |
CO |
None |
Croatia |
HR |
None |
Cuba |
CU |
None |
Curaçao |
CW |
None |
Cyprus |
CY |
None |
Czechia |
CZ |
None |
Denmark |
DK |
None |
Djibouti |
DJ |
None |
Dominican Republic |
DO |
None |
Egypt |
EG |
None |
Estonia |
EE |
None |
Ethiopia |
ET |
None |
Finland |
FI |
None |
France |
FR |
Départements: 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 |
Georgia |
GE |
None |
Germany |
DE |
States: BB, BE, BW, BY, BYP, HB, HE, HH, MV, NI, NW, RP, SH, SL, SN, ST, TH |
Greece |
GR |
None |
Honduras |
HN |
None |
Hong Kong |
HK |
None |
Hungary |
HU |
None |
Iceland |
IS |
None |
India |
IN |
States: AN, AP, AR, AS, BR, CG, CH, DD, DH, DL, GA, GJ, HP, HR, JH, JK, KA, KL, LA, LD, MH, ML, MN, MP, MZ, NL, OR, PB, PY, RJ, SK, TN, TR, TS, UK, UP, WB |
Ireland |
IE |
None |
Isle of Man |
IM |
None |
Israel |
IL |
None |
Italy |
IT |
Provinces: AG, AL, AN, AO, AP, AQ, AR, AT, AV, BA, BG, BI, BL, BN, BO, BR, BS, BT, BZ, CA, CB, CE, CH, CL, CN, CO, CR, CS, CT, CZ, EN, FC, FE, FG, FI, FM, FR, GE, GO, GR, IM, IS, KR, LC, LE, LI, LO, LT, LU, MB, MC, ME, MI, MN, MO, MS, MT, NA, NO, NU, OR, PA, PC, PD, PE, PG, PI, PN, PO, PR, PT, PU, PV, PZ, RA, RC, RE, RG, RI, RM, RN, RO, SA, SI, SO, SP, SR, SS, SU, SV, TA, TE, TN, TO, TP, TR, TS, TV, UD, VA, VB, VC, VE, VI, VR, VT, VV; Cities: Barletta, Andria, Trani, Cesena, Forlì, Pesaro, Urbino |
Jamaica |
JM |
None |
Japan |
JP |
None |
Kazakhstan |
KZ |
None |
Kenya |
KE |
None |
Korea |
KR |
None |
Latvia |
LV |
None |
Lesotho |
LS |
None |
Liechtenstein |
LI |
None |
Lithuania |
LT |
None |
Luxembourg |
LU |
None |
Madagascar |
MG |
None |
Malaysia |
MY |
States: JHR, KDH, KTN, MLK, NSN, PHG, PNG, PRK, PLS, SBH, SWK, SGR, TRG, KUL, LBN, PJY |
Malawi |
MW |
None |
Malta |
MT |
None |
Mexico |
MX |
None |
Moldova |
MD |
None |
Morocco |
MA |
None |
Mozambique |
MZ |
None |
Netherlands |
NL |
None |
Namibia |
NA |
None |
New Zealand |
NZ |
Regions: AUK, CAN, HKB, MBH, NSN, NTL, OTA, STL, TKI, WGN, WTC, CIT; Sub-regions: South Canterbury |
Nicaragua |
NI |
Departments: MN (default) |
Nigeria |
NG |
None |
North Macedonia |
MK |
None |
Norway |
NO |
None |
Paraguay |
PY |
None |
Peru |
PE |
None |
Poland |
PL |
None |
Portugal |
PT |
Districts: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18; Use subdiv=’Ext’ to include holidays most people have off |
Romania |
RO |
None |
Russia |
RU |
None |
Saudi Arabia |
SA |
None |
Serbia |
RS |
None |
Singapore |
SG |
None |
Slovakia |
SK |
None |
Slovenia |
SI |
None |
South Africa |
ZA |
None |
Spain |
ES |
Autonomous communities: AN (Andalucía), AR (Aragón), AS (Asturias), CB (Cantabria), CE (Ceuta), CL (Castilla y León), CM (Castilla La Mancha), CN (Canarias), CT (Cataluña), EX (Extremadura), GA (Galicia), IB (Islas Baleares), MC (Murcia), MD (Madrid), NC (Navarra), PV (País Vasco), RI (La Rioja), VC (Comunidad Valenciana) |
Swaziland |
SZ |
None |
Sweden |
SE |
None |
Switzerland |
CH |
Cantons: 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 |
Taiwan |
TW |
None |
Turkey |
TR |
None |
Tunisia |
TN |
None |
Ukraine |
UA |
None |
United Arab Emirates |
AE |
None |
United Kingdom |
GB |
Subdivisions: UK (default), England, Northern Ireland, Scotland, Wales. For Isle of Man use country code IM. |
United States |
US |
States and territories: 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 |
Uruguay |
UY |
None |
Uzbekistan |
UZ |
None |
Venezuela |
VE |
None |
Vietnam |
VN |
None |
Zambia |
ZM |
None |
Zimbabwe |
ZW |
None |
Available Financial Markets
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:
Entity |
Code |
Info |
---|---|---|
European Central Bank |
ECB |
Trans-European Automated Real-time Gross Settlement (TARGET2) |
New York Stock Exchange |
XNYS |
NYSE market holidays (used by all other US-exchanges, including NASDAQ, etc.) |
Beta Version
The latest development (beta) version can be installed directly from GitHub:
$ 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.
Contributions
Issues and pull requests are always welcome. Please see here for more information.
License
Code and documentation are available according to the MIT License (see LICENSE).
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for holidays-0.17.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 43d3e1bb14f430be66c15bc56f59c922e448f4b52ec31fdc6e26102758e8c3db |
|
MD5 | ecaf461ba793f1a6cdeea3dd54fb7213 |
|
BLAKE2b-256 | 480d4fee3ddb80bcb08714a0e783e47b552bdfb8e5cb2ed9e4d87ae13d926850 |