cnlunar — 基于《钦定协纪辨方书》的 Python 农历黄历库

cnlunar 是一个无需数据库、纯 Python 实现的中国农历与黄历计算库，以清代《钦定协纪辨方书》为核心依据，提供节气、干支八字、每日宜忌、神煞、建除十二神、二十八宿、时辰吉凶等完整传统历法数据。

核心特点

• 无数据库依赖：所有 1901–2100 年的农历、节气、节假日数据通过压缩编码内嵌在代码中，运行快速、部署简单。
• 以《钦定协纪辨方书》为源：每日宜忌、吉神凶煞、值神、建除十二神等规则均来自该书，并保留原文注释。
• 弃用寿星通式：采用香港天文台观测/预测数据计算二十四节气，避免 [Y×D+C]-L 经验公式在边界年份的误差。
• 数据完整：覆盖农历转换、八字四柱、黄历宜忌、彭祖百忌、纳音、九宫飞星、二十八宿、时辰经络、吉神方位等。

安装

pip3 install cnlunar

快速使用

import datetime, cnlunar

a = cnlunar.Lunar(datetime.datetime(2022, 11, 14, 10, 30), godType='8char')

print('农历', a.lunarYearCn, a.year8Char, a.lunarMonthCn, a.lunarDayCn)
print('八字', a.year8Char, a.month8Char, a.day8Char, a.twohour8Char)
print('今日节气', a.todaySolarTerms)
print('十二神', a.get_today12DayOfficer())
print('廿八宿', a.get_the28Stars())
print('宜', a.goodThing)
print('忌', a.badThing)
print('吉神', a.goodGodName)
print('凶煞', a.badGodName)

主要功能

模块	能力
历法	公历↔农历转换、二十四节气、季节、节假日
八字	年柱、月柱、日柱、时柱，支持立春切换算法
黄历	每日宜忌、宜忌等第、神煞宜忌
神煞	吉神方位、今日胎神、时辰凶吉、建除十二神
星宿	二十八宿、九宫飞星、星次、星座
杂项	彭祖百忌、纳音、生肖冲煞、今日三合/六合

项目数据

• GitHub: https://github.com/OPN48/cnlunar
• Stars: 792 / Forks: 188
• 最新 Release: 0.2.4
• License: MIT

适用场景

• 需要在中国网站或 App 中显示传统黄历的开发者
• 八字排盘、择日、风水类工具的后端计算
• 日历应用、万年历、民俗类产品的历法引擎
• 需要精确节气与农历转换的数据分析项目

同类项目对比

项目	定位	是否基于协纪辨方书	热度
cnlunar	Python 黄历库	✅ 核心依据	792⭐
kanripo/KR3g0051	协纪辨方书原文	✅ 古籍全文	0⭐
danielyuen/pyLunarCalendar	cnlunar 早期分支	✅	3⭐
geneliu/pyGregorian2LunarCalendar	农历转换分支	✅	0⭐