Issue 5354: Change API for import_fresh_module() to better support test_warnings use case (also fixes some bugs in the original implementation)

1 files changed, 28 insertions, 4 deletions

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index ccca299..ba2c3b8 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -351,15 +351,39 @@ The :mod:`test.test_support` module defines the following functions:
    .. versionadded:: 2.7
 
 
-.. function:: import_fresh_module(name, blocked_names=None, deprecated=False)
+.. function:: import_fresh_module(name, fresh=(), blocked=(), deprecated=False)
 
-   This function imports and returns a fresh copy of the named Python module. The
-   ``sys.modules`` cache is bypassed temporarily, and the ability to import the
-   modules named in *blocked_names* is suppressed for the duration of the import.
+   This function imports and returns a fresh copy of the named Python module
+   by removing the named module from ``sys.modules`` before doing the import.
+   Note that unlike :func:`reload`, the original module is not affected by
+   this operation.
+
+   *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`
+   in the module cache during the import to ensure that attempts to import
+   them raise :exc:`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 :const:`True`.
 
+   This function will raise :exc:`unittest.SkipTest` is the named module
+   cannot be imported.
+
+   Example use::
+
+      # Get copies of the warnings module for testing without
+      # affecting the version being used by the rest of the test suite
+      # One copy uses the C implementation, the other is forced to use
+      # the pure Python fallback implementation
+      py_warnings = import_fresh_module('warnings', blocked=['_warnings'])
+      c_warnings = import_fresh_module('warnings', fresh=['_warnings'])
+
    .. versionadded:: 2.7