[docs] [issue37488] Document the "gotcha" behaviors in utcnow() and utcfromtimestamp()

[Paul Ganssle]

New submission from Paul Ganssle <p.ganssle at gmail.com>:

Between Python 2 and Python 3, the meaning of a naive datetime underwent a subtle change. Previously a naive datetime was mostly treated as an abstract datetime in the same way a unitless number is treated as an abstract quantity (this is reflected in the current datetime documentation). In Python 3, though, it became more concrete in the sense that rather than just throwing an error whenever you try to do an operation that requires knowing the absolute datetime (e.g. convert between time zones, convert to timestamp, etc), certain operations will succeed with the assumption that naive times represent system local times. This makes `utcnow()` and `utcfromtimestamp()` dangerous, because they create a naive datetime as if the naive datetime represents UTC, but this context is then lost and if you ever use one of these "aware-only" operations (.astimezone, .timestamp, etc), you'll get an unexpected answer.

For example, see this script, executed this with `TZ=America/New_York` on a machine with IANA data installed:

    >>> from datetime import datetime
    >>> dt = datetime.utcfromtimestamp(0)
    >>> dt
    datetime.datetime(1970, 1, 1, 0, 0)
    >>> dt.timestamp()
    18000

This happens because EST is 18000s behind UTC, and `.timestamp()` gives a number of seconds after UTC (a concrete, not an abstract time). You get the same gotchas with `utcnow()`.

I'm not sure if actually deprecating `utcnow` and `utcfromtimestamp` is worth it at the moment, but we can definitely start by adding a warning box to `utcnow()` and `utcfromtimestamp()` suggesting that you use the timezone-aware versions of these instead. We may also want to adjust the opening phrasing for the "naive objects" portion of the datetime documentation as well (https://docs.python.org/3.7/library/datetime.html), to reflect the fact that naive datetimes are no longer purely abstract quantities.

----------
assignee: docs at python
components: Documentation
messages: 347148
nosy: belopolsky, docs at python, p-ganssle
priority: normal
severity: normal
stage: needs patch
status: open
title: Document the "gotcha" behaviors in utcnow() and utcfromtimestamp()
type: enhancement
versions: Python 3.7, Python 3.8, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue37488>
_______________________________________