gh-74929: Rudimentary docs for PEP 667 by gvanrossum · Pull Request #118581 · python/cpython (original) (raw)

It's not something that has to be done in this PR, but if we think that there are some subtleties here that warrant detailed explanation and that the datamodel docs aren't the right place to do that, one option would be to add a howto similar to the one Larry added in 3.10 to explain the semantics of the __annotations__ attribute: https://docs.python.org/3/howto/annotations.html

It wouldn't really be a howto in the Diataxis sense of the term, but we don't really have a better place for that kind of in-depth article in the CPython docs currently, and there are lots of other articles in that directory that also don't meet Diataxis's strict definition of a "howto" article. And as @gvanrossum says, all the relevant information regarding the semantics here should ideally be findable in the CPython docs somewhere, without having to refer to the PEP, which is a historical document now that it has been accepted.

(But we can probably update the PEP as well, given that it's only just been accepted :-)