This is the format recommended by https://www.python.org/dev/peps/pep-0008/#variable-annotations

This sentence is just repetitive

I'm also not sure I agree with the recommendation. There's a few plausible scenarios where it won't work:

• The annotation uses a name defined in a nested scope that's no longer accessible (one of the scenarios that PEP 649 would fix)
• The annotation uses a name defined in if TYPE_CHECKING
• The annotation uses PEP 604 syntax int | str and from __future__ import annotations before Python 3.10

In such cases, eval will throw an error at runtime, but if you try hard enough you can still extract useful information. In my own tool (pyanalyze) I instead ast.parse string annotations and evaluate them manually.

I would recommend at least adding a warning that eval() may throw for some annotations that static type checkers will process correctly.

I followed all your suggestions, except adding references from datamodel.rst. Again, I'm not sure how to work it in in a way that reads well. Can you give a concrete example of how you'd add a reference to this HOWTO?

p.s. I also found one or two spots where I added a contraction. When I get exacting, I tend to stop using contractions, and which I think makes my text sound stiff.

p.p.s. Did I forget any quirks?

Can you give a concrete example of how you'd add a reference to this HOWTO?

How about adding "For more details on how to use this attribute, see " to the cell for __annotations__ in the table under https://docs.python.org/3/reference/datamodel.html#the-standard-type-hierarchy ?

This might work better as a bulleted list, instead of a long string of semicolon-separated fragments.

Though I take neither credit nor blame for the original formatting, and such improvements are verging on mission creep, I'll still give it a go. I'm going to try a "definition list" first and see if I can make that work; failing that, a bulleted list as you suggest. Either way I'll do that in both spots, modules and classes.

I quite like how that turned out! I invite you to see if you agree.

It makes me wonder if I should now touch up the Special read-only attribute: paragraph in the Modules section somehow. On the other hand, there are a bunch of previous instances of special read-only attributes sprinkled through the preceding text, so it's not completely out of line.