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