Python Holidays Module

Holidays in Python is a library used for handling and determining public holidays across different countries and regions. This module simplifies the process of determining whether a certain date falls within a holiday, calculating holidays for a particular year, and even creating a personal holiday calendar.

Detailed description of the holidays module and features follows:

Installation

You need to install the holidays library before using it.

pip install holidays

Core Features

• Retrieve holidays for specific countries and years.
• Check if a date is a holiday.
• Add custom holidays or create your own calendar.
• Support for localization (holidays in different languages).

Basic Usage

1. Importing the Module

import holidays

2. Listing All Holidays for a Year

# Example: US holidays in 2023
us_holidays = holidays.US(years=2023)
for date, name in us_holidays.items():
    print(f"{date}: {name}")

Expected Output:

2023-01-01: New Year's Day
2023-01-16: Martin Luther King Jr. Day
2023-02-20: Washington's Birthday
2023-05-29: Memorial Day
2023-06-19: Juneteenth National Independence Day
2023-07-04: Independence Day
2023-09-04: Labor Day
2023-10-09: Columbus Day
2023-11-10: Veterans Day (Observed)
2023-11-23: Thanksgiving
2023-12-25: Christmas Day

3. Checking if a Date is a Holiday

from datetime import date

# Example: Checking if July 4, 2023, is a US holiday
is_holiday = date(2023, 7, 4) in us_holidays
print(is_holiday)

Expected Output:

True

4. Getting the Name of a Holiday

holiday_name = us_holidays.get(date(2023, 7, 4))
print(holiday_name)

Expected Output:

Independence Day

Supported Countries and Regions

The holidays module supports many countries and regions. You can specify these with country codes like US for the United States, UK for the United Kingdom, and CA for Canada.

5. Using Regional Holidays

# Example: California state holidays in the US
ca_holidays = holidays.US(state='CA', years=2023)
for date, name in ca_holidays.items():
    print(f"{date}: {name}")

Expected Output: The output will include California-specific holidays (like Cesar Chavez Day) along with national holidays.

Customizing Holidays

6. Adding Custom Holidays

my_holidays = holidays.US(years=2023)
my_holidays.append({date(2023, 12, 31): "New Year's Eve"})
for date, name in my_holidays.items():
    print(f"{date}: {name}")

Expected Output:

2023-12-31: New Year's Eve

7. Creating a Custom Holiday Class

from holidays import HolidayBase

class MyHolidays(HolidayBase):
    def _populate(self, year):
        self[date(year, 1, 1)] = "My New Year's Day"
        self[date(year, 12, 25)] = "My Christmas"

my_holidays = MyHolidays(years=2023)
for date, name in my_holidays.items():
    print(f"{date}: {name}")

Expected Output:

2023-01-01: My New Year's Day
2023-12-25: My Christmas

Localization Support

8. Retrieving Holidays in Another Language

# Example: Canadian holidays in French
can_holidays = holidays.Canada(years=2023, language="fr")
for date, name in can_holidays.items():
    print(f"{date}: {name}")

Expected Output (in French):

2023-01-01: Jour de l'An
2023-07-01: Fête du Canada
2023-12-25: Noël

Advanced Usage

9. Combining Multiple Holiday Calendars

us_holidays = holidays.US(years=2023)
ca_holidays = holidays.Canada(years=2023)
combined_holidays = us_holidays + ca_holidays

for date, name in combined_holidays.items():
    print(f"{date}: {name}")

Expected Output: This will show holidays from both the US and Canada.

10. Removing Holidays

us_holidays.pop(date(2023, 7, 4))  # Remove Independence Day
for date, name in us_holidays.items():
    print(f"{date}: {name}")

Expected Output: Independence Day (July 4, 2023) will no longer be in the list.

Real-World Applications

• Business calendars: Handle working days and public holidays.
• Event planning: Avoid scheduling events on holidays.
• Financial modeling: Adjust predictions for holidays.
• International operations: Support holidays for global teams.

Full Use Case Example

from datetime import date
import holidays

# US Holidays in 2023
us_holidays = holidays.US(years=2023)

# Check if today is a holiday
today = date(2023, 7, 4)
if today in us_holidays:
    print(f"{today} is a holiday: {us_holidays[today]}")

# Add a custom holiday
us_holidays.append({date(2023, 11, 1): "Custom Holiday"})

# Print all holidays
for holiday_date, holiday_name in us_holidays.items():
    print(f"{holiday_date}: {holiday_name}")

Expected Output:

2023-07-04 is a holiday: Independence Day
2023-01-01: New Year's Day
...
2023-11-01: Custom Holiday
2023-12-25: Christmas Day

This example demonstrates holiday checking, adding custom holidays, and iterating over the calendar. The holidays module is a powerful tool for managing holidays in Python programs.