Georg Brandl | 0eaab97 | 2009-06-08 08:00:22 +0000 | [diff] [blame] | 1 | :mod:`contextlib` --- Utilities for :keyword:`with`\ -statement contexts |
| 2 | ======================================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: contextlib |
| 5 | :synopsis: Utilities for with-statement contexts. |
| 6 | |
| 7 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | This module provides utilities for common tasks involving the :keyword:`with` |
| 9 | statement. For more information see also :ref:`typecontextmanager` and |
| 10 | :ref:`context-managers`. |
| 11 | |
| 12 | Functions provided: |
| 13 | |
| 14 | |
| 15 | .. function:: contextmanager(func) |
| 16 | |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 17 | This function is a :term:`decorator` that can be used to define a factory |
| 18 | function for :keyword:`with` statement context managers, without needing to |
| 19 | create a class or separate :meth:`__enter__` and :meth:`__exit__` methods. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | |
| 21 | A simple example (this is not recommended as a real way of generating HTML!):: |
| 22 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 23 | from contextlib import contextmanager |
| 24 | |
| 25 | @contextmanager |
| 26 | def tag(name): |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 27 | print("<%s>" % name) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | yield |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 29 | print("</%s>" % name) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | |
| 31 | >>> with tag("h1"): |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 32 | ... print("foo") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 33 | ... |
| 34 | <h1> |
| 35 | foo |
| 36 | </h1> |
| 37 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 38 | The function being decorated must return a :term:`generator`-iterator when |
| 39 | called. This iterator must yield exactly one value, which will be bound to |
| 40 | the targets in the :keyword:`with` statement's :keyword:`as` clause, if any. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 41 | |
| 42 | At the point where the generator yields, the block nested in the :keyword:`with` |
| 43 | statement is executed. The generator is then resumed after the block is exited. |
| 44 | If an unhandled exception occurs in the block, it is reraised inside the |
| 45 | generator at the point where the yield occurred. Thus, you can use a |
| 46 | :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` statement to trap |
| 47 | the error (if any), or ensure that some cleanup takes place. If an exception is |
| 48 | trapped merely in order to log it or to perform some action (rather than to |
| 49 | suppress it entirely), the generator must reraise that exception. Otherwise the |
| 50 | generator context manager will indicate to the :keyword:`with` statement that |
| 51 | the exception has been handled, and execution will resume with the statement |
| 52 | immediately following the :keyword:`with` statement. |
| 53 | |
| 54 | |
| 55 | .. function:: nested(mgr1[, mgr2[, ...]]) |
| 56 | |
| 57 | Combine multiple context managers into a single nested context manager. |
| 58 | |
| 59 | Code like this:: |
| 60 | |
| 61 | from contextlib import nested |
| 62 | |
Benjamin Peterson | f07d002 | 2009-03-21 17:31:58 +0000 | [diff] [blame] | 63 | with nested(A(), B(), C()) as (X, Y, Z): |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 64 | do_something() |
| 65 | |
| 66 | is equivalent to this:: |
| 67 | |
Benjamin Peterson | f07d002 | 2009-03-21 17:31:58 +0000 | [diff] [blame] | 68 | m1, m2, m3 = A(), B(), C() |
| 69 | with m1 as X: |
| 70 | with m2 as Y: |
| 71 | with m3 as Z: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | do_something() |
| 73 | |
| 74 | Note that if the :meth:`__exit__` method of one of the nested context managers |
| 75 | indicates an exception should be suppressed, no exception information will be |
| 76 | passed to any remaining outer context managers. Similarly, if the |
| 77 | :meth:`__exit__` method of one of the nested managers raises an exception, any |
| 78 | previous exception state will be lost; the new exception will be passed to the |
| 79 | :meth:`__exit__` methods of any remaining outer context managers. In general, |
| 80 | :meth:`__exit__` methods should avoid raising exceptions, and in particular they |
| 81 | should not re-raise a passed-in exception. |
| 82 | |
Raymond Hettinger | 91e3b9d | 2009-05-28 22:20:03 +0000 | [diff] [blame] | 83 | .. deprecated:: 3.1 |
| 84 | The with-statement now supports this functionality directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | |
| 86 | .. function:: closing(thing) |
| 87 | |
| 88 | Return a context manager that closes *thing* upon completion of the block. This |
| 89 | is basically equivalent to:: |
| 90 | |
| 91 | from contextlib import contextmanager |
| 92 | |
| 93 | @contextmanager |
| 94 | def closing(thing): |
| 95 | try: |
| 96 | yield thing |
| 97 | finally: |
| 98 | thing.close() |
| 99 | |
| 100 | And lets you write code like this:: |
| 101 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | from contextlib import closing |
Georg Brandl | 0f7ede4 | 2008-06-23 11:23:31 +0000 | [diff] [blame] | 103 | from urllib.request import urlopen |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 104 | |
Georg Brandl | 0f7ede4 | 2008-06-23 11:23:31 +0000 | [diff] [blame] | 105 | with closing(urlopen('http://www.python.org')) as page: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 106 | for line in page: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 107 | print(line) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 108 | |
| 109 | without needing to explicitly close ``page``. Even if an error occurs, |
| 110 | ``page.close()`` will be called when the :keyword:`with` block is exited. |
| 111 | |
| 112 | |
| 113 | .. seealso:: |
| 114 | |
| 115 | :pep:`0343` - The "with" statement |
| 116 | The specification, background, and examples for the Python :keyword:`with` |
| 117 | statement. |
| 118 | |