Skip to content

taljishi/python-holidays

 
 

Repository files navigation

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

Package:Python supported versions PyPI version Downloads
CD/CI: http://img.shields.io/coveralls/dr-prodigy/python-holidays/master
Docs:Documentation Status
Meta:Code style License

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

About

Generate and work with holidays in Python

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 100.0%