From 3cd04fc07deaf7488de6a1d87f5a9f596057ac2b Mon Sep 17 00:00:00 2001 From: Nicolas Trangez Date: Wed, 14 May 2025 23:43:59 +0100 Subject: [PATCH 1/2] gh-76595: Add note on `PyCapsule_Import` behavior There's a PR (GH-6898) which changes this behavior (to be less surprising, I believe), but this seems to have stalled. See: https://github.com/python/cpython/issues/76595 See: https://github.com/python/cpython/pull/6898 --- Doc/c-api/capsule.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst index cdb8aa33e9fd32..e04b4ff9814eaf 100644 --- a/Doc/c-api/capsule.rst +++ b/Doc/c-api/capsule.rst @@ -108,6 +108,14 @@ Refer to :ref:`using-capsules` for more information on using these objects. Return the capsule's internal *pointer* on success. On failure, set an exception and return ``NULL``. + .. note:: + + :c:func:`PyCapsule_Import` splits *name* on the ``.`` character, and + imports the first element. It then processes further elements using + attribute lookups. As a result, if *name* points to an attribute in + some submodule or subpackage, this submodule or subpackage must be + previously imported using other means (e.g. by using :c:func:`PyImport_ImportModule`). + .. versionchanged:: 3.3 *no_block* has no effect anymore. From 177ec164c27af39b84a373123e3e90a6713dca9c Mon Sep 17 00:00:00 2001 From: Nicolas Trangez Date: Thu, 15 May 2025 20:00:26 +0100 Subject: [PATCH 2/2] Handle reviewer feedback --- Doc/c-api/capsule.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst index e04b4ff9814eaf..64dc4f5275b512 100644 --- a/Doc/c-api/capsule.rst +++ b/Doc/c-api/capsule.rst @@ -105,16 +105,18 @@ 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:: - :c:func:`PyCapsule_Import` splits *name* on the ``.`` character, and - imports the first element. It then processes further elements using - attribute lookups. As a result, if *name* points to an attribute in - some submodule or subpackage, this submodule or subpackage must be - previously imported using other means (e.g. by using :c:func:`PyImport_ImportModule`). + 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.