nhatnguyet
Vietnamese lunar calendar, Zi Wei Dou Shu (紫微斗数, Purple Star Astrology), BaZi (八字, Four Pillars of Destiny), Pythagorean numerology and Vietnamese festivals in pure Python. Standard library only, no dependencies, Python 3.9 or later.
- Lunar calendar for Vietnam (UTC+7) and China, Korea, Japan: lunar and Gregorian conversion, sexagenary cycle (can chi, 干支), 24 solar terms to the minute, 28 lunar mansions, nạp âm. Over 1900 to 2100, new moons are 0.9 minutes late on average against NASA, and solar terms are within 0.9 minutes of IMCCE.
- Zi Wei Dou Shu: 12 palaces, major and minor stars, brightness, Four Transformations, 10-year and yearly periods, transiting stars, the patterns with the original classical line.
- BaZi: four pillars by solar term, hidden stems, Ten Gods, symbolic stars, luck pillars, minor periods.
- Numerology for Vietnamese names with diacritics.
- 200 Vietnamese festivals with dates for any year, in three languages.
Results carry Vietnamese, English and Chinese names. Every result matches, field by field, the engine behind nhatnguyet.org and the Nhat Nguyet app, in 17,291 shared test cases.
Install
pip install nhatnguyet
Usage
Named arguments, dates as "YYYY-MM-DD" (or datetime.date), clock times as
"HH:MM" (the Tý hour runs 23:00 to 00:59), lang="en" | "vi" | "zh". Results
are plain dicts with the same keys as the TypeScript packages.
>>> from nhatnguyet import cast_zi_wei, decade_luck, cast_bazi, minor_luck, to_lunar, to_solar, numerology, festivals
>>> chart = cast_zi_wei(date="1990-09-19", time="20:00", gender="male", view_year=2026)
>>> chart["bureau"]
{'number': 5, 'name': 'Earth Five'}
>>> life = chart["palaces"][chart["lifePalace"]]
>>> life["name"], life["stars"][0]
('Life Palace', {'name': 'Moon', 'nameVi': 'Thái Âm', 'kind': 'major', 'brightness': 'Exalted', 'transformation': 'Hóa Kỵ'})
>>> decade_luck(chart)[3]
{'order': 4, 'palaceIndex': 2, 'branch': 'Dần', 'palace': 'Property', 'fromAge': 35, 'toAge': 44, 'fromYear': 2024, 'toYear': 2033, 'majorStars': ['Military Song', 'Celestial General']}
>>> zh = cast_zi_wei(date="1990-09-19", time="20:00", gender="male", lang="zh")
>>> zh["palaces"][zh["lifePalace"]]["name"], zh["bureau"]["name"]
('命宫', '土五局')
>>> bz = cast_bazi(date="1990-09-19", time="20:00", gender="male")
>>> [bz["pillars"][k]["label"] for k in ("year", "month", "day", "hour")]
['Canh Ngọ', 'Ất Dậu', 'Đinh Hợi', 'Canh Tuất']
>>> bz["dayMaster"], bz["luck"]["startAge"], minor_luck(bz, 2026)["label"]
({'stem': 'Đinh', 'element': 'Fire', 'yinYang': 'Yin'}, {'years': 6, 'months': 4}, 'Đinh Hợi')
>>> to_lunar("2027-02-06")
{'year': 2027, 'month': 1, 'day': 1, 'leap': False, 'solarDate': '2027-02-06', 'country': 'VN', 'timeZone': 7, 'yearName': 'Đinh Mùi', 'monthName': 'Nhâm Dần', 'dayName': 'Bính Thìn', 'zodiac': 'Goat', 'solarTerm': 'Start of Spring', 'lang': 'en'}
>>> to_lunar("1985-01-21")["month"], to_lunar("1985-01-21", country="CN")["month"] # Tết in Vietnam, 12th month in China
(1, 12)
>>> to_solar(2023, 2, 1, leap=True)
{'day': 22, 'month': 3, 'year': 2023, 'date': '2023-03-22'}
>>> n = numerology("Nguyen Van An", "1990-09-19", today="2026-11-19")
>>> n["lifePath"], n["expression"], n["soulUrge"], n["personalYear"]
(11, 3, 1, 2)
>>> len(festivals(2027)), festivals(2027, lang="zh")[2]["name"]
(158, '越南春节')
Also solar_terms, solar_term_on, day_pillar, year_pillar,
hour_branch, yearly_luck, yearly_stars, find_patterns. Drawing and text
for language models:
>>> from nhatnguyet import zi_wei_svg, chart_to_text
>>> zi_wei_svg(chart, theme="dark")[:40]
'<svg xmlns="http://www.w3.org/2000/svg" '
>>> print(chart_to_text(chart, detail="summary").splitlines()[0])
# Zi Wei Dou Shu chart
zi_wei_svg, bazi_svg and numerology_svg give the same SVG, byte for byte,
as the TypeScript packages. The command line prints the same text too:
nhatnguyet ziwei 1990-09-19 20:00 male --year 2026
nhatnguyet lunar 2027-02-06 --country CN
nhatnguyet bazi 1990-09-19 20:00 male --json
All options: API docs.
Original API
The functions of the reference engine, with positional arguments and Vietnamese field names.
Lunar calendar
>>> from nhatnguyet import am_lich
>>> am_lich.solar_to_lunar(17, 2, 2026) # day, month, year -> Tết 2026
{'day': 1, 'month': 1, 'year': 2026, 'leap': False}
>>> am_lich.lunar_to_solar(1, 1, 2026, False) # lunar day, month, year, leap month?
({'day': 17, 'month': 2, 'year': 2026}, True)
>>> am_lich.year_can_chi(2026)["label"], am_lich.day_can_chi(17, 2, 2026)["label"]
('Bính Ngọ', 'Nhâm Tuất')
>>> am_lich.tiet_khi_cua_ngay(19, 11, 2026)["tenEn"]
'Start of Winter'
>>> am_lich.moc_tiet_khi_trong_nam(2026)[0] # first solar term of 2026, Vietnam time
{'index': 19, 'kinhDo': 285, 'ten': 'Tiểu Hàn', 'tenEn': 'Minor Cold', 'yNghia': 'Bắt đầu rét đậm', 'yNghiaEn': 'Deep cold sets in', 'yNghiaZh': '严寒来临', 'laTiet': True, 'ngay': {'day': 5, 'month': 1, 'year': 2026}, 'gio': 15, 'phut': 23}
>>> # Same day, two calendars: Tết in Vietnam, still the 12th month in China
>>> am_lich.solar_to_lunar(21, 1, 1985)
{'day': 1, 'month': 1, 'year': 1985, 'leap': False}
>>> am_lich.solar_to_lunar(21, 1, 1985, am_lich.MUI_GIO_THEO_NUOC["CN"])
{'day': 1, 'month': 12, 'year': 1984, 'leap': False}
Zi Wei Dou Shu
>>> from nhatnguyet import tu_vi
>>> # name, gender ("Nam" male, "Nữ" female), day, month, year, hour branch index
>>> # (0 Tý 11 pm to 1 am ... 10 Tuất 7 to 9 pm, 11 Hợi)
>>> chart = tu_vi.lap_la_so_tu_vi("", "Nam", 19, 9, 1990, 10)
>>> chart["canChiNam"], chart["tenCuc"], chart["ngaySinhAm"]
('Canh Ngọ', 'Thổ Ngũ Cục', {'day': 1, 'month': 8, 'year': 1990, 'leap': False})
>>> life = chart["cung"][chart["cungMenh"]]
>>> [(s["ten"], s["tenEn"], s["mieuVuongEn"], s["tuHoa"]) for s in life["sao"] if s["loai"] == "chinh-tinh"]
[('Thái Âm', 'Moon', 'Exalted', 'Hóa Kỵ')]
>>> [c["ten"] for c in tu_vi.nhan_dien_cach_cuc(chart)]
['Cơ Nguyệt Đồng Lương', 'Tả Hữu đồng hội', 'Nhật xuất Phù Tang', 'Nguyệt lạc Hợi cung']
>>> tu_vi.dai_van(chart)[0] # first 10-year period
{'thu': 1, 'viTri': 11, 'chi': 'Hợi', 'chiZh': '亥', 'tenCung': 'Mệnh', 'tenCungEn': 'Life Palace', 'tenCungZh': '命宫', 'tuTuoi': 5, 'denTuoi': 14, 'chinhTinh': 'Thái Âm', 'chinhTinhEn': 'Moon', 'chinhTinhZh': '太阴'}
>>> year = tu_vi.tinh_han_nam(chart, 2026)
>>> year["tuoiMu"], year["luuNienTenCung"], year["daiVanTenCung"]
(37, 'Tật Ách', 'Điền Trạch')
BaZi
>>> from nhatnguyet import bat_tu
>>> # day, month, year, hour, minute (Vietnam time), gender; hour None if unknown
>>> chart = bat_tu.lap_la_so_bat_tu(19, 9, 1990, 20, 0, "Nam")
>>> [chart[k]["label"] for k in ("truNam", "truThang", "truNgay", "truGio")]
['Canh Ngọ', 'Ất Dậu', 'Đinh Hợi', 'Canh Tuất']
>>> chart["nhatChu"], chart["tietKhi"], chart["truThang"]["thapThanCanEn"]
('Đinh', 'Bạch Lộ', 'Indirect Resource')
>>> [f'{v["label"]} {v["namTu"]}-{v["namDen"]}' for v in chart["daiVan"]["cacVan"][:3]]
['Bính Tuất 1996-2005', 'Đinh Hợi 2006-2015', 'Mậu Tý 2016-2025']
>>> bat_tu.tinh_tieu_van_bat_tu(chart, 2026)["label"]
'Đinh Hợi'
Numerology and festivals
>>> from nhatnguyet import than_so_hoc, le_hoi
>>> # full name, day, month, year of birth, then the view year, month, day
>>> p = than_so_hoc.tinh_ho_so_than_so_hoc_sau("Nguyễn Văn An", 1, 10, 1960, 2026, 1, 1)
>>> p["soDuongDoi"], p["soSuMenh"], p["soLinhHon"], p["soNamCaNhan"] # life path, expression, soul urge, personal year
(9, 3, 1, 3)
>>> len(le_hoi.danh_sach_le_hoi()), le_hoi.le_hoi_trong_nam(2027)[:2]
(200, [{'id': 'cho-vieng', 'ngay': '2027-02-13'}, {'id': 'dai-le-hoi-yen-dieu-tri-cung', 'ngay': '2027-09-15'}])
>>> [l["ten_en"] for l in le_hoi.le_hoi_theo_ngay(25, 9, 2026)]
['Diêu Trì Cung Banquet Festival (Cao Đài Mid-Autumn Grand Ceremony)', 'Trần Thương Temple Traditional Festival', 'Mid-Autumn Festival']
Conventions
- Function names are the reference engine's names in snake_case:
solar_to_lunar(Gregorian to lunar),lunar_to_solar(lunar to Gregorian),lap_la_so_tu_vi(cast a Zi Wei chart),lap_la_so_bat_tu(cast a BaZi chart),tinh_ho_so_than_so_hoc_sau(full numerology profile). - Results are plain
dicts with the camelCase keys of the shared test cases (soDuongDoi,canChiNam,kinhDo...). Gregorian dates are{"day", "month", "year"}; lunar dates add"leap". - All calendar calculations use Vietnam time, UTC+7, for every year, unless you pass another time zone.
- Numerology never reads the system clock: personal month and day use the view date you pass in. Vietnamese names are folded like the reference engine ("đ" becomes "d").
- Zi Wei Dou Shu, BaZi and numerology are traditional or conventional systems, not validated science. Do not use them for health, financial or legal decisions.
Tests
The package is checked against the shared test cases generated by the reference engine (14,936 calendar cases, 777 Zi Wei charts, 777 BaZi charts, 600 numerology profiles, 201 festival years). Any port in any language can use the same cases; see https://nhatnguyet.org/en/ma-nguon-mo.
Related
- JavaScript and TypeScript:
@nhatnguyet/am-lich,@nhatnguyet/tu-vi,@nhatnguyet/bat-tu,@nhatnguyet/than-so-hoc,@nhatnguyet/le-hoion npm. - Open datasets (3,597,286 interpreted charts, 412 public domain classical texts, 33 calendar and culture datasets): https://nhatnguyet.org/en/du-lieu and Hugging Face.
- Guide: How rare are chart patterns? Data analysis with Python.
Credits and license
Astronomical formulas after Jean Meeus, Astronomical Algorithms; solar
longitude for the solar terms from a truncated VSOP87D (Bretagnon and
Francou, IMCCE); ΔT after Espenak and Meeus (NASA, 2006). The month rules are the common rules of the
traditional lunisolar calendar (the Thời Hiến calendar), applied at UTC+7.
Code: MIT. Festival data: CC BY 4.0. Please credit
Data: Nhat Nguyet (nhatnguyet.org) when you show results to users.
Tiếng Việt
Bản Python của lõi tính Nhật Nguyệt: âm lịch Việt Nam (giờ UTC+7), can chi, 24
tiết khí tới phút, Nhị Thập Bát Tú, nạp âm; lá số Tử Vi, Bát Tự; thần số học
cho tên tiếng Việt; 200 lễ hội. Chỉ dùng thư viện chuẩn, Python 3.9 trở lên,
khớp lõi tính gốc trong 17.291 ca kiểm. Cài: pip install nhatnguyet. Tài
liệu: https://nhatnguyet.org/ma-nguon-mo.
中文
纯 Python 实现的越南农历、紫微斗数、八字、数字命理与越南节庆,零依赖;详见 https://nhatnguyet.org/zh/ma-nguon-mo。
Metadata
Release files for nhatnguyet 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nhatnguyet-0.2.0.tar.gz | 213.4 kB | Without provenance | Details for nhatnguyet-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nhatnguyet-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for nhatnguyet-0.2.0-py3-none-any.whl |
Total release size: 421.5 kB
Release files / nhatnguyet-0.2.0.tar.gz
| Download URL | nhatnguyet-0.2.0.tar.gz |
|---|---|
| Size | 213.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
85398d03cb2b5f44dfce5435e5850574683ff926579071d70a72491f5ac5a4c6
|
|
BLAKE2b-256 checksum How to use checksums |
abbc78c33234fe709599a6fb7f0815b9b868ac43222b534e9032287fc70cd68e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / nhatnguyet-0.2.0-py3-none-any.whl
| Download URL | nhatnguyet-0.2.0-py3-none-any.whl |
|---|---|
| Size | 208.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1d2bbb423779ee227e2ebbbc80459541562b846449552b599bf7adcb1ab32650
|
|
BLAKE2b-256 checksum How to use checksums |
53f96308a88d01b4ea0e58daba6a90daec5863bf1eb82b69afef1426af1d7d76
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Security for nhatnguyet 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.