Metadata-Version: 2.4
Name: lunar-vn
Version: 1.4.0
Summary: Typed, dependency-free Vietnamese lunar calendar conversion for personal and business systems
Author: thongbui
License: MIT
Project-URL: Homepage, https://github.com/junkeythong/amlichvietnam
Project-URL: Source, https://github.com/junkeythong/amlichvietnam
Project-URL: Bug Tracker, https://github.com/junkeythong/amlichvietnam/issues
Keywords: calendar,conversion,am-lich,vietnam,lunar,lunar-calendar,lunarcalendar,amlich,solar-to-lunar,lich-am,calendar-conversion,python-calendar,licham,vietnamese-lunar-calendar,vietnamese-calendar,lunar-to-solar,tet,tet-nguyen-dan,ho-ngoc-duc,enterprise,no-dependencies
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Âm Lịch Việt Nam cho Python 🇻🇳

[![PyPI version](https://img.shields.io/pypi/v/lunar-vn.svg)](https://pypi.org/project/lunar-vn/)
[![CI](https://github.com/junkeythong/amlichvietnam/actions/workflows/ci.yml/badge.svg)](https://github.com/junkeythong/amlichvietnam/actions/workflows/ci.yml)
[![License](https://img.shields.io/pypi/l/lunar-vn.svg)](https://pypi.org/project/lunar-vn/)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/lunar-vn?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=MAGENTA&left_text=downloads)](https://pypi.org/project/lunar-vn/)
[![Monthly Downloads](https://static.pepy.tech/personalized-badge/lunar-vn?period=month&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLUE&left_text=downloads/month)](https://pypi.org/project/lunar-vn/)

`lunar-vn` là thư viện Python siêu nhẹ, typed, không có phụ thuộc, dùng để lấy âm lịch Việt Nam, tra ngày lễ phổ biến và tính Can Chi.

Module này được thiết kể cho:

- Ứng dụng lịch âm Việt Nam.
- Tích hợp vào hệ thống nhân sự, chấm công, đặt lịch, sự kiện.
- Bot hoặc backend cần ngày âm lịch Việt Nam.
- Ưu tiên sự chính xác, đơn giản, gọn nhẹ.
- CLI ngay trên terminal.

---

## Tính năng

- Không có dependency runtime.
- Hỗ trợ type hint và PEP 561 (`py.typed`).
- Chuyển đổi dương lịch sang âm lịch và ngược lại.
- Hỗ trợ tháng nhuận chính xác.
- Múi giờ mặc định `UTC+7` theo Việt Nam.
- Tính Can Chi năm, tháng, ngày, giờ.
- Liệt kê, tra cứu ngày lễ dương lịch và âm lịch phổ biến ở Việt Nam.
- CLI `lunar-vn` với output text hoặc JSON.
- Khoảng ngày dương lịch hỗ trợ: `1900-01-01` đến `2100-12-31`.

---

## Cài đặt

```bash
pip install lunar-vn
```

---

## CLI

Xem âm lịch hôm nay:

```bash
lunar-vn today
```

Đổi dương lịch sang âm lịch:

```bash
lunar-vn solar 2026-02-17
```

Đổi âm lịch sang dương lịch:

```bash
lunar-vn lunar 1 1 2026
```

Liệt kê ngày lễ trong năm dương lịch:

```bash
lunar-vn holidays 2026
```

Xem Can Chi theo ngày dương lịch:

```bash
lunar-vn canchi 2024-02-10
```

Thêm `--json` vào cuối lệnh để nhận dữ liệu JSON:

```bash
lunar-vn solar 2026-02-17 --json
```

Ví dụ JSON:

```json
{"holiday": "Tết Nguyên Đán", "lunar": {"day": 1, "leap": false, "month": 1, "year": 2026}, "solar": "2026-02-17"}
```

Với tháng âm lịch nhuận, dùng `--leap`:

```bash
lunar-vn lunar 1 2 2004 --leap
```

## Sử dụng trong Python

### Chuyển đổi cơ bản

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

# Tết nguyên đán
solar_date = dt.date(2026, 2, 17)
lunar_date = solar_to_lunar(solar_date)

print(lunar_date) # LunarDate(day=1, month=1, year=2026, leap=False)

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

### Âm lịch hôm nay

```python
import datetime as dt
from lunar_vn import solar_to_lunar

today = dt.date.today()
lunar = solar_to_lunar(today)

print(f"Solar: {today}")
print(f"Lunar: {lunar.day}/{lunar.month}/{lunar.year}")
print(f"Leap month: {lunar.leap}")
```

### Can Chi và ngày lễ

```python
import datetime as dt
from lunar_vn import can_chi, holidays, jd_from_date, list_holidays, solar_to_lunar

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

# Lấy năm Can Chi
print(can_chi.get_year_can_chi(lunar.year))  # Giáp Thìn

# Lấy ngày Can Chi
jdn = jd_from_date(date.day, date.month, date.year)
print(can_chi.get_day_can_chi(jdn))  # Giáp Thìn

# Kiểm tra ngày lễ
print(holidays.get_holiday(date))  # Tết Nguyên Đán

# Danh sách ngày lễ Dương lịch
for solar_date, name in list_holidays(2026):
    print(solar_date, name)
```

---

## Ngày lễ Việt Nam

`lunar-vn` có sẵn một tập ngày lễ dương lịch và âm lịch phổ biến.

Ngày lễ dương lịch:

- Tết Dương Lịch
- Ngày Lễ Tình Nhân (Valentine)
- Ngày Quốc Tế Phụ Nữ
- Ngày Giải Phóng Miền Nam
- Ngày Quốc Tế Lao Động
- Ngày Quốc Tế Thiếu Nhi
- Ngày Quốc Khánh
- Ngày Phụ Nữ Việt Nam
- Ngày Nhà Giáo Việt Nam
- Ngày Thành Lập Quân Đội Nhân Dân Việt Nam
- Lễ Giáng Sinh

Ngày lễ âm lịch:

- Tết Nguyên Đán
- Rằm Tháng Giêng
- Tết Hàn Thực
- Giỗ Tổ Hùng Vương
- Lễ Phật Đản
- Tết Đoan Ngọ
- Lễ Thất Tịch
- Lễ Vu Lan
- Tết Trung Thu
- Tết Hạ Nguyên
- Tết Ông Công Ông Táo

Các nhắc lịch âm phổ biến mỗi tháng:

- Mùng 1
- Rằm

---

## Benchmark

Chạy benchmark:

```bash
PYTHONPATH=src python3 scripts/benchmark.py
```

*Kỳ vọng: hơn 100.000 lượt chuyển đổi mỗi giây trên máy phổ thông.*

---

## Độ chính xác và phạm vi

`lunar-vn` tập trung vào các nhu cầu cốt lõi của âm lịch Việt Nam: chuyển đổi ngày, Can Chi và ngày lễ phổ biến. Thư viện không mở rộng sang Vạn Sự, tử vi, giờ hoàng đạo hoặc chọn ngày tốt để API nhỏ, rõ và dễ kiểm chứng.

Khoảng ngày dương lịch hỗ trợ là `1900-01-01` đến `2100-12-31`. Test suite có kiểm tra roundtrip dương lịch -> âm lịch -> dương lịch trong toàn bộ khoảng này.

---

## So sánh với âm lịch Trung Quốc

Xem tài liệu tại [docs/comparison_chinese_lunar.md](docs/comparison_chinese_lunar.md).

---

## Nguồn

Thuật toán âm lịch Việt Nam dựa trên đặc tả của **Hồ Ngọc Đức** tại:
[https://xemamlich.uhm.vn](https://xemamlich.uhm.vn)

Thư viện này là bản triển khai lại bằng Python của thuật toán đã công bố.

---

## License

MIT License.
