datetime: add ability to parse RFC 3339 dates and times

[nagle]

BPO	15873
Nosy	@warsaw, @jcea, @cben, @ncoghlan, @abalkin, @vstinner, @jwilk, @mcepl, @merwok, @bitdancer, @karlcow, @elprans, @flying-sheep, @mihaic, @Fak3, @berkerpeksag, @vadmium, @boxed, @jstasiak, @offby1, @deronnax, @pbryan, @pganssle, @sirex, @jaitaiwan
PRs	bpo-15873: Implement [date][time].fromisoformat #4699 bpo-15873: add '.fromisoformat' for date, time and datetime #4841 bpo-15873Add What's new entry for datetime.fromisoformat #5559 bpo-15873Add What's new entry for datetime.fromisoformat #5559 [3.7] bpo-15873 Add What's new entry for datetime.fromisoformat (GH-5559) #5939
Files	issue15873-proto.diff test-cases.py: Test cases fromisoformat.patch fromisoformat2.patch: slightly improved version, better use of timedelta fromisoformat3.patch fromisoformat4.patch simplerfromisoformat.patch: simpler, stricter version of fromisoformat fromisoformat_new.patch fromisoformat_new2.patch fromisoformat_new3.patch fromisoformat_singledispatch.patch fromisoformat_regexinclasses.patch: regex as class attributes fromisoformat_strptimesingledispatch.patch: regex looked up by class type in _strptime.py fromisoformat_regexinclasses2.patch: regex as class attributes, 2nd version

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/abalkin'
closed_at = <Date 2018-03-01.18:50:17.237>
created_at = <Date 2012-09-06.21:08:49.605>
labels = ['3.7', 'type-feature', 'library']
title = 'datetime: add ability to parse RFC 3339 dates and times'
updated_at = <Date 2018-03-01.18:50:17.236>
user = 'https://bugs.python.org/nagle'

bugs.python.org fields:

activity = <Date 2018-03-01.18:50:17.236>
actor = 'belopolsky'
assignee = 'belopolsky'
closed = True
closed_date = <Date 2018-03-01.18:50:17.237>
closer = 'belopolsky'
components = ['Library (Lib)']
creation = <Date 2012-09-06.21:08:49.605>
creator = 'nagle'
dependencies = []
files = ['27141', '27165', '41922', '41923', '41926', '41927', '41934', '41935', '41940', '41945', '41951', '44015', '44016', '44019']
hgrepos = []
issue_num = 15873
keywords = ['patch']
message_count = 90.0
messages = ['169941', '169952', '169966', '169968', '169970', '170098', '170104', '170109', '170112', '170114', '170116', '170180', '170181', '174339', '183672', '183743', '183809', '183921', '183931', '221829', '221830', '221831', '221903', '260099', '260100', '260150', '260266', '260276', '260280', '260282', '260292', '260293', '260294', '260295', '260298', '260303', '260309', '260318', '260337', '260342', '260343', '260344', '260345', '260347', '260350', '260356', '260382', '260420', '260426', '260427', '260440', '260441', '260442', '260445', '260449', '260989', '260990', '260991', '263867', '269714', '269722', '270529', '270828', '270829', '270831', '270899', '272021', '272026', '273609', '291822', '291831', '304950', '307603', '307604', '307605', '307606', '307607', '307610', '307616', '308214', '308505', '308507', '308510', '308569', '308637', '308851', '309168', '309175', '311703', '313105']
nosy_count = 36.0
nosy_names = ['barry', 'jcea', 'cben', 'roysmith', 'ncoghlan', 'belopolsky', 'nagle', 'vstinner', 'jwilk', 'mcepl', 'eric.araujo', 'Arfrever', 'r.david.murray', 'davydov', 'cvrebert', 'karlcow', 'SilentGhost', 'Elvis.Pranskevichus', 'perey', 'flying sheep', 'mihaic', 'aymeric.augustin', 'Roman.Evstifeev', 'berker.peksag', 'martin.panter', 'piotr.dobrogost', 'kirpit', 'Anders.Hovm\xc3\xb6ller', 'jstasiak', 'Eric.Hanchrow', 'deronnax', 'pbryan', 'p-ganssle', 'sirex', 'larsonreever', 'jaitaiwan']
pr_nums = ['4699', '4841', '5559', '5559', '5939']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue15873'
versions = ['Python 3.7']

[nagle]

The datetime module has support for output to a string of dates and times in ISO 8601 format ("2012-09-09T18:00:00-07:00"), with the object method "isoformat([sep])". But there's no support for parsing such strings. A string to datetime class method should be provided, one capable of parsing at least the RFC 3339 subset of ISO 8601.

The problem is parsing time zone information correctly.
The allowed formats for time zone are
empty - no TZ, date/time is "naive" in the datetime sense
Z - zero, or Zulu time, i.e. UTC.
[+-]nn.nn - offset from UTC

"strptime" does not understand timezone offsets. The "datetime" documentation suggests that the "z" format directive handles time zone info, but that's not actually implemented for input.

Pypi has four modules for parsing ISO 8601 dates. Each has least one major
problem in time zone handling:

iso8601 0.1.4
Abandonware. Mishandles time zone when time zone is "Z" and
the default time zone is specified.
iso8601.py 0.1dev
Always returns a "naive" datetime object, even if zone specified.
iso8601plus 0.1.6
Fork of abandonware version above. Same bug.
zc.iso8601 0.2.0
Zope version. Imports the pytz module with the full Olsen time zone
database, but doesn't actually use that database.

Thus, nothing in Pypi provides a good alternative.

It would be appropriate to handle this in the datetime module. One small, correct, tested function would be better than the existing five bad alternatives.

[AlexanderBelopolsky]

%z format is supported, but it cannot accept colon in TZ offset. It can parse offsets like -0600 just fine. What OP is looking for is the GNU date %:z format which datetime does not support.

For ISO 8601 compliance, however I think we need a way to specify a parser that will accept any valid 8601 format: with T or space separator and with or without : in time and timezone and with or without dashes in date.

I would very much like such promiscuous parser to be implemented in datetime.__new__. So that we can create datetime objects from strings the way we do it with numbers.

[nagle]

Re: "%z format is supported".

That's platform-specific; the actual parsing is delegated to the C library. It's not in Python 2.7 / Win32:

ValueError: 'z' is a bad directive in format '%Y-%m-%dT%H:%M:%S%z'

It really shouldn't be platform-specific; the underlying platform is irrelevant to this task. That's more of a documentation error; the features not common to all supported Python platforms should not be mentioned in the documentation.

Re: "I would very much like such promiscuous parser to be implemented in datetime.__new__. "

For string input, it's probably better to do this conversion in a specific class-level function. Full ISO 8601 dates/times generally come from computer-generated data via a file or API. If invalid text shows up, it should be detected as an error, not be heuristically interpreted as a date. There's already "fromtimestamp" and "fromordinal",
and "isoformat" as an instance method, so "fromisoformat" seems reasonable.

I'd also suggest providing a standard subclass of tzinfo in datetime for fixed offsets. That's needed to express the time zone information in an ISO 8601 date. The new "fromisoformat" would convert an ISO 8601 date/time would be convertible to a time-zone "aware" datetime object. If converted back to an ISO 8601 string with .isoformat(), the round trip should preserve the original data, including time zone offset.

(Several more implementations of this conversion have turned up. In addition to the four already mentioned, there was one in xml.util, and one in feedparser. There are probably more yet to be found.)

[AlexanderBelopolsky]

On Thu, Sep 6, 2012 at 9:51 PM, John Nagle <report@bugs.python.org> wrote:

It's not in Python 2.7 / Win32.

Python 2.x series is closed and cannot accept new features. Both %z
and fixed offset tzinfo subclass are implemented in 3.2.

[abalkin]

I am attaching a quick python only prototype for the proposed feature. My goal is to make date/time objects behave like numeric types for which constructors accept strings produced by str(). Since str() format is ISO 8601, it is natural to accept ISO 8601 formats in constructors.

[roysmith]

We need to define the scope of what input strings will be accepted. ISO-8601 defines a lot of stuff which we may not wish to accept.

Do we want to accept both basic format (YYYYMMDD) and extended format (YYYY-MM-DD)?

Do we want to accept things like "1985-W15-5", which is (if I understand this correctly(), the 5th day of the 15th week of 1985 [section 4.1.4.2].

Do we want to accept [section 4.2.2.4], "23:20,8", which is 23 hours, 20 minutes, 8 tenths of a minute.

I suspect most people who have been following the recent thread (https://groups.google.com/d/topic/comp.lang.python/Q2w4R89Nq1w/discussion) would say none of the above are needed. All that's needed is if you have an existing datetime object, d1, you can do:

s = str(d1)
d2 = datetime.datetime(s)
assert d1 == d2

for all values of d1.

But, let's at least agree on that. Or, in the alternative, agree on something else. Then we know what we're shooting for.

[AlexanderBelopolsky]

On Sep 9, 2012, at 8:15 AM, Roy Smith <report@bugs.python.org> wrote:

We need to define the scope of what input strings will be accepted.

Since it is easier to widen the domain of acceptable arguments than to narrow it in the future, I would say let's start by accepting str(x) only where x is date, time, timezone or datetime. I would leave out timedelta for now because it's str(x) does not resemble ISO at all.

Either that or full ISO 8601. Anything in between is just too hard to explain.

[roysmith]

I see I mis-stated my example. When I wrote:

s = str(d1)
d2 = datetime.datetime(s)
assert d1 == d2

what I really meant was:

s = d1.isoformat()
d2 = datetime.datetime(s)
assert d1 == d2

But, now I realize that while that is certainly an absolute lower bound, it's almost certainly not sufficient. The most common use case I see on a daily basis is parsing strings that look like "2012-09-07T23:59:59+00:00". This is also John Nagle's original use case from the cited mailing list thread:

I want to parse standard ISO date/time strings such as
2012-09-09T18:00:00-07:00

Datetime.isoformat() returns something that matches the beginning of that, but doesn't have the time zone offset. And it's the offset that makes strptime() not usable as a soluation, because "%z" isn't portable.

If we don't satisfy the "2012-09-07T23:59:59+00:00" case, then we won't have really done anything useful.

[nagle]

For what parts of ISO 8601 to accept, there's a standard: RFC3339, "Date and Time on the Internet: Timestamps". See section 5.6:

date-fullyear = 4DIGIT
date-month = 2DIGIT ; 01-12
date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on
; month/year
time-hour = 2DIGIT ; 00-23
time-minute = 2DIGIT ; 00-59
time-second = 2DIGIT ; 00-58, 00-59, 00-60 based on leap second
; rules
time-secfrac = "." 1*DIGIT
time-numoffset = ("+" / "-") time-hour ":" time-minute
time-offset = "Z" / time-numoffset

partial-time = time-hour ":" time-minute ":" time-second
[time-secfrac]
full-date = date-fullyear "-" date-month "-" date-mday
full-time = partial-time time-offset

date-time = full-date "T" full-time

NOTE: Per [ABNF] and ISO8601, the "T" and "Z" characters in this
syntax may alternatively be lower case "t" or "z" respectively.

  ISO 8601 defines date and time separated by "T".
  Applications using this syntax may choose, for the sake of
  readability, to specify a full-date and full-time separated by
  (say) a space character.

That's straightforward, and can be expressed as a regular expression.

[abalkin]

I realize that while that is certainly an absolute lower bound,
it's almost certainly not sufficient. The most common use case
I see on a daily basis is parsing strings that look like
"2012-09-07T23:59:59+00:00".

This is exactly what isoformat() of an aware datetime looks like:

>>> datetime.now(timezone.utc).isoformat()
'2012-09-09T16:09:46.165886+00:00'

str() is the same up to T replaced by space:

>>> print(datetime.now(timezone.utc))
2012-09-09 15:19:12.567692+00:00

[abalkin]

For what parts of ISO 8601 to accept, there's a standard: RFC3339

This is almost indistinguishable from the idea of accepting .isoformat() and str() results. From what I see the only difference is that 't' is accepted for date/time separator and 'z' is accepted as a timezone.

Let's start with this.

As an ultimate solution, I would like to see something like codec registry so that we can do things like datetime(.., format='rfc3339') or date(.., format='gnu') for GNU parse_datetime. I think this will look more pythonic than strptime(). Of course, strptime format can also be accepted as the value for the format keyword.

[roysmith]

I've started collecting some test cases. I'll keep adding to the collection. I'm going to start trolling ISO 8601:2004(E) for more. Let me know if there are other sources I should be considering.