1 

     2 :mod:`contextlib` --- Utilities for :keyword:`with`\ -statement contexts.

     3 =========================================================================

     4 

     5 .. module:: contextlib

     6    :synopsis: Utilities for with-statement contexts.

     7 

     8 

     9 .. versionadded:: 2.5

    10 

    11 This module provides utilities for common tasks involving the :keyword:`with`

    12 statement. For more information see also :ref:`typecontextmanager` and

    13 :ref:`context-managers`.

    14 

    15 Functions provided:

    16 

    17 

    18 .. function:: contextmanager(func)

    19 

    20    This function is a :term:`decorator` that can be used to define a factory

    21    function for :keyword:`with` statement context managers, without needing to

    22    create a class or separate :meth:`__enter__` and :meth:`__exit__` methods.

    23 

    24    A simple example (this is not recommended as a real way of generating HTML!)::

    25 

    26       from contextlib import contextmanager

    27 

    28       @contextmanager

    29       def tag(name):

    30           print "<%s>" % name

    31           yield

    32           print "</%s>" % name

    33 

    34       >>> with tag("h1"):

    35       ...    print "foo"

    36       ...

    37       <h1>

    38       foo

    39       </h1>

    40 

    41    The function being decorated must return a :term:`generator`-iterator when

    42    called. This iterator must yield exactly one value, which will be bound to

    43    the targets in the :keyword:`with` statement's :keyword:`as` clause, if any.

    44 

    45    At the point where the generator yields, the block nested in the :keyword:`with`

    46    statement is executed.  The generator is then resumed after the block is exited.

    47    If an unhandled exception occurs in the block, it is reraised inside the

    48    generator at the point where the yield occurred.  Thus, you can use a

    49    :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` statement to trap

    50    the error (if any), or ensure that some cleanup takes place. If an exception is

    51    trapped merely in order to log it or to perform some action (rather than to

    52    suppress it entirely), the generator must reraise that exception. Otherwise the

    53    generator context manager will indicate to the :keyword:`with` statement that

    54    the exception has been handled, and execution will resume with the statement

    55    immediately following the :keyword:`with` statement.

    56 

    57 

    58 .. function:: nested(mgr1[, mgr2[, ...]])

    59 

    60    Combine multiple context managers into a single nested context manager.

    61 

    62    Code like this::

    63 

    64       from contextlib import nested

    65 

    66       with nested(A, B, C) as (X, Y, Z):

    67           do_something()

    68 

    69    is equivalent to this::

    70 

    71       with A as X:

    72           with B as Y:

    73               with C as Z:

    74                   do_something()

    75 

    76    Note that if the :meth:`__exit__` method of one of the nested context managers

    77    indicates an exception should be suppressed, no exception information will be

    78    passed to any remaining outer context managers. Similarly, if the

    79    :meth:`__exit__` method of one of the nested managers raises an exception, any

    80    previous exception state will be lost; the new exception will be passed to the

    81    :meth:`__exit__` methods of any remaining outer context managers. In general,

    82    :meth:`__exit__` methods should avoid raising exceptions, and in particular they

    83    should not re-raise a passed-in exception.

    84 

    85 

    86 .. function:: closing(thing)

    87 

    88    Return a context manager that closes *thing* upon completion of the block.  This

    89    is basically equivalent to::

    90 

    91       from contextlib import contextmanager

    92 

    93       @contextmanager

    94       def closing(thing):

    95           try:

    96               yield thing

    97           finally:

    98               thing.close()

    99 

   100    And lets you write code like this::

   101 

   102       from contextlib import closing

   103       import urllib

   104 

   105       with closing(urllib.urlopen('http://www.python.org')) as page:

   106           for line in page:

   107               print line

   108 

   109    without needing to explicitly close ``page``.  Even if an error occurs,

   110    ``page.close()`` will be called when the :keyword:`with` block is exited.

   111 

   112 

   113 .. seealso::

   114 

   115    :pep:`0343` - The "with" statement

   116       The specification, background, and examples for the Python :keyword:`with`

   117       statement.

   118