/python-holidays

Generate and work with holidays in Python

Primary LanguagePythonMIT LicenseMIT

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.

PyPI:Downloads PyPI version Release date
CI/CD:CI/CD status Documentation status
Code:License Python supported versions Code style Code coverage
GitHub:GitHub stars GitHub forks GitHub contributors GitHub last commit

Install

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

$ pip install --upgrade holidays

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

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

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

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 141 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 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, available languages and additional categories. All countries support PUBLIC holidays category by default. All other default values are highlighted with bold:

Country Code Subdivisions Supported Languages Supported Categories
Albania AL      
Algeria DZ   ar, en_US, fr  
American Samoa AS Can also be loaded as country US, subdivision AS    
Andorra AD Parishes: 02, 03, 04, 05, 06, 07, 08    
Angola AO   en_US, pt_AO, uk  
Argentina AR   en_US, es, uk  
Armenia AM   en_US, hy  
Aruba AW   en_US, nl, pap, uk  
Australia AU States and territories: ACT, NSW, NT, QLD, SA, TAS, VIC, WA    
Austria AT States: 1, 2, 3, 4, 5, 6, 7, 8, 9 de, en_US, uk BANK
Azerbaijan AZ   az, en_US, uk WORKDAY
Bahamas BS      
Bahrain BH   ar, en_US  
Bangladesh BD      
Barbados BB      
Belarus BY   be, en_US  
Belgium BE   de, en_US, fr, nl, uk BANK
Belize BZ      
Bolivia BO Departments: B, C, H, L, N, O, P, S, T en_US, es, uk  
Bosnia and Herzegovina BA Entities and district: BIH, BRC, SRP bs, en_US, sr, uk  
Botswana BW      
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   OPTIONAL
Brunei BN   en_US, ms, th  
Bulgaria BG   bg, en_US, uk SCHOOL
Burkina Faso BF      
Burundi BI      
Cambodia KH   en_US, km, th  
Cameroon CM      
Canada CA Provinces and territories: AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT ar, en, fr, th GOVERNMENT, OPTIONAL
Chad TD      
Chile CL Regions: AI, AN, AP, AR, AT, BI, CO, LI, LL, LR, MA, ML, NB, RM, TA, VS en_US, es, uk  
China CN   en_US, th, zh_CN, zh_TW HALF_DAY
Colombia CO   en_US, es, uk  
Costa Rica CR   en_US, es, uk  
Croatia HR   en_US, hr, uk  
Cuba CU   en_US, es, uk  
Curacao CW   en_US, nl, pap, uk  
Cyprus CY   el, en_US  
Czechia CZ   cs, en_US, sk, uk  
Denmark DK   da, en_US, uk OPTIONAL
Djibouti DJ   ar, en_US, fr  
Dominican Republic DO   en_US, es, uk  
Ecuador EC   en_US, es, uk  
Egypt EG   ar, en_US  
El Salvador SV Departments: AH, CA, CH, CU, LI, MO, PA, SA, SM, SO, SS, SV, UN, US    
Estonia EE   en_US, et, uk  
Eswatini SZ      
Ethiopia ET   am, ar, en_US  
Finland FI   en_US, fi, sv, uk  
France FR Départements: BL, GES, GP, GY, MF, MQ, NC, PF, RE, WF, YT en_US, fr, uk  
Gabon GA      
Georgia GE   en_US, ka, uk  
Germany DE States: BB, BE, BW, BY, BYP, HB, HE, HH, MV, NI, NW, RP, SH, SL, SN, ST, TH de, en_US, uk  
Greece GR   el, en_US, uk HALF_DAY
Guam GU Can also be loaded as country US, subdivision GU    
Guatemala GT   en_US, es  
Honduras HN   en_US, es, uk  
Hong Kong HK      
Hungary HU   en_US, hu, uk  
Iceland IS   en_US, is, uk  
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   en_US, id, uk GOVERNMENT
Iran IR   en_US, fa  
Ireland IE      
Isle of Man IM      
Israel IL   en_US, he, uk OPTIONAL, SCHOOL
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, Forli, Pesaro, Trani, Urbino    
Jamaica JM      
Japan JP   en_US, ja, th BANK
Kazakhstan KZ      
Kenya KE      
Kyrgyzstan KG      
Laos LA   en_US, lo, th BANK, SCHOOL, WORKDAY
Latvia LV   en_US, lv, uk  
Lesotho LS      
Liechtenstein LI   de, en_US, uk BANK
Lithuania LT   en_US, lt, uk  
Luxembourg LU   de, en_US, fr, lb, uk  
Madagascar MG   en_US, mg, uk  
Malawi MW      
Malaysia MY States: JHR, KDH, KTN, KUL, LBN, MLK, NSN, PHG, PJY, PLS, PNG, PRK, SBH, SGR, SWK, TRG    
Maldives MV      
Malta MT   en_MT, mt  
Marshall Islands (the) MH      
Mexico MX   en_US, es, uk  
Moldova MD   en_US, ro, uk  
Monaco MC   en_US, fr, uk  
Montenegro ME      
Morocco MA   ar, en_US, fr  
Mozambique MZ   en_US, pt_MZ, uk  
Namibia NA      
Netherlands NL   en_US, nl, uk OPTIONAL
New Zealand NZ Regions: AUK, BOP, CAN, CIT, GIS, HKB, MBH, MWT, NSN, NTL, OTA, STL, TAS, TKI, WGN, WKO, WTC    
Nicaragua NI Departments: AN, AS, BO, CA, CI, CO, ES, GR, JI, LE, MD, MN, MS, MT, NS, RI, SJ en_US, es, uk  
Nigeria NG      
Northern Mariana Islands (the) MP Can also be loaded as country US, subdivision MP    
North Macedonia MK      
Norway NO   en_US, no, uk  
Pakistan PK      
Panama PA      
Papua New Guinea PG      
Paraguay PY   en_US, es, uk  
Peru PE   en_US, es, uk  
Philippines PH      
Poland PL   en_US, pl, uk  
Portugal PT Districts: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 20, 30 en_US, pt_PT OPTIONAL
Puerto Rico PR Can also be loaded as country US, subdivision PR    
Romania RO   en_US, ro, uk  
Russia RU   en_US, ru  
San Marino SM      
Saudi Arabia SA   ar, en_US  
Serbia RS   en_US, sr  
Singapore SG      
Slovakia SK   en_US, sk, uk WORKDAY
Slovenia SI   en_US, sl, uk  
South Africa ZA      
South Korea KR   en_US, ko, th BANK
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   en_US, sv, uk  
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 de, en_US, fr, it, uk  
Taiwan TW   en_US, th, zh_CN, zh_TW  
Tanzania TZ   en_US, sw BANK
Thailand TH   en_US, th ARMED_FORCES, BANK, GOVERNMENT, SCHOOL, WORKDAY
Timor Leste TL   en_US, pt_TL, tet GOVERNMENT, WORKDAY
Tonga TO   en_US, to  
Tunisia TN   ar, en_US  
Turkey TR   en_US, tr, uk HALF_DAY
Ukraine UA   ar, en_US, uk  
United Arab Emirates AE   ar, en_US  
United Kingdom GB Subdivisions: ENG, NIR, SCT, WLS    
United States Minor Outlying Islands UM Can also be loaded as country US, subdivision UM    
United States of America (the) US States and territories: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY    
United States Virgin Islands (the)   See Virgin Islands (U.S.)    
Uruguay UY   en_US, es, uk BANK
Uzbekistan UZ      
Vanuatu VU      
Vatican City VA      
Venezuela VE   en_US, es, uk  
Vietnam VN      
Virgin Islands (U.S.) VI Can also be loaded as country US, subdivision VI    
Zambia ZM      
Zimbabwe ZW      

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

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