Skip to content

Commit a872024

Browse files
gh-158797: Update docs for test.support.import_helper (#158875)
Co-authored-by: Stan Ulbrych <stan@python.org>
1 parent d100c64 commit a872024

1 file changed

Lines changed: 157 additions & 39 deletions

File tree

‎Doc/library/test.rst‎

Lines changed: 157 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1706,34 +1706,126 @@ The :mod:`!test.support.import_helper` module provides support for import tests.
17061706

17071707
.. versionadded:: 3.10
17081708

1709+
Creating module objects
1710+
-----------------------
17091711

1710-
.. function:: forget(module_name)
1712+
.. function:: create_module(name, loader=None, *, ispkg=False)
17111713

1712-
Remove the module named *module_name* from ``sys.modules`` and delete any
1714+
Create a new, empty :term:`module` or :term:`package` and return it.
1715+
1716+
*name*, *loader* and *ispkg* (as ``is_package``) are passed to
1717+
:class:`importlib.machinery.ModuleSpec`.
1718+
1719+
1720+
.. function:: add_module(spec, *, parents=True)
1721+
1722+
Create a :term:`module` from a name or spec and add it to :data:`sys.modules`.
1723+
1724+
If *parents* is ``True``, create any missing parent modules.
1725+
1726+
Return the new module.
1727+
1728+
1729+
.. function:: add_package(spec, *, parents=True)
1730+
1731+
Create a :term:`package` from a name or spec and add it to :data:`sys.modules`.
1732+
1733+
If *parents* is ``True``, create any missing parent modules.
1734+
1735+
Return the new package.
1736+
1737+
1738+
Manipulating sys.modules
1739+
------------------------
1740+
1741+
1742+
.. function:: unload(name)
1743+
1744+
Remove the module named *name* from :data:`sys.modules`.
1745+
1746+
1747+
.. function:: forget(modname)
1748+
1749+
Remove the module named *modname* from :data:`sys.modules` and delete any
17131750
byte-compiled files of the module.
17141751

17151752

1716-
.. function:: import_fresh_module(name, fresh=(), blocked=(), deprecated=False)
1753+
.. function:: modules_setup()
1754+
1755+
Return a tuple containing a copy of :data:`sys.modules`.
1756+
1757+
1758+
.. function:: modules_cleanup(oldmodules)
1759+
1760+
Remove modules except for *oldmodules* and ``encodings`` from :data:`sys.modules`
1761+
in order to preserve the internal cache.
1762+
1763+
1764+
.. function:: isolated_modules()
1765+
1766+
A context manager that makes a copy of :data:`sys.modules` on entry and restores
1767+
it on exit.
1768+
1769+
1770+
.. class:: CleanImport(*module_names, usefrozen=False)
1771+
1772+
A context manager to force imports to return new module references. This
1773+
is useful for testing module-level behaviors, such as the emission of a
1774+
:exc:`DeprecationWarning` on import.
1775+
1776+
When created, this makes a copy of :data:`sys.modules` and removes names from
1777+
*module_names* from the original. On exit, the original module references are
1778+
restored.
1779+
1780+
If *usefrozen* is False (the default) then the frozen importer is
1781+
disabled (except for essential modules like ``importlib._bootstrap``).
1782+
1783+
Example usage::
1784+
1785+
with CleanImport('foo'):
1786+
importlib.import_module('foo') # New reference.
1787+
1788+
1789+
Importing modules
1790+
-----------------
1791+
1792+
.. function:: import_module(name, deprecated=False, *, required_on=())
1793+
1794+
This function imports and returns the named module. Unlike a normal
1795+
import, this function raises :exc:`unittest.SkipTest` if the module
1796+
cannot be imported.
1797+
1798+
Module and package deprecation messages are suppressed during this import
1799+
if *deprecated* is ``True``. If a module is required on a platform but
1800+
optional for others, set *required_on* to an iterable of platform prefixes
1801+
which will be compared against :data:`sys.platform`.
1802+
1803+
.. versionadded:: 3.1
1804+
1805+
.. function:: import_fresh_module(name, fresh=(), blocked=(), *, deprecated=False, usefrozen=False)
17171806

17181807
This function imports and returns a fresh copy of the named Python module
1719-
by removing the named module from ``sys.modules`` before doing the import.
1720-
Note that unlike :func:`importlib.reload`, the original module is not
1808+
by removing the named module from :data:`sys.modules` before doing the import.
1809+
Note that unlike :func:`reload <importlib.reload>`, the original module is not
17211810
affected by this operation.
17221811

17231812
*fresh* is an iterable of additional module names that are also removed
1724-
from the ``sys.modules`` cache before doing the import.
1813+
from the :data:`sys.modules` cache before doing the import.
17251814

17261815
*blocked* is an iterable of module names that are replaced with ``None``
17271816
in the module cache during the import to ensure that attempts to import
17281817
them raise :exc:`ImportError`.
17291818

17301819
The named module and any modules named in the *fresh* and *blocked*
17311820
parameters are saved before starting the import and then reinserted into
1732-
``sys.modules`` when the fresh import is complete.
1821+
:data:`sys.modules` when the fresh import is complete.
17331822

17341823
Module and package deprecation messages are suppressed during this import
17351824
if *deprecated* is ``True``.
17361825

1826+
If *usefrozen* is False (the default) then the frozen importer is
1827+
disabled (except for essential modules like ``importlib._bootstrap``).
1828+
17371829
This function will raise :exc:`ImportError` if the named module cannot be
17381830
imported.
17391831

@@ -1749,65 +1841,91 @@ The :mod:`!test.support.import_helper` module provides support for import tests.
17491841
.. versionadded:: 3.1
17501842

17511843

1752-
.. function:: import_module(name, deprecated=False, *, required_on=())
1844+
.. function:: ensure_module_imported(name, *, clearnone=True)
17531845

1754-
This function imports and returns the named module. Unlike a normal
1755-
import, this function raises :exc:`unittest.SkipTest` if the module
1756-
cannot be imported.
1846+
Import and return the named module.
17571847

1758-
Module and package deprecation messages are suppressed during this import
1759-
if *deprecated* is ``True``. If a module is required on a platform but
1760-
optional for others, set *required_on* to an iterable of platform prefixes
1761-
which will be compared against :data:`sys.platform`.
1848+
If the module is already imported, this is returned. Otherwise, import
1849+
the module and return it. If the module is not found a new, empty module
1850+
will be created.
17621851

1763-
.. versionadded:: 3.1
1852+
If *clearnone* is ``True``, this will first remove any ``None`` values that
1853+
would block the import.
17641854

17651855

1766-
.. function:: modules_setup()
1856+
Manipulating sys.path
1857+
---------------------
17671858

1768-
Return a copy of :data:`sys.modules`.
1859+
.. class:: DirsOnSysPath(*paths)
17691860

1861+
A context manager to temporarily add directories to :data:`sys.path`.
17701862

1771-
.. function:: modules_cleanup(oldmodules)
1863+
This makes a copy of :data:`sys.path`, appends any directories given
1864+
as positional arguments, then reverts :data:`sys.path` to the copied
1865+
settings when the context ends.
17721866

1773-
Remove modules except for *oldmodules* and ``encodings`` in order to
1774-
preserve internal cache.
1867+
Note that *all* :data:`sys.path` modifications in the body of the
1868+
context manager, including replacement of the object,
1869+
will be reverted at the end of the block.
17751870

17761871

1777-
.. function:: unload(name)
1872+
.. function:: ready_to_import(name=None, source="")
1873+
1874+
A context manager that will create a new Python module *name* with *source*
1875+
source code in a temporary directory and inserts this directory at the start
1876+
of :data:`sys.path`. The context manager yields a tuple with the name and the path
1877+
to the script in the temporary directory.
1878+
1879+
If the name matches an existing module, this will be cleared from :data:`sys.modules`
1880+
on entry and restored on exit.
17781881

1779-
Delete *name* from ``sys.modules``.
1882+
If no name is given, the module will be named "spam".
17801883

17811884

1782-
.. function:: make_legacy_pyc(source)
1885+
1886+
Manipulating internals
1887+
----------------------
1888+
1889+
.. function:: make_legacy_pyc(source, allow_compile=False)
17831890

17841891
Move a :pep:`3147`/:pep:`488` pyc file to its legacy pyc location and return the file
17851892
system path to the legacy pyc file. The *source* value is the file system
17861893
path to the source file. It does not need to exist, however the PEP
1787-
3147/488 pyc file must exist.
1894+
3147/488 pyc file must exist or *allow_compile* must be set.
17881895

1896+
If *allow_compile* is ``True`` this will create a .pyc file if it does not exist.
17891897

1790-
.. class:: CleanImport(*module_names)
17911898

1792-
A context manager to force import to return a new module reference. This
1793-
is useful for testing module-level behaviors, such as the emission of a
1794-
:exc:`DeprecationWarning` on import. Example usage::
1899+
.. function:: frozen_modules(enabled=True)
17951900

1796-
with CleanImport('foo'):
1797-
importlib.import_module('foo') # New reference.
1901+
A context manager that forces frozen modules to be used or excluded.
17981902

1903+
If *enabled* is ``True`` frozen modules are used, otherwise they are excluded.
17991904

1800-
.. class:: DirsOnSysPath(*paths)
1905+
This only applies to modules that have not yet been imported. Some essential
1906+
modules will always be imported frozen.
18011907

1802-
A context manager to temporarily add directories to :data:`sys.path`.
18031908

1804-
This makes a copy of :data:`sys.path`, appends any directories given
1805-
as positional arguments, then reverts :data:`sys.path` to the copied
1806-
settings when the context ends.
1909+
.. function:: multi_interp_extensions_check(enabled=True)
18071910

1808-
Note that *all* :data:`sys.path` modifications in the body of the
1809-
context manager, including replacement of the object,
1810-
will be reverted at the end of the block.
1911+
A context manager that forces (if *enabled* is ``True``) or prevents legacy (single-phase init)
1912+
modules from being allowed in subinterpreters.
1913+
1914+
This only applies to modules that haven't been imported yet.
1915+
It overrides the :c:member:`PyInterpreterConfig.check_multi_interp_extensions`
1916+
setting.
1917+
1918+
1919+
Lazy imports
1920+
------------
1921+
1922+
.. function:: ensure_lazy_imports(imported_module, modules_to_block, *, additional_code=None)
1923+
1924+
Test that when *imported_module* is imported, none of the modules named in *modules_to_block*
1925+
are imported as a side effect.
1926+
1927+
*additional_code* if given should be additional Python source code to execute before
1928+
checking that the blocked modules still haven't been imported.
18111929

18121930

18131931
:mod:`!test.support.warnings_helper` --- Utilities for warnings tests

0 commit comments

Comments
 (0)