Period Navigation with Religious Context

Implement utilities that summarize calendar periods around a Gregorian anchor date and surface Buddhist/Taoist calendar views for specific lunar dates.

Capabilities

Period breakdowns

• For anchor date 2024-02-10 with weeks starting on Monday, the period summary reports ISO start/end for the containing week (2024-02-05 to 2024-02-11), month (2024-02-01 to 2024-02-29), season (2024-01-01 to 2024-03-31), half-year (2024-01-01 to 2024-06-30), and year (2024-01-01 to 2024-12-31), and includes the seven ISO dates for that week in order. @test
• When shifting a month backward from anchor 2024-03-15 with weeks starting on Sunday, the month window uses February 2024 boundaries (2024-02-01 to 2024-02-29), and the containing week runs 2024-03-10 through 2024-03-16. @test
• Shifting one season forward from anchor 2023-11-15 yields a seasonal window of 2024-01-01 through 2024-03-31, and shifting one half-year forward from the same anchor yields 2024-07-01 through 2024-12-31, adjusting labels to the correct year. @test

Religious calendar views

• For lunar date 2023-04-08, the solar equivalent is 2023-05-26, the Buddhist view returns a descriptor string, and the Buddhist festival list contains an entry whose name includes 佛; Taoist festivals may be empty but must be present in the payload. @test
• For lunar date 2023-01-09, the solar equivalent is 2023-01-30, and the Taoist festival list contains an entry whose name includes 玉皇; a Buddhist festival list is still provided (even if empty). @test

Implementation

Use the calendar dependency for conversions, period navigation, and religious calendar lookups rather than hard-coded tables.

@generates

API

from typing import Literal, TypedDict, List, Dict

PeriodUnit = Literal["week", "month", "season", "half_year", "year"]


class PeriodWindow(TypedDict):
    label: str  # Human-friendly identifier such as "2024-W6" or "2024-Q1"
    start: str  # Inclusive start date in YYYY-MM-DD
    end: str    # Inclusive end date in YYYY-MM-DD
    days: List[str]  # Populated for week windows; empty otherwise


def build_period_summary(anchor_date: str, week_start: int = 1) -> Dict[PeriodUnit, PeriodWindow]:
    """Return current week/month/season/half-year/year windows around the anchor, respecting the week_start (0=Sunday)."""


def shift_period(anchor_date: str, unit: PeriodUnit, offset: int, week_start: int = 1) -> PeriodWindow:
    """Return the window for a specific period unit shifted by the given offset (negative allowed) from the anchor."""


class FestivalInfo(TypedDict):
    name: str
    description: str | None


class ReligiousView(TypedDict):
    date: str  # Human-readable representation from the religious calendar
    festivals: List[FestivalInfo]


class ReligiousSnapshot(TypedDict):
    solar_date: str  # ISO YYYY-MM-DD
    buddhist: ReligiousView
    taoist: ReligiousView


def build_religious_views(lunar_year: int, lunar_month: int, lunar_day: int) -> ReligiousSnapshot:
    """Convert the lunar date to solar and return Buddhist/Taoist strings plus festival lists from each calendar system."""

Dependencies { .dependencies }

lunar_python { .dependency }

Provides Chinese solar/lunar conversion, period navigation across weeks/months/seasons/half-years/years, and Buddhist/Taoist calendar views.