gh-105922: Add PyImport_AddModuleRef() function

* Add tests on PyImport_AddModuleRef(), PyImport_AddModule() and PyImport_AddModuleObject(). * PyRun_InteractiveOneObjectEx(), _PyRun_SimpleFileObject() and PyRun_SimpleStringFlags() now use PyImport_AddModuleRef() and keep the module strong reference alive longer than before.

Author: vstinner

Doc/c-api/import.rst

@@ -98,27 +98,46 @@ 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.
+
+ The module name *name* is decoded from UTF-8.
+
+ 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.
 
- 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.
+ .. versionadded:: 3.13
 
- .. 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.
+.. c:function:: PyObject* PyImport_AddModuleObject(PyObject *name)
+
+ Similar to :c:func:`PyImport_AddModuleRef`, but return a :term:`borrowed
+ reference` and *name* is a Python :class:`str` object.
 
  .. versionadded:: 3.3
 
+ .. deprecated-removed:: 3.13 3.15
+ Use :c:func:`PyImport_AddModuleRef` instead.
+
 
 .. 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`.
+
+ .. deprecated-removed:: 3.13 3.15
+ Use :c:func:`PyImport_AddModuleRef` instead.
 
 
 .. c:function:: PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co)

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::
 

Doc/data/stable_abi.dat

@@ -989,9 +989,11 @@ is less clear, here, however, since a few common routines are exceptions:
 :c:func:`PyDict_GetItemString` all return references that you borrow from the
 tuple, list or dictionary.
 
-The function :c:func:`PyImport_AddModule` also returns a borrowed reference, even
-though it may actually create the object it returns: this is possible because an
-owned reference to the object is stored in ``sys.modules``.
+The deprecated function :c:func:`PyImport_AddModule` also returns a
+:term:`borrowed reference`, even though it may actually create the object it
+returns: this is possible because an owned reference to the object is stored in
+``sys.modules``. The new function :c:func:`PyImport_AddModuleRef` is
+recommended since it returns a :term:`strong reference`.
 
 When you pass an object reference into another function, in general, the
 function borrows the reference from you --- if it needs to store it, it will use

Doc/extending/extending.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` function to replace the deprecated
+ :c:func:`PyImport_AddModule` function: return a :term:`strong reference` to
+ the module, instead of a :term:`borrowed reference`.
+ (Contributed by Victor Stinner in :gh:`105922`.)
+
 
 Porting to Python 3.13
 ----------------------
@@ -457,6 +462,12 @@ Deprecated
  Scheduled for removal in Python 3.15.
  (Contributed by Victor Stinner in :gh:`105396`.)
 
+* Deprecate :c:func:`PyImport_AddModule` and :c:func:`PyImport_AddModuleObject`
+ functions which return a :term:`borrowed reference`. Replace them with the
+ new :c:func:`PyImport_AddModuleRef` function which returns a :term:`strong
+ reference`.
+ (Contributed by Victor Stinner in :gh:`105922`.)
+
 Removed
 -------
 

Doc/whatsnew/3.13.rst

@@ -43,6 +43,11 @@ PyAPI_FUNC(PyObject *) PyImport_AddModuleObject(
 PyAPI_FUNC(PyObject *) PyImport_AddModule(
  const char *name /* UTF-8 encoded string */
  );
+#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000
+PyAPI_FUNC(PyObject *) PyImport_AddModuleRef(
+ const char *name /* UTF-8 encoded string */
+ );
+#endif
 PyAPI_FUNC(PyObject *) PyImport_ImportModule(
  const char *name /* UTF-8 encoded string */
  );

Include/import.h

@@ -2621,6 +2621,30 @@ def test_basic_multiple_interpreters_reset_each(self):
  # * module's global state was initialized, not reset
 
 
+@cpython_only
+class CAPITests(unittest.TestCase):
+ def test_pyimport_addmodule(self):
+ # gh-105922: Test PyImport_AddModuleRef(), PyImport_AddModule()
+ # and PyImport_AddModuleObject()
+ import _testcapi
+ for name in (
+ 'sys', # frozen module
+ 'test', # package
+ __name__, # package.module
+ ):
+ _testcapi.check_pyimport_addmodule(name)
+
+ def test_pyimport_addmodule_create(self):
+ # gh-105922: Test PyImport_AddModuleRef(), create a new module
+ import _testcapi
+ name = 'dontexist'
+ self.assertNotIn(name, sys.modules)
+ self.addCleanup(unload, name)
+
+ mod = _testcapi.check_pyimport_addmodule(name)
+ self.assertIs(mod, sys.modules[name])
+
+
 if __name__ == '__main__':
  # Test needs to be a package, so we can do relative imports.
  unittest.main()

Lib/test/test_import/__init__.py

@@ -0,0 +1,4 @@
+Add :c:func:`PyImport_AddModuleRef` function to replace the deprecated
+:c:func:`PyImport_AddModule` function: return a :term:`strong reference` to
+the module, instead of a :term:`borrowed reference`. Patch by Victor
+Stinner.

Lib/test/test_stable_abi_ctypes.py

@@ -2428,3 +2428,5 @@
  added = '3.12'
 [const.Py_TPFLAGS_ITEMS_AT_END]
  added = '3.12'
+[function.PyImport_AddModuleRef]
+ added = '3.13'