DOCSEARCHbyAlgolia
Submit Docs

jpholiday

repository·master·Indexed 42 days ago

https://github.com/lalcs/jpholiday

A Pure-Python library for generating Japanese public holiday data based on official Cabinet Office information. It provides a JPHoliday class and module-level functions to check if a date is a holiday, retrieve holiday names, and list holidays by year, month, or date range. The library supports custom holiday extensions via the OriginalHolidayCheckerInterface.

Tokens
4.1K
Snippets
20
Records
22
Agent score
44%

What's inside jpholiday

  1. How to remove custom holidays

    master

    If you no longer need a custom holiday checker, you can remove it using the unregister method. This prevents the custom logic from affecting subsequent holiday checks.

    from jpholiday import JPHoliday, OriginalHolidayCheckerInterface
import datetime

jpholiday = JPHoliday()

class TestHoliday(OriginalHolidayCheckerInterface):
    def is_holiday(self, date):
        if date == datetime.date(2020, 2, 9):
            return True
        return False

    def holiday_name(self, date):
        return '特別休暇'

checker = TestHoliday()
jpholiday.register(checker)

# Remove the custom holiday
jpholiday.unregister(checker)

print(jpholiday.is_holiday(datetime.date(2020, 2, 9))) # False

  2. How to add custom holidays using OriginalHolidayCheckerInterface

    master

    You can extend the holiday logic by implementing the OriginalHolidayCheckerInterface. This allows you to define custom holidays (e.g., company holidays or special events) that will be recognized by both the JPHoliday class and the module-level functions.

    To add custom holidays:

    1. Create a class that inherits from OriginalHolidayCheckerInterface.
    2. Implement is_holiday(self, date) returning a boolean.
    3. Implement holiday_name(self, date) returning the name string.
    4. Use jpholiday.register(instance) or jpholiday_instance.register(instance) to activate it.
    from jpholiday import JPHoliday, OriginalHolidayCheckerInterface
import datetime

jpholiday = JPHoliday()

class TestHoliday(OriginalHolidayCheckerInterface):
    def is_holiday(self, date):
        if date == datetime.date(2020, 2, 9):
            return True
        return False

    def holiday_name(self, date):
        return '特別休暇'

# Register the custom holiday
jpholiday.register(TestHoliday())

# Now it is recognized
print(jpholiday.is_holiday(datetime.date(2020, 2, 9))) # True

  4. Iterate over holidays with iter_* methods

    master

    For large date ranges, use the iterator versions of the lookup methods to avoid loading all holidays into memory at once. These methods yield Holiday objects one by one.

    • iter_year_holidays(year: int)
    • iter_month_holidays(year: int, month: int)
    • iter_between(start_date, end_date)
    # Example: Iterating through holidays in a year
for holiday in jph.iter_year_holidays(2024):
    print(holiday.date, holiday.name)

  5. Use jpholiday module functions

    master

    For a functional approach without instantiating a class, you can use the top-level functions provided by the jpholiday module. These functions behave similarly to the JPHoliday class methods.

    Key functions:

    • is_holiday_name(date): Returns the name of the holiday as a string, or None if not a holiday.
    • is_holiday(date): Returns True if the date is a holiday.
    • year_holidays(year): Returns a list of (date, name) tuples for the year.
    • month_holidays(year, month): Returns a list of (date, name) tuples for the month.
    • between(start_date, end_date): Returns a list of (date, name) tuples within the range.
    • register(checker): Registers a custom holiday checker globally.
    • unregister(checker): Unregisters a custom holiday checker globally.
    import jpholiday
import datetime

# Get holiday name
name = jpholiday.is_holiday_name(datetime.date(2017, 1, 1))

# Check if holiday
check = jpholiday.is_holiday(datetime.date(2017, 1, 1))

# Get holidays in range
holidays = jpholiday.between(datetime.date(2017, 1, 1), datetime.date(2017, 5, 3))

  6. Use the JPHoliday class for holiday operations

    master

    The JPHoliday class provides an object-oriented interface for checking holidays and retrieving holiday names. It supports both datetime.date and datetime.datetime objects.

    Key methods:

    • holidays(date): Returns a list of Holiday objects for the given date.
    • is_holiday(date): Returns True if the date is a holiday, False otherwise.
    • year_holidays(year): Returns all holidays in a specific year.
    • month_holidays(year, month): Returns all holidays in a specific month.
    • between(start_date, end_date): Returns all holidays within a date range.
    • register(checker): Adds a custom holiday checker.
    • unregister(checker): Removes a custom holiday checker.
    from jpholiday import JPHoliday
import datetime

jpholiday = JPHoliday()

# Get holiday name for a specific date
print(jpholiday.holidays(datetime.date(2017, 1, 1)))

# Check if a date is a holiday
print(jpholiday.is_holiday(datetime.date(2017, 1, 1)))

# Get all holidays in a year
print(jpholiday.year_holidays(2017))

# Get all holidays in a month
print(jpholiday.month_holidays(2017, 5))

# Get holidays between two dates
print(jpholiday.between(datetime.date(2017, 1, 1), datetime.date(2017, 5, 3)))

  7. Get the package version

    master

    You can access the current version of the jpholiday package via the __version__ string or the __version_tuple__ tuple.

    import jpholiday

print(jpholiday.__version__)
# Output: "1.0.3" (or current version)

print(jpholiday.__version_tuple__)
# Output: (1, 0, 3)

  8. Register or unregister custom holiday checkers

    master

    You can extend the holiday logic by registering custom checkers that implement the OriginalHolidayCheckerInterface. When a checker is registered or unregistered, the internal cache is cleared to ensure consistency.

    Note: Registering a new checker will clear the existing in-memory cache.

    # Register a custom checker
jph.register(my_custom_checker)

# Unregister a custom checker
jph.unregister(my_custom_checker)

  9. Get holidays within a date range with between()

    master

    Use between(start_date, end_date) to retrieve all holidays occurring between two specified dates (inclusive). Both start_date and end_date can be datetime.date or datetime.datetime objects. The function returns a list of tuples in the format (date, name).

    import datetime
import jpholiday

start = datetime.date(2024, 1, 1)
end = datetime.date(2024, 1, 31)
holidays = jpholiday.between(start, end)

  10. Get all holidays for a specific month with month_holidays()

    master

    Use month_holidays(year, month) to retrieve a list of all holidays within a specific month of a given year. The function returns a list of tuples in the format (date, name).

    import jpholiday

holidays = jpholiday.month_holidays(2024, 1)
# Example output: [(datetime.date(2024, 1, 1), '元日'), ...]

  11. Get all holidays for a specific year with year_holidays()

    master

    Use year_holidays(year) to retrieve a list of all holidays in a given year. The function returns a list of tuples, where each tuple contains a datetime.date object and the holiday name as a str in the format (date, name).

    import jpholiday

holidays = jpholiday.year_holidays(2024)
# Example output: [(datetime.date(2024, 1, 1), '元日'), ...]