[3.14] gh-76595: Add note on PyCapsule_Import behavior (GH-134022) (GH-136074)

miss-islington · NicolasT · web-flow · commit 42e13b8f8a68 · 2025-06-28T13:08:15.000Z
gh-76595: Add note on `PyCapsule_Import` behavior (GH-134022) (cherry picked from commit 579acf4) Co-authored-by: Nicolas Trangez <ikke@nicolast.be>
diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst
@@ -105,9 +105,19 @@ Refer to :ref:`using-capsules` for more information on using these objects.
    ``module.attribute``.  The *name* stored in the capsule must match this
    string exactly.
 
+   This function splits *name* on the ``.`` character, and imports the first
+   element. It then processes further elements using attribute lookups.
+
    Return the capsule's internal *pointer* on success.  On failure, set an
    exception and return ``NULL``.
 
+   .. note::
+
+      If *name* points to an attribute of some submodule or subpackage, this
+      submodule or subpackage must be previously imported using other means
+      (for example, by using :c:func:`PyImport_ImportModule`) for the
+      attribute lookups to succeed.
+
    .. versionchanged:: 3.3
       *no_block* has no effect anymore.
 
