From 80622b7711fd63fbe8f6d208ba3a8b0fc6a4b256 Mon Sep 17 00:00:00 2001 From: Builder106 Date: Fri, 19 Jun 2026 14:12:49 -0700 Subject: [PATCH] gh-139140: Document that reading __annotations__ via __dict__ is unreliable on Python 3.14+ --- Doc/howto/annotations.rst | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/Doc/howto/annotations.rst b/Doc/howto/annotations.rst index fcc4fe838c783b..e9d490a078c57e 100644 --- a/Doc/howto/annotations.rst +++ b/Doc/howto/annotations.rst @@ -243,10 +243,22 @@ If you use a class with a custom metaclass and access ``__annotations__`` on the class, you may observe unexpected behavior; see :pep:`749 <749#pep749-metaclasses>` for some examples. You can avoid these quirks by using :func:`annotationlib.get_annotations` on Python 3.14+ or -:func:`inspect.get_annotations` on Python 3.10+. On earlier versions of -Python, you can avoid these bugs by accessing the annotations from the -class's :attr:`~type.__dict__` -(for example, ``cls.__dict__.get('__annotations__', None)``). +:func:`inspect.get_annotations` on Python 3.10+. + +.. note:: + + On Python 3.14 and later, annotations are evaluated lazily (see + :pep:`649` and :pep:`749`), and how the annotations dict is stored in + the class's :attr:`~type.__dict__` is a private implementation detail. + Reading ``cls.__dict__.get('__annotations__', None)`` may therefore + return ``None`` even when the class has annotations. On these versions, + always use :func:`annotationlib.get_annotations` (or + :func:`inspect.get_annotations`) rather than accessing + :attr:`~type.__dict__` directly. + +Only on Python 3.9 and earlier, where neither function is available, can you +avoid these bugs by reading the annotations from the class's +:attr:`~type.__dict__` (for example, ``cls.__dict__.get('__annotations__', None)``). In some versions of Python, instances of classes may have an ``__annotations__`` attribute. However, this is not supported functionality. If you need the