rest25/library/contextlib.rst => rest262/library/contextlib.rst
4
5.. module:: contextlib
6   :synopsis: Utilities for with-statement contexts.
7
8
9.. versionadded:: 2.5
10
11This module provides utilities for common tasks involving the :keyword:`with`
n12-statement.
n12+statement. For more information see also :ref:`typecontextmanager` and
13+:ref:`context-managers`.
13
14Functions provided:
15
16
17.. function:: contextmanager(func)
18
n19-   This function is a decorator that can be used to define a factory function for
n20+   This function is a :term:`decorator` that can be used to define a factory
20-   :keyword:`with` statement context managers, without needing to create a class or
21+   function for :keyword:`with` statement context managers, without needing to
21-   separate :meth:`__enter__` and :meth:`__exit__` methods.
22+   create a class or separate :meth:`__enter__` and :meth:`__exit__` methods.
22
23   A simple example (this is not recommended as a real way of generating HTML!)::
24
n25-      from __future__ import with_statement
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
n41-   The function being decorated must return a generator-iterator when called. This
n41+   The function being decorated must return a :term:`generator`-iterator when
42-   iterator must yield exactly one value, which will be bound to the targets in the
42+   called. This iterator must yield exactly one value, which will be bound to
43-   :keyword:`with` statement's :keyword:`as` clause, if any.
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
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
n66-      with nested(A, B, C) as (X, Y, Z):
n66+      with nested(A(), B(), C()) as (X, Y, Z):
67          do_something()
68
69   is equivalent to this::
70
n71+      m1, m2, m3 = A(), B(), C()
71-      with A as X:
72+      with m1 as X:
72-          with B as Y:
73+          with m2 as Y:
73-              with C as Z:
74+              with m3 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.
n84- 
85-.. _context-closing:
86
87
88.. function:: closing(thing)
89
90   Return a context manager that closes *thing* upon completion of the block.  This
91   is basically equivalent to::
92
93      from contextlib import contextmanager
96      def closing(thing):
97          try:
98              yield thing
99          finally:
100              thing.close()
101
102   And lets you write code like this::
103
n104-      from __future__ import with_statement
105      from contextlib import closing
t106-      import codecs
t104+      import urllib
107
108      with closing(urllib.urlopen('http://www.python.org')) as page:
109          for line in page:
110              print line
111
112   without needing to explicitly close ``page``.  Even if an error occurs,
113   ``page.close()`` will be called when the :keyword:`with` block is exited.
114
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op