[issue46447] datetime.isoformat() documentation does not point to the risk of using it with naive datetime objects

[Paul Ganssle]

Paul Ganssle  added the comment:

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 `datetime.now().isoformat()`. 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 `datetime.now` 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 
`datetime.now()` 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, `datetime.now()` 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 `datetime.now()` 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(datetime.now().isoformat())`, so there are definitely 
also legitimate use cases for `datetime.now()`.

I'm inclined to say that we should *not* have a warning on `datetime.now()`, 
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).

--
nosy: +belopolsky, p-ganssle

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46447] datetime.isoformat() documentation does not point to the risk of using it with naive datetime objects

[Jean Carlo Machado]

Change by Jean Carlo Machado :


--
keywords: +patch
pull_requests: +29032
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/30850

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46447] datetime.isoformat() documentation does not point to the risk of using it with naive datetime objects

[Jean Carlo Machado]

New submission from Jean Carlo Machado :

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 
datetime.now().isoformat(). 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 datetime.now() 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.

--
assignee: docs@python
components: Documentation
messages: 411046
nosy: docs@python, jeanCarloMachado
priority: normal
severity: normal
status: open
title: datetime.isoformat() documentation does not point to the risk of using 
it with naive datetime objects
type: enhancement
versions: Python 3.11

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com