lunar-vn 1.2.0

Vietnamese lunar calendar conversion (Ho Ngoc Duc algorithm, per calrules) - Enterprise Ready

Âm Lịch Việt Nam

Python library for converting between Gregorian (solar) calendar and Vietnamese lunar calendar.

Goal: lightweight - simple – accurate – easy to reuse - Enterprise Ready

---

FEATURES

• No Dependencies: Ready for enterprise usage with strict typing support (PEP-561 compliant).
• Support Can Chi: Heavenly Stems and Earthly Branches for year, month, day, hour.
• Vietnamese Holidays: Common solar and lunar holidays included.
• Convert Solar → Lunar: Accepts robust datetime.date inputs.
• Convert Lunar → Solar: Accurate conversion using the Ho Ngoc Duc algorithm.
• Supported Range: High precision conversion from years 1900 to 2100.
• Leap month support: Handled automatically.
• Timezone support: Default UTC+7 (Vietnam).
• Processing Time Benchmark: High-performance conversions utilizing automated caching (clear_cache supported).

---

INSTALLATION

pip install lunar-vn

---

USAGE EXAMPLE

Basic Conversion

import datetime as dt
from lunar_vn import solar_to_lunar, lunar_to_solar, LunarDate

# Solar -> Lunar
date = dt.date(2026, 2, 17)
l = solar_to_lunar(date)   # Vietnamese Lunar New Year 2026
print(l)  # LunarDate(day=1, month=1, year=2026, leap=False)

# Lunar -> Solar
d = lunar_to_solar(LunarDate(1, 1, 2026))
print(d)  # 2026-02-17

Can Chi and Holidays

from lunar_vn import solar_to_lunar, can_chi, holidays
import datetime as dt

date = dt.date(2024, 2, 10)
lunar = solar_to_lunar(date)

# Get Year Can Chi
print(can_chi.get_year_can_chi(lunar.year))  # Giáp Thìn

# Get Day Can Chi (requires JDN)
from lunar_vn import jd_from_date
jdn = jd_from_date(date.day, date.month, date.year)
print(can_chi.get_day_can_chi(jdn))  # Giáp Thìn

# Check for Holiday
print(holidays.get_holiday(date))  # Tết Nguyên Đán

---

BENCHMARK

To run the benchmark script:

python scripts/benchmark.py

Expected: > 100,000 conversions per second.

---

COMPARISON WITH CHINESE LUNAR CALENDAR

See documentation.

---

ATTRIBUTION

The Vietnamese lunar calendar algorithm is described by Ho Ngoc Duc on the website: https://xemamlich.uhm.vn

This library is a Python re-implementation of the published algorithm.

---

LICENSE

MIT License