Solar Term Insight

Solar term utilities that expose the active term, neighboring Jie/Qi transitions, and the Hou/WuHou pentad descriptions for a given moment in the Asia/Shanghai timezone.

Capabilities

Identify active solar term and neighbors

• For 2023-02-04 10:00 (UTC+8), the active solar term label is "立春"; the previous term is "大寒" that began on 2023-01-20, and the next term is "雨水" scheduled for 2023-02-19. @test
• When whole_day is true at the transition into "雨水" on 2023-02-19, any timestamp that day still reports "雨水" as the active term while exposing the adjacent previous/next entries. @test

Annual solar term schedule

• The Gregorian year 2023 produces an ordered schedule of 24 solar terms; entries include "小暑" dated 2023-07-07 and "冬至" dated 2023-12-22 in chronological order. @test

Pentad (Hou/WuHou) descriptions

• On 2023-02-04 10:00 (UTC+8), the pentad index is 1 with the description "东风解冻" under the current solar term. @test
• On 2023-02-09 12:00 (UTC+8), the pentad index is 2 with the description "蛰虫始振" under the current solar term. @test

Implementation

@generates

API

from dataclasses import dataclass
from datetime import datetime
from typing import List, Literal, Optional, TypedDict

TermType = Literal["jie", "qi"]

class TermWindow(TypedDict):
    name: str            # Solar term display label
    starts_at: datetime  # Solar term start timestamp
    type: TermType       # "jie" or "qi"

@dataclass
class Pentad:
    term_name: str  # Parent solar term name
    index: int      # 1-3 pentad index within the solar term
    label: str      # Traditional pentad description

def describe_term(moment: datetime, whole_day: bool = False) -> dict:
    """Return the active solar term and its immediate neighbors as TermWindow entries keyed by current/previous/next."""

def yearly_term_table(year: int) -> List[TermWindow]:
    """Return the ordered 24-term schedule for the Gregorian year."""

def active_pentad(moment: datetime) -> Optional[Pentad]:
    """Return the pentad (Hou/WuHou) active at the given moment."""

Dependencies { .dependencies }

lunar_python { .dependency }

Provides Chinese solar term data, Jie/Qi traversal, and Hou/WuHou descriptions.