From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 26 Sep 2024 23:57:50 +0000 (-0700)
Subject: [3.13] gh-123242: Note that type.__annotations__ may not exist (GH-124557) (#124569)
X-Git-Tag: v3.13.0rc3~67
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=b27e2273be6fc33e1bb3425d95b5b5f53829030d;p=thirdparty%2FPython%2Fcpython.git

[3.13] gh-123242: Note that type.__annotations__ may not exist (GH-124557) (#124569)

Closes GH-123242. The real criterion is that the attribute does not
exist on heap types, but I don't think we should discuss heap vs.
static types in the language reference.
(cherry picked from commit 99b23c64de301c9e77add6b0d8e60118ef807840)
---

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 45c4852da03f..bd90e37ea27c 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1011,6 +1011,14 @@ Special attributes
        collected during class body execution. For best practices on working
        with :attr:`!__annotations__`, please see :ref:`annotations-howto`.
 
+       .. caution::
+
+          Accessing the :attr:`!__annotations__` attribute of a class
+          object directly may yield incorrect results in the presence of
+          metaclasses. In addition, the attribute may not exist for
+          some classes. Use :func:`inspect.get_annotations` to
+          retrieve class annotations safely.
+
    * - .. attribute:: type.__type_params__
      - A :class:`tuple` containing the :ref:`type parameters <type-params>` of
        a :ref:`generic class <generic-classes>`.