Official Holiday Override Planner

Builds a patched Chinese official holiday/workday schedule for a given year using the provided calendar data, then answers day-level queries and navigation requests against that patched schedule.

Capabilities

Baseline schedule inspection

• For a requested year, produce a summary mapping date strings to status and name using the package's official dataset; the entry for 2024-10-01 remains labeled with the official National Day name and marked as a holiday. @test

Runtime day overrides

• Accept override inputs (date, optional new name, optional workday flag, optional target anchor) and apply them over the official calendar; overriding 2024-10-05 to a workday with name "Release Catch-up" keeps the target anchored to 2024-10-01 and surfaces the override values. @test

Ad-hoc holiday insertion

• Allow insertion of a new holiday not present in the official dataset (e.g., 2024-05-10 labeled "Team Retreat" with target 2024-05-01) so it appears in summaries and day lookups as a non-workday. @test

Workday-aware navigation

• Provide next-workday lookup that respects official data plus overrides; with the overrides above, the next workday after 2024-10-04 is 2024-10-05, while the next workday after 2024-05-09 skips the new holiday to 2024-05-13. @test

Implementation

@generates

API

from typing import Dict, List, Optional, TypedDict

class DayOverride(TypedDict, total=False):
    date: str              # YYYY-MM-DD
    name: str              # Custom label; falls back to official when absent
    workday: bool          # True marks a working day, False marks a break
    target: str            # Anchor holiday date for make-up or shifted days

class HolidaySchedule:
    def __init__(self, year: int, overrides: Optional[List[DayOverride]] = None): ...
    def get_day_status(self, date: str) -> Dict[str, str]: ...
    def next_workday(self, date: str) -> str: ...
    def summary(self) -> Dict[str, Dict[str, str]]: ...

Dependencies { .dependencies }

lunar_python { .dependency }

Uses the official Chinese holiday/workday calendar and helper utilities for overrides and workday lookups.