From b4534ae704a4efb385e2343ecdbc15f232ef78b6 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sun, 13 Oct 2013 23:23:08 +1000 Subject: Docs tweaks for contextlib additions --- 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 index cac113e..cef5f1a 100644 --- 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 bf958ba..4927b66 100644 --- 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 --- -- cgit v0.12