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