Timmy
ae21a0ae66
- Add lunar calendar astronomical calculation engine (lunar_calendar.py) - Add converter utilities for solar/lunar date conversion - Add historical era name conversions (chrono_converter.py, converter_with_eras.py) - Add FastAPI REST API for date conversion services - Add age calculator using lunar calendar - Add batch generation script for lunar calendar JSON data - Add project documentation (CLAUDE.md, pyproject.toml) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
113 lines
4.3 KiB
Markdown
113 lines
4.3 KiB
Markdown
# 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)
|
|
```bash
|
|
# Generate all years (1-2149, parallel processing)
|
|
python generate_lunar_calendar_json.py
|
|
|
|
# Generate single year
|
|
python lunar_calendar.py 2025
|
|
```
|
|
|
|
### Run conversions
|
|
```bash
|
|
# 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
|
|
```bash
|
|
python api.py
|
|
```
|
|
|
|
### Run tests
|
|
```bash
|
|
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
|