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>
124 lines
3.7 KiB
Plaintext
124 lines
3.7 KiB
Plaintext
Lunar Calendar Converter 農曆轉換工具
|
||
|
||
一套使用 Python 3.13+ 與 Skyfield 天文資料庫實作的農曆轉換工具，支援西曆↔農曆、閏月查詢，並提供 CLI 與 API（FastAPI）。
|
||
|
||
需求
|
||
|
||
- Python >= 3.13（可用 uv 安裝）
|
||
- 套件：
|
||
- skyfield
|
||
- jplephem
|
||
- numpy
|
||
- fastapi、uvicorn（僅在使用 API 時）
|
||
- Skyfield 天文資料檔（本庫已附）：
|
||
- de422.bsp（程式目前預設使用）
|
||
- de440s.bsp、de421.bsp（可替代）
|
||
|
||
安裝與環境（使用 uv）
|
||
|
||
初始化與安裝依賴（如已存在可略過 init）
|
||
uv init lunar-converter
|
||
cd lunar-converter
|
||
uv add skyfield jplephem numpy flask
|
||
uv lock
|
||
uv sync
|
||
|
||
uv 會自動建立 .venv/ 虛擬環境，無需手動啟動。
|
||
|
||
專案結構（重點檔案）
|
||
|
||
.
|
||
├── converter.py # 西曆↔農曆轉換核心與閏月查詢（供程式/API 使用）
|
||
├── converter_with_eras.py # 指令列工具：solar2lunar / lunar2solar / era
|
||
├── api.py # FastAPI 服務
|
||
├── generate_lunar_calendar_json.py # 批次產生 JSON（可自訂年份範圍）
|
||
├── lunar_calendar.py # 天文計算與 JSON 產生
|
||
├── lunar_json/ # 每年一檔的農曆 JSON（執行產生器後）
|
||
|
||
產生農曆資料（JSON）
|
||
|
||
預設腳本為 `generate_lunar_calendar_json.py`，內含可調整的年份範圍。
|
||
|
||
uv run python generate_lunar_calendar_json.py
|
||
|
||
會輸出到 `lunar_json/`，例如：`lunar_json/2025.json`。
|
||
|
||
若只想產生 1900–2100，可修改腳本內的 years 範圍：
|
||
|
||
# generate_lunar_calendar_json.py
|
||
# years = range(1900, 2101)
|
||
|
||
指令列（CLI）使用
|
||
|
||
CLI 功能位於 `converter_with_eras.py`：
|
||
|
||
uv run python converter_with_eras.py solar2lunar 2025-10-12
|
||
uv run python converter_with_eras.py lunar2solar 1977-08-30 --leap # 閏月請加上 --leap
|
||
uv run python converter_with_eras.py era 1906-02-07 # 歷代年號 / 日本元號查詢
|
||
|
||
範例輸出（solar2lunar）
|
||
|
||
{
|
||
"西曆": "2025-10-12",
|
||
"農曆": "8月21日",
|
||
"干支": "乙巳",
|
||
"生肖": "蛇",
|
||
"節氣": ""
|
||
}
|
||
|
||
啟用 API（FastAPI）
|
||
|
||
uv run python api.py
|
||
|
||
程式會自動尋找可用埠（預設從 5000 開始）。可瀏覽 `/docs` 或 `/redoc` 查看互動式文件。
|
||
或直接用 Uvicorn 啟動：
|
||
|
||
uv run uvicorn api:app --host 0.0.0.0 --port 5000
|
||
|
||
API 範例
|
||
|
||
# 查詢一個存在的日期
|
||
curl "http://127.0.0.1:5001/solar2lunar?date=2025-10-06" | jq
|
||
|
||
# 不提供 date 參數
|
||
curl "http://127.0.0.1:5001/solar2lunar" | jq
|
||
|
||
# 查詢一個沒有閏月的日期
|
||
curl "http://127.0.0.1:5001/lunar2solar?date=1977-08-30" | jq
|
||
|
||
# 查詢一個有閏月的日期
|
||
curl "http://127.0.0.1:5001/lunar2solar?date=1976-08-25" | jq
|
||
|
||
# 查詢一個不存在的日期（會得到 404）
|
||
curl -i "http://127.0.0.1:5001/lunar2solar?date=2025-08-30"
|
||
|
||
# 查詢 2023 年（該年有閏二月）
|
||
curl "http://127.0.0.1:5001/leap-info?year=2023" | jq
|
||
|
||
# 查詢 1977 年
|
||
curl "http://127.0.0.1:5001/leap-info?year=1977" | jq
|
||
|
||
# 提供一個非數字的年份
|
||
curl "http://127.0.0.1:5001/leap-info?year=abc" | jq
|
||
|
||
備註
|
||
|
||
- 干支與生肖依據「農曆年」切換。
|
||
- 使用 Skyfield 計算節氣與朔望月，精度高於傳統對照表。
|
||
- 目前 `lunar_calendar.py` 預設載入 `de422.bsp`。欲改用 `de440s.bsp` 或 `de421.bsp`，請修改：
|
||
self.eph = load('de422.bsp')
|
||
- 若缺少某年 JSON 檔，查詢會提示錯誤，請先執行產生器產生對應年份。
|
||
|
||
作者
|
||
|
||
由 Timmy（羅楊竣）開發。
|
||
|
||
MIT License
|
||
|
||
開發小工具（直接使用 uv 指令）
|
||
|
||
- `uv run --group dev black .`：使用 Black 格式化專案
|
||
- `uv run --group dev ruff format .`：使用 Ruff 內建 formatter 格式化
|
||
- `uv run --group dev ruff check .`：Ruff 檢查
|
||
- `uv run --group dev ruff check --fix .`：Ruff 自動修正
|