| |
| .. module:: contextlib |
| :synopsis: Utilities for with-statement contexts. |
| |
| |
| .. versionadded:: 2.5 |
| |
| This module provides utilities for common tasks involving the :keyword:`with` |
n | statement. |
n | statement. For more information see also :ref:`typecontextmanager` and |
| :ref:`context-managers`. |
| |
| Functions provided: |
| |
| |
| .. function:: contextmanager(func) |
| |
n | This function is a decorator that can be used to define a factory function for |
n | This function is a :term:`decorator` that can be used to define a factory |
| :keyword:`with` statement context managers, without needing to create a class or |
| function for :keyword:`with` statement context managers, without needing to |
| separate :meth:`__enter__` and :meth:`__exit__` methods. |
| 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!):: |
| |
n | 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> |
| |
n | The function being decorated must return a generator-iterator when called. This |
n | The function being decorated must return a :term:`generator`-iterator when |
| iterator must yield exactly one value, which will be bound to the targets in the |
| called. This iterator must yield exactly one value, which will be bound to |
| :keyword:`with` statement's :keyword:`as` clause, if any. |
| 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 |
| .. function:: nested(mgr1[, mgr2[, ...]]) |
| |
| Combine multiple context managers into a single nested context manager. |
| |
| Code like this:: |
| |
| from contextlib import nested |
| |
n | with nested(A, B, C) as (X, Y, Z): |
n | with nested(A(), B(), C()) as (X, Y, Z): |
| do_something() |
| |
| is equivalent to this:: |
| |
n | m1, m2, m3 = A(), B(), C() |
| with A as X: |
| with m1 as X: |
| with B as Y: |
| with m2 as Y: |
| with C as Z: |
| with m3 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. |
n | |
| .. _context-closing: |
| |
| |
| .. function:: closing(thing) |
| |
| Return a context manager that closes *thing* upon completion of the block. This |
| is basically equivalent to:: |
| |
| from contextlib import contextmanager |