Japan Public Holiday Generator

1.0.3 · active · verified Wed Apr 15

jpholiday is a pure-Python library designed to easily retrieve Japan's national holidays based on data published by the Cabinet Office. It is currently at version 1.0.3 and maintains an active release cadence with several updates in recent months, continuously improving accuracy and functionality.

Warnings

breaking The interface for defining custom holidays (`OriginalHoliday`) changed significantly in v1.0.0, causing incompatibility with previous versions. Custom holiday implementations require updates.
Fix: Review and rewrite custom holiday classes to align with the new `OriginalHoliday` interface introduced in v1.0.0 and later.
gotcha Versions prior to v1.0.1 had issues with correct imports, which could lead to `ImportError` or unexpected behavior.
Fix: Upgrade to v1.0.1 or newer to resolve import stability issues. Ensure your import statement is `from jpholiday import JPHoliday`.
deprecated Support for Python 3.5 was officially removed in version 0.1.6.
Fix: Ensure your project uses Python 3.9 or newer, as specified in the `requires_python` metadata.
gotcha Accuracy for holidays beyond 2027 is not guaranteed. While the library can calculate them, official announcements from the Cabinet Office are only verified up to 2027.
Fix: Be aware that holiday data for years past 2027 may be provisional and subject to change upon official government announcement. Use with caution for long-term planning.
gotcha Older versions (prior to v0.1.5) had discrepancies with Cabinet Office data for certain days between 1990 and 2021 (specifically, 4 days were incorrect).
Fix: Upgrade to v0.1.5 or newer to ensure the most accurate historical holiday data is used, correcting previous discrepancies.

Install

pip install jpholiday Install stable release

Imports

JPHoliday
```
from jpholiday import JPHoliday
```

Quickstart

This quickstart demonstrates how to check if a specific date is a holiday, retrieve holiday names for a given date, and list all holidays for a particular year using the JPHoliday class.

import datetime
from jpholiday import JPHoliday

# Initialize the JPHoliday instance
jpholiday_instance = JPHoliday()

# Check if a specific date is a holiday
date_to_check = datetime.date(2024, 1, 1) # New Year's Day
is_holiday = jpholiday_instance.is_holiday(date_to_check)
print(f"Is {date_to_check} a holiday? {is_holiday}")

# Get the name(s) of holidays on a specific date
holidays_on_date = jpholiday_instance.holidays(date_to_check)
if holidays_on_date:
    for holiday in holidays_on_date:
        print(f"Holiday on {holiday.date}: {holiday.name}")

# Get all holidays for a specific year
year_to_check = 2024
year_holidays = jpholiday_instance.year_holidays(year_to_check)
print(f"\nHolidays in {year_to_check} (first 3):")
for holiday in year_holidays[:3]:
    print(f"  {holiday.date}: {holiday.name}")

view raw JSON →