Issue 5354: Change API for import_fresh_module() to better support test_warnings use case (also fixes some bugs in the original implementation)
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 @@
.. 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