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.
pip install jpholidayVerified import paths — ran on the pinned version, not inferred.
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.
Review and rewrite custom holiday classes to align with the new `OriginalHoliday` interface introduced in v1.0.0 and later.
Upgrade to v1.0.1 or newer to resolve import stability issues. Ensure your import statement is `from jpholiday import JPHoliday`.
Ensure your project uses Python 3.9 or newer, as specified in the `requires_python` metadata.
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.
Upgrade to v0.1.5 or newer to ensure the most accurate historical holiday data is used, correcting previous discrepancies.
Use the `.map()` or `.apply()` method on the Pandas Series to apply the `jpholiday` function to each individual date within the Series. ```python import jpholiday import pandas as pd import datetime dates_series = pd.Series([datetime.date(2023, 1, 1), datetime.date(2023, 1, 2), datetime.date(2023, 1, 3)]) is_holiday_series = dates_series.map(jpholiday.is_holiday) print(is_holiday_series) ```
When creating custom holiday logic, define your holiday data directly within the class or pass it during initialization, and ensure `_is_holiday` and `_is_holiday_name` methods implement the logic to check the input `date` without relying on non-existent attributes. The `JPHoliday` class then registers instances of your custom checker.
```python
import jpholiday
import datetime
class MyCustomHolidayChecker(jpholiday.OriginalHoliday):
def __init__(self, custom_dates):
self._custom_dates = custom_dates
def _is_holiday(self, date):
return date in self._custom_dates
def _is_holiday_name(self, date):
if date == datetime.date(2023, 10, 20):
return 'Company Anniversary'
return None # Return None if not a custom holiday for this checker
jph = jpholiday.JPHoliday()
custom_dates_to_add = {datetime.date(2023, 10, 20)}
jph.register(MyCustomHolidayChecker(custom_dates_to_add))
print(jph.is_holiday(datetime.date(2023, 10, 20)))
print(jph.holidays(datetime.date(2023, 10, 20)))
```Install the `jpholiday` library using pip. ```bash pip install jpholiday ```
Ensure you have the latest version of the `jpholiday` library installed to access the most current holiday data and bug fixes. ```bash pip install --upgrade jpholiday ```
No dependency data recorded yet.