summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
Diffstat (limited to 'Doc')
-rw-r--r--Doc/c-api/import.rst37
-rw-r--r--Doc/data/refcounts.dat3
-rw-r--r--Doc/data/stable_abi.dat1
-rw-r--r--Doc/whatsnew/3.13.rst5
4 files changed, 34 insertions, 12 deletions
diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst
index 6db2023..7aacc21 100644
--- a/Doc/c-api/import.rst
+++ b/Doc/c-api/import.rst
@@ -98,27 +98,40 @@ Importing Modules
an exception set on failure (the module still exists in this case).
-.. c:function:: PyObject* PyImport_AddModuleObject(PyObject *name)
+.. c:function:: PyObject* PyImport_AddModuleRef(const char *name)
+
+ Return the module object corresponding to a module name.
+
+ The *name* argument may be of the form ``package.module``. First check the
+ modules dictionary if there's one there, and if not, create a new one and
+ insert it in the modules dictionary.
+
+ Return a :term:`strong reference` to the module on success. Return ``NULL``
+ with an exception set on failure.
- Return the module object corresponding to a module name. The *name* argument
- may be of the form ``package.module``. First check the modules dictionary if
- there's one there, and if not, create a new one and insert it in the modules
- dictionary. Return ``NULL`` with an exception set on failure.
+ The module name *name* is decoded from UTF-8.
- .. note::
+ This function does not load or import the module; if the module wasn't
+ already loaded, you will get an empty module object. Use
+ :c:func:`PyImport_ImportModule` or one of its variants to import a module.
+ Package structures implied by a dotted name for *name* are not created if
+ not already present.
+
+ .. versionadded:: 3.13
+
+
+.. c:function:: PyObject* PyImport_AddModuleObject(PyObject *name)
- This function does not load or import the module; if the module wasn't already
- loaded, you will get an empty module object. Use :c:func:`PyImport_ImportModule`
- or one of its variants to import a module. Package structures implied by a
- dotted name for *name* are not created if not already present.
+ Similar to :c:func:`PyImport_AddModuleRef`, but return a :term:`borrowed
+ reference` and *name* is a Python :class:`str` object.
.. versionadded:: 3.3
.. c:function:: PyObject* PyImport_AddModule(const char *name)
- Similar to :c:func:`PyImport_AddModuleObject`, but the name is a UTF-8
- encoded string instead of a Unicode object.
+ Similar to :c:func:`PyImport_AddModuleRef`, but return a :term:`borrowed
+ reference`.
.. c:function:: PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co)
diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index f5628ab..d707cc3 100644
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -974,6 +974,9 @@ PyCoro_New:PyFrameObject*:frame:0:
PyCoro_New:PyObject*:name:0:
PyCoro_New:PyObject*:qualname:0:
+PyImport_AddModuleRef:PyObject*::+1:
+PyImport_AddModuleRef:const char*:name::
+
PyImport_AddModule:PyObject*::0:reference borrowed from sys.modules
PyImport_AddModule:const char*:name::
diff --git a/Doc/data/stable_abi.dat b/Doc/data/stable_abi.dat
index 80806ae..a3fde01 100644
--- a/Doc/data/stable_abi.dat
+++ b/Doc/data/stable_abi.dat
@@ -298,6 +298,7 @@ type,PyGetSetDef,3.2,,full-abi
var,PyGetSetDescr_Type,3.2,,
function,PyImport_AddModule,3.2,,
function,PyImport_AddModuleObject,3.7,,
+function,PyImport_AddModuleRef,3.13,,
function,PyImport_AppendInittab,3.2,,
function,PyImport_ExecCodeModule,3.2,,
function,PyImport_ExecCodeModuleEx,3.2,,
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index 735715f..bbe02a9 100644
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -426,6 +426,11 @@ New Features
APIs accepting the format codes always use ``Py_ssize_t`` for ``#`` formats.
(Contributed by Inada Naoki in :gh:`104922`.)
+* Add :c:func:`PyImport_AddModuleRef`: similar to
+ :c:func:`PyImport_AddModule`, but return a :term:`strong reference` instead
+ of a :term:`borrowed reference`.
+ (Contributed by Victor Stinner in :gh:`105922`.)
+
Porting to Python 3.13
----------------------