It occurs to me that part of this work should also be a new "best practices for __annotations__" entry in the Python docs.


Best practices for working with annotations, for code that requires a minimum Python version of 3.10+:

Best practice is to call either inspect.get_annotations() or typing.get_type_hints() to access annotations.  But if you want to access '__annotations__' on an object directly:

* Always access the annotations on an object using the attribute interface, either o.__annotations__ or getattr(o, '__annotations__').  Accessing '__annotations__' through other mechanisms (e.g. looking in the class dict) is unsupported.
* Assume that o.__annotations__ is always either a dict or None.
* It's best to not assign to o.__annotations__.  But if you must, always set it to either a dict or None.
* Never delete o.__annotations__.
* Never modify o.__annotations__.