mirror of
https://github.com/python/cpython.git
synced 2025-10-31 10:26:02 +00:00
120 lines
4 KiB
ReStructuredText
120 lines
4 KiB
ReStructuredText
|
|
: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.
|
|
|