Documentation

At the PyCon US 2023 sprints, I spent some time with @glyph, @hauntsaninja, @AlexWaygood and others trying to put together a plan to make the type stubs for datetime distinguish between naïve and aware datetimes (even if the runtime types don't reflect this). Unfortunately, we came to the conclusion that there's no way to do it in a backwards-compatible way that accounts for subclasses without the use of higher-kinded types (this is not the first time we came to that conclusion, and unfortunately in neither case did we write down the exact reason this is a problem as far as I know, so, uh... let's remember to do that next time we tilt at this particular windmill).

Some time ago, however, @glyph did come up with a set of Protocol classes that basically solves the problem for anyone who is willing to opt in to it, since that frees him from certain backwards compatibility concerns. The upshot of the conversation was that the best we can do from the CPython side is probably to add a link to DateType into the datetime documentation, presumably in the "See also" infobox, along with a recommendation that it can be used to improve type checking of naïve vs. aware datetimes.

I realized that we didn't get around to this in the sprints and we never made an issue to track the progress, so when this recently came up in this issue, it reminded me to open this issue.

CC: @abalkin

Linked PRs

• gh-105563: Add a reference to DateType in datetime's documentation #105946
• [3.12] gh-105563: reference DateType in datetime's documentation (GH-105946) #108789
• [3.11] gh-105563: reference DateType in datetime's documentation (GH-105946) #108790