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.
- 206 Vietnamese festivals in three languages; the 164 with a fixed lunar
or Gregorian date are computed for any year, with province, ethnic group,
sourced venue coordinates and iCalendar export (
festivals_ics).
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 core test vectors (18,819 including school options and auspicious hours).
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", and in
English terms="pinyin" (default: "Geng Wu", "Hua Ji"), "han" (庚午, 化忌) or
"vi" (Canh Ngọ, Hóa Kỵ) for the stems, branches and Four Transformations.
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': 'Hua Ji'})
>>> decade_luck(chart)[3]
{'order': 4, 'palaceIndex': 2, 'branch': 'Yin', 'palace': 'Property', 'fromAge': 35, 'toAge': 44, 'fromYear': 2024, 'toYear': 2033, 'majorStars': ['Military Song', 'Celestial Minister']}
>>> han = cast_zi_wei(date="1990-09-19", time="20:00", gender="male", terms="han")
>>> han["palaces"][han["lifePalace"]]["stemBranch"], han["palaces"][han["lifePalace"]]["stars"][0]["transformation"]
('丁亥', '化忌')
>>> 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")]
['Geng Wu', 'Yi You', 'Ding Hai', 'Geng Xu']
>>> bz["dayMaster"], bz["luck"]["startAge"], minor_luck(bz, 2026)["label"]
({'stem': 'Ding', 'element': 'Fire', 'yinYang': 'Yin'}, {'years': 6, 'months': 4}, 'Ding Hai')
>>> cast_bazi(date="1990-09-19", time="20:00", gender="male", terms="vi")["pillars"]["day"]["label"]
'Đ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': 'Ding Wei', 'monthName': 'Ren Yin', 'dayName': 'Bing Chen', '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"] # 164 of the 206 have a fixed date
(164, '越南春节')
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]
(206, [{'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; 206 lễ hội, xuất iCalendar. 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 lõi (18.819 ca nếu tính cả tuỳ chọn
trường phái và giờ hoàng đạo). 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.3.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.3.0.tar.gz | 268.4 kB | With provenance | Details for nhatnguyet-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nhatnguyet-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for nhatnguyet-0.3.0-py3-none-any.whl |
Total release size: 528.3 kB
Release files / nhatnguyet-0.3.0.tar.gz
| Download URL | nhatnguyet-0.3.0.tar.gz |
|---|---|
| Size | 268.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2e7dd993379667667332d74a81cd817ee9f6213b90cc72cd731fb2405a035200
|
|
BLAKE2b-256 checksum How to use checksums |
98dbaeb3275739814da72d52e04d8de020e500d292a87d93ea70fa6dbaac67ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / nhatnguyet-0.3.0-py3-none-any.whl
| Download URL | nhatnguyet-0.3.0-py3-none-any.whl |
|---|---|
| Size | 259.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
af0be37e6c522f45614b83525c14af4b4d4a505a4ccf0c51c7691abd8f7e3128
|
|
BLAKE2b-256 checksum How to use checksums |
75e6e06248ff372b76e7cdabe5ae8bc848906bc5ec08b7c53615518d8d2bb32a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for nhatnguyet 0.3.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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for nhatnguyet-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA 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.