28.7. "contextlib" — Utilities for "with"-statement contexts
************************************************************

New in version 2.5.

**Source code:** Lib/contextlib.py

======================================================================

This module provides utilities for common tasks involving the "with"
statement. For more information see also Context Manager Types and
With Statement Context Managers.

Functions provided:

contextlib.contextmanager(func)

   This function is a *decorator* that can be used to define a factory
   function for "with" statement context managers, without needing to
   create a class or separate "__enter__()" and "__exit__()" methods.

   While many objects natively support use in with statements,
   sometimes a resource needs to be managed that isn’t a context
   manager in its own right, and doesn’t implement a "close()" method
   for use with "contextlib.closing"

   An abstract example would be the following to ensure correct
   resource management:

      from contextlib import contextmanager

      @contextmanager
      def managed_resource(*args, **kwds):
          # Code to acquire resource, e.g.:
          resource = acquire_resource(*args, **kwds)
          try:
              yield resource
          finally:
              # Code to release resource, e.g.:
              release_resource(resource)

      >>> with managed_resource(timeout=3600) as resource:
      ...     # Resource is released at the end of this block,
      ...     # even if code in the block raises an exception

   The function being decorated must return a *generator*-iterator
   when called. This iterator must yield exactly one value, which will
   be bound to the targets in the "with" statement’s "as" clause, if
   any.

   At the point where the generator yields, the block nested in the
   "with" statement is executed.  The generator is then resumed after
   the block is exited. If an unhandled exception occurs in the block,
   it is reraised inside the generator at the point where the yield
   occurred.  Thus, you can use a "try"…"except"…"finally" statement
   to trap the error (if any), or ensure that some cleanup takes
   place. If an exception is trapped merely in order to log it or to
   perform some action (rather than to suppress it entirely), the
   generator must reraise that exception. Otherwise the generator
   context manager will indicate to the "with" statement that the
   exception has been handled, and execution will resume with the
   statement immediately following the "with" statement.

contextlib.nested(mgr1[, mgr2[, ...]])

   Combine multiple context managers into a single nested context
   manager.

   This function has been deprecated in favour of the multiple manager
   form of the "with" statement.

   The one advantage of this function over the multiple manager form
   of the "with" statement is that argument unpacking allows it to be
   used with a variable number of context managers as follows:

      from contextlib import nested

      with nested(*managers):
          do_something()

   Note that if the "__exit__()" method of one of the nested context
   managers indicates an exception should be suppressed, no exception
   information will be passed to any remaining outer context managers.
   Similarly, if the "__exit__()" method of one of the nested managers
   raises an exception, any previous exception state will be lost; the
   new exception will be passed to the "__exit__()" methods of any
   remaining outer context managers. In general, "__exit__()" methods
   should avoid raising exceptions, and in particular they should not
   re-raise a passed-in exception.

   This function has two major quirks that have led to it being
   deprecated. Firstly, as the context managers are all constructed
   before the function is invoked, the "__new__()" and "__init__()"
   methods of the inner context managers are not actually covered by
   the scope of the outer context managers. That means, for example,
   that using "nested()" to open two files is a programming error as
   the first file will not be closed promptly if an exception is
   thrown when opening the second file.

   Secondly, if the "__enter__()" method of one of the inner context
   managers raises an exception that is caught and suppressed by the
   "__exit__()" method of one of the outer context managers, this
   construct will raise "RuntimeError" rather than skipping the body
   of the "with" statement.

   Developers that need to support nesting of a variable number of
   context managers can either use the "warnings" module to suppress
   the DeprecationWarning raised by this function or else use this
   function as a model for an application specific implementation.

   Deprecated since version 2.7: The with-statement now supports this
   functionality directly (without the confusing error prone quirks).

contextlib.closing(thing)

   Return a context manager that closes *thing* upon completion of the
   block.  This is basically equivalent to:

      from contextlib import contextmanager

      @contextmanager
      def closing(thing):
          try:
              yield thing
          finally:
              thing.close()

   And lets you write code like this:

      from contextlib import closing
      import urllib

      with closing(urllib.urlopen('http://www.python.org')) as page:
          for line in page:
              print line

   without needing to explicitly close "page".  Even if an error
   occurs, "page.close()" will be called when the "with" block is
   exited.

See also:

  **PEP 343** - The “with” statement
     The specification, background, and examples for the Python "with"
     statement.