lunar-python节假日数据压缩原理与fix()自定义节日、纪念日完整指南

原创2026-11-03 20:04:221,451 阅读

lunar-python节假日数据压缩原理与fix()自定义节日、纪念日完整指南

lunar-python是一款零第三方依赖的 Python 日历库,它的法定节假日数据用"每 18 位字符 = 1 天"的极简压缩串存储,整份 20 年数据仅约 15KB。本文带你读懂 lunar-python 节假日数据压缩原理,并手把手教你用 fix() 函数完成自定义节日、纪念日(生日、结婚纪念日)的追加、修改与删除,是面向新手的完整指南。

1. 30 秒认识 HolidayUtil

节假日相关的核心代码就两个文件:

内置数据覆盖 2001 年 12 月 29 日起的法定节假日,共 860 条记录。默认支持的节假日名称只有 9 种(定义在 HolidayUtil.py 的 NAMES):

元旦节、春节、清明节、劳动节、端午节、中秋节、国庆节、国庆中秋、抗战胜利日

查询接口非常直观,三种写法等价:

from lunar_python.util import HolidayUtil

HolidayUtil.getHoliday('2020-05-02')        # 写法一:完整日期串
HolidayUtil.getHoliday(2020, 5, 2)           # 写法二:年月日分开传
HolidayUtil.getHolidays(2020, 5)             # 查 2020 年 5 月所有节假日
HolidayUtil.getHolidaysByTarget('2020-10-01') # 反查:哪些天关联 10 月 1 日

返回的 Holiday 对象可调用 getName()(名称)、isWork()(是否调休上班)、getTarget()(关联的节日日期),或直接 toString() 输出类似 2020-05-02 劳动节 2020-05-01 的完整描述。

2. 节假日数据压缩原理:18 位字符串 = 1 天

打开 HolidayUtil.py,你会看到一段令人惊叹的"天书"(第 13 行)——一整行没有任何分隔符的数字串。它不是乱码,而是按 18 位一条、顺序排列的节假日记录:

字段 占位 说明
当天日期 8 位 YYYYMMDD,如 20200502
名称下标 1 位 对应 NAMES 表下标:0→'0',1→'1'……下标 9 及以上按 ASCII 顺排(9、:、;…)
调休标识 1 位 0 = 调休要上班,1 = 放假
关联节日 8 位 假期所属节日当天,如 20200501

以 20200502 3 1 20200501 为例:

  • 下标 3 对应"劳动节",调休位 1 表示放假;
  • 结论:2020-05-02 是劳动节假期,对应节日 2020-05-01 ✅

再看一条调休记录 20200119 1 0 20200205(春节前周末补班日):调休位为 0,表示这天要上班。

为什么这样做?

  • 极致省空间:860 天数据仅 15480 个字符(约 15KB),比 JSON 表格小一个数量级;
  • 查找极快:数据天然按日期升序拼接,查询时直接 find() 定位前缀,再按 18 位步进即可,无需解析整个文件;
  • 可追加可编辑:修改只需字符串替换(见下节),这是 fix() 能轻松实现增删改的底层原因。

3. fix() 函数:自定义节日、纪念日的三种操作

fix() 是节假日数据的"入口",定义在 HolidayUtil.py,签名为 fix(names, data):

  • names:替换默认名称表。传 None 表示沿用默认;想自定义节日时,先把名称追加到列表再传入;
  • data:18 位一段的压缩数据串,一段代表一天,可多段拼接传入。

官方演示脚本 demo.py 覆盖了全部用法,下面逐一说透。

3.1 修改已有节假日

把内置的"2020-01-01 元旦节"改成"春节"(下标 1):

# 20200101 + 名称下标1 + 调休1(放假) + 关联日20200101
HolidayUtil.fix(None, "202001011120200101")
print(HolidayUtil.getHoliday('2020-01-01'))  # 2020-01-01 春节 2020-01-01

原理:fix() 发现该日期已有记录,就用新记录原位替换旧数据。

3.2 追加新节日 / 纪念日

数据里没有的日期会被自动追加到串尾。追加 2099 年的元旦:

HolidayUtil.fix(None, "209901010120990101")
print(HolidayUtil.getHoliday('2099-01-01'))  # 2099-01-01 元旦节 2099-01-01

3.3 删除节假日(~ 标记)

第 9 位(名称位)写 ~ 表示删除该日期记录,其余位置任意(建议补 0):

HolidayUtil.fix(None, "20100101~000000000000000000000000000")
print(HolidayUtil.getHoliday(2010, 1, 1))  # None

该用例与官方测试 HolidayTest.py 完全一致。

3.4 进阶:自定义节日 + 纪念日的正确姿势

默认 NAMES 表只有 9 项。要存"我的生日""结婚纪念日"这类个人纪念日,必须先扩展名称表,下标 9、10 对应字符 9 和 ::

from lunar_python.util import HolidayUtil

names = list(HolidayUtil.NAMES)          # 复制默认名称表
names.append("我的生日")                # 下标 9  -> 字符 '9'
names.append("结婚纪念日")              # 下标 10 -> 字符 ':'
names.append("她的生日")                # 下标 11 -> 字符 ';'

# 一次性传入多段:2021-05-29 我的生日、2021-11-11 结婚纪念日、2021-12-01 她的生日
HolidayUtil.fix(names, "20210529912021052920211111:12021111120211201;120211201")
print(HolidayUtil.getHoliday('2021-05-29'))  # 2021-05-29 我的生日 2021-05-29
print(HolidayUtil.getHoliday('2021-11-11'))  # 2021-11-11 结婚纪念日 2021-11-11

💡 实用建议:做个人日历应用时,可以把"名称表 + 压缩串"整体序列化保存下来,下次启动时先调一次 fix(names, data) 恢复状态,纪念日数据即刻生效。

4. 上手清单与常见问题

  • ✅ 数据长度必须按 18 位对齐:不足 18 位的尾部会被忽略(fix() 内 while len(data) >= 18 循环决定);
  • ✅ 调休位别写反:0 = 上班,1 = 放假;
  • ✅ fix() 修改的是进程内内存数据:不会写回源码文件,进程重启后需重新调用(这也是"保存 names + data 自行恢复"建议的由来);
  • ✅ 新增名称后下标立即生效:下标 9 及以上按 ASCII 顺排,无需重启;
  • 🎯 节假日还会驱动工作日推算:Solar.py 的 next(days, only_work_day=True) 会结合节假日数据跳过假期,例如 2020-01-23 的下一个工作日自动跳到 2020-02-03(春节后首个工作日)。

掌握"18 位压缩格式 + fix() 增删改"这两块拼图,你就能把 lunar-python 的节假日能力用到极致——从公司调休表到个人纪念日,全部一个 API 搞定。

登录后查看全文
lunar-python