chinese-calendar for statutory holidays and workdays in Python

chinese-calendar's holiday and workday decision model

chinese-calendar solves a narrow scheduling problem: determining whether a calendar date falls on a statutory holiday or statutory workday in China. It is aimed at Python developers building applications that display holiday status, validate leave dates, calculate business-day counts, or explain why a particular date works differently under the published schedule. The README says the package covers 2004 through 2026, including the extended Spring Festival period in 2020.

The distinction between a holiday and a workday is central. A weekday is not necessarily a workday under this package because China can designate weekend dates for adjusted work. Conversely, a date that looks like a weekend can be a statutory holiday. The package therefore cannot be replaced by a simple weekday calculation if the application needs the official schedule represented by the project.

Its API is intentionally small. `is_holiday()` returns whether a date is a holiday, while `is_workday()` returns whether it is a workday. `get_holiday_detail()` returns both the holiday state and the holiday name. A separate `is_in_lieu()` check identifies whether a statutory holiday is associated with a compensatory working arrangement. The README's example uses these operations with `datetime.date` values, so the package works with standard Python date objects rather than requiring an application-specific calendar type.

How chinesecalendar stores and serves annual schedules

Based on the repository layout, the package exposes public functions from `chinese_calendar`, while the schedule itself is held in `chinese_calendar/constants.py`. That file contains the holiday arrangement as constants. The README also links a constants file specifically as the option for people who cannot use Python, which indicates that the data representation is deliberately separable from the convenience functions.

Annual schedules are generated from a definition file at `chinese_calendar/scripts/data.py`. The repository's contribution instructions say to edit that definition and execute `chinese_calendar/scripts/__init__.py`, which automatically generates `constants.py`. This gives the project a data-to-API structure: contributors update the schedule definition, the script regenerates the constants, and callers query the generated package data through the public functions.

The README does not document the internal matching algorithm beyond these generated constants, so it would be inaccurate to claim a particular lookup optimization or unsupported fallback behavior. The observable contract is nevertheless clear. Callers supply a date, and the package returns the corresponding status or holiday detail. The package declares no runtime dependencies in `setup.py`, which reduces installation concerns for basic use, but it also means the schedule data is packaged directly rather than obtained from a separate service.

Installing chinesecalendar and checking a real date

The README gives the package name as `chinesecalendar`, while the Python import name is `chinese_calendar`. Install it from PyPI with the documented command. The repository's setup metadata identifies the distribution as `chinesecalendar`, so this spelling matters when adding it to an environment.

pip install chinesecalendar

After installation, use `datetime.date` rather than a formatted string for the first check. The following example follows the README's April 30, 2018 holiday check. The expected assertions indicate that the date is not a workday and is a holiday.

import datetime
from chinese_calendar import is_holiday, is_workday

april_last = datetime.date(2018, 4, 30)
assert is_workday(april_last) is False
assert is_holiday(april_last) is True

To obtain the holiday name, import the package under an alias and call `get_holiday_detail()`. For the same date, the README expects the second return value to be `calendar.Holiday.labour_day.value`.

import datetime
import chinese_calendar as calendar

on_holiday, holiday_name = calendar.get_holiday_detail(
    datetime.date(2018, 4, 30)
)
assert on_holiday is True
assert holiday_name == calendar.Holiday.labour_day.value

The package should be upgraded when a newer annual schedule is needed. The README states that releases are generally published around November after the State Council publishes the next year's arrangement. Its upgrade command is:

pip install -U chinesecalendar

chinese-calendar's adjusted-workday boundary and limitations

The most important limitation is the annual data boundary. The README explicitly limits support to 2004 through 2026, and it explains that the next year's schedule depends on an announcement from the State Council. That makes future-year behavior uncertain until a release containing the new schedule is available. An application that assumes any future date can be classified will be making an unsupported assumption.

The package also represents statutory scheduling, not every rule an organization may need. The documented API answers whether a date is a statutory holiday or workday. It does not document company-specific leave approval, collective bargaining agreements, local employer policies, or exceptions imposed by an organization. Those decisions must remain outside the package.

The data is date-specific and policy-specific. A future administrative adjustment may affect business logic even when the Python code is unchanged. Users who need traceability should record the installed package version when saving a scheduling decision. The README does not provide an API for fetching official announcements at runtime, so this is an offline data package, not a live policy service.

There is also a practical boundary around the word "statutory." A date may be a normal working day in one part of an organization while an internal rule treats it differently. chinesecalendar cannot resolve that discrepancy by itself. Its result should be treated as the published national schedule represented in the package, then combined with any organization-specific rules required by the application.

Translating chinesecalendar constants for non-Python systems

The README gives a concrete alternative for non-Python users: translate the existing constants file to obtain the complete holiday arrangement table. This is different from switching to another holiday package. The alternative keeps the same schedule data but changes the integration method from importing Python functions to reading or translating `chinese_calendar/constants.py`.

That approach can fit a service written in Java, Go, JavaScript, or another language when the team needs the same annual data but cannot install the Python package. It also creates maintenance work. The translation must preserve holiday dates, holiday names, workday exceptions, and the `is_in_lieu` distinction. The README does not document a maintained multi-language package or a machine-readable JSON export, so the translation method is not documented as a fully automated interface.

For Python applications, the package is the more direct option because it already exposes the status functions. For other runtimes, constants translation is the documented fallback, not an equivalent SDK. The difference is integration cost rather than a different interpretation of the schedule.

chinese-calendar release maintenance and upgrade costs

The repository is not archived, and its last push was on 2026-06-06. The release list reports version 1.11.0 on 2025-11-04, version 1.10.0 on 2024-11-13, and version 1.9.2 on 2024-09-16. The release naming in the list contains `1.11.0 (v1.10.0)`, so version labeling should be checked against the package metadata when upgrading rather than inferred from the heading alone.

The README says annual updates generally follow publication of the next year's State Council schedule, usually around November. That creates a predictable upgrade cycle for applications that need newly announced dates, but it also means the project depends on an external policy publication rather than changing continuously throughout the year. The release cadence is tied to annual schedule availability.

The package uses the MIT license. The repository setup metadata identifies `MIT License`, and the repository includes a LICENSE file. MIT licensing generally permits use, modification, distribution, and private use subject to its notice and disclaimer terms, although this review does not provide legal advice. There are no runtime dependencies in `setup.py`, so routine installation does not add a dependency chain. Upgrading still requires checking whether the new version contains the dates and holiday labels expected by the application.

Editorial conclusion

Python applications that need the published Chinese holiday schedule should adopt chinesecalendar after confirming that the required year is covered and that its adjusted-workday data matches the policy source used by the application. It is not suitable for automatic coverage of future years, organization-specific attendance rules, or non-Python systems without translating its constants file. Before adoption, check the latest installed version, the supported date range, and the result for a known holiday and adjusted working day. For this project, those boundary checks matter more than the package's small API surface.

Frequently asked questions

Official sources

1. License: MIT
2. liriansu-opus/chinese-calendar on GitHub
3. Project website
4. README
5. Releases