# cnlunar - 基于协纪辨方书的 Python 黄历库

> 无需数据库，以《钦定协纪辨方书》为核心计算农历、节气、八字、每日宜忌、神煞、建除十二神、二十八宿

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

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

## 核心特点

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

## 安装

```bash
pip3 install cnlunar
```

## 快速使用

```python
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⭐ |

---

**分类**：软件
**标签**：cnlunar · 农历 · print
**作者**：Xiao.Xi
**链接**：https://octohz.com/p/1902