一、lunar-python库核心概览
lunar-python是一款纯Python实现、无第三方依赖的历法处理库，核心用于公历、农历、佛历、道历的相互转换，同时集成干支、生肖、节气、八字、节假日、吉凶方位等传统文化要素计算。其原理基于中国传统历法算法与天文数据，通过Solar、Lunar等核心模块实现日期映射与信息解析。优点是跨平台兼容、API简洁、功能全面、支持0001-9999年超宽日期范围；缺点是部分命理类功能偏小众，无可视化模块。该库采用MIT License，可自由商用、修改与分发。
二、lunar-python库安装与基础配置
2.1 环境准备与安装
lunar-python支持Python 3.6及以上版本，安装前需确保Python环境正常，通过pip一键安装即可：
# 安装最新版lunar-python
pip install lunar-python
# 安装指定版本（可选，如1.4.7）
pip install lunar-python==1.4.7安装完成后，可通过以下代码验证安装是否成功：
# 验证lunar-python安装
try:
from lunar import Lunar, Solar
print("lunar-python安装成功！")
except ImportError:
print("lunar-python安装失败，请检查pip环境或重新安装")2.2 核心模块导入
lunar-python的核心功能集中在lunar包下，常用模块包括：
Lunar：农历日期核心类，处理农历创建、转换、信息查询Solar：公历日期核心类，处理公历创建、转换、信息查询EightChar：八字计算模块，用于命理分析Holiday：节假日查询模块，支持法定节假日与传统节日JieQi：二十四节气计算模块
基础使用只需导入Lunar和Solar即可：
# 导入核心模块
from lunar import Lunar, Solar三、lunar-python基础使用：日期创建与转换
3.1 公历日期创建与基础信息查询
Solar类用于处理公历日期，可通过fromYmd方法创建公历对象，支持查询年、月、日、星期、星座、儒略日等基础信息：
# 1. 创建公历日期对象（2026年3月3日，2026年元宵节）
solar_date = Solar.fromYmd(2026, 3, 3)
# 2. 查询公历基础信息
print("公历日期：", solar_date.toFullString()) # 完整公历字符串
print("年份：", solar_date.getYear())
print("月份：", solar_date.getMonth())
print("日期：", solar_date.getDay())
print("星期：", solar_date.getWeekInChinese()) # 中文星期
print("星座：", solar_date.getXingZuo())
print("儒略日：", solar_date.getJulianDay())
# 3. 公历日期运算（加1天、减1个月）
solar_next_day = solar_date.next(1) # 加1天
solar_prev_month = solar_date.next(-30) # 减30天（近似1个月）
print("次日公历：", solar_next_day.toFullString())
print("前一个月公历：", solar_prev_month.toFullString())代码说明：fromYmd(year, month, day)接收公历年月日创建对象；toFullString()返回包含完整信息的字符串；next(n)可实现日期加减，n为正数加、负数减，单位为天。
3.2 农历日期创建与基础信息查询
Lunar类用于处理农历日期，支持通过fromYmd创建（需注意闰月参数），可查询农历年、月、日、干支、生肖、节气等信息：
# 1. 创建农历日期对象（2026年正月十五，元宵节，无闰月）
lunar_date = Lunar.fromYmd(2026, 1, 15)
# 2. 创建闰月农历对象（示例：2025年闰六月初十，第四个参数为True表示闰月）
lunar_leap = Lunar.fromYmd(2025, 6, 10, True)
# 3. 查询农历基础信息
print("农历日期：", lunar_date.toFullString()) # 完整农历字符串
print("农历年：", lunar_date.getYearInChinese()) # 中文农历年
print("农历月：", lunar_date.getMonthInChinese()) # 中文农历月
print("农历日：", lunar_date.getDayInChinese()) # 中文农历日
print("干支纪年：", lunar_date.getYearGanZhi())
print("生肖：", lunar_date.getShengXiao())
print("是否闰月：", lunar_date.isLeapMonth())
print("当前节气：", lunar_date.getJieQi())
# 4. 农历日期运算
lunar_next_day = lunar_date.next(1) # 加1天
print("次日农历：", lunar_next_day.toFullString())代码说明：Lunar.fromYmd(year, month, day, isLeapMonth=False)中，isLeapMonth用于标记是否为闰月，默认False；getYearGanZhi()返回干支纪年，getShengXiao()自动匹配生肖。
3.3 公历与农历相互转换
lunar-python最核心的功能是公历↔农历双向转换，通过getLunar()（公历转农历）和getSolar()（农历转公历）实现：
# 场景1：公历转农历（2026年3月3日转农历）
solar = Solar.fromYmd(2026, 3, 3)
lunar_from_solar = solar.getLunar()
print("公历2026-03-03 转农历：", lunar_from_solar.toFullString())
# 场景2：农历转公历（2026年正月十五转公历）
lunar = Lunar.fromYmd(2026, 1, 15)
solar_from_lunar = lunar.getSolar()
print("农历2026年正月十五 转公历：", solar_from_lunar.toFullString())
# 场景3：批量转换（10天内公历转农历）
print("\n未来10天公历转农历结果：")
for i in range(10):
solar_batch = Solar.fromYmd(2026, 3, 3).next(i)
lunar_batch = solar_batch.getLunar()
print(f"公历：{solar_batch.toYmd()} → 农历：{lunar_batch.toFullString()}")代码说明：双向转换无需额外参数，直接调用对象方法即可；批量转换可结合next()方法实现，适用于日历生成、节日统计等场景。
四、lunar-python进阶功能：传统文化要素查询
4.1 二十四节气与物候查询
JieQi模块与Lunar类集成，可精准查询任意日期的节气、物候，支持节气时间计算：
from lunar import JieQi
# 1. 查询指定日期的节气（2026年3月3日）
lunar = Lunar.fromYmd(2026, 1, 15)
jieqi = lunar.getJieQi()
print(f"2026年正月十五对应节气：{jieqi}")
# 2. 查询2026年所有节气及公历日期
print("\n2026年二十四节气：")
for i in range(24):
jieqi_name = JieQi.getName(i)
jieqi_solar = JieQi.getSolar(2026, i)
print(f"{jieqi_name}：{jieqi_solar.toYmd()}")
# 3. 查询节气物候（以立春为例）
li_chun = JieQi.getSolar(2026, 0) # 0对应立春
wu_hou = li_chun.getLunar().getWuHou()
print(f"\n立春物候：{wu_hou}")代码说明：JieQi.getName(index)通过索引（0-23）获取节气名称；JieQi.getSolar(year, index)获取指定年份、索引的节气公历日期；getWuHou()返回对应节气的物候信息。
4.2 干支、纳音与五行查询
干支纪年、纳音五行是传统文化核心要素，lunar-python可精准计算年、月、日、时的干支与五行：
# 1. 查询年月日时干支（2026年正月十五 子时）
lunar = Lunar.fromYmdHms(2026, 1, 15, 0, 0, 0) # 含时辰的农历对象
print("年干支：", lunar.getYearGanZhi())
print("月干支：", lunar.getMonthGanZhi())
print("日干支：", lunar.getDayGanZhi())
print("时干支：", lunar.getTimeGanZhi())
# 2. 查询纳音五行
na_yin = lunar.getNaYin()
print("纳音五行：", na_yin)
# 3. 查询五行属性
wu_xing = lunar.getWuXing()
print("五行属性：", wu_xing)代码说明：fromYmdHms()可创建含时辰的农历对象，时辰范围0-23；getNaYin()返回年月日时的纳音组合，getWuXing()返回五行属性。
4.3 节假日与传统节日查询
Holiday模块支持查询法定节假日、调休及传统节日，可判断日期是否为节日：
from lunar import Holiday
# 1. 判断指定日期是否为节假日（2026年3月3日，元宵节）
solar = Solar.fromYmd(2026, 3, 3)
holiday_name = Holiday.getName(solar)
is_holiday = Holiday.isHoliday(solar)
is_work = Holiday.isWork(solar)
print(f"2026-03-03 节日：{holiday_name}")
print(f"是否节假日：{is_holiday}")
print(f"是否工作日：{is_work}")
# 2. 查询2026年所有法定节假日
print("\n2026年法定节假日：")
holidays = Holiday.getHolidays(2026)
for hd in holidays:
print(f"{hd['name']}：{hd['start']} 至 {hd['end']}")
# 3. 批量判断未来7天是否为节日
print("\n未来7天节日查询：")
for i in range(7):
s = solar.next(i)
name = Holiday.getName(s)
print(f"{s.toYmd()}：{name if name else '无节日'}")代码说明：Holiday.getName(solar)返回节日名称，无则为空；isHoliday()判断是否为节假日，isWork()判断是否为调休工作日；getHolidays(year)返回指定年份的节假日列表。
4.4 吉凶方位与彭祖百忌查询
lunar-python集成老黄历功能，可查询每日吉神、凶煞方位及彭祖百忌：
lunar = Lunar.fromYmd(2026, 1, 15)
# 1. 查询吉神方位（喜神、福神、财神、贵神）
xi_shen = lunar.getXiShenFangWei()
fu_shen = lunar.getFuShenFangWei()
cai_shen = lunar.getCaiShenFangWei()
yang_gui = lunar.getYangGuiShenFangWei()
yin_gui = lunar.getYinGuiShenFangWei()
print(f"喜神方位：{xi_shen}")
print(f"福神方位：{fu_shen}")
print(f"财神方位：{cai_shen}")
print(f"阳贵神方位：{yang_gui}")
print(f"阴贵神方位：{yin_gui}")
# 2. 查询彭祖百忌
peng_zu = lunar.getPengZuBaiJi()
print(f"彭祖百忌：{peng_zu}")
# 3. 查询冲煞信息
chong_sha = lunar.getChongSha()
print(f"冲煞：{chong_sha}")代码说明：方位返回中文方位词（如东南、正南）；彭祖百忌返回当日禁忌；冲煞返回冲犯生肖与方位。
4.5 八字命理计算
EightChar模块支持八字排盘，可查询四柱八字、大运、流年等命理信息：
from lunar import EightChar
# 1. 创建八字对象（2026年正月十五 子时）
lunar = Lunar.fromYmdHms(2026, 1, 15, 0, 0, 0)
eight_char = EightChar(lunar)
# 2. 查询四柱八字
print("四柱八字：", eight_char.getFourPillar())
print("年柱：", eight_char.getYearPillar())
print("月柱：", eight_char.getMonthPillar())
print("日柱：", eight_char.getDayPillar())
print("时柱：", eight_char.getTimePillar())
# 3. 查询大运（起运岁数、大运干支）
da_yun = eight_char.getDaYun()
print("\n大运：")
for dy in da_yun:
print(f"{dy['age']}岁：{dy['ganZhi']}")
# 4. 查询流年（2026-2030年流年）
print("\n2026-2030年流年：")
for year in range(2026, 2031):
liu_nian = eight_char.getLiuNian(year)
print(f"{year}年：{liu_nian}")代码说明：八字计算需基于含时辰的农历对象；getFourPillar()返回完整四柱，getDaYun()返回大运信息，getLiuNian(year)返回指定年份的流年干支。
五、lunar-python实战案例：多功能日历生成工具
5.1 案例需求
开发一个Python脚本，实现以下功能：
- 输入公历日期，输出对应农历、干支、生肖、节气、节日
- 生成指定月份的公历-农历对照日历
- 批量查询未来30天的吉神方位与彭祖百忌
- 支持命令行交互，操作简单
5.2 完整代码实现
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
from lunar import Lunar, Solar, Holiday
def query_single_date(year, month, day):
"""查询单个公历日期的详细信息"""
try:
solar = Solar.fromYmd(year, month, day)
lunar = solar.getLunar()
# 基础信息
print("="*50)
print(f"【公历日期】{solar.toFullString()}")
print(f"【对应农历】{lunar.toFullString()}")
print(f"【干支纪年】{lunar.getYearGanZhi()} 【生肖】{lunar.getShengXiao()}")
print(f"【当前节气】{lunar.getJieQi() if lunar.getJieQi() else '无'}")
# 节日信息
holiday = Holiday.getName(solar)
print(f"【节日】{holiday if holiday else '无'}")
# 黄历信息
print(f"【喜神方位】{lunar.getXiShenFangWei()} 【财神方位】{lunar.getCaiShenFangWei()}")
print(f"【彭祖百忌】{lunar.getPengZuBaiJi()}")
print("="*50 + "\n")
except Exception as e:
print(f"日期查询错误：{e}")
def generate_month_calendar(year, month):
"""生成指定月份的公历-农历对照日历"""
print(f"\n{'='*20} {year}年{month}月 公历-农历对照日历 {'='*20}")
print(f"{'公历日期':<12} {'农历日期':<12} {'星期':<4} {'节日':<8} {'节气':<6}")
print("-"*60)
# 获取当月天数
first_day = Solar.fromYmd(year, month, 1)
for i in range(31):
try:
solar = first_day.next(i)
if solar.getMonth() != month:
break
lunar = solar.getLunar()
holiday = Holiday.getName(solar) or "无"
jieqi = lunar.getJieQi() or "无"
print(f"{solar.toYmd():<12} {lunar.toYmd():<12} {solar.getWeekInChinese():<4} {holiday:<8} {jieqi:<6}")
except:
break
print("-"*60 + "\n")
def batch_query_thirty_days(year, month, day):
"""批量查询未来30天的黄历信息"""
print(f"\n{'='*20} 未来30天黄历查询 {'='*20}")
start_solar = Solar.fromYmd(year, month, day)
for i in range(30):
solar = start_solar.next(i)
lunar = solar.getLunar()
print(f"{solar.toYmd()} | 农历：{lunar.toYmd()} | 喜神：{lunar.getXiShenFangWei()} | 彭祖百忌：{lunar.getPengZuBaiJi()}")
print("="*60 + "\n")
def main():
"""主函数：命令行交互"""
print("欢迎使用lunar-python多功能日历工具")
while True:
print("\n请选择功能：")
print("1. 查询单个日期详细信息")
print("2. 生成月份公历-农历对照日历")
print("3. 批量查询未来30天黄历")
print("4. 退出工具")
choice = input("请输入功能编号（1-4）：")
if choice == "1":
try:
y = int(input("请输入公历年份："))
m = int(input("请输入公历月份："))
d = int(input("请输入公历日期："))
query_single_date(y, m, d)
except ValueError:
print("输入错误，请输入有效数字！")
elif choice == "2":
try:
y = int(input("请输入年份："))
m = int(input("请输入月份："))
generate_month_calendar(y, m)
except ValueError:
print("输入错误，请输入有效数字！")
elif choice == "3":
try:
y = int(input("请输入起始公历年份："))
m = int(input("请输入起始公历月份："))
d = int(input("请输入起始公历日期："))
batch_query_thirty_days(y, m, d)
except ValueError:
print("输入错误，请输入有效数字！")
elif choice == "4":
print("感谢使用，再见！")
break
else:
print("输入无效，请重新选择！")
if __name__ == "__main__":
main()5.3 代码说明与运行效果
- 函数设计：拆分
query_single_date（单日期查询）、generate_month_calendar（月历生成）、batch_query_thirty_days（批量查询）、main（交互入口）4个函数，结构清晰，便于维护。 - 异常处理：加入
try-except捕获日期格式错误、输入非数字等异常，提升工具稳定性。 - 功能覆盖：整合基础转换、节日查询、黄历信息、批量处理等核心功能，满足日常日历需求。
- 运行方式：保存为
lunar_calendar.py，命令行执行python lunar_calendar.py，按提示操作即可。
六、lunar-python库相关资源
6.1 官方资源地址
- PyPI地址：https://pypi.org/project/lunar-python/
- GitHub地址：https://github.com/6tail/lunar-python
- 官方文档地址：http://6tail.cn/calendar/api.html
6.2 资源使用建议
- PyPI页面可查看版本更新日志、依赖信息，安装时可指定稳定版本。
- GitHub仓库包含完整源码、示例代码、issue记录，可提交bug或功能建议。
- 官方文档提供详细API说明、参数解释、进阶示例，是开发的核心参考。
关注我，每天分享一个实用的Python自动化工具。
