[Python-checkins] cpython: Docs tweaks for contextlib additions

[nick.coghlan]

http://hg.python.org/cpython/rev/de15abcdf2c8
changeset:   86300:de15abcdf2c8
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Sun Oct 13 23:23:08 2013 +1000
summary:
  Docs tweaks for contextlib additions

files:
  Doc/library/contextlib.rst |  14 ++++++++++++--
  Doc/whatsnew/3.4.rst       |  13 +++++++++++++
  2 files changed, 25 insertions(+), 2 deletions(-)


diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst
--- 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
--- 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
 ---
 

-- 
Repository URL: http://hg.python.org/cpython