1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
: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 :term:`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 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.
This function has been deprecated in favour of the multiple manager form
of the :keyword:`with` statement.
The one advantage of this function over the multiple manager form of the
:keyword:`with` statement is that argument unpacking allows it to be
used with a variable number of context managers as follows::
from contextlib import nested
with nested(*managers):
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.
This function has two major quirks that have led to it being deprecated. Firstly,
as the context managers are all constructed before the function is invoked, the
:meth:`__new__` and :meth:`__init__` methods of the inner context managers are
not actually covered by the scope of the outer context managers. That means, for
example, that using :func:`nested` to open two files is a programming error as the
first file will not be closed promptly if an exception is thrown when opening
the second file.
Secondly, if the :meth:`__enter__` method of one of the inner context managers
raises an exception that is caught and suppressed by the :meth:`__exit__` method
of one of the outer context managers, this construct will raise
:exc:`RuntimeError` rather than skipping the body of the :keyword:`with`
statement.
Developers that need to support nesting of a variable number of context managers
can either use the :mod:`warnings` module to suppress the DeprecationWarning
raised by this function or else use this function as a model for an application
specific implementation.
.. deprecated:: 2.7
The with-statement now supports this functionality directly (without the
confusing error prone quirks).
.. 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 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.
|
