lunar-vn 1.1.0

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

Am Lich Viet 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.
• Support Can Chi: Heavenly Stems and Earthly Branches for year, month, day, hour.
• Vietnamese Holidays: Common solar and lunar holidays included.
• Convert Solar → Lunar: (dd/mm/yyyy → lunar day/month/year with leap month flag)
• Convert Lunar → Solar: Accurate conversion using the Ho Ngoc Duc algorithm.
• Leap month support: Handled automatically.
• Timezone support: Default UTC+7 (Vietnam).
• Processing Time Benchmark: High-performance conversions.

---

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
l = solar_to_lunar((17, 2, 2026))   # 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, lunar))  # 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