Docs tweaks for contextlib additions
diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst
index cac113e..cef5f1a 100644
--- a/Doc/library/contextlib.rst
+++ b/Doc/library/contextlib.rst
@@ -99,22 +99,27 @@
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 @@
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 bf958ba..4927b66 100644
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -205,6 +205,19 @@
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
---