Skip to main content

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.

Package:
Python supported versions PyPI version Downloads
CD/CI:
https://github.com/dr-prodigy/python-holidays/workflows/Tests/badge.svg 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 python-holidays documentation for additional examples and detailed information.

Available Countries

We currently support 126 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.

The list of supported countries, their subdivisions and supported languages (all default values are hightlighted with bold):

Country

Code

Subdivisions

Supported Languages

Albania

AL

Algeria

DZ

American Samoa

AS

Can also be loaded as country US, subdivision AS

Andorra

AD

Parishes: 02, 03, 04, 05, 06, 07, 08

Angola

AO

Argentina

AR

en_US, es, uk

Armenia

AM

en_US, hy

Aruba

AW

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

Azerbaijan

AZ

Bahrain

BH

Bangladesh

BD

Belarus

BY

be, en_US

Belgium

BE

Belize

BZ

Bolivia

BO

Departments: B, C, H, L, N, O, P, S, T

Bosnia and Herzegovina

BA

Departments: BD, FBiH, RS

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

Bulgaria

BG

bg, en_US

Burundi

BI

Cameroon

CM

Canada

CA

Provinces and territories: AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT

ar, en, en_US, fr, th

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

Colombia

CO

en_US, es, uk

Costa Rica

CR

en_US, es, uk

Croatia

HR

Cuba

CU

en_US, es, uk

Curacao

CW

Cyprus

CY

el, en_US

Czechia

CZ

Denmark

DK

da, en_US, uk

Djibouti

DJ

Dominican Republic

DO

en_US, es, uk

Ecuador

EC

en_US, es, uk

Egypt

EG

El Salvador

SV

Departments: AH, CA, CH, CU, LI, MO, PA, SA, SM, SO, SS, SV, UN, US

Estonia

EE

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

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

Guam

GU

Can also be loaded as country US, subdivision GU

Honduras

HN

en_US, es, uk

Hong Kong

HK

Hungary

HU

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

Ireland

IE

Isle of Man

IM

Israel

IL

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

Kazakhstan

KZ

Kenya

KE

Kyrgyzstan

KG

Latvia

LV

Lesotho

LS

Liechtenstein

LI

de, en_US, uk

Lithuania

LT

Luxembourg

LU

Madagascar

MG

Malawi

MW

Malaysia

MY

States: JHR, KDH, KTN, KUL, LBN, MLK, NSN, PHG, PJY, PLS, PNG, PRK, SBH, SGR, SWK, TRG

Malta

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

Mozambique

MZ

Namibia

NA

Netherlands

NL

en_US, nl, uk

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

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, Ext; Use subdiv=’Ext’ to include holidays most people have off

en_US, pt_PT

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

Serbia

RS

en_US, sr

Singapore

SG

Slovakia

SK

en_US, sk, uk

Slovenia

SI

South Africa

ZA

South Korea

KR

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

Thailand

TH

en_US, th

Tunisia

TN

Turkey

TR

Ukraine

UA

ar, en_US, uk

United Arab Emirates

AE

United Kingdom

GB

Subdivisions: England, Northern Ireland, Scotland, UK, Wales; For Isle of Man use country code IM

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, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, 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

Uzbekistan

UZ

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

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

holidays-0.26.tar.gz (445.7 kB view hashes)

Uploaded Source

Built Distribution

holidays-0.26-py3-none-any.whl (541.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page