strict-rfc3339 0.7

目标

• Convert unix timestamps to and from RFC3339.
• Either produce RFC3339 strings with a UTC offset (Z) or with the offset that the C time module reports is the local timezone offset.
• Simple with minimal dependencies/libraries.
• Avoid timezones as much as possible.
• Be very strict and follow RFC3339.

注意事项

• Leap seconds are not quite supported, since timestamps do not support them, and it requires access to timezone data.
• You may be limited by the size of time_t on 32 bit systems.

在这两种情况下，请参见下面的“注释”。

基本原理

• A lot of libraries have trouble with DST transitions and ambiguous times.
• Generally, using the python datetime object causes trouble, introducing problems with timezones.
• The excellent pytz library seems to achieve timezone perfection, however it didn’t (at the time of writing) have a method for getting the local timezone or the ‘now’ time in the local zone.
• I saw a lot of problems ultimately due to information lost when converting or transferring between two libraries (e.g., time -> datetime loses DST info in the tuple)

用法

验证：

>>> strict_rfc3339.validate_rfc3339("some rubbish")
False
>>> strict_rfc3339.validate_rfc3339("2013-03-25T12:42:31+00:32")
True

实际上，我们可以：

>>> strict_rfc3339.rfc3339_to_timestamp("2013-03-25T12:42:31+00:32")
1364213431
>>> tuple(time.gmtime(1364213431))[:6]
(2013, 3, 25, 12, 10, 31)

不需要两个函数调用：

>>> strict_rfc3339.rfc3339_to_timestamp("some rubbish")
Traceback [...]
strict_rfc3339.InvalidRFC3339Error

生成字符串（在本例中，tz=america/new嫒york）：

>>> strict_rfc3339.timestamp_to_rfc3339_utcoffset(1364213431)
'2013-03-25T12:10:31Z'
>>> strict_rfc3339.timestamp_to_rfc3339_localoffset(1364213431)
'2013-03-25T08:10:31-04:00'

以及TZ=欧洲/伦敦

>>> strict_rfc3339.timestamp_to_rfc3339_localoffset(1364213431)
'2013-03-25T12:10:31+00:00'

便利功能：

>>> strict_rfc3339.now_to_rfc3339_utcoffset()
'2013-03-25T21:39:35Z'
>>> strict_rfc3339.now_to_rfc3339_localoffset()
'2013-03-25T17:39:39-04:00'

浮动：

>>> strict_rfc3339.now_to_rfc3339_utcoffset(integer=True) # The default
'2013-03-25T22:04:01Z'
>>> strict_rfc3339.now_to_rfc3339_utcoffset(integer=False)
'2013-03-25T22:04:01.04399Z'
>>> strict_rfc3339.rfc3339_to_timestamp("2013-03-25T22:04:10.04399Z")
1364249050.0439899

幕后

这些函数本质上只是字符串格式和算术。非常 少数功能起重作用。它们来自两个模块： 时间和日历。

time是c时间函数的薄包装。我正在研究 假设这些通常是高质量的并且是正确的。从 时间模块，严格的RFC3339使用：

• time: (actually calls gettimeofday) to get the current timestamp / “now”
• gmtime: splits a timestamp into a UTC time tuple
• localtime: splits a timestamp into a local time tuple

基于它们是正确的假设，我们可以使用 在gmtime和localtime返回的值之间查找本地 抵消。尽管听起来很笨拙，但它远比使用成熟的 时区库。

日历在python中实现。从日历，严格的RFC3339使用：

• timegm: turns a UTC time tuple into a timestamp. This essentially just multiplies each number in the tuple by the number of seconds in it. It does use datetime.date to work out the number of days between Jan 1 1970 and the Y-M-D in the tuple, but this is fine. It does not perform much validation at all.
• monthrange: gives the number of days in a (year, month). I checked and (at least in my copy of python 2.6) the function used for leap years is identical to the one specified in RFC3339 itself.

注释

• RFC3339 specifies an offset, not a timezone, and the difference is important. Timezones are evil.
• It is perhaps simpler to think of a RFC3339 string as a human readable method of specifying a moment in time (only). These functions merely provide access to the one-to-many timestamp-to-RFC3339 mapping.
• Timestamps don’t support leap seconds: a day is always 86400 “long”. Also, validating leap seconds is particularly fiddly, because not only do you need some data, but it must be kept up to date. For this reason, strict_rfc3339 does not support leap seconds: in validation, seconds == 60 or seconds == 61 is rejected. In the case of reverse leap seconds, calendar.timegm will blissfully accept it. The result would be about as correct as you could get.
• RFC3339 generation using gmtime or localtime may be limited by the size of time_t on the system: if it is 32 bit, you’re limited to dates between (approx) 1901 and 2038. This does not affect rfc3339_to_timestamp.