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.

classification
Title: Document that naïve datetime objects represent local time
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: p-ganssle Nosy List: belopolsky, p-ganssle
Priority: normal Keywords:

Created on 2022-04-05 14:04 by p-ganssle, last changed 2022-04-11 14:59 by admin.

Messages (1)
msg416778 - (view) Author: Paul Ganssle (p-ganssle) * (Python committer) Date: 2022-04-05 14:04
Currently, the `datetime` documentation has this to say about naïve datetimes:

> A naive object does not contain enough information to unambiguously locate itself relative to other date/time objects. Whether a naive object represents Coordinated Universal Time (UTC), local time, or time in some other timezone is purely up to the program, just like it is up to the program whether a particular number represents metres, miles, or mass. Naive objects are easy to understand and to work with, at the cost of ignoring some aspects of reality.

This was accurate in Python 2.7, but as of Python 3, the picture is a bit more nuanced. `.astimezone()` and `.timestamp()` work for naïve datetimes, but they are treated as *system local times*. It is no longer really appropriate to use a naïve datetime to a datetime in any specific concrete time zone — instead, they should be considered either abstract datetimes for the purposes of calendar calculations, or they should be considered as representing the realization of that abstract datetime *in the current system locale*. This new behavior is referenced in, for example, the warning in `.utcnow()`: https://docs.python.org/3.10/library/datetime.html#datetime.datetime.utcnow

We make reference to this in the documentation for `.timestamp()`: https://docs.python.org/3.10/library/datetime.html#datetime.datetime.timestamp and in `.astimezone()`: https://docs.python.org/3.10/library/datetime.html#datetime.datetime.astimezone, but the top level explanation makes no reference to it.

I have written a blog post about *why* this is the case: https://blog.ganssle.io/articles/2022/04/naive-local-datetimes.html and made reference to this behavior in an earlier blog post about `utcnow`: https://blog.ganssle.io/articles/2019/11/utcnow.html, but I think it would be a good idea to revamp the official documentation to reflect this change in status (12 years or so after the change…)
History
Date User Action Args
2022-04-11 14:59:58adminsetgithub: 91384
2022-04-05 14:04:48p-gansslecreate