Skip to content

Commit 7f888c7

Browse files
shihai1991shihai1991
authored
bpo-40275: Add import_helper submodule in test.support (GH-20794)
1 parent 3b3b83c commit 7f888c7

3 files changed

Lines changed: 359 additions & 330 deletions

File tree

‎Doc/library/test.rst‎

Lines changed: 116 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -398,25 +398,6 @@ The :mod:`test.support` module defines the following constants:
398398

399399
The :mod:`test.support` module defines the following functions:
400400

401-
.. function:: forget(module_name)
402-
403-
Remove the module named *module_name* from ``sys.modules`` and delete any
404-
byte-compiled files of the module.
405-
406-
407-
.. function:: unload(name)
408-
409-
Delete *name* from ``sys.modules``.
410-
411-
412-
.. function:: make_legacy_pyc(source)
413-
414-
Move a :pep:`3147`/:pep:`488` pyc file to its legacy pyc location and return the file
415-
system path to the legacy pyc file. The *source* value is the file system
416-
path to the source file. It does not need to exist, however the PEP
417-
3147/488 pyc file must exist.
418-
419-
420401
.. function:: is_resource_enabled(resource)
421402

422403
Return ``True`` if *resource* is enabled and available. The list of
@@ -889,67 +870,6 @@ The :mod:`test.support` module defines the following functions:
889870
Open *url*. If open fails, raises :exc:`TestFailed`.
890871

891872

892-
.. function:: import_module(name, deprecated=False, *, required_on())
893-
894-
This function imports and returns the named module. Unlike a normal
895-
import, this function raises :exc:`unittest.SkipTest` if the module
896-
cannot be imported.
897-
898-
Module and package deprecation messages are suppressed during this import
899-
if *deprecated* is ``True``. If a module is required on a platform but
900-
optional for others, set *required_on* to an iterable of platform prefixes
901-
which will be compared against :data:`sys.platform`.
902-
903-
.. versionadded:: 3.1
904-
905-
906-
.. function:: import_fresh_module(name, fresh=(), blocked=(), deprecated=False)
907-
908-
This function imports and returns a fresh copy of the named Python module
909-
by removing the named module from ``sys.modules`` before doing the import.
910-
Note that unlike :func:`reload`, the original module is not affected by
911-
this operation.
912-
913-
*fresh* is an iterable of additional module names that are also removed
914-
from the ``sys.modules`` cache before doing the import.
915-
916-
*blocked* is an iterable of module names that are replaced with ``None``
917-
in the module cache during the import to ensure that attempts to import
918-
them raise :exc:`ImportError`.
919-
920-
The named module and any modules named in the *fresh* and *blocked*
921-
parameters are saved before starting the import and then reinserted into
922-
``sys.modules`` when the fresh import is complete.
923-
924-
Module and package deprecation messages are suppressed during this import
925-
if *deprecated* is ``True``.
926-
927-
This function will raise :exc:`ImportError` if the named module cannot be
928-
imported.
929-
930-
Example use::
931-
932-
# Get copies of the warnings module for testing without affecting the
933-
# version being used by the rest of the test suite. One copy uses the
934-
# C implementation, the other is forced to use the pure Python fallback
935-
# implementation
936-
py_warnings = import_fresh_module('warnings', blocked=['_warnings'])
937-
c_warnings = import_fresh_module('warnings', fresh=['_warnings'])
938-
939-
.. versionadded:: 3.1
940-
941-
942-
.. function:: modules_setup()
943-
944-
Return a copy of :data:`sys.modules`.
945-
946-
947-
.. function:: modules_cleanup(oldmodules)
948-
949-
Remove modules except for *oldmodules* and ``encodings`` in order to
950-
preserve internal cache.
951-
952-
953873
.. function:: reap_children()
954874

955875
Use this at the end of ``test_main`` whenever sub-processes are started.
@@ -1113,29 +1033,6 @@ The :mod:`test.support` module defines the following classes:
11131033
On both platforms, the old value is restored by :meth:`__exit__`.
11141034

11151035

1116-
.. class:: CleanImport(*module_names)
1117-
1118-
A context manager to force import to return a new module reference. This
1119-
is useful for testing module-level behaviors, such as the emission of a
1120-
DeprecationWarning on import. Example usage::
1121-
1122-
with CleanImport('foo'):
1123-
importlib.import_module('foo') # New reference.
1124-
1125-
1126-
.. class:: DirsOnSysPath(*paths)
1127-
1128-
A context manager to temporarily add directories to sys.path.
1129-
1130-
This makes a copy of :data:`sys.path`, appends any directories given
1131-
as positional arguments, then reverts :data:`sys.path` to the copied
1132-
settings when the context ends.
1133-
1134-
Note that *all* :data:`sys.path` modifications in the body of the
1135-
context manager, including replacement of the object,
1136-
will be reverted at the end of the block.
1137-
1138-
11391036
.. class:: SaveSignals()
11401037

11411038
Class to save and restore signal handlers registered by the Python signal
@@ -1646,3 +1543,119 @@ The :mod:`test.support.os_helper` module provides support for os tests.
16461543

16471544
Call :func:`os.unlink` on *filename*. On Windows platforms, this is
16481545
wrapped with a wait loop that checks for the existence fo the file.
1546+
1547+
1548+
:mod:`test.support.import_helper` --- Utilities for import tests
1549+
================================================================
1550+
1551+
.. module:: test.support.import_helper
1552+
:synopsis: Support for import tests.
1553+
1554+
The :mod:`test.support.import_helper` module provides support for import tests.
1555+
1556+
.. versionadded:: 3.10
1557+
1558+
1559+
.. function:: forget(module_name)
1560+
1561+
Remove the module named *module_name* from ``sys.modules`` and delete any
1562+
byte-compiled files of the module.
1563+
1564+
1565+
.. function:: import_fresh_module(name, fresh=(), blocked=(), deprecated=False)
1566+
1567+
This function imports and returns a fresh copy of the named Python module
1568+
by removing the named module from ``sys.modules`` before doing the import.
1569+
Note that unlike :func:`reload`, the original module is not affected by
1570+
this operation.
1571+
1572+
*fresh* is an iterable of additional module names that are also removed
1573+
from the ``sys.modules`` cache before doing the import.
1574+
1575+
*blocked* is an iterable of module names that are replaced with ``None``
1576+
in the module cache during the import to ensure that attempts to import
1577+
them raise :exc:`ImportError`.
1578+
1579+
The named module and any modules named in the *fresh* and *blocked*
1580+
parameters are saved before starting the import and then reinserted into
1581+
``sys.modules`` when the fresh import is complete.
1582+
1583+
Module and package deprecation messages are suppressed during this import
1584+
if *deprecated* is ``True``.
1585+
1586+
This function will raise :exc:`ImportError` if the named module cannot be
1587+
imported.
1588+
1589+
Example use::
1590+
1591+
# Get copies of the warnings module for testing without affecting the
1592+
# version being used by the rest of the test suite. One copy uses the
1593+
# C implementation, the other is forced to use the pure Python fallback
1594+
# implementation
1595+
py_warnings = import_fresh_module('warnings', blocked=['_warnings'])
1596+
c_warnings = import_fresh_module('warnings', fresh=['_warnings'])
1597+
1598+
.. versionadded:: 3.1
1599+
1600+
1601+
.. function:: import_module(name, deprecated=False, *, required_on())
1602+
1603+
This function imports and returns the named module. Unlike a normal
1604+
import, this function raises :exc:`unittest.SkipTest` if the module
1605+
cannot be imported.
1606+
1607+
Module and package deprecation messages are suppressed during this import
1608+
if *deprecated* is ``True``. If a module is required on a platform but
1609+
optional for others, set *required_on* to an iterable of platform prefixes
1610+
which will be compared against :data:`sys.platform`.
1611+
1612+
.. versionadded:: 3.1
1613+
1614+
1615+
.. function:: modules_setup()
1616+
1617+
Return a copy of :data:`sys.modules`.
1618+
1619+
1620+
.. function:: modules_cleanup(oldmodules)
1621+
1622+
Remove modules except for *oldmodules* and ``encodings`` in order to
1623+
preserve internal cache.
1624+
1625+
1626+
.. function:: unload(name)
1627+
1628+
Delete *name* from ``sys.modules``.
1629+
1630+
1631+
.. function:: make_legacy_pyc(source)
1632+
1633+
Move a :pep:`3147`/:pep:`488` pyc file to its legacy pyc location and return the file
1634+
system path to the legacy pyc file. The *source* value is the file system
1635+
path to the source file. It does not need to exist, however the PEP
1636+
3147/488 pyc file must exist.
1637+
1638+
1639+
.. class:: CleanImport(*module_names)
1640+
1641+
A context manager to force import to return a new module reference. This
1642+
is useful for testing module-level behaviors, such as the emission of a
1643+
DeprecationWarning on import. Example usage::
1644+
1645+
with CleanImport('foo'):
1646+
importlib.import_module('foo') # New reference.
1647+
1648+
1649+
.. class:: DirsOnSysPath(*paths)
1650+
1651+
A context manager to temporarily add directories to sys.path.
1652+
1653+
This makes a copy of :data:`sys.path`, appends any directories given
1654+
as positional arguments, then reverts :data:`sys.path` to the copied
1655+
settings when the context ends.
1656+
1657+
Note that *all* :data:`sys.path` modifications in the body of the
1658+
context manager, including replacement of the object,
1659+
will be reverted at the end of the block.
1660+
1661+

0 commit comments

Comments
 (0)