Close #12645: Clarify and reformat the documentation of import_fresh_module

Doc/library/test.rst

@@ -489,7 +489,7 @@ The :mod:`test.support` module defines the following functions:
    *fresh* is an iterable of additional module names that are also removed
    from the ``sys.modules`` cache before doing the import.
 
-   *blocked* is an iterable of module names that are replaced with :const:`0`
+   *blocked* is an iterable of module names that are replaced with ``None``
    in the module cache during the import to ensure that attempts to import
    them raise :exc:`ImportError`.
 
@@ -500,15 +500,15 @@ The :mod:`test.support` module defines the following functions:
    Module and package deprecation messages are suppressed during this import
    if *deprecated* is ``True``.
 
-   This function will raise :exc:`unittest.SkipTest` if the named module
+   This function will raise :exc:`ImportError` if the named module cannot be
-   cannot be imported.
+   imported.
 
    Example use::
 
-      # Get copies of the warnings module for testing without
+      # Get copies of the warnings module for testing without affecting the
-      # affecting the version being used by the rest of the test suite
+      # version being used by the rest of the test suite. One copy uses the
-      # One copy uses the C implementation, the other is forced to use
+      # C implementation, the other is forced to use the pure Python fallback
-      # the pure Python fallback implementation
+      # implementation
       py_warnings = import_fresh_module('warnings', blocked=['_warnings'])
       c_warnings = import_fresh_module('warnings', fresh=['_warnings'])
 

Lib/test/support/__init__.py

@@ -144,7 +144,8 @@ def _save_and_remove_module(name, orig_modules):
 def _save_and_block_module(name, orig_modules):
     """Helper function to save and block a module in sys.modules
 
-       Return True if the module was in sys.modules, False otherwise."""
+    Return True if the module was in sys.modules, False otherwise.
+    """
     saved = True
     try:
         orig_modules[name] = sys.modules[name]
@@ -166,18 +167,30 @@ def anticipate_failure(condition):
 
 
 def import_fresh_module(name, fresh=(), blocked=(), deprecated=False):
-    """Imports and returns a module, deliberately bypassing the sys.modules cache
+    """Import and return a module, deliberately bypassing sys.modules.
-    and importing a fresh copy of the module. Once the import is complete,
-    the sys.modules cache is restored to its original state.
 
-    Modules named in fresh are also imported anew if needed by the import.
+    This function imports and returns a fresh copy of the named Python module
-    If one of these modules can't be imported, None is returned.
+    by removing the named module from sys.modules before doing the import.
+    Note that unlike reload, the original module is not affected by
+    this operation.
 
-    Importing of modules named in blocked is prevented while the fresh import
+    *fresh* is an iterable of additional module names that are also removed
-    takes place.
+    from the sys.modules cache before doing the import.
 
-    If deprecated is True, any module or package deprecation messages
+    *blocked* is an iterable of module names that are replaced with None
-    will be suppressed."""
+    in the module cache during the import to ensure that attempts to import
+    them raise ImportError.
+
+    The named module and any modules named in the *fresh* and *blocked*
+    parameters are saved before starting the import and then reinserted into
+    sys.modules when the fresh import is complete.
+
+    Module and package deprecation messages are suppressed during this import
+    if *deprecated* is True.
+
+    This function will raise ImportError if the named module cannot be
+    imported.
+    """
     # NOTE: test_heapq, test_json and test_warnings include extra sanity checks
     # to make sure that this utility function is working as expected
     with _ignore_deprecated_imports(deprecated):