In [1]: import datetime

In [2]: datetime.datetime.utcfromtimestamp(0)
Out[2]: datetime.datetime(1970, 1, 1, 0, 0)

In [3]: datetime.datetime.utcfromtimestamp(0).replace(tzinfo=datetime.timezone.utc)
Out[3]: datetime.datetime(1970, 1, 1, 0, 0, tzinfo=datetime.timezone.utc)

datetime.utcfromtimestamp() returns naive datetime.
But some methods assumes naive datetime is localtime. (e.g. datetime.timestamp()).
This is big pitfall for many Pythonistas.

We can't change default behavior for backward compatibility.
How about adding `aware` keyword-only option?

>>> datetime.datetime.utcfromtimestamp(0, aware=True)
datetime.datetime(1970, 1, 1, 0, 0, tzinfo=datetime.timezone.utc)

I don't find the keyword to be superior to the 'replace' spelling, myself.  I think the replace spelling makes it clearer what the intent is.

This is not a spelling issue.

When people writing code converting between unixtime and datetime,
they should find `.timestamp()` and `.utcfromtimestamp()`.
But they may not awake about `.replace(tzinfo=datetime.timezone.utc)` is very important.

Since `fromtimestamp` takes `tz` as optional 2nd argument,
I feel adding 2nd `aware` option to `utcfromtimestamp` is good for symmetry.


If `datetime.datetime.utcfromtimestamp(ts).replace(tzinfo=datetime.timezone.utc)`
is clearer than `datetime.datetime.utcfromtimestamp(ts, aware=True)`,
docstring of `utcfromtimestamp` should notice about how `replace()` important:

"""
Note that it returns **naive** (tz=None) datetime.  Since naive datetime is
treated as localtime in most functions, you may have to call `.replace(tzinfo=datetime.datetime.utc)` before using it.
"""

Yes, I agree that a doc note would be appropriate.  timezone is relatively new, originally there was no way to produce aware datetimes from the datetime module without writing your own tzinfo class.  Now that there is, there are may be more than one place in the datetime docs that should be enhanced.

>>> from datetime import datetime, timezone
  >>> datetime.fromtimestamp(0, timezone.utc)
  datetime.datetime(1970, 1, 1, 0, 0, tzinfo=datetime.timezone.utc)

already works and it is documented [1]

[1] https://docs.python.org/3/library/datetime.html#datetime.datetime.fromtimestamp

Or it can be written as:

  >>> epoch = datetime(1970, 1, 1, tzinfo=timezone.utc)
  >>> aware_utc = epoch + timedelta(seconds=posix_timestamp)

I personally wish we could deprecate utcfromtimestamp.  With timezone.utc in stdlib and being a singleton there is no reason to put UTC time in naive datetime instances.

akira:

It seems cleaner than utcfromtimestamp().replace().
I think utcfromtimestamp() should have note about it.

"""
Note that it returns **naive** (tz=None) datetime.  Naive datetime is
treated as localtime in most functions.
If you want to create aware datetime, use `.fromtimestamp(ts, tz=timezone.utc)` instead.
"""

And I want to add this note to docstring too, since I read docstring before
document.

I agree the documentation should nudge towards aware
datetime objects.

I've attached a documentation patch as an example.

I like Akira's documentation patch.  Will apply unless hear objections from documentation folks.

New changeset 4a590c66070d by Alexander Belopolsky in branch 'default':
Closes issue #22791: Improved datetime from timestamp methods documentation.
https://hg.python.org/cpython/rev/4a590c66070d