| |
| :mod:`contextlib` --- Utilities for :keyword:`with`\ -statement contexts. |
| ========================================================================= |
| |
| .. module:: contextlib |
| :synopsis: Utilities for with-statement contexts. |
| |
| |
| 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 :term:`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. |
| |