lunar-converter/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a lunar calendar converter (lunar-converter) that provides:

• Western (Gregorian) calendar ↔ Chinese lunar calendar conversion
• Historical era name conversions (Ming/Qing dynasties, Taiping Heavenly Kingdom, Japanese eras, Republic of China era)
• Age calculation (real age and East Asian nominal age)
• REST API for date conversion services

Core Architecture

Data Generation Pipeline

1. lunar_calendar.py - Astronomical calculation engine using Skyfield

   • Computes lunar calendar data from first principles using JPL ephemeris
   • Uses de421.bsp / de422.bsp / de440s.bsp ephemeris files (must exist in working directory)
   • Calculates new moons, solar terms (24 jieqi), and determines leap months
   • Generates ganzhi (sexagenary cycle) and zodiac animals
   • Output: yearly JSON files with complete lunar calendar mapping

2. generate_lunar_calendar_json.py - Batch generation script

   • Generates JSON files for multiple years in parallel using multiprocessing
   • Outputs to lunar_json/{year}.json directory
   • Usage: python generate_lunar_calendar_json.py

Conversion Layer

3. converter.py - Primary conversion class using JSON data
   • Converter.solar_to_lunar(date_str) - Convert "YYYY-MM-DD" to lunar date info
   • Converter.lunar_to_solar(year, month, day, leap=False) - Reverse conversion
   • Converter.get_leap_month(year) - Return leap month number or None
   • Depends on lunar_json/ directory containing pre-generated JSON files

Historical Era Conversion

4. chrono_converter.py - Historical era name conversions

   • Converts Western dates to era names (Ming/Qing dynasties, Taiping, Minguo)
   • Contains era date ranges as class constants

5. converter_with_eras.py - Combined converter (CLI tool)

   • Merges lunar conversion with era name conversion
   • CLI usage: python converter_with_eras.py solar2lunar YYYY-MM-DD
   • CLI usage: python converter_with_eras.py lunar2solar YYYY-MM-DD [--leap]
   • CLI usage: python converter_with_eras.py era YYYY-MM-DD

Applications

6. api.py - FastAPI REST API server

   • GET /solar2lunar?date=YYYY-MM-DD - Solar to lunar conversion
   • GET /lunar2solar?date=YYYY-MM-DD - Lunar to solar (handles leap months)
   • GET /leap-info?year=YYYY - Leap month info for a year
   • Runs on a dynamically-assigned free port

7. age_calculator.py - Age calculator using lunar calendar

   • Calculates "real age" (足歲) and "East Asian age" (虛歲)
   • Uses dependency injection pattern with Converter
   • Accurately handles leap month birthdays

Common Commands

Generate lunar calendar data (required before conversions work)

# Generate all years (1-2149, parallel processing)
python generate_lunar_calendar_json.py

# Generate single year
python lunar_calendar.py 2025

Run conversions

# Solar to lunar
python -c "from converter import Converter; print(Converter().solar_to_lunar('2025-01-01'))"

# Lunar to solar
python -c "from converter import Converter; print(Converter().lunar_to_solar(2025, 1, 1))"

# Era conversion
python converter_with_eras.py era 1900-01-01

Run API server

python api.py

Run tests

pytest

Important Notes

• Ephemeris files: The JPL ephemeris files (de421.bsp, de422.bsp, or de440s.bsp) are required for astronomical calculations. These must be present in the working directory. lunar_calendar.py:92 selects which ephemeris to use.

• Data dependency: converter.py and dependent modules require pre-generated JSON files in lunar_json/ directory. Generate these first using generate_lunar_calendar_json.py or lunar_calendar.py.

• Calendar systems: The code handles multiple calendar systems:

  • Gregorian (Western) calendar
  • Chinese lunar calendar (with leap months)
  • Historical era names (Chinese dynasties, Japanese eras)
  • Republic of China (Minguo) calendar

• Timezone: All calculations use UTC+8 (Taipei timezone) as defined in LunarCalendar.TZ_OFFSET.

• Date ranges:

  • Chinese eras defined in converter_with_eras.py:15-31 (CHINESE_ERAS_SOLAR)
  • Japanese eras defined in converter_with_eras.py:91-98 (JAPANESE_ERAS)
  • Taiping Heavenly Kingdom: 1851-02-01 to 1872-07-05