A request to un-deprecate (resurrect) timeutils.isotime()

[Amrith Kumar]

Earlier changes and discussions concluded that it was appropriate for OSLO to deprecate timeutils.isotime(). The thinking at the time was that consumers of isotime() should instead use datetime.datetime.isoformat() which provided some benefits over isotime().

For a summary of those reasons and considerations, readers are directed to https://review.openstack.org/#/c/182602/ and a variety of conversations on the ML including the following threads http://openstack.markmail.org/thread/l2frlgqasexwrcti, http://openstack.markmail.org/thread/nucp2x34ttwupjud.

A more recent ML thread is at http://openstack.markmail.org/thread/xosf5h7gvhqdwtz7.

An unfortunate consequence of the proposed deprecation of the isotime() function, the perfectly valid recommendation that datetime.datetime.isoformat() is a valid timestamp notwithstanding, is that some projects addressed the issue by merely cloning the soon to be deprecated code from timeutils and made them part of their own projects.

This kind of thing has been proposed three times (and rejected) in Trove.

https://review.openstack.org/257152
https://review.openstack.org/260921
https://review.openstack.org/265515/

It strikes me as not a good thing for all projects to have this same code in their respective projects if it is felt that it is worth deprecating from oslo. On the other hand, I also see the rationale why projects are looking to maintain the same code that was in oslo_utils.timeutils.isotime(). It isn't just a matter of using datetime.datetime.isoformat().

To that end, I think the issue(s) with isotime() in OSLO are fixable and it is beneficial if the code remains in a single location (oslo_utils.timeutils). This will not only allow OpenStack to have a single standardized timestamp format, and will also eliminate the issue(s) that come with copying and cloning code.

This bug is being added for two reasons.

First, in the proposed change I will reference it and it will serve as a record of why it was felt that we should not deprecate the isotime() code.

Second, it will provide an explanation of the change being proposed and the rationale.

----

The issue(s) with the old isotime() include the fact that it was:

- not timezone aware
- did not respect timezones when they were part of a timestamp

The issue with just expecting projects to use datetime.datetime.isoformat() include the fact that this changes the timestamp as shown in user visible places, and potentially changes the API contract.

For these reasons, projects opted in some cases to just keep the isotime() code in their projects; warts and all.

The code being proposed with the fix for this bug will attempt to address the issues with isotime() and minimize the issues for projects that use them.

[Amrith Kumar (amrith)]

Another gnarly problem is that isotime() does two things that make it not quite iso.

First, it uses this thing called PERFECT_TIME_FORMAT which isn't.

_ISO8601_TIME_FORMAT_SUBSECOND = '%Y-%m-%dT%H:%M:%S.%f'
_ISO8601_TIME_FORMAT = '%Y-%m-%dT%H:%M:%S'
PERFECT_TIME_FORMAT = _ISO8601_TIME_FORMAT_SUBSECOND

It is NOT (as best as I can tell) to have a subsecond time with no timezone information. (see: RFC 3339, section 5.6).

date-time = full-date "T" full-time
full-time = partial-time time-offset
partial-time = time-hour ":" time-minute ":" time-second [time-secfrac]
time-offset = "Z" / time-numoffset
time-numoffset = ("+" / "-") time-hour ":" time-minute

Observe therefore that full-time has only one optional component; time-secfrac. time-offset is mandatory.

Second, isotime() uses iso8601 (the python library), which is kind-of on thin ice in some areas.

For example, see http://pyiso8601.readthedocs.io/en/latest/#where-it-differs-from-iso-8601

In the documentation for 'latest' (current: iso8601 0.1.11), I see that there are three 'listed' differences.

I see immediately above, in the 'Time Zones' section (http://pyiso8601.readthedocs.io/en/latest/#time-zones) that there are five time zones supported. Three of them are iso8601, two are not. +/-HH is the other one that is NOT iso8601.

So it happens that PERFECT_TIME_FORMAT is really not consistent with RFC 3339 and something that iso8601 (the library) does support.

These two things mean that it may well be worthwhile considering (also) submitting fixes to iso8601 (the library).

[Amrith Kumar (amrith)]

In previous comment, read " +/-HH is the other one that is NOT iso8601." as " +/-HH is the other one that is NOT RFC 3339 compliant".

ISO8601 does (it appears) allow it. Also, RFC 3339 allows for the specification of -00:00 for UTC which is not iso 8601 compliant, but I digress.