序列化
模块:
borax.calendars.festivals2
Updated in 3.6.0:LunarDate类不再支持直接序列,必须先转化对应的 WrappedDate 对象。
Updated in 3.5.6: 星期型节日(WeekFestival)类支持倒数序号。如:“国际麻风节(1月最后一个星期天)”
Add in 3.5.0
概述
Borax.Calendars 实现了日期和节日的序列化和持久化,将表示日期或节日的python对象转化为特定格式的字符串存储在外部文件、数据库,也可以通过网络传输对象(如RPC调用)。
下面是一些简单的示例:
节日 | 序列化格式 | 节日 | 序列化格式 | 节日 | 序列化格式 |
---|---|---|---|---|---|
元旦 | 001010 | 劳动节 | 005010 | 国庆节 | 010010 |
春节 | 101010 | 中秋节 | 108150 | 母亲节 | 205026 |
感恩节 | 211043 | 除夕 | 312011 | 清明 | 400060 |
2021元旦 | 0202101010 | 2021年劳动节 | 0202105050 | 2021年正月初一 | 1202101010 |
2020年闰四月十五 | 1202004151 | - | - | - | - |
其中日期使用10位编码表示、节日使用6位编码表。日期字符串编码的第2-5位表示年份信息,其他字段的意义和节日字段相同。
Borax.Calendars 使用类似下列接口实现序列化和反序列化。
class EncodeMixin:
def encode(self) -> str:
pass
@classmethod
def decode(cls, raw:str) -> 'cls':
pass
下表是 festivals2
模块中实现该接口的日期节日对象。
日期节日类 | 描述 |
---|---|
WrappedDate | 公历日期、农历日期 |
Festival | 节日的基类 |
SolarFestival | 公历节日,如元旦、劳动节、程序员节 |
LunarFestival | 农历节日,如除夕、中秋节 |
WeekFestival | 公历星期节日,如母亲节、感恩节 |
TermFestival | 节气型节日,如清明、冬至 |
和 festivals
相比, festivals2
不再支持 LunarDate
的序列化,必须转化为对应的 WrappedDate
对象。这一特定将在Borax3.6版本移除。
使用方法
序列化方法定义在三个模块方法。
encode
festivals2.encode(obj: Union[WrappedDate, Festival]) -> str
序列化日期或节日对象,返回特定格式的字符串。
decode
festivals2.decode(raw: Union[str, bytes]) -> Union[WrappedDate, Festival]
反序列化日期或节日对象,返回 WrappedDate
或 Festival
对象。
decode_festival
festivals2.decode_festival(raw: Union[str, bytes]) -> Festival
反序列化节日对象,返回 Festival
对象。
基本定义
编码格式
基本的编码格式如下:
<1位schema> [<4位year>] <2位month> <2位day> <1位标志>
一些节日在此基础上进行了修改,参见下面的各子Festival的定义。
FestivalSchema
第一位表示日期/节日类型,具体的对应关系如下:
首位取值 | 节日类 | 备注 |
---|---|---|
0 | SolarFestival / WrappedDate | |
1 | LunarFestival / WrapedDate | |
2 | WeekFestival | |
3 | LunarFestival / WrappedDate | 兼容旧版本DayLunarSchema,只作解析,不作编码 |
4 | TermFestival |
EncoderFlag
SolarFestival
和 LunarFestival
的最后一位表示标志位。
flag 字段使用聚合布尔值表示若干个标志的取值。
flag 的取值范围为0-F,标志值对应关系如下:
flag取值 | day年序号 | 是否每月 | 是否倒序 | 是否闰月 | |
---|---|---|---|---|---|
0 | 0 | 0 | 0 | 0 | 月序号,每年,正序,平月 |
1 | 0 | 0 | 0 | 1 | 月序号,每年,正序,闰月 |
2 | 0 | 0 | 1 | 0 | 月序号,每年,倒序,平月 |
3 | 0 | 0 | 1 | 1 | 月序号,每年,倒序,闰月 |
4 | 0 | 1 | 0 | 0 | 月序号,每月,正序,平月 |
5 | 0 | 1 | 0 | 1 | 月序号,每月,正序,闰月 |
6 | 0 | 1 | 1 | 0 | 月序号,每月,倒序,平月 |
7 | 0 | 1 | 1 | 1 | 月序号,每月,倒序,闰月 |
8 | 1 | 0 | 0 | 0 | 年序号,每年,正序,平月 |
9 | 1 | 0 | 0 | 1 | 年序号,每年,正序,闰月 |
A | 1 | 0 | 1 | 0 | 年序号,每年,倒序,平月 |
B | 1 | 0 | 1 | 1 | 年序号,每年,倒序,闰月 |
C | 1 | 1 | 0 | 0 | 年序号,每月,正序,平月 |
D | 1 | 1 | 0 | 1 | 年序号,每月,正序,闰月 |
E | 1 | 1 | 1 | 0 | 年序号,每月,倒序,平月 |
F | 1 | 1 | 1 | 1 | 年序号,每月,倒序,闰月 |
日期序列化
WrappedDate
字段(偏移量) | type(1) | year(4) | month(2) | day(2) | flag(1) |
---|---|---|---|---|---|
描述 | 节日类型 | 年份 | 月份 | 日期 | 标志位 |
取值范围 | 0(公历) | 1900-2100 | 01-12 | 01-31 | 0 |
1(农历) | 1900-2100 | - | 01-30 | 0-1 |
公历农历日期。
- 当type=1表示农历日期,此时flag表示是否是农历闰月。
节日序列化
SolarFestival
字段(偏移量) | type(1) | month(2) | day(2) | flag(1) |
---|---|---|---|---|
描述 | 节日类型 | 月份 | 日期 | 标志位 |
取值范围 | 0 | 01-12 | 01-31 | 0-7 |
0 | - | 0000-0366 | 8-F |
公历型节日。
- 当 flag 取4-7 时,编码第2-5位共同表示一个day字段。
LunarFestival
字段(偏移量) | type(1) | month(2) | day(2) | flag(1) |
---|---|---|---|---|
描述 | 节日类型 | 月份 | 日期 | 标志位 |
取值范围 | 1 | 01-12 | 01-31 | 0-7 |
1 | - | 0000-0384 | 8-F | |
3 | 00-12 | 01-31 | 0-1 |
农历型节日。
- 当 type = 1 且 flag 取4-7 时,编码第2-5位共同表示一个day字段。
- type = 3时为兼容旧版本之用,此时 0 表示(每年,正序,平月),1表示(每年,倒序,平月)
WeekFestival
Updated in 3.5.6: index字段支持10以上数值,表示倒数计数。
Updated in 3.5.6: month允许取值0。
字段(偏移量) | type(1) | month(2) | index(2) | week(1) |
---|---|---|---|---|
描述 | 节日类型 | 月份 | 序号 | 星期 |
取值范围(每年) | 2 | 01-12 | 01-05,11-15 | 0-6 |
(每月) | 2 | 00 | 01-05,11-15 | 0-6 |
星期型节日。
- month=0时,表示每月频率。
- index 大于10表示倒数,如12表示倒数第二。
TermFestival
字段(偏移量) | type(1) | nth_t(1) | nth_v(1) | index(2) | day_gz(1) |
---|---|---|---|---|---|
描述 | 节日类型 | 序号类型 | - | 节气序号 | 日期天干或地支 |
取值范围 | 4 | 0 | 0 | 00-23 | 0 |
天干、向前向后 | 1 | 1-9 | 00-23 | 0-9 | |
天干、向前计数 | 2 | 1-9 | 00-23 | 0-9 | |
地支、向前向后 | 3 | 1-9 | 00-23 | 0-B | |
地支、向前计数 | 4 | 1-9 | 00-23 | 0-B |
节气型节日。
- 节气序号(index )按照公历一年先后排序,即0为小寒、1为大寒、6为清明、23为冬至。