timeutils - datetime 添加内容

Python 的 datetime 模块提供了一些在Python标准库中最复杂和最强大的原语。时间不是微不足道的，但值得庆幸的是，它的支持在Python中是一流的。 dateutils 提供了一些处理时间的其他工具。

此外，timeutils还提供了一些基本的实用程序，用于在Python中使用时区。 Python datetime 模块的文档介绍了如何创建 datetime -兼容 tzinfo 子类型。它甚至提供了几个例子。

以下模块定义了这些文档中可用的时区形式，以及其他几个有用的时区形式， UTC (又名GMT)和 LocalTZ (表示操作系统中配置的本地时区)。对于这些时区之外的时区，以及在转角情况下的更高精度，请查看 pytz 和 `dateutil`_ 。

boltons.timeutils.daterange(start, stop, step=1, inclusive=False)

本着……的精神 range() 和 xrange() vt.的. daterange 生成一个序列的生成器 date 对象，从 start ，递增 step ，直到 stop 已经到达了。

When inclusive is True, the final date may be stop, if step falls evenly on it. By default, step is one day. See details below for many more details.

参数:

• start (datetime.date) -- 开始日期序列中的第一个值。

• stop (datetime.date) -- 停止日期。默认情况下，不包括在返还中。可以是 None 产生一个无限的序列。

• step (int) -- 要递增的值 start 按需到达 stop 。可以是一个 int 天数，a datetime.timedelta ，或一个 tuple 在整数中， (year, month, day) 。正反两面 step 支持值。

• inclusive (bool) -- 不管是不是 stop 可以返回日期。 stop 仅当 step 均匀地落在上面。

>>> christmas = date(year=2015, month=12, day=25)
>>> boxing_day = date(year=2015, month=12, day=26)
>>> new_year = date(year=2016, month=1,  day=1)
>>> for day in daterange(christmas, new_year):
...     print(repr(day))
datetime.date(2015, 12, 25)
datetime.date(2015, 12, 26)
datetime.date(2015, 12, 27)
datetime.date(2015, 12, 28)
datetime.date(2015, 12, 29)
datetime.date(2015, 12, 30)
datetime.date(2015, 12, 31)
>>> for day in daterange(christmas, boxing_day):
...     print(repr(day))
datetime.date(2015, 12, 25)
>>> for day in daterange(date(2017, 5, 1), date(2017, 8, 1),
...                      step=(0, 1, 0), inclusive=True):
...     print(repr(day))
datetime.date(2017, 5, 1)
datetime.date(2017, 6, 1)
datetime.date(2017, 7, 1)
datetime.date(2017, 8, 1)

Be careful when using stop=None, as this will yield an infinite sequence of dates.

boltons.timeutils.isoparse(iso_str)

的有限子集分析 ISO8601-formatted time 由返回的字符串 datetime.datetime.isoformat() 。

>>> epoch_dt = datetime.utcfromtimestamp(0)
>>> iso_str = epoch_dt.isoformat()
>>> print(iso_str)
1970-01-01T00:00:00
>>> isoparse(iso_str)
datetime.datetime(1970, 1, 1, 0, 0)

>>> utcnow = datetime.utcnow()
>>> utcnow == isoparse(utcnow.isoformat())
True

有关进一步的日期时间分析，请参见 iso8601 用于严格的ISO解析和 `dateutil`_ 用于松散解析和更多内容的包。

boltons.timeutils.parse_timedelta(text)

强健地将一段时间段的简短文本描述解析为 datetime.timedelta 。支持周、日、小时、分钟和秒，带或不带小数点：

参数:

text (str) -- 要分析的文本。

返回:

datetime.timedelta

抛出:

ValueError -- 在分析失败时。

>>> parse_td('1d 2h 3.5m 0s') == timedelta(days=1, seconds=7410)
True

还支持完整的单词和空格。

>>> parse_td('2 weeks 1 day') == timedelta(days=15)
True

也支持负值时间：

>>> parse_td('-1.5 weeks 3m 20s') == timedelta(days=-11, seconds=43400)
True

boltons.timeutils.strpdate(string, format)

中的格式解析日期字符串 format 。返回一个 date 对象。在内部， datetime.strptime() 用于分析字符串，从而分析时间字段的转换说明符(例如 %H )可以提供；这些将被解析但被忽略。

参数:

• string (str) -- 要分析的日期字符串。

• format (str) -- 这个 strptime -样式日期格式字符串。

返回:

datetime.date

>>> strpdate('2016-02-14', '%Y-%m-%d')
datetime.date(2016, 2, 14)
>>> strpdate('26/12 (2015)', '%d/%m (%Y)')
datetime.date(2015, 12, 26)
>>> strpdate('20151231 23:59:59', '%Y%m%d %H:%M:%S')
datetime.date(2015, 12, 31)
>>> strpdate('20160101 00:00:00.001', '%Y%m%d %H:%M:%S.%f')
datetime.date(2016, 1, 1)

boltons.timeutils.total_seconds(td)

boltons.timeutils.dt_to_timestamp(dt)

从 datetime 对象转换为一个整型时间戳，适合与 time.time() 及其他 Epoch-based timestamps 。

>>> abs(round(time.time() - dt_to_timestamp(datetime.utcnow()), 2))
0.0

dt_to_timestamp 同时支持时区感知和朴素 datetime 物体。请注意，它假定天真的DateTime对象是隐含的UTC，比如用 datetime.datetime.utcnow() 。如果您的DateTime对象是本地时间，例如用 datetime.datetime.now() ，首先使用 datetime.datetime.replace() 方法： tzinfo= LocalTZ 对象，然后将结果传递给 dt_to_timestamp 。

boltons.timeutils.relative_time(d, other=None, ndigits=0)

获取两个值之间的差异的字符串表示形式 datetime 对象或一个 datetime 和当前时间。处理过去和未来的时间。

参数:

• d (datetime) -- 第一个DateTime对象。

• other (datetime) -- 可选的第二个DateTime对象。如果未设置，则默认为已确定的当前时间 datetime.utcnow() 。

• ndigits (int) -- 要舍入到的小数位数，默认为 0 。

返回:

一个简短的英语字符串。

>>> now = datetime.utcnow()
>>> relative_time(now, ndigits=1)
'0 seconds ago'
>>> relative_time(now - timedelta(days=1, seconds=36000), ndigits=1)
'1.4 days ago'
>>> relative_time(now + timedelta(days=7), now, ndigits=1)
'1 week from now'

boltons.timeutils.decimal_relative_time(d, other=None, ndigits=0, cardinalize=True)

获取一个元组，该元组表示 datetime 对象或一个 datetime 而现在。

参数:

• d (datetime) -- 第一个DateTime对象。

• other (datetime) -- 可选的第二个DateTime对象。如果未设置，则默认为已确定的当前时间 datetime.utcnow() 。

• ndigits (int) -- 要舍入到的小数位数，默认为 0 。

• cardinalize (bool) -- 如果合适，是否将时间单位复数，默认为 True 。

返回:

对象的元组 float 差异和各自的时间单位，如果适当，则复数 cardinalize 设为 True 。

返回类型:

(float, str)

不像 relative_time() ，此方法的返回适用于本地化为其他语言以及自定义语法和格式。

>>> now = datetime.utcnow()
>>> decimal_relative_time(now - timedelta(days=1, seconds=3600), now)
(1.0, 'day')
>>> decimal_relative_time(now - timedelta(seconds=0.002), now, ndigits=5)
(0.002, 'seconds')
>>> decimal_relative_time(now, now - timedelta(days=900), ndigits=1)
(-2.5, 'years')

一般时区

默认情况下， datetime.datetime 对象很“幼稚”，这意味着它们缺少附加的时区信息。这些对象可用于许多操作，但许多操作需要支持时区的DateTime。

编程中最重要的两个时区是协调世界时 (UTC) 以及运行您的代码的主机的本地时区。boltons提供了两个 datetime.tzinfo 使用它们的子类型：

备注

这些天，Python有了一个 built-in UTC ，而这里的UTC tzinfo虽然等价，但仅用于后向比较。

timeutils.UTC = ConstantTZInfo(name='UTC', offset=datetime.timedelta(0))

boltons.timeutils.LocalTZ = LocalTZInfo()

这个 LocalTZInfo 类型获取Time模块中有关本地时区的可用数据，并使 datetime.tzinfo 表示操作系统的时区设置。

有关与操作系统的更深入集成，请查看 tzlocal 。它建立在 pytz 并实现了启发式算法，为各大操作系统的多个版本提供了官方 pytz Tzinfo，而不是LocalTZ泛化。

class boltons.timeutils.ConstantTZInfo(name='ConstantTZ', offset=datetime.timedelta(0))

A tzinfo 其子类型 offset 保持不变(无夏令时)。

参数:

• name (str) -- 时区的名称。

• offset (datetime.timedelta) -- 时区的偏移量。

美国时区

这四个美国时区是在 datetime 文件，为方便起见，已在boltons转载。更深入的支持由 `dateutil`_ 和 pytz 。

timeutils.Eastern = Eastern

timeutils.Central = Central

timeutils.Mountain = Mountain

timeutils.Pacific = Pacific

class boltons.timeutils.USTimeZone(hours, reprname, stdname, dstname)

直接从Python文档复制， USTimeZone 是一种 datetime.tzinfo 子类型，用于创建 Eastern ， Central ， Mountain ，及 Pacific Tzinfo类型。