| single |
Strict, simple, lightweight RFC3339 functions
=============================================
Goals
-----
- 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.
Caveats
-------
- 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.
In both cases, see 'Notes' below.
Rationale
---------
- 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)
Usage
-----
Validation:
>>> strict_rfc3339.validate_rfc3339("some rubbish")
False
>>> strict_rfc3339.validate_rfc3339("2013-03-25T12:42:31+00:32")
True
Indeed, we can then:
>>> strict_rfc3339.rfc3339_to_timestamp("2013-03-25T12:42:31+00:32")
1364213431
>>> tuple(time.gmtime(1364213431))[:6]
(2013, 3, 25, 12, 10, 31)
No need for two function calls:
>>> strict_rfc3339.rfc3339_to_timestamp("some rubbish")
Traceback [...]
strict_rfc3339.InvalidRFC3339Error
Producing strings (for this example `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'
And with `TZ=Europe/London`:
>>> strict_rfc3339.timestamp_to_rfc3339_localoffset(1364213431)
'2013-03-25T12:10:31+00:00'
Convenience functions:
>>> strict_rfc3339.now_to_rfc3339_utcoffset()
'2013-03-25T21:39:35Z'
>>> strict_rfc3339.now_to_rfc3339_localoffset()
'2013-03-25T17:39:39-04:00'
Floats:
>>> 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
Behind the scenes
-----------------
These functions are essentially string formatting and arithmetic only. A
very
small number of functions do the heavy lifting. These come from two
modules:
`time` and `calendar`.
|