Skip to content

Commit d4031e6

Browse files
miss-islingtonDavidCEllisStanFromIreland
authored
[3.15] gh-158797: Update docs for test.support.import_helper (GH-158875) (#161825)
(cherry picked from commit a872024) Co-authored-by: David Ellis <ducksual@gmail.com> Co-authored-by: Stan Ulbrych <stan@python.org>
1 parent de27073 commit d4031e6

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
@@ -1697,34 +1697,126 @@ The :mod:`!test.support.import_helper` module provides support for import tests.
16971697

16981698
.. versionadded:: 3.10
16991699

1700+
Creating module objects
1701+
-----------------------
17001702

1701-
.. function:: forget(module_name)
1703+
.. function:: create_module(name, loader=None, *, ispkg=False)
17021704

1703-
Remove the module named *module_name* from ``sys.modules`` and delete any
1705+
Create a new, empty :term:`module` or :term:`package` and return it.
1706+
1707+
*name*, *loader* and *ispkg* (as ``is_package``) are passed to
1708+
:class:`importlib.machinery.ModuleSpec`.
1709+
1710+
1711+
.. function:: add_module(spec, *, parents=True)
1712+
1713+
Create a :term:`module` from a name or spec and add it to :data:`sys.modules`.
1714+
1715+
If *parents* is ``True``, create any missing parent modules.
1716+
1717+
Return the new module.
1718+
1719+
1720+
.. function:: add_package(spec, *, parents=True)
1721+
1722+
Create a :term:`package` 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 package.
1727+
1728+
1729+
Manipulating sys.modules
1730+
------------------------
1731+
1732+
1733+
.. function:: unload(name)
1734+
1735+
Remove the module named *name* from :data:`sys.modules`.
1736+
1737+
1738+
.. function:: forget(modname)
1739+
1740+
Remove the module named *modname* from :data:`sys.modules` and delete any
17041741
byte-compiled files of the module.
17051742

17061743

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

17091798
This function imports and returns a fresh copy of the named Python module
1710-
by removing the named module from ``sys.modules`` before doing the import.
1711-
Note that unlike :func:`importlib.reload`, the original module is not
1799+
by removing the named module from :data:`sys.modules` before doing the import.
1800+
Note that unlike :func:`reload <importlib.reload>`, the original module is not
17121801
affected by this operation.
17131802

17141803
*fresh* is an iterable of additional module names that are also removed
1715-
from the ``sys.modules`` cache before doing the import.
1804+
from the :data:`sys.modules` cache before doing the import.
17161805

17171806
*blocked* is an iterable of module names that are replaced with ``None``
17181807
in the module cache during the import to ensure that attempts to import
17191808
them raise :exc:`ImportError`.
17201809

17211810
The named module and any modules named in the *fresh* and *blocked*
17221811
parameters are saved before starting the import and then reinserted into
1723-
``sys.modules`` when the fresh import is complete.
1812+
:data:`sys.modules` when the fresh import is complete.
17241813

17251814
Module and package deprecation messages are suppressed during this import
17261815
if *deprecated* is ``True``.
17271816

1817+
If *usefrozen* is False (the default) then the frozen importer is
1818+
disabled (except for essential modules like ``importlib._bootstrap``).
1819+
17281820
This function will raise :exc:`ImportError` if the named module cannot be
17291821
imported.
17301822

@@ -1740,65 +1832,91 @@ The :mod:`!test.support.import_helper` module provides support for import tests.
17401832
.. versionadded:: 3.1
17411833

17421834

1743-
.. function:: import_module(name, deprecated=False, *, required_on=())
1835+
.. function:: ensure_module_imported(name, *, clearnone=True)
17441836

1745-
This function imports and returns the named module. Unlike a normal
1746-
import, this function raises :exc:`unittest.SkipTest` if the module
1747-
cannot be imported.
1837+
Import and return the named module.
17481838

1749-
Module and package deprecation messages are suppressed during this import
1750-
if *deprecated* is ``True``. If a module is required on a platform but
1751-
optional for others, set *required_on* to an iterable of platform prefixes
1752-
which will be compared against :data:`sys.platform`.
1839+
If the module is already imported, this is returned. Otherwise, import
1840+
the module and return it. If the module is not found a new, empty module
1841+
will be created.
17531842

1754-
.. versionadded:: 3.1
1843+
If *clearnone* is ``True``, this will first remove any ``None`` values that
1844+
would block the import.
17551845

17561846

1757-
.. function:: modules_setup()
1847+
Manipulating sys.path
1848+
---------------------
17581849

1759-
Return a copy of :data:`sys.modules`.
1850+
.. class:: DirsOnSysPath(*paths)
17601851

1852+
A context manager to temporarily add directories to :data:`sys.path`.
17611853

1762-
.. function:: modules_cleanup(oldmodules)
1854+
This makes a copy of :data:`sys.path`, appends any directories given
1855+
as positional arguments, then reverts :data:`sys.path` to the copied
1856+
settings when the context ends.
17631857

1764-
Remove modules except for *oldmodules* and ``encodings`` in order to
1765-
preserve internal cache.
1858+
Note that *all* :data:`sys.path` modifications in the body of the
1859+
context manager, including replacement of the object,
1860+
will be reverted at the end of the block.
17661861

17671862

1768-
.. function:: unload(name)
1863+
.. function:: ready_to_import(name=None, source="")
1864+
1865+
A context manager that will create a new Python module *name* with *source*
1866+
source code in a temporary directory and inserts this directory at the start
1867+
of :data:`sys.path`. The context manager yields a tuple with the name and the path
1868+
to the script in the temporary directory.
1869+
1870+
If the name matches an existing module, this will be cleared from :data:`sys.modules`
1871+
on entry and restored on exit.
17691872

1770-
Delete *name* from ``sys.modules``.
1873+
If no name is given, the module will be named "spam".
17711874

17721875

1773-
.. function:: make_legacy_pyc(source)
1876+
1877+
Manipulating internals
1878+
----------------------
1879+
1880+
.. function:: make_legacy_pyc(source, allow_compile=False)
17741881

17751882
Move a :pep:`3147`/:pep:`488` pyc file to its legacy pyc location and return the file
17761883
system path to the legacy pyc file. The *source* value is the file system
17771884
path to the source file. It does not need to exist, however the PEP
1778-
3147/488 pyc file must exist.
1885+
3147/488 pyc file must exist or *allow_compile* must be set.
17791886

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

1781-
.. class:: CleanImport(*module_names)
17821889

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

1787-
with CleanImport('foo'):
1788-
importlib.import_module('foo') # New reference.
1892+
A context manager that forces frozen modules to be used or excluded.
17891893

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

1791-
.. class:: DirsOnSysPath(*paths)
1896+
This only applies to modules that have not yet been imported. Some essential
1897+
modules will always be imported frozen.
17921898

1793-
A context manager to temporarily add directories to :data:`sys.path`.
17941899

1795-
This makes a copy of :data:`sys.path`, appends any directories given
1796-
as positional arguments, then reverts :data:`sys.path` to the copied
1797-
settings when the context ends.
1900+
.. function:: multi_interp_extensions_check(enabled=True)
17981901

1799-
Note that *all* :data:`sys.path` modifications in the body of the
1800-
context manager, including replacement of the object,
1801-
will be reverted at the end of the block.
1902+
A context manager that forces (if *enabled* is ``True``) or prevents legacy (single-phase init)
1903+
modules from being allowed in subinterpreters.
1904+
1905+
This only applies to modules that haven't been imported yet.
1906+
It overrides the :c:member:`PyInterpreterConfig.check_multi_interp_extensions`
1907+
setting.
1908+
1909+
1910+
Lazy imports
1911+
------------
1912+
1913+
.. function:: ensure_lazy_imports(imported_module, modules_to_block, *, additional_code=None)
1914+
1915+
Test that when *imported_module* is imported, none of the modules named in *modules_to_block*
1916+
are imported as a side effect.
1917+
1918+
*additional_code* if given should be additional Python source code to execute before
1919+
checking that the blocked modules still haven't been imported.
18021920

18031921

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

0 commit comments

Comments
 (0)