Docs tweaks for contextlib additions

diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst
index cac113e839aadc2b99079a5f37753ebc539c84b2..cef5f1a83be1508501349c3fa0d6cb9ac529bde3 100644 (file)
--- a/Doc/library/contextlib.rst
+++ b/Doc/library/contextlib.rst
@@ -99,22 +99,27 @@ Functions and classes provided:
    Return a context manager that ignores the specified exceptions if they
    occur in the body of a with-statement.
 
+   As with any other mechanism that completely suppresses exceptions, it
+   should only be used to cover very specific errors where silently
+   ignoring the exception is known to be the right thing to do.
+
    For example::
 
        from contextlib import ignore
 
-       with ignore(OSError):
+       with ignore(FileNotFoundError):
            os.remove('somefile.tmp')
 
    This code is equivalent to::
 
        try:
            os.remove('somefile.tmp')
-       except OSError:
+       except FileNotFoundError:
            pass
 
    .. versionadded:: 3.4
 
+
 .. function:: redirect_stdout(new_target)
 
    Context manager for temporarily redirecting :data:`sys.stdout` to
@@ -144,6 +149,11 @@ Functions and classes provided:
         with redirect_stdout(sys.stderr):
             help(pow)
 
+   Note that the global side effect on :data:`sys.stdout` means that this
+   context manager is not suitable for use in library code and most threaded
+   applications. It also has no effect on the output of subprocesses.
+   However, it is still a useful approach for many utility scripts.
+
    .. versionadded:: 3.4
 
 .. class:: ContextDecorator()

diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index bf958bae2abc8047be91e864a622ace41c10a1f6..4927b66a43a63a13e80c624728b69a033a8eda3d 100644 (file)
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -205,6 +205,19 @@ been expanded so that they match the FCC NTSC versions.  The change in
 results should be less than 1% and may better match results found elsewhere.
 
 
+contextlib
+----------
+
+The new :class:`contextlib.ignore` context manager helps to clarify the
+intent of code that deliberately ignores failures from a particular
+operation.
+
+The new :class:`contextlib.redirect_stdio` context manager makes it easier
+for utility scripts to handle inflexible APIs that don't provide any
+options to retrieve their output as a string or direct it to somewhere
+other than :data:`sys.stdout`.
+
+
 dis
 ---