挑战Arrow，需要怎样的实力？Pendulum使用笔记

Pendulum简介

Pendulum是一款很优秀的Python时间处理模块，其内置数据类型拓展自datetime，与datetime有着很好的兼容性。Pendulum比dateutil功能更丰富，足矣和Arrow对标。Pendulum[ˈpendʒələm]意为钟摆，很好的时间意向。Pendulum在时间解析、转换、属性获取、时区、时间序列等方面都有很好的表现，其用于时间处理的语句概览如下。

时间对象生成

Pendulum内置对象是一个自定义的DateTime对象，但可以当成datetime使用，也就是说dt.year、.strftime()等是完全可以正常使用的，并且Pendulum的一些函数需要输入DateTime作为参数时，输入datetime对象也兼容。
Pendulum支持手动输入年月日等属性构建时间对象，也能非常方便地把时间戳或字符串转换为时间对象，一些常用方法如下。

pendulum.datetime(2020,5,7)：输入年月日等生成DateTime，对应着datetime.datetime()的写法;
pendulum.now()：获取当前时间，时区直接取当地时区，还有 .today() .tomorrow() .yesterday() 等可以用；
pendulum.local(args)：获取当地时间的对象，可以输入年月日等；
pendulum.parse(text)：从文本中解析出时间对象，有个类似的方法是pendulum.from_format(text,s)；
pendulum.from_timestamp(ts)：把时间戳ts转为时间对象；
pendulum.timezone(“Europe/Paris”)：生成一个时区对象；

import pendulum
pendulum.datetime(2020,12,1, tz='America/Toronto')
#DateTime(2020,12,1,0,0,0,tzinfo=Timezone('America/Toronto'))
dt=pendulum.now()
#DateTime(2020,12,8,18,0,8,697484,tzinfo=Timezone('Asia/Shanghai'))
pendulum.tomorrow() #明天的这个时候
pendulum.parse('2020-05-21T22:00:00', tz='Europe/Paris')
pendulum.from_timestamp(1607343278)

要素获取与格式化

从各种数据格式中解析出时间对象后，获取其日期属性及进行计算是最常见的，和datetime一致，通过dt.year得到对象dt所在年份，这也是很自然的写法，Pendulum有一个特色属性是.age，是对应日期在目前的年龄。

#dt=pendulum.now()
dt.year # .month .second 等
# 2020
dt.week_of_year #dt所在周是本年第几周
dt.int_timestamp #把dt表示为整数的timestamp
#还有.float_timestamp可以用
dt.age #dt对应日期目前的年龄

将DateTime对象转为字符串既有dt.strftime(fmt)可以用，fmt占位符意义datetime库一致，还有一个和Arrow对标的dt.format(fmt)。

dt.strftime('%Y-%m-%d')
#'2020-12-07'
dt.format('YYYY-MM-DD')
#'2020-12-07'
dt.format('dddd Do [of] MMMM YYYY HH:mm:ss A')
#'Monday 7th of December 2020 20:20:36 PM'

时间偏移

要修改DateTime对象dt的属性使用dt.set()方法，例如修改年份为2019年，是dt.set(year=2019)，这种方法生成的是新的时间对象。要生成一段时间后的时间对象，也可以用dt.add/subtract方法，也就是时间偏移的效果。Pendulum的接口很丰富，修改时间要素还可以使用on和at，例如dt.on(1975).at(22)，on处理年月日，at处理时间的小时分钟和秒。

d2=dt.set(year=2019) #把年份变成2019
dt.add(years=-1) #把时间变成1年前，注意是years不是year
dt.subtract(years=1) #1年前
dt.start_of('day') #获得当天的0点时间，也即开始时间
#对应的有 dt.end_of('day')

两个时间的时间间隔，在datetime里是timedelta，Pendulum库是抽象为Period。可以直接通过d2-d1生成，或者用diff()方法。

dt-dt.set(year=2019)
#<Period [2019-12-11T14:26:54.769932+08:00 -> 2020-12-11T14:26:54.769932+08:00]>
p=dt.diff(dt.set(year=2019))
p.years  
#Out[]:1
p.in_hours()
# 8784

diff_for_humans方法可以将时间间隔按自然语言输出。

pendulum.now().diff_for_humans(dt)
#'2 minutes after'
dur = pendulum.duration(days=15)
dur.in_words(locale='en')
#'2 weeks 1 day'

时间序列

要生成一个时间序列使用Period和Range结合，先约定序列的开始时间和结束时间，再设定频率。

start = pendulum.datetime(2020, 1, 1)
end = pendulum.datetime(2020, 1, 10)
period = pendulum.period(start, end)
list(period.range('days',2))
#[DateTime(2020, 1, 1, 0, 0, 0, tzinfo=Timezone('UTC')),
# DateTime(2020, 1, 3, 0, 0, 0, tzinfo=Timezone('UTC')), ...

总结

Pendulum是一个能和Arrow对标的时间处理库。Arrow的易用性体现在接口简洁，Pendulum的易用性表现在很多datetime的方法都兼容。Pendulum通过其内置的DateTime对象实现和拓展datetime.datetime的功能，同时封装出Duration、Period及Timezones处理时间偏移、时区、时间序列。Pendulum的官方文档1美观漂亮，而且写得很详细，是非常优秀的文档范例。
【整体的xmind】

参考资料

Pendulum Github；
[Pendulum doc