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

holidays-0.17.2.tar.gz (127.1 kB view hashes)

Uploaded Source

Built Distribution

holidays-0.17.2-py3-none-any.whl (187.5 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