From: Nicolas Trangez <ikke@nicolast.be>
Date: Sat, 28 Jun 2025 13:01:41 +0000 (+0200)
Subject: gh-76595: Add note on `PyCapsule_Import` behavior (GH-134022)
X-Git-Tag: v3.15.0a1~1149
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=579acf45629fa0b7787ec78fa4049fc6a6388b71;p=thirdparty%2FPython%2Fcpython.git

gh-76595: Add note on `PyCapsule_Import` behavior (GH-134022)
---

diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst
index cdb8aa33e9fd..64dc4f5275b5 100644
--- 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.