Move the 3k reST doc tree in place.

Doc/library/contextlib.rst

@@ -0,0 +1,120 @@
+
+:mod:`contextlib` --- Utilities for :keyword:`with`\ -statement contexts.
+=========================================================================
+
+.. module:: contextlib
+   :synopsis: Utilities for with-statement contexts.
+
+
+.. versionadded:: 2.5
+
+This module provides utilities for common tasks involving the :keyword:`with`
+statement. For more information see also :ref:`typecontextmanager` and
+:ref:`context-managers`.
+
+Functions provided:
+
+
+.. function:: contextmanager(func)
+
+   This function is a decorator that can be used to define a factory function for
+   :keyword:`with` statement context managers, without needing to create a class or
+   separate :meth:`__enter__` and :meth:`__exit__` methods.
+
+   A simple example (this is not recommended as a real way of generating HTML!)::
+
+      from __future__ import with_statement
+      from contextlib import contextmanager
+
+      @contextmanager
+      def tag(name):
+          print "<%s>" % name
+          yield
+          print "</%s>" % name
+
+      >>> with tag("h1"):
+      ...    print "foo"
+      ...
+      <h1>
+      foo
+      </h1>
+
+   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
+   :keyword:`with` statement's :keyword:`as` clause, if any.
+
+   At the point where the generator yields, the block nested in the :keyword:`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
+   :keyword:`try`...\ :keyword:`except`...\ :keyword:`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 :keyword:`with` statement that
+   the exception has been handled, and execution will resume with the statement
+   immediately following the :keyword:`with` statement.
+
+
+.. function:: nested(mgr1[, mgr2[, ...]])
+
+   Combine multiple context managers into a single nested context manager.
+
+   Code like this::
+
+      from contextlib import nested
+
+      with nested(A, B, C) as (X, Y, Z):
+          do_something()
+
+   is equivalent to this::
+
+      with A as X:
+          with B as Y:
+              with C as Z:
+                  do_something()
+
+   Note that if the :meth:`__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
+   :meth:`__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
+   :meth:`__exit__` methods of any remaining outer context managers. In general,
+   :meth:`__exit__` methods should avoid raising exceptions, and in particular they
+   should not re-raise a passed-in exception.
+
+
+.. function:: 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 __future__ import with_statement
+      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 :keyword:`with` block is exited.
+
+
+.. seealso::
+
+   :pep:`0343` - The "with" statement
+      The specification, background, and examples for the Python :keyword:`with`
+      statement.
+