vnlunar - Vietnamese Lunar Calendar for Python

Thư viện Âm lịch Việt Nam cho Python - Vietnamese Lunar Calendar Library

Giới thiệu / Introduction

vnlunar là thư viện Python để chuyển đổi và tính toán lịch âm Việt Nam, dựa trên thuật toán thiên văn chính xác. Thư viện hỗ trợ:

• Chuyển đổi dương lịch <-> âm lịch
• Tính Can Chi, Ngũ Hành
• Xem ngày tốt xấu (Hoàng Đạo / Hắc Đạo)
• 12 Sao Kiến Trừ, 28 Tú Sao
• Hướng xuất hành, Tuổi xung
• Giờ Hoàng Đạo
• Và nhiều tính năng khác...

Cài đặt / Installation

pip install vnlunar

Hoặc cài đặt từ source:

git clone https://github.com/min9802/pyvnlunar.git
cd pyvnlunar
pip install -e .

Sử dụng cơ bản / Basic Usage

1. Chuyển đổi dương lịch sang âm lịch

import vnlunar

# Lấy thông tin âm lịch của ngày 7/11/2025
lunar = vnlunar.get_lunar_date(7, 11, 2025)

print(f"Ngày âm lịch: {lunar['day']}/{lunar['month']}/{lunar['year']}")
print(f"Tháng nhuận: {'Có' if lunar['leap'] == 1 else 'Không'}")

2. Lấy thông tin đầy đủ về một ngày

import vnlunar

info = vnlunar.get_full_info(7, 11, 2025)

print(f"Dương lịch: {info['solar']['day']}/{info['solar']['month']}/{info['solar']['year']}")
print(f"Âm lịch: {info['lunar']['day']}/{info['lunar']['month']}/{info['lunar']['year']}")
print(f"Can Chi ngày: {info['can_chi']['day']}")
print(f"Can Chi tháng: {info['can_chi']['month']}")
print(f"Can Chi năm: {info['can_chi']['year']}")
print(f"Sao: {info['12_stars']['name']} - {info['12_stars']['description']}")
print(f"Hoàng/Hắc Đạo: {info['day_type']['type']}")

3. Xem ngày tốt xấu cho các việc

import vnlunar

# Tính Julian Day Number
jd = vnlunar.jdn(7, 11, 2025)

# Xem ngày có tốt cho cưới hỏi không
ket_qua = vnlunar.check_good_day(jd, "wedding")
print(f"Ngày {ket_qua['star']['name']}: {ket_qua['description']}")

# Tìm các ngày tốt để khai trương trong tháng 11/2025
start_jd = vnlunar.jdn(1, 11, 2025)
end_jd = vnlunar.jdn(30, 11, 2025)
ngay_tot = vnlunar.find_good_days(start_jd, end_jd, "opening")

print(f"\nCác ngày tốt để khai trương trong tháng 11/2025:")
for ngay in ngay_tot:
    print(f"  {ngay['solar']['day']}/{ngay['solar']['month']}/{ngay['solar']['year']} - Sao {ngay['star']['name']}")

4. Kiểm tra tuổi xung

import vnlunar

jd = vnlunar.jdn(7, 11, 2025)
nam_sinh = 1990

# Kiểm tra tuổi có xung không
xung = vnlunar.check_age_conflict(jd, nam_sinh)
print(f"Năm sinh {nam_sinh} xung với ngày này: {'Có' if xung else 'Không'}")

# Lấy thông tin chi tiết về tuổi xung
tuoi_xung_info = vnlunar.get_conflicting_ages(jd, 2025)
print(f"\n{tuoi_xung_info['description']}")
print(f"Các tuổi xung trong ngày này:")
for tuoi in tuoi_xung_info['ages'][:5]:
    print(f"  Tuổi {tuoi['age']}: {tuoi['can_chi']} ({tuoi['animal']})")

5. Xem hướng xuất hành

import vnlunar

jd = vnlunar.jdn(7, 11, 2025)

# Hướng theo ngày
huong_ngay = vnlunar.get_direction_info(jd)
print(f"Hướng tốt: {', '.join(huong_ngay['good_directions'])}")
print(f"Hướng xấu: {', '.join(huong_ngay['bad_directions'])}")

# Hướng theo tuổi
huong_tuoi = vnlunar.get_age_direction(1990, 2025)
print(f"\nTuổi: {huong_tuoi['age']} ({huong_tuoi['zodiac']})")
print(f"Hướng tốt: {', '.join(huong_tuoi['good_directions'])}")

# Hướng kết hợp
huong_xuat_hanh = vnlunar.get_travel_direction(jd, 1990, 2025)
print(f"\n{huong_xuat_hanh['advice']}")

6. Giờ Hoàng Đạo

import vnlunar

jd = vnlunar.jdn(7, 11, 2025)

# Lấy các giờ Hoàng Đạo trong ngày
gio_hoang_dao = vnlunar.get_auspicious_hours(jd)
print("Giờ Hoàng Đạo:")
for hour in gio_hoang_dao:
    print(f"  {hour['hour_name']}: {hour['time_range']}")

# Kiểm tra một giờ cụ thể
gio_info = vnlunar.check_travel_hour(jd, "Tý")
print(f"\nGiờ {gio_info['zodiac_hour']}: {'TỐT' if gio_info['is_good'] else 'XẤU'}")

Các loại việc hỗ trợ xem ngày

• "wedding": Cưới hỏi
• "building": Xây nhà
• "travel": Xuất hành
• "opening": Khai trương
• "moving": Chuyển nhà
• "investing": Đầu tư

API Reference

Core Functions

• jdn(day, month, year): Chuyển ngày dương lịch sang Julian Day Number
• jdn2date(jd): Chuyển Julian Day Number sang ngày dương lịch
• get_lunar_date(day, month, year): Lấy thông tin âm lịch
• convert_solar_to_lunar(day, month, year, timezone): Chuyển đổi với múi giờ tùy chỉnh

Calendar Functions

• get_can_chi(lunar): Lấy Can Chi của ngày, tháng, năm
• get_year_can_chi(year): Lấy Can Chi của năm
• get_year_element(year): Lấy Ngũ Hành của năm
• get_auspicious_hours(jd): Lấy giờ Hoàng Đạo
• get_day_of_week(jd): Lấy thứ trong tuần

Astrology Functions

• get_12_stars(lunar_day, lunar_month): Lấy 12 Sao Kiến Trừ
• get_12_gods(jd): Lấy 12 Thần Hoàng Đạo/Hắc Đạo
• get_12_constructions(lunar_day, lunar_month): Lấy Thập Nhị Trực
• get_28_mansions(jd): Lấy 28 Tú Sao
• get_nayin(jd): Lấy Nạp Âm
• get_day_type(lunar_day, lunar_month): Kiểm tra Hoàng Đạo/Hắc Đạo
• check_good_day(jd, activity): Xem ngày tốt xấu cho việc
• find_good_days(start_jd, end_jd, activity): Tìm các ngày tốt

Direction Functions

• get_conflicting_ages(jd, current_year): Lấy thông tin tuổi xung
• check_age_conflict(jd, birth_year): Kiểm tra tuổi xung
• get_direction_info(jd): Lấy hướng theo Ngọc Hạp Thông Thư
• get_god_directions(jd): Lấy hướng thần (Thần Tài, Hỷ Thần, Phúc Thần)
• get_age_direction(birth_year, current_year): Hướng theo tuổi
• get_travel_direction(jd, birth_year, current_year): Hướng xuất hành tổng hợp
• check_travel_hour(jd, zodiac_hour): Kiểm tra giờ xuất hành

Main Function

• get_full_info(day, month, year): Lấy tất cả thông tin của một ngày

So sánh với cnlunar (Lịch Trung Quốc)

Tính năng	vnlunar (VN)	cnlunar (CN)
Múi giờ mặc định	UTC+7 (VN)	UTC+8 (CN)
Thuật toán	Thiên văn VN	Thiên văn CN
Tên Can Chi	Tiếng Việt	Tiếng Trung
Con giáp	Mèo (năm Mão)	Thỏ (năm Mão)
Tiết khí	Tiếng Việt	Tiếng Trung
Hướng xuất hành	Theo truyền thống VN	Theo truyền thống CN

Đóng góp / Contributing

Mọi đóng góp đều được hoan nghênh! Vui lòng:

1. Fork repository
2. Tạo branch mới (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Mở Pull Request

License

Free for personal and non-commercial use.

Version

Current version: 1.0.4

Credits

• Dựa trên thuật toán thiên văn của Ho Ngoc Duc
• Tham khảo: "Lịch Việt Nam - Nguyên lý và các bảng tra cứu" - Hoàng Xuân Hãn

Liên hệ / Contact

• Website: https://vnlunar.min-services.com
• GitHub Issues: https://github.com/min9802/pyvnlunar/issues

---

Made with ❤️ for Vietnamese Lunar Calendar