This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: datetime.isoformat() documentation does not point to the risk of using it with naive datetime objects
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.11
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: belopolsky, docs@python, jeanCarloMachado, p-ganssle
Priority: normal Keywords: patch

Created on 2022-01-20 21:16 by jeanCarloMachado, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 30850 open jeanCarloMachado, 2022-01-24 13:00
Messages (2)
msg411046 - (view) Author: Jean Carlo Machado (jeanCarloMachado) * Date: 2022-01-20 21:16
datetime.utcnow() already present a warning box describing the risk of using it without specifying timezone information. However, one might still have the same problem and never encounter this warning information by doing Or just by not reading the docs of datetime.utcnow, just the datetime.isoformat docs.

By adding a similar warning to the datetime.isoformat() we could make the risk clearer and reduce the likelihood of errors. Is when calling isoformat() where people get confident to be producing ISO's.

I just recently had an incident in my company where we produced naive datetimes using and serialized them using isoformat() while expecting them to be a transferrable ISO format. Nevertheless, the other system read the dates without Z in the end and interpreted it as local time.

If you agree that this suggestion could be a good improvement to the docs, I can send a patch in the next 2 weeks.
msg411499 - (view) Author: Paul Ganssle (p-ganssle) * (Python committer) Date: 2022-01-24 17:55
Sorry I missed this! Thank you for taking the time to write this up and to make a PR.

Unfortunately, I don't think I agree with the idea of warning about this. The warnings about `utcnow` and `utcfromtimestamp` are a problem because `utcnow` and `utcfromtimestamp` are intended to represent times in UTC, but they return datetimes that actually represent local times in the semantics of modern Python. Basically, these functions are dangerous not because they are using naïve datetimes, but because they are *mis*using naïve datetimes.

The same can not be said of `.isoformat()`, which is doing the right thing when you use ``. If you look at Wikipedia's article on ISO 8601 (which is pretty much the best resource on this, since ISO 8601 is itself paywalled and we never should have standardized on a proprietary standard in the first place), you'll see it says:

> Local time (unqualified)
> If no UTC relation information is given with a time representation, the time is assumed to be in local time. While it may be safe to assume local time when communicating in the same time zone, it is ambiguous when used in communicating across different time zones.

It may be that for the kind of programming you do, it doesn't make sense to use local datetimes in an interchange format — but it is a legitimate use case and there are definitely situations where it is very much the right thing to do, so I don't think we should warn against it in the `datetime.isoformat` documentation.

There is *might* be some case for warning about this or something like it in the `` documentation. The major use cases for naïve datetimes are things where you are working with system time or things where you are working with dates in the future — you don't want to specify that some event is going to happen at 2030-03-31T12:00Z if the actual event is planned for April 1, 2030 at 13:00 *London time*, because if, between now and then, the UK decides to cancel DST or move the start back a week, the event you've stored as a UTC time now longer represents what it was intended to represent. In a lot of cases `` will just be used as "what time is it now", which is not subject to that particular problem because by the time the datetime gets stored or used, `` is a date in the *past*, and can safely be converted to UTC for all time.

Of course, if you are consuming a bunch of event dates stored in local time and you want to compare them to the current time, then `` would be appropriate. Similarly if you want to display the current time to a user on a given system (rather than logging or storing it), it would also make sense to do things like `print(`, so there are definitely also legitimate use cases for ``.

I'm inclined to say that we should *not* have a warning on ``, because we will  give people warning fatigue if we do, and we definitely want people to see `now()` as the correct alternative to `utcnow()`. I am more sympathetic to rewording the `.now()` documentation to make it clear that this will be a naïve time *representing the current time in the system local time zone* if `None` is passed (i.e. rewording or appending to the "If optional argument `tz`" paragraph).
Date User Action Args
2022-04-11 14:59:55adminsetgithub: 90605
2022-01-24 17:55:07p-gansslesetnosy: + belopolsky, p-ganssle
messages: + msg411499
2022-01-24 13:00:35jeanCarloMachadosetkeywords: + patch
stage: patch review
pull_requests: + pull_request29032
2022-01-20 21:16:16jeanCarloMachadocreate