Workday Calendar Toolkit

Utility module for Gregorian dates that reports leap years, returns official festivals, and moves through the calendar using workday rules (including holiday make-up days).

Capabilities

Leap year detection

• Identifies 2024 as a leap year while 1900 is not. @test

Festival lookup

• Listing festivals for 2024-10-01 includes the official National Day entry (“国庆节”) and no unrelated extras. @test
• Listing festivals for 2024-02-12 returns the Spring Festival entry (“春节”) instead of an empty list. @test

Workday classification

• Reports 2024-02-18 (a scheduled make-up Sunday) as a workday and 2024-02-12 as a non-work holiday. @test

Workday-aware navigation

• Advancing 1 workday from 2024-02-12 lands on 2024-02-18, skipping the holiday block and honoring the make-up day. @test
• Advancing 3 workdays from Friday 2024-03-08 lands on 2024-03-13, skipping the intervening weekend. @test

Implementation

@generates

API

class WorkdayPlanner:
    def is_leap_year(self, year: int) -> bool: ...
    # Returns True when the Gregorian year is a leap year.

    def festivals_on(self, date_str: str) -> list[str]: ...
    # Returns unique festival names for the given YYYY-MM-DD date, sorted by name and including official and other observances tied to that day.

    def is_workday(self, date_str: str) -> bool: ...
    # True when the date is a working day under the official calendar rules (including make-up weekends).

    def next_workday(self, date_str: str, offset: int = 1) -> str: ...
    # Returns the YYYY-MM-DD date reached by moving forward offset working days (offset >= 1), honoring weekends, holidays, and make-up workdays.

Dependencies { .dependencies }

lunar_python { .dependency }

Provides Gregorian festival lookups, leap-year logic, and workday-aware date arithmetic using official Chinese holiday data. @satisfied-by