Skip to main content

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.

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)

Source distribution for nhatnguyet 0.2.0
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)

Table of built distributions (wheels) for nhatnguyet 0.2.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page