holidays 0.23

Generate and work with holidays in Python

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.

Package:

CD/CI:

Docs:

Meta:

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 python-holidays documentation for additional examples and detailed information.

Available Countries

We currently support 121 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. The following countries and subdivisions are available:

Country	Code	Subdivisions Available
Albania	AL	None
American Samoa	AS	None; Can also be loaded as country US, subdivision AS
Andorra	AD	Parishes: 02, 03, 04, 05, 06, 07, 08
Angola	AO	None
Argentina	AR	None
Armenia	AM	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
Bahrain	BH	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: BD, FBiH, RS
Botswana	BW	None
Brazil	BR	States: AC, AL, AM, AP, BA, CE, DF, ES, GO, MA, MG, MS, MT, PA, PB, PE, PI, PR, 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
Costa Rica	CR	None
Croatia	HR	None
Cuba	CU	None
Curacao	CW	None
Cyprus	CY	None
Czechia	CZ	None
Denmark	DK	None
Djibouti	DJ	None
Dominican Republic	DO	None
Ecuador	EC	None
Egypt	EG	None
Estonia	EE	None
Eswatini	SZ	None
Ethiopia	ET	None
Finland	FI	None
France	FR	Départements: Alsace-Moselle, Guadeloupe, Guyane, La Réunion, Martinique, Mayotte, Métropole, Nouvelle-Calédonie, 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
Guam	GU	None; Can also be loaded as country US, subdivision GU
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
Indonesia	ID	None
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: Andria, Barletta, Cesena, Forlì, Pesaro, Trani, Urbino
Jamaica	JM	None
Japan	JP	None
Kazakhstan	KZ	None
Kenya	KE	None
Kyrgyzstan	KG	None
Latvia	LV	None
Lesotho	LS	None
Liechtenstein	LI	None
Lithuania	LT	None
Luxembourg	LU	None
Madagascar	MG	None
Malawi	MW	None
Malaysia	MY	States: JHR, KDH, KTN, KUL, LBN, MLK, NSN, PHG, PJY, PLS, PNG, PRK, SBH, SGR, SWK, TRG
Malta	MT	None
Marshall Islands (the)	MH	None
Mexico	MX	None
Moldova	MD	None
Monaco	MC	None
Montenegro	ME	None
Morocco	MA	None
Mozambique	MZ	None
Namibia	NA	None
Netherlands	NL	None
New Zealand	NZ	Regions: AUK, CAN, HKB, MBH, NSN, NTL, OTA, STL, TKI, WGN, WTC, CIT. Sub-regions: South Canterbury
Nicaragua	NI	Departments: AN, AS, BO, CA, CI, CO, ES, GR, JI, LE, MD, MN (default), MS, MT, NS, RI, SJ
Nigeria	NG	None
Northern Mariana Islands (the)	MP	None; Can also be loaded as country US, subdivision MP
North Macedonia	MK	None
Norway	NO	None
Pakistan	PK	None
Panama	PA	None
Paraguay	PY	None
Peru	PE	None
Philippines	PH	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, 20, 30, Ext; Use subdiv=’Ext’ to include holidays most people have off
Puerto Rico	PR	None; Can also be loaded as country US, subdivision PR
Romania	RO	None
Russia	RU	None
San Marino	SM	None
Saudi Arabia	SA	None
Serbia	RS	None
Singapore	SG	None
Slovakia	SK	None
Slovenia	SI	None
South Africa	ZA	None
South Korea	KR	None
Spain	ES	Autonomous communities: AN, AR, AS, CB, CE, CL, CM, CN, CT, EX, GA, IB, MC, MD, ML, NC, PV, RI, VC
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
Thailand	TH	None
Tunisia	TN	None
Turkey	TR	None
Ukraine	UA	None
United Arab Emirates	AE	None
United Kingdom	GB	Subdivisions: England, Northern Ireland, Scotland, UK (default), Wales; For Isle of Man use country code IM
United States Minor Outlying Islands	UM	None; Can also be loaded as country US, subdivision UM
United States of America (the)	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, UM, UT, VT, VA, VI, WA, WV, WI, WY
United States Virgin Islands (the)		See Virgin Islands (U.S.)
Uruguay	UY	None
Uzbekistan	UZ	None
Vatican City	VA	None
Venezuela	VE	None
Vietnam	VN	None
Virgin Islands (U.S.)	VI	None; Can also be loaded as country US, subdivision VI
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.)

Localization

Some of the supported entities (country/market) provide more than one language for holiday names output. The 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.

Country	Default Language	Supported languages
Argentina	es	en_US, es, uk
Armenia	hy	en_US, hy
Austria	de	de, en_US, uk
Belarus	be	be, en_US
Bulgaria	bg	bg, en_US
Canada	en	en, fr, th
Chile	es	en_US, es, uk
Colombia	es	en_US, es, uk
Costa Rica	es	en_US, es, uk
Cuba	es	en_US, es, uk
Cyprus	el	el, en
Denmark	da	da, en_US, uk
Dominican Republic	es	en_US, es, uk
Ecuador	es	en_US, es, uk
Ethiopia	am	am, en_US
Finland	fi	en_US, fi, sv, uk
France	fr	en_US, fr, uk
Georgia	ka	en_US, ka
Germany	de	de, en_US, uk
Greece	el	el, en_US
Honduras	es	en_US, es, uk
Iceland	is	en_US, is, uk
Japan	ja	en_US, ja
Liechtenstein	de	de, en_US, uk
Mexico	es	en_US, es, uk
Moldova	ro	en_US, ro, uk
Monaco	fr	en_US, fr, uk
Netherlands	nl	en_US, nl, uk
Nicaragua	es	en_US, es, uk
Norway	no	en_US, no, uk
Paraguay	es	en_US, es, uk
Peru	es	en_US, es, uk
Poland	pl	en_US, pl, uk
Portugal	pt_PT	en_US, pt_PT
Romania	ro	en_US, ro, uk
Russia	ru	en_US, ru
Serbia	sr	en_US, sr
Sweden	sv	en_US, sv, uk
Thailand	th	en_US, th
Ukraine	uk	en_US, uk
Uruguay	es	en_US, es, uk
Venezuela	es	en_US, es, uk

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