Seasonal Tradition Reporter

Build a utility that reports Chinese seasonal tradition details for a given Gregorian date, covering winter counting, dog days, pentad phrases, and the moon phase in one normalized response.

Capabilities

ShuJiu winter count

• For date 2021-12-21, the winter counting status reports period name 一九 and day index 1, while summer dog days are absent. @test

Sanfu dog days

• For date 2020-08-24, the dog-days status reports period name 末伏 and day index 10, with no winter counting period. @test

WuHou pentad lookup

• For date 2020-04-23, the pentad description corresponds to 萍始生, with no winter or dog-day periods present. @test

YueXiang moon phase

• For date 2021-05-26, the moon phase description is 望 (full moon), and other seasonal fields remain unset when not applicable. @test

Implementation

@generates

API

from typing import Optional, TypedDict

class TraditionInfo(TypedDict):
    name: str          # Human-readable period label such as 一九 or 末伏
    day_index: int     # 1-based index within the current period

class TraditionReport(TypedDict):
    date: str
    shujiu: Optional[TraditionInfo]
    fu: Optional[TraditionInfo]
    wuhou: Optional[str]
    yuexiang: str

def describe_traditions(date_str: str) -> TraditionReport:
    """
    Returns normalized seasonal tradition details for an ISO date (YYYY-MM-DD).
    ShuJiu and Fu are null when out of range; WuHou is null when unavailable.
    """

Dependencies { .dependencies }

lunar_python { .dependency }

Chinese lunisolar calendar library providing ShuJiu, Fu, WuHou, and moon-phase calculations.