Human-Readable Lunar Summary

Generate a single-call description of a moment that blends Gregorian details with Chinese lunar calendar context for end users.

Capabilities

Solar datetime summary

• Given a Gregorian datetime with minute precision, return a two-line human-readable summary containing the Gregorian date/time, weekday name, Western zodiac sign, the corresponding lunar date in Chinese numerals, the cyclical designations for year/month/day/time, the NaYin classification for each of those cycles, and the year’s Chinese zodiac animal. @test
  • render_summary(datetime(2023, 5, 29, 13, 0)) yields:
    • Solar: 2023-05-29 13:00 Monday | Western zodiac: Gemini
    • Lunar: 癸卯年(兔) 丁巳月 癸酉日 己未时 | 农历: 四月十一 | 纳音: 金箔金/沙中土/剑锋金/天上火

Lunar input parity

• Accept the same moment expressed as a lunar date/time and produce exactly the same summary as when provided the equivalent Gregorian datetime, including identical ordering, spacing, and wording. @test
  • render_summary(datetime(2023, 4, 11, 13, 0), input_calendar="lunar") returns the same two-line text as the Gregorian input above.

Compact output option

• When a compact flag is enabled, emit a single-line summary that preserves all required fields (Gregorian date/time, weekday, Western zodiac, lunar date, cyclical stems/branches, NaYin set, and animal) separated by pipe characters without reordering or dropping any information. @test
  • render_summary(datetime(2023, 5, 29, 13, 0), compact=True) returns 2023-05-29 13:00 Mon Gemini | 癸卯年(兔) 丁巳月 癸酉日 己未时 | 农历 四月十一 | 纳音 金箔金/沙中土/剑锋金/天上火.

All summaries use zero-padded 24-hour times, English weekday names in full form for the two-line output and three-letter form for the compact line, and pipe separators surrounded by single spaces in the exact order shown in the examples.

Implementation

@generates

API

from datetime import datetime
from typing import Literal

def render_summary(moment: datetime, *, input_calendar: Literal["solar", "lunar"] = "solar", compact: bool = False) -> str:
    """
    Return a formatted description for the given moment.
    moment is interpreted as Gregorian time when input_calendar="solar" and as a lunar date/time when input_calendar="lunar".
    """

Dependencies { .dependencies }

lunar_python { .dependency }

Provides lunar/solar conversion, cyclical stems/branches, NaYin, Chinese zodiac animals, weekday lookup, and Western zodiac lookup.