From c894b634856d428765c5d9f1ef08a303a3e8d7d8 Mon Sep 17 00:00:00 2001
From: Olayinka Vaughan <114308865+Builder106@users.noreply.github.com>
Date: Sat, 31 Oct 2026 20:18:16 -0400
Subject: [PATCH] =?UTF-8?q?gh-139140:=20Document=20that=20reading=20=5F=5F?=
 =?UTF-8?q?annotations=5F=5F=20via=20=5F=5Fdict=5F=5F=20is=20unre=E2=80=A6?=
 =?UTF-8?q?=20(GH-151750)=20(cherry=20picked=20from=20commit=20410fdda081b?=
 =?UTF-8?q?a1ca95be0c2ed85c9a7ab2f560604)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Olayinka Vaughan <114308865+Builder106@users.noreply.github.com>
---
 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 e2a5aa708d7b63..7236cc1a3cb9f6 100644
--- a/Doc/howto/annotations.rst
+++ b/Doc/howto/annotations.rst
@@ -245,10 +245,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