New submission from Paul Ganssle <b...@m.ganssle.io>: 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…) ---------- assignee: p-ganssle components: Documentation messages: 416778 nosy: belopolsky, p-ganssle priority: normal severity: normal stage: needs patch status: open title: Document that naïve datetime objects represent local time type: enhancement versions: Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue47228> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
