https://github.com/python/cpython/commit/d4031e68c032dcb681b2fe18356634b90f1f1173
commit: d4031e68c032dcb681b2fe18356634b90f1f1173
branch: 3.15
author: Miss Islington (bot) <[email protected]>
committer: StanFromIreland <[email protected]>
date: 2026-11-11T19:26:27Z
summary:

[3.15] gh-158797: Update docs for `test.support.import_helper` (GH-158875) 
(#161825)

(cherry picked from commit a8720240f12eb60f760e5d32735286720be00bdf)

Co-authored-by: David Ellis <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>

files:
M Doc/library/test.rst

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index ded41359a6e032..0e44b318b2679b 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -1697,22 +1697,111 @@ The :mod:`!test.support.import_helper` module provides 
support for import tests.
 
 .. versionadded:: 3.10
 
+Creating module objects
+-----------------------
 
-.. function:: forget(module_name)
+.. function:: create_module(name, loader=None, *, ispkg=False)
 
-   Remove the module named *module_name* from ``sys.modules`` and delete any
+   Create a new, empty :term:`module` or :term:`package` and return it.
+
+   *name*, *loader* and *ispkg* (as ``is_package``) are passed to
+   :class:`importlib.machinery.ModuleSpec`.
+
+
+.. function:: add_module(spec, *, parents=True)
+
+   Create a :term:`module` from a name or spec and add it to 
:data:`sys.modules`.
+
+   If *parents* is ``True``, create any missing parent modules.
+
+   Return the new module.
+
+
+.. function:: add_package(spec, *, parents=True)
+
+   Create a :term:`package` from a name or spec and add it to 
:data:`sys.modules`.
+
+   If *parents* is ``True``, create any missing parent modules.
+
+   Return the new package.
+
+
+Manipulating sys.modules
+------------------------
+
+
+.. function:: unload(name)
+
+   Remove the module named *name* from :data:`sys.modules`.
+
+
+.. function:: forget(modname)
+
+   Remove the module named *modname* from :data:`sys.modules` and delete any
    byte-compiled files of the module.
 
 
-.. function:: import_fresh_module(name, fresh=(), blocked=(), deprecated=False)
+.. function:: modules_setup()
+
+   Return a tuple containing a copy of :data:`sys.modules`.
+
+
+.. function:: modules_cleanup(oldmodules)
+
+   Remove modules except for *oldmodules* and ``encodings`` from 
:data:`sys.modules`
+   in order to preserve the internal cache.
+
+
+.. function:: isolated_modules()
+
+   A context manager that makes a copy of :data:`sys.modules` on entry and 
restores
+   it on exit.
+
+
+.. class:: CleanImport(*module_names, usefrozen=False)
+
+   A context manager to force imports to return new module references.  This
+   is useful for testing module-level behaviors, such as the emission of a
+   :exc:`DeprecationWarning` on import.
+
+   When created, this makes a copy of :data:`sys.modules` and removes names 
from
+   *module_names* from the original. On exit, the original module references 
are
+   restored.
+
+   If *usefrozen* is False (the default) then the frozen importer is
+   disabled (except for essential modules like ``importlib._bootstrap``).
+
+   Example usage::
+
+      with CleanImport('foo'):
+            importlib.import_module('foo')  # New reference.
+
+
+Importing modules
+-----------------
+
+.. function:: import_module(name, deprecated=False, *, required_on=())
+
+   This function imports and returns the named module. Unlike a normal
+   import, this function raises :exc:`unittest.SkipTest` if the module
+   cannot be imported.
+
+   Module and package deprecation messages are suppressed during this import
+   if *deprecated* is ``True``.  If a module is required on a platform but
+   optional for others, set *required_on* to an iterable of platform prefixes
+   which will be compared against :data:`sys.platform`.
+
+   .. versionadded:: 3.1
+
+.. function:: import_fresh_module(name, fresh=(), blocked=(), *, 
deprecated=False, usefrozen=False)
 
    This function imports and returns a fresh copy of the named Python module
-   by removing the named module from ``sys.modules`` before doing the import.
-   Note that unlike :func:`importlib.reload`, the original module is not
+   by removing the named module from :data:`sys.modules` before doing the 
import.
+   Note that unlike :func:`reload <importlib.reload>`, the original module is 
not
    affected by this operation.
 
    *fresh* is an iterable of additional module names that are also removed
-   from the ``sys.modules`` cache before doing the import.
+   from the :data:`sys.modules` cache before doing the import.
 
    *blocked* is an iterable of module names that are replaced with ``None``
    in the module cache during the import to ensure that attempts to import
@@ -1720,11 +1809,14 @@ The :mod:`!test.support.import_helper` module provides 
support for import tests.
 
    The named module and any modules named in the *fresh* and *blocked*
    parameters are saved before starting the import and then reinserted into
-   ``sys.modules`` when the fresh import is complete.
+   :data:`sys.modules` when the fresh import is complete.
 
    Module and package deprecation messages are suppressed during this import
    if *deprecated* is ``True``.
 
+   If *usefrozen* is False (the default) then the frozen importer is
+   disabled (except for essential modules like ``importlib._bootstrap``).
+
    This function will raise :exc:`ImportError` if the named module cannot be
    imported.
 
@@ -1740,65 +1832,91 @@ The :mod:`!test.support.import_helper` module provides 
support for import tests.
    .. versionadded:: 3.1
 
 
-.. function:: import_module(name, deprecated=False, *, required_on=())
+.. function:: ensure_module_imported(name, *, clearnone=True)
 
-   This function imports and returns the named module. Unlike a normal
-   import, this function raises :exc:`unittest.SkipTest` if the module
-   cannot be imported.
+   Import and return the named module.
 
-   Module and package deprecation messages are suppressed during this import
-   if *deprecated* is ``True``.  If a module is required on a platform but
-   optional for others, set *required_on* to an iterable of platform prefixes
-   which will be compared against :data:`sys.platform`.
+   If the module is already imported, this is returned. Otherwise, import
+   the module and return it. If the module is not found a new, empty module
+   will be created.
 
-   .. versionadded:: 3.1
+   If *clearnone* is ``True``, this will first remove any ``None`` values that
+   would block the import.
 
 
-.. function:: modules_setup()
+Manipulating sys.path
+---------------------
 
-   Return a copy of :data:`sys.modules`.
+.. class:: DirsOnSysPath(*paths)
 
+   A context manager to temporarily add directories to :data:`sys.path`.
 
-.. function:: modules_cleanup(oldmodules)
+   This makes a copy of :data:`sys.path`, appends any directories given
+   as positional arguments, then reverts :data:`sys.path` to the copied
+   settings when the context ends.
 
-   Remove modules except for *oldmodules* and ``encodings`` in order to
-   preserve internal cache.
+   Note that *all* :data:`sys.path` modifications in the body of the
+   context manager, including replacement of the object,
+   will be reverted at the end of the block.
 
 
-.. function:: unload(name)
+.. function:: ready_to_import(name=None, source="")
+
+   A context manager that will create a new Python module *name* with *source*
+   source code in a temporary directory and inserts this directory at the start
+   of :data:`sys.path`. The context manager yields a tuple with the name and 
the path
+   to the script in the temporary directory.
+
+   If the name matches an existing module, this will be cleared from 
:data:`sys.modules`
+   on entry and restored on exit.
 
-   Delete *name* from ``sys.modules``.
+   If no name is given, the module will be named "spam".
 
 
-.. function:: make_legacy_pyc(source)
+
+Manipulating internals
+----------------------
+
+.. function:: make_legacy_pyc(source, allow_compile=False)
 
    Move a :pep:`3147`/:pep:`488` pyc file to its legacy pyc location and 
return the file
    system path to the legacy pyc file.  The *source* value is the file system
    path to the source file.  It does not need to exist, however the PEP
-   3147/488 pyc file must exist.
+   3147/488 pyc file must exist or *allow_compile* must be set.
 
+   If *allow_compile* is ``True`` this will create a .pyc file if it does not 
exist.
 
-.. class:: CleanImport(*module_names)
 
-   A context manager to force import to return a new module reference.  This
-   is useful for testing module-level behaviors, such as the emission of a
-   :exc:`DeprecationWarning` on import.  Example usage::
+.. function:: frozen_modules(enabled=True)
 
-      with CleanImport('foo'):
-          importlib.import_module('foo')  # New reference.
+   A context manager that forces frozen modules to be used or excluded.
 
+   If *enabled* is ``True`` frozen modules are used, otherwise they are 
excluded.
 
-.. class:: DirsOnSysPath(*paths)
+   This only applies to modules that have not yet been imported. Some essential
+   modules will always be imported frozen.
 
-   A context manager to temporarily add directories to :data:`sys.path`.
 
-   This makes a copy of :data:`sys.path`, appends any directories given
-   as positional arguments, then reverts :data:`sys.path` to the copied
-   settings when the context ends.
+.. function:: multi_interp_extensions_check(enabled=True)
 
-   Note that *all* :data:`sys.path` modifications in the body of the
-   context manager, including replacement of the object,
-   will be reverted at the end of the block.
+   A context manager that forces (if *enabled* is ``True``) or prevents legacy 
(single-phase init)
+   modules from being allowed in subinterpreters.
+
+   This only applies to modules that haven't been imported yet.
+   It overrides the 
:c:member:`PyInterpreterConfig.check_multi_interp_extensions`
+   setting.
+
+
+Lazy imports
+------------
+
+.. function:: ensure_lazy_imports(imported_module, modules_to_block, *, 
additional_code=None)
+
+   Test that when *imported_module* is imported, none of the modules named in 
*modules_to_block*
+   are imported as a side effect.
+
+   *additional_code* if given should be additional Python source code to 
execute before
+   checking that the blocked modules still haven't been imported.
 
 
 :mod:`!test.support.warnings_helper` --- Utilities for warnings tests

_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]

Reply via email to