lunar-python节假日数据压缩原理与fix()自定义节日、纪念日完整指南
lunar-python节假日数据压缩原理与fix()自定义节日、纪念日完整指南
lunar-python是一款零第三方依赖的 Python 日历库,它的法定节假日数据用"每 18 位字符 = 1 天"的极简压缩串存储,整份 20 年数据仅约 15KB。本文带你读懂 lunar-python 节假日数据压缩原理,并手把手教你用 fix() 函数完成自定义节日、纪念日(生日、结婚纪念日)的追加、修改与删除,是面向新手的完整指南。
1. 30 秒认识 HolidayUtil
节假日相关的核心代码就两个文件:
- 数据与压缩算法:HolidayUtil.py
- 查询结果对象:Holiday.py
内置数据覆盖 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 搞定。