Metadata-Version: 2.4
Name: vi-lunaire
Version: 2026.4.11
Summary: Vietnamese Solar-Lunar calendar converter with CLI and iCal export
Author-email: Erik Dao <erikcuongdao@gmail.com>
Requires-Python: >=3.11
Requires-Dist: icalendar>=6.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# vi-lunaire

Vietnamese Solar-Lunar calendar converter. Convert dates between the Gregorian calendar and the Vietnamese lunar calendar (Âm lịch), look up holidays, and export lunar events to iCal files for Apple and Google Calendar.

## Install

```bash
pip install vi-lunaire
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv tool install vi-lunaire
```

## CLI

The CLI is available as `vi-lunaire`, `vilunaire`, or `clv` — all three are identical.

### Convert dates

Solar to lunar:

```
$ vi-lunaire convert 2025-01-29

☀️ Solar              →    🌙 Lunar
2025-01-29                 01/01/2025 (Ất Tỵ)

Tết Nguyên Đán
```

Lunar to solar:

```
$ vi-lunaire convert --lunar 2025-01-01

🌙 Lunar              →    ☀️ Solar
01/01/2025 (Ất Tỵ)        2025-01-29
```

For leap months, add `--leap`:

```
$ vi-lunaire convert --lunar --leap 2023-02-15
```

### List holidays

```
$ vi-lunaire holidays 2025

🌙 Vietnamese Lunar Holidays — 2025 (Ất Tỵ)

┌─────────────────────────┬───────┬────────────┐
│ Holiday                 │ Lunar │ Solar      │
├─────────────────────────┼───────┼────────────┤
│ Tết Nguyên Đán          │ 01/01 │ 2025-01-29 │
│ Tết Nguyên Đán (Mùng 2) │ 01/02 │ 2025-01-30 │
│ Tết Nguyên Đán (Mùng 3) │ 01/03 │ 2025-01-31 │
│ Tết Nguyên Tiêu         │ 01/15 │ 2025-02-12 │
│ Tết Hàn Thực            │ 03/03 │ 2025-03-31 │
│ Lễ Phật Đản             │ 04/15 │ 2025-05-12 │
│ Tết Đoan Ngọ            │ 05/05 │ 2025-05-31 │
│ Vu Lan                  │ 07/15 │ 2025-09-06 │
│ Tết Trung Thu           │ 08/15 │ 2025-10-06 │
│ Ông Công Ông Táo        │ 12/23 │ 2026-02-10 │
└─────────────────────────┴───────┴────────────┘
```

### List custom events

Define recurring lunar events in a YAML, JSON, or CSV file:

```yaml
# family.yaml
events:
  - name: "Giỗ Ông Nội"
    lunar_month: 3
    lunar_day: 10
    type: gio
  - name: "Tết Trung Thu"
    lunar_month: 8
    lunar_day: 15
    type: holiday
```

Then resolve them to solar dates for a given year:

```
$ vi-lunaire events --file family.yaml --year 2025

🌙 Lunar Events — 2025 (Ất Tỵ)

┌──────────────┬──────────┬───────┬────────────┐
│ Event        │ Type     │ Lunar │ Solar      │
├──────────────┼──────────┼───────┼────────────┤
│ Giỗ Ông Nội  │ gio      │ 03/10 │ 2025-04-07 │
│ Tết Trung Thu │ holiday │ 08/15 │ 2025-10-06 │
└──────────────┴──────────┴───────┴────────────┘
```

JSON and CSV work too:

```json
{
  "events": [
    {"name": "Giỗ Ông Nội", "lunar_month": 3, "lunar_day": 10, "type": "gio"}
  ]
}
```

```csv
name,lunar_month,lunar_day,type
Giỗ Ông Nội,3,10,gio
Tết Trung Thu,8,15,holiday
```

### Export to iCal

Generate `.ics` files to import into Apple Calendar or Google Calendar:

```bash
# Holidays only
vi-lunaire ical --holidays --year 2025 -o holidays.ics

# Your events only
vi-lunaire ical --file family.yaml --year 2025 -o family.ics

# Both
vi-lunaire ical --file family.yaml --holidays --year 2025 -o 2025.ics
```

Import the `.ics` file into your calendar app and share it with anyone.

## Python API

```python
from vi_lunaire import solar_to_lunar, lunar_to_solar

# Solar to lunar
lunar = solar_to_lunar(2025, 1, 29)
lunar.month    # 1
lunar.day      # 1
lunar.can_chi  # "Ất Tỵ"
lunar.leap     # False

# Lunar to solar
solar = lunar_to_solar(2025, 1, 1)  # datetime.date(2025, 1, 29)

# Leap month
solar = lunar_to_solar(2023, 2, 15, leap=True)
```

### Holidays

```python
from vi_lunaire import get_holidays

for h in get_holidays(2025):
    print(f"{h.name}: {h.solar_date}")
```

### Events

```python
from vi_lunaire import load_events, get_events_for_year

events = load_events("family.yaml")
for e in get_events_for_year(events, 2025):
    print(f"{e.name}: {e.solar_date}")
```

### iCal

```python
from vi_lunaire import load_events, get_holidays, get_events_for_year, generate_ical

events = get_events_for_year(load_events("family.yaml"), 2025)
holidays = get_holidays(2025)
generate_ical(events=events, holidays=holidays, year=2025, output="2025.ics")
```

## How it works

The conversion uses Hồ Ngọc Đức's algorithm structure with Jean Meeus's new moon formula for better accuracy on modern dates. All calculations use Vietnamese timezone (UTC+7), which means lunar dates may occasionally differ by one day from the Chinese lunar calendar.

Supported year range: 1900-2100.

## License

MIT
