原文地址：https://kinegratii.github.io/2019/01/05/lunardate-module/

感谢原作者！本人只是搬运工。看完这个和上一篇基本对农历就有了一个较全面的认识。

本文简要介绍了我国传统的农历历法知识，并叙述了 Borax-Lunar 工具库开发背后的一些算法原理和技术资料。

目录

1 农历概述

1.1 编排规则

1.2 表示方法

1.3 二十四节气

2 数据结构

2.1 大小月和闰月

2.2 节气的数据结构

3 Borax-Lunardate概述

4 模块设计

4.1 LunarDate日期类

4.1.1 初始化日期对象

4.1.2 基准日期

4.2 格式化显示

4.2.1 使用方法

4.2.2 源码解析

4.3 类型标注

4.3.1 概述

4.3.2 常用的使用示例

5 参考资料

农历是我国的传统历法，依据太阳和月球位置的精确预报以及约定的日期编排规则编排日期，并以传统命名方法表述日期。

2017年，我国已经颁布了国家推荐性标准《GB/T 33661-2017 农历的编算和颁行》。

农历属于一种阴阳合历，基本规则如下：其年份分为平年和闰年。平年为十二个月；闰年为十三个月。月份分为大月和小月，大月三十天，小月二十九天。一年中哪个月大，哪个月小，可由“置闰规则”计算决定。

若从某个农历十一月开始到下一个农历十一月（不含）之间有13个农历月，则需要置闰。置闰规则为：去其中最先出现的一个不包含中气的农历月为农历闰月。

除此之外，还有生肖纪年、干支纪年、二十四节气等。

农历日期通常有以下几种表示方法：

一个回归年内24个太阳地心视黄经等于15度的整数倍的时刻的总称，每个时刻成为一个节气。太阳每年运行360度，共经历二十四个节气，分别为立春（315度）、雨水（330度）、惊蛰（345度）、春分（0度、360度）、清明（15度）、谷雨（30度）、立夏（45度）、小满（60度）、芒种（75度）、夏至（90度）、小暑（105度）、大暑（120度）、立秋（135度）、处暑（150度）、白露（165度）、秋分（180度）、寒露（195度）、霜降（210度）、立冬（225度）、小雪（240度）、大雪（255度）、冬至（270度）、小寒（285度）、大寒（300度）。可以通过下面的儿歌记忆这些节气。

2016年11月30日，中国“二十四节气”被正式列入联合国教科文组织人类非物质文化遗产代表作名录。

农历月份大小、农历闰/平年、二十四节气的日期没有什么特定的规律，只能使用原始的“查表法”存储和查询这些信息。

从香港天文台网站可以获取1900 - 2100年的农历信息，每一天包含公历日期、农历日期、星期、节气四项基本信息。日期范围的基本信息如下表：

具体到一个农历年中，从中可以看出以下几点信息：

如何使用精炼的数据结构表述这些信息，是一个重要的前提，主要要求算法简单、内存占用少。网上有许多种方式，一种比较通行的做法是使用5字节的数据，高3位总是“000”，实际使用的低17位二进制。

综上所述，2017年信息可以使用 0x15176 表示；2019年信息可使用 0x0a930 表示。

36位字符串

二十四节气开始的日期，与通用的公历几乎一致，最多相差一两天，因为是按照地球一年绕太阳公转一周作为依据。比如小寒通常落在在1月5-7日，立春落在2月3-5日，冬至落在12月21-23日。即每个月都会有2个节气，1月只能有小寒、大寒这两个节气。

构建两个含有24元素的数组，

第一个数组以小寒为第1个节气重新排列这24个节气。

第二个数组表示对应节气对应的日期数字。

结合这两个数组，可记录在一个公历年中，二十四个节气分别是在哪一天。比如上述的24个数字可解释为：1月6日是小寒、1月20日是大寒…12月7日是大雪、12月22日是冬至。

在 Python 语言层面，可以使用字符串（基本数据类型）代替上述数组（复合数据类型），即"620419621520621622723823823924823722" ，需要36位字符存储。

解析表中数据的 Python 代码实现如下：

30位字符串

jjonline/calendar.js 提供了一种用更为简单的表示方法：利用十六进制压缩数字的位数，进一步简化为30位的字符串。具体计算过程如下：

使用 Python代码实现上述算法如下：

24位字符串

从 Borax v1.2.0 开始使用算法。

统计1900-2100年之前节气日期统计可知，中气的日期都是在18-24日之间，这些均为两位数，可以通过线性变化转为一位数的数字，结合月份特点，可以通过减去一个固定偏移量15就是比较好的选择。

同样的按照上述处理，具体过程如下：

同样的使用Python 代码如下，和30位表示法相比，更为简单直接。

到2019年1月为止，关于农历的主题，github/PyPI 上已经有非常多的代码项目，语言有C、Java、Python等，具体的思路也不一样。综合来看，这些库有的功能单一，只覆盖某几个方面；有的已经很久没有更新了，主要是农历信息已在多年之前就采集完成，但是对于一些最新的数据修正未能及时涵盖；也有的在代码层面没有很好的适用最新的 Python 语言特性。

基于此，本人利用收集整理的一些技术资料开发出了 Borax-Lunar 这个库，主要的目标和特点有：

在开发过程中我收集网络上的几个重要农历数据，包含了干支、生肖、节气等事项，并同时将它们作为数据验证的参考标准。

另外，一些术语命名（比如天干、地支等）采用 《GB/T 33661-2017 农历的编算和颁行》 所规定的文字。

Borax-Lunardate 库分为三个部分：1) 基于 LunarDate 的农历日期表示；2）类似于 datetime.strftime 的字符串格式系统；3） 一些常用的农历工具接口。

其中第2,3部分是网络上的农历库比较少涉及的，Borax-Lunardate 在这一方面非常有优势的。

在模块/类层面的组织和分类上，Borax-Lunardate 对标标准库的 datetime 和 calendar 模块，实现了这两个模块中与农历日期相联系的方法，LunarDate 和 date 类有许多相同的特性，包括不可变类、可比较性、时间加减等。 甚至有些命名也是一样的，比如 strftime 方法。

LunarDate 是一个重要的类，每一个对象表示一个农历日期，一个特定的农历日期可以由农历年、月、日、闰月标志4个字段唯一确定，可以使用这些字段初始化对象。

对于一些特定的日期，也可以通过类方法创建这些日期对象。

LunarDate 类使用可表示范围的下限作为基准日期（即LunarDate(1990, 1, 1, False)）。对象的 offset 属性表示与基准日期相差的天数，这也是一种可以唯一确定日期的方法。

该功能由 Borax-Lunardate 特有的功能，提供了与 datetime.date.strftime 相似的功能。

LunarDate 提供了 strftime 方法，可以将一个农历日期按照给定的格式转化为字符串。

格式字符串使用 ‘%’ 加一个字母的描述符(Directive)表示日期对象的一个字段，常用的描述符见下表：

备注：

下面是几个使用 strftime 的例子：

strftime 的具体实现定义在 lunardate.Formatter 类。该类接受一个 %形式的格式字符串，转化为命名字段形式的格式字符串，并格式化给定的日期对象，如下图：

某个字段 field 的具体值，根据下列先后顺序确定具体的值。

核心代码如下：

PEP 484 和 PEP526 提供了一种针对 Python 语言的类型标注方法。在 Python3.5+ 以上，可以使用 typing 标准模块实现这一目的，需要说明的是：

方便使用者了解所调用函数的参数类型和返回值类型

类型标注不会影响运行，不会抛出异常，只是警告

配合IDE的语法语义检查功能，增强智能提示功能

下面是一个参数和返回值都是字符串的函数标注：

除了一些基本类型，常用的符合数据类型还有 Any、Union、Tuple、List、Callable、TyVar、Generic 等。

需要注意的是，Python 的语言特性也可能给类型标准的使用带来了一些麻烦，比如变量在使用过程中其类型有所变化。基于目标用户是API使用者，大概可以整理出几条实用的原则：

类型标注学习起来也不困难，掌握几种常见的情形即可。

使用 :表示参数类型，使用 -> 表示返回值类型，如上述的 greeting 函数 。

默认参数

可选参数，需要使用 Optional，通常和上面的默认参数相互配合。

自定义类型、混合类型，闰月标记可以使用布尔值或者整数。

后向引用，如果使用的类还没有定义，可以使用包含类名的字符串，以便后续实例化。一般用于创建对象的方法或者树形结构的定义。

类型绑定。在后向引用的例子中，通常需要在多个地方使用字符串方式，为避免拼写错误，可以使用 TypeVar 的 bound 参数提前预定义。

T = TypeVar('T', bound=BaseClass) 使用父类创建类型变量以便所有子类均可匹配，这和 Java/C++ 语言中的 多态 相类似。

迭代器，使用 Iterator。