{"id":6688,"library":"jpholiday","title":"Japan Public Holiday Generator","description":"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.","status":"active","version":"1.0.3","language":"python","source_language":"en","source_url":"https://github.com/Lalcs/jpholiday","tags":["holiday","japan","date","calendar","public holiday"],"install":[{"cmd":"pip install jpholiday","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"symbol":"JPHoliday","correct":"from jpholiday import JPHoliday"}],"quickstart":{"code":"import datetime\nfrom jpholiday import JPHoliday\n\n# Initialize the JPHoliday instance\njpholiday_instance = JPHoliday()\n\n# Check if a specific date is a holiday\ndate_to_check = datetime.date(2024, 1, 1) # New Year's Day\nis_holiday = jpholiday_instance.is_holiday(date_to_check)\nprint(f\"Is {date_to_check} a holiday? {is_holiday}\")\n\n# Get the name(s) of holidays on a specific date\nholidays_on_date = jpholiday_instance.holidays(date_to_check)\nif holidays_on_date:\n    for holiday in holidays_on_date:\n        print(f\"Holiday on {holiday.date}: {holiday.name}\")\n\n# Get all holidays for a specific year\nyear_to_check = 2024\nyear_holidays = jpholiday_instance.year_holidays(year_to_check)\nprint(f\"\\nHolidays in {year_to_check} (first 3):\")\nfor holiday in year_holidays[:3]:\n    print(f\"  {holiday.date}: {holiday.name}\")","lang":"python","description":"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."},"warnings":[{"fix":"Review and rewrite custom holiday classes to align with the new `OriginalHoliday` interface introduced in v1.0.0 and later.","message":"The interface for defining custom holidays (`OriginalHoliday`) changed significantly in v1.0.0, causing incompatibility with previous versions. Custom holiday implementations require updates.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Upgrade to v1.0.1 or newer to resolve import stability issues. Ensure your import statement is `from jpholiday import JPHoliday`.","message":"Versions prior to v1.0.1 had issues with correct imports, which could lead to `ImportError` or unexpected behavior.","severity":"gotcha","affected_versions":"<1.0.1"},{"fix":"Ensure your project uses Python 3.9 or newer, as specified in the `requires_python` metadata.","message":"Support for Python 3.5 was officially removed in version 0.1.6.","severity":"deprecated","affected_versions":"<0.1.6"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (for future dates)"},{"fix":"Upgrade to v0.1.5 or newer to ensure the most accurate historical holiday data is used, correcting previous discrepancies.","message":"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).","severity":"gotcha","affected_versions":"<0.1.5"}],"env_vars":null,"search_vec":"'1.0.3':33 'accuraci':48 'activ':37 'base':20 'cabinet':26 'cadenc':39 'calendar':54 'continu':46 'current':30 'data':22 'date':53 'design':12 'easili':14 'function':50 'generat':4 'holiday':3,19,51,56 'improv':47 'japan':1,16,52 'jpholiday':5 'librari':11 'maintain':35 'month':45 'nation':18 'offic':27 'public':2,55 'publish':23 'pure':9 'pure-python':8 'python':10 'recent':44 'releas':38 'retriev':15 'sever':41 'updat':42 'version':32","created_at":"2026-04-15T18:38:40.669374+00:00","updated_at":"2026-04-16T15:53:25.269550+00:00","problems":[{"fix":"Use the `.map()` or `.apply()` method on the Pandas Series to apply the `jpholiday` function to each individual date within the Series.\n```python\nimport jpholiday\nimport pandas as pd\nimport datetime\n\ndates_series = pd.Series([datetime.date(2023, 1, 1), datetime.date(2023, 1, 2), datetime.date(2023, 1, 3)])\nis_holiday_series = dates_series.map(jpholiday.is_holiday)\nprint(is_holiday_series)\n```","cause":"The `jpholiday` functions like `is_holiday` expect a single `datetime.date` or `datetime.datetime` object, but are being applied directly to a Pandas Series, which is a collection of dates, not a single date object.","error":"AttributeError: 'Series' object has no attribute 'month'"},{"fix":"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.\n```python\nimport jpholiday\nimport datetime\n\nclass MyCustomHolidayChecker(jpholiday.OriginalHoliday):\n    def __init__(self, custom_dates):\n        self._custom_dates = custom_dates\n\n    def _is_holiday(self, date):\n        return date in self._custom_dates\n\n    def _is_holiday_name(self, date):\n        if date == datetime.date(2023, 10, 20):\n            return 'Company Anniversary'\n        return None # Return None if not a custom holiday for this checker\n\njph = jpholiday.JPHoliday()\ncustom_dates_to_add = {datetime.date(2023, 10, 20)}\njph.register(MyCustomHolidayChecker(custom_dates_to_add))\n\nprint(jph.is_holiday(datetime.date(2023, 10, 20)))\nprint(jph.holidays(datetime.date(2023, 10, 20)))\n```","cause":"This error typically occurs when attempting to implement a custom holiday checker by inheriting from `jpholiday.OriginalHoliday` and incorrectly referencing an attribute like `self.original_holidays` inside the `_is_holiday` or `_is_holiday_name` method. The base `OriginalHoliday` class does not automatically provide an `original_holidays` attribute for custom data storage.","error":"AttributeError: 'OriginalHoliday' object has no attribute 'original_holidays'"},{"fix":"Install the `jpholiday` library using pip.\n```bash\npip install jpholiday\n```","cause":"The `jpholiday` package is not installed in your current Python environment or the environment where your script is being run.","error":"ModuleNotFoundError: No module named 'jpholiday'"},{"fix":"Ensure you have the latest version of the `jpholiday` library installed to access the most current holiday data and bug fixes.\n```bash\npip install --upgrade jpholiday\n```","cause":"This can occur if you are using an outdated version of the `jpholiday` library that does not include the latest national holiday data, or if there was a bug in a specific older version. The library maintains holiday data up to 2026.","error":"jpholiday.is_holiday returns False for a known national holiday"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.0.3","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/Lalcs/jpholiday","docs":null,"changelog":null,"pypi":"https://pypi.org/project/jpholiday/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}