> Are you saying the user would expect to be able to change __annotations__ my modifying the dict they get back?
As the docs are currently written, it's ambiguous.
> Is it ever the case that the user can modify __annotations__ through the dict that's returned? That is: does __annotations__ itself ever get returned?
Yes. I could enumerate the cases in which that is true but I don't think it would shed light. Suffice to say, as currently written, get_annotations() currently returns the original dict unmodified when it can, and returns a freshly-created dict when it can't.
> I think you'd either want __annotations__ returned all the time, or never returned. Otherwise some cases could modify __annotations__, and some couldn't.
I think you're right! And since there are definitely circumstances in which it can't return __annotations__ directly, that indicates that it should never return __annotations__ directly. Good call!