Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | .. _compound: |
| 2 | |
| 3 | ******************* |
| 4 | Compound statements |
| 5 | ******************* |
| 6 | |
| 7 | .. index:: pair: compound; statement |
| 8 | |
| 9 | Compound statements contain (groups of) other statements; they affect or control |
| 10 | the execution of those other statements in some way. In general, compound |
| 11 | statements span multiple lines, although in simple incarnations a whole compound |
| 12 | statement may be contained in one line. |
| 13 | |
| 14 | The :keyword:`if`, :keyword:`while` and :keyword:`for` statements implement |
| 15 | traditional control flow constructs. :keyword:`try` specifies exception |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 16 | handlers and/or cleanup code for a group of statements, while the |
| 17 | :keyword:`with` statement allows the execution of initialization and |
| 18 | finalization code around a block of code. Function and class definitions are |
| 19 | also syntactically compound statements. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | |
| 21 | .. index:: |
| 22 | single: clause |
| 23 | single: suite |
| 24 | |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 25 | A compound statement consists of one or more 'clauses.' A clause consists of a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | header and a 'suite.' The clause headers of a particular compound statement are |
| 27 | all at the same indentation level. Each clause header begins with a uniquely |
| 28 | identifying keyword and ends with a colon. A suite is a group of statements |
| 29 | controlled by a clause. A suite can be one or more semicolon-separated simple |
| 30 | statements on the same line as the header, following the header's colon, or it |
| 31 | can be one or more indented statements on subsequent lines. Only the latter |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 32 | form of a suite can contain nested compound statements; the following is illegal, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 33 | mostly because it wouldn't be clear to which :keyword:`if` clause a following |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 34 | :keyword:`else` clause would belong:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 35 | |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 36 | if test1: if test2: print(x) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 37 | |
| 38 | Also note that the semicolon binds tighter than the colon in this context, so |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 39 | that in the following example, either all or none of the :func:`print` calls are |
| 40 | executed:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 41 | |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 42 | if x < y < z: print(x); print(y); print(z) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | |
| 44 | Summarizing: |
| 45 | |
| 46 | .. productionlist:: |
| 47 | compound_stmt: `if_stmt` |
| 48 | : | `while_stmt` |
| 49 | : | `for_stmt` |
| 50 | : | `try_stmt` |
| 51 | : | `with_stmt` |
| 52 | : | `funcdef` |
| 53 | : | `classdef` |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 54 | : | `async_with_stmt` |
| 55 | : | `async_for_stmt` |
| 56 | : | `async_funcdef` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT |
| 58 | statement: `stmt_list` NEWLINE | `compound_stmt` |
| 59 | stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"] |
| 60 | |
| 61 | .. index:: |
| 62 | single: NEWLINE token |
| 63 | single: DEDENT token |
| 64 | pair: dangling; else |
| 65 | |
| 66 | Note that statements always end in a ``NEWLINE`` possibly followed by a |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 67 | ``DEDENT``. Also note that optional continuation clauses always begin with a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 68 | keyword that cannot start a statement, thus there are no ambiguities (the |
| 69 | 'dangling :keyword:`else`' problem is solved in Python by requiring nested |
| 70 | :keyword:`if` statements to be indented). |
| 71 | |
| 72 | The formatting of the grammar rules in the following sections places each clause |
| 73 | on a separate line for clarity. |
| 74 | |
| 75 | |
| 76 | .. _if: |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 77 | .. _elif: |
| 78 | .. _else: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | |
| 80 | The :keyword:`if` statement |
| 81 | =========================== |
| 82 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 83 | .. index:: |
| 84 | statement: if |
| 85 | keyword: elif |
| 86 | keyword: else |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 87 | keyword: elif |
| 88 | keyword: else |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 89 | |
| 90 | The :keyword:`if` statement is used for conditional execution: |
| 91 | |
| 92 | .. productionlist:: |
| 93 | if_stmt: "if" `expression` ":" `suite` |
| 94 | : ( "elif" `expression` ":" `suite` )* |
| 95 | : ["else" ":" `suite`] |
| 96 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 97 | It selects exactly one of the suites by evaluating the expressions one by one |
| 98 | until one is found to be true (see section :ref:`booleans` for the definition of |
| 99 | true and false); then that suite is executed (and no other part of the |
| 100 | :keyword:`if` statement is executed or evaluated). If all expressions are |
| 101 | false, the suite of the :keyword:`else` clause, if present, is executed. |
| 102 | |
| 103 | |
| 104 | .. _while: |
| 105 | |
| 106 | The :keyword:`while` statement |
| 107 | ============================== |
| 108 | |
| 109 | .. index:: |
| 110 | statement: while |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 111 | keyword: else |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 112 | pair: loop; statement |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 113 | keyword: else |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | |
| 115 | The :keyword:`while` statement is used for repeated execution as long as an |
| 116 | expression is true: |
| 117 | |
| 118 | .. productionlist:: |
| 119 | while_stmt: "while" `expression` ":" `suite` |
| 120 | : ["else" ":" `suite`] |
| 121 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 122 | This repeatedly tests the expression and, if it is true, executes the first |
| 123 | suite; if the expression is false (which may be the first time it is tested) the |
| 124 | suite of the :keyword:`else` clause, if present, is executed and the loop |
| 125 | terminates. |
| 126 | |
| 127 | .. index:: |
| 128 | statement: break |
| 129 | statement: continue |
| 130 | |
| 131 | A :keyword:`break` statement executed in the first suite terminates the loop |
| 132 | without executing the :keyword:`else` clause's suite. A :keyword:`continue` |
| 133 | statement executed in the first suite skips the rest of the suite and goes back |
| 134 | to testing the expression. |
| 135 | |
| 136 | |
| 137 | .. _for: |
| 138 | |
| 139 | The :keyword:`for` statement |
| 140 | ============================ |
| 141 | |
| 142 | .. index:: |
| 143 | statement: for |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 144 | keyword: in |
| 145 | keyword: else |
| 146 | pair: target; list |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 147 | pair: loop; statement |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 148 | keyword: in |
| 149 | keyword: else |
| 150 | pair: target; list |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 151 | object: sequence |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 152 | |
| 153 | The :keyword:`for` statement is used to iterate over the elements of a sequence |
| 154 | (such as a string, tuple or list) or other iterable object: |
| 155 | |
| 156 | .. productionlist:: |
| 157 | for_stmt: "for" `target_list` "in" `expression_list` ":" `suite` |
| 158 | : ["else" ":" `suite`] |
| 159 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 160 | The expression list is evaluated once; it should yield an iterable object. An |
| 161 | iterator is created for the result of the ``expression_list``. The suite is |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 162 | then executed once for each item provided by the iterator, in the order returned |
| 163 | by the iterator. Each item in turn is assigned to the target list using the |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 164 | standard rules for assignments (see :ref:`assignment`), and then the suite is |
| 165 | executed. When the items are exhausted (which is immediately when the sequence |
| 166 | is empty or an iterator raises a :exc:`StopIteration` exception), the suite in |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 167 | the :keyword:`else` clause, if present, is executed, and the loop terminates. |
| 168 | |
| 169 | .. index:: |
| 170 | statement: break |
| 171 | statement: continue |
| 172 | |
| 173 | A :keyword:`break` statement executed in the first suite terminates the loop |
| 174 | without executing the :keyword:`else` clause's suite. A :keyword:`continue` |
| 175 | statement executed in the first suite skips the rest of the suite and continues |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 176 | with the next item, or with the :keyword:`else` clause if there is no next |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 177 | item. |
| 178 | |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 179 | The for-loop makes assignments to the variables(s) in the target list. |
| 180 | This overwrites all previous assignments to those variables including |
| 181 | those made in the suite of the for-loop:: |
| 182 | |
| 183 | for i in range(10): |
| 184 | print(i) |
| 185 | i = 5 # this will not affect the for-loop |
Zachary Ware | 2f78b84 | 2014-06-03 09:32:40 -0500 | [diff] [blame] | 186 | # because i will be overwritten with the next |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 187 | # index in the range |
| 188 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 189 | |
| 190 | .. index:: |
| 191 | builtin: range |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 192 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 193 | Names in the target list are not deleted when the loop is finished, but if the |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 194 | sequence is empty, they will not have been assigned to at all by the loop. Hint: |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 195 | the built-in function :func:`range` returns an iterator of integers suitable to |
Benjamin Peterson | 3db5e7b | 2009-06-03 03:13:30 +0000 | [diff] [blame] | 196 | emulate the effect of Pascal's ``for i := a to b do``; e.g., ``list(range(3))`` |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 197 | returns the list ``[0, 1, 2]``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 198 | |
Georg Brandl | e720c0a | 2009-04-27 16:20:50 +0000 | [diff] [blame] | 199 | .. note:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 200 | |
| 201 | .. index:: |
| 202 | single: loop; over mutable sequence |
| 203 | single: mutable sequence; loop over |
| 204 | |
| 205 | There is a subtlety when the sequence is being modified by the loop (this can |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 206 | only occur for mutable sequences, i.e. lists). An internal counter is used |
| 207 | to keep track of which item is used next, and this is incremented on each |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 208 | iteration. When this counter has reached the length of the sequence the loop |
| 209 | terminates. This means that if the suite deletes the current (or a previous) |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 210 | item from the sequence, the next item will be skipped (since it gets the |
| 211 | index of the current item which has already been treated). Likewise, if the |
| 212 | suite inserts an item in the sequence before the current item, the current |
| 213 | item will be treated again the next time through the loop. This can lead to |
| 214 | nasty bugs that can be avoided by making a temporary copy using a slice of |
| 215 | the whole sequence, e.g., :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 216 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 217 | for x in a[:]: |
| 218 | if x < 0: a.remove(x) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 219 | |
| 220 | |
| 221 | .. _try: |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 222 | .. _except: |
| 223 | .. _finally: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 224 | |
| 225 | The :keyword:`try` statement |
| 226 | ============================ |
| 227 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 228 | .. index:: |
| 229 | statement: try |
| 230 | keyword: except |
| 231 | keyword: finally |
Georg Brandl | 1617457 | 2007-09-01 12:38:06 +0000 | [diff] [blame] | 232 | .. index:: keyword: except |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 233 | |
| 234 | The :keyword:`try` statement specifies exception handlers and/or cleanup code |
| 235 | for a group of statements: |
| 236 | |
| 237 | .. productionlist:: |
| 238 | try_stmt: try1_stmt | try2_stmt |
| 239 | try1_stmt: "try" ":" `suite` |
Terry Jan Reedy | 65e3ecb | 2014-08-23 19:29:47 -0400 | [diff] [blame] | 240 | : ("except" [`expression` ["as" `identifier`]] ":" `suite`)+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 241 | : ["else" ":" `suite`] |
| 242 | : ["finally" ":" `suite`] |
| 243 | try2_stmt: "try" ":" `suite` |
| 244 | : "finally" ":" `suite` |
| 245 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 246 | |
| 247 | The :keyword:`except` clause(s) specify one or more exception handlers. When no |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 248 | exception occurs in the :keyword:`try` clause, no exception handler is executed. |
| 249 | When an exception occurs in the :keyword:`try` suite, a search for an exception |
| 250 | handler is started. This search inspects the except clauses in turn until one |
| 251 | is found that matches the exception. An expression-less except clause, if |
| 252 | present, must be last; it matches any exception. For an except clause with an |
| 253 | expression, that expression is evaluated, and the clause matches the exception |
| 254 | if the resulting object is "compatible" with the exception. An object is |
| 255 | compatible with an exception if it is the class or a base class of the exception |
| 256 | object or a tuple containing an item compatible with the exception. |
| 257 | |
| 258 | If no except clause matches the exception, the search for an exception handler |
| 259 | continues in the surrounding code and on the invocation stack. [#]_ |
| 260 | |
| 261 | If the evaluation of an expression in the header of an except clause raises an |
| 262 | exception, the original search for a handler is canceled and a search starts for |
| 263 | the new exception in the surrounding code and on the call stack (it is treated |
| 264 | as if the entire :keyword:`try` statement raised the exception). |
| 265 | |
| 266 | When a matching except clause is found, the exception is assigned to the target |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 267 | specified after the :keyword:`as` keyword in that except clause, if present, and |
| 268 | the except clause's suite is executed. All except clauses must have an |
| 269 | executable block. When the end of this block is reached, execution continues |
| 270 | normally after the entire try statement. (This means that if two nested |
| 271 | handlers exist for the same exception, and the exception occurs in the try |
| 272 | clause of the inner handler, the outer handler will not handle the exception.) |
| 273 | |
| 274 | When an exception has been assigned using ``as target``, it is cleared at the |
| 275 | end of the except clause. This is as if :: |
| 276 | |
| 277 | except E as N: |
| 278 | foo |
| 279 | |
| 280 | was translated to :: |
| 281 | |
| 282 | except E as N: |
| 283 | try: |
| 284 | foo |
| 285 | finally: |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 286 | del N |
| 287 | |
Benjamin Peterson | fb288da | 2010-06-29 01:27:35 +0000 | [diff] [blame] | 288 | This means the exception must be assigned to a different name to be able to |
| 289 | refer to it after the except clause. Exceptions are cleared because with the |
| 290 | traceback attached to them, they form a reference cycle with the stack frame, |
| 291 | keeping all locals in that frame alive until the next garbage collection occurs. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 292 | |
| 293 | .. index:: |
| 294 | module: sys |
| 295 | object: traceback |
| 296 | |
| 297 | Before an except clause's suite is executed, details about the exception are |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 298 | stored in the :mod:`sys` module and can be accessed via :func:`sys.exc_info`. |
Georg Brandl | b30f330 | 2011-01-06 09:23:56 +0000 | [diff] [blame] | 299 | :func:`sys.exc_info` returns a 3-tuple consisting of the exception class, the |
| 300 | exception instance and a traceback object (see section :ref:`types`) identifying |
| 301 | the point in the program where the exception occurred. :func:`sys.exc_info` |
| 302 | values are restored to their previous values (before the call) when returning |
| 303 | from a function that handled an exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 304 | |
| 305 | .. index:: |
| 306 | keyword: else |
| 307 | statement: return |
| 308 | statement: break |
| 309 | statement: continue |
| 310 | |
| 311 | The optional :keyword:`else` clause is executed if and when control flows off |
| 312 | the end of the :keyword:`try` clause. [#]_ Exceptions in the :keyword:`else` |
| 313 | clause are not handled by the preceding :keyword:`except` clauses. |
| 314 | |
| 315 | .. index:: keyword: finally |
| 316 | |
| 317 | If :keyword:`finally` is present, it specifies a 'cleanup' handler. The |
| 318 | :keyword:`try` clause is executed, including any :keyword:`except` and |
| 319 | :keyword:`else` clauses. If an exception occurs in any of the clauses and is |
| 320 | not handled, the exception is temporarily saved. The :keyword:`finally` clause |
Mark Dickinson | 05ee581 | 2012-09-24 20:16:38 +0100 | [diff] [blame] | 321 | is executed. If there is a saved exception it is re-raised at the end of the |
| 322 | :keyword:`finally` clause. If the :keyword:`finally` clause raises another |
| 323 | exception, the saved exception is set as the context of the new exception. |
| 324 | If the :keyword:`finally` clause executes a :keyword:`return` or :keyword:`break` |
| 325 | statement, the saved exception is discarded:: |
Andrew Svetlov | f158d86 | 2012-08-14 15:38:15 +0300 | [diff] [blame] | 326 | |
Zachary Ware | 9fafc9f | 2014-05-06 09:18:17 -0500 | [diff] [blame] | 327 | >>> def f(): |
| 328 | ... try: |
| 329 | ... 1/0 |
| 330 | ... finally: |
| 331 | ... return 42 |
| 332 | ... |
| 333 | >>> f() |
| 334 | 42 |
Andrew Svetlov | f158d86 | 2012-08-14 15:38:15 +0300 | [diff] [blame] | 335 | |
| 336 | The exception information is not available to the program during execution of |
| 337 | the :keyword:`finally` clause. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 338 | |
| 339 | .. index:: |
| 340 | statement: return |
| 341 | statement: break |
| 342 | statement: continue |
| 343 | |
| 344 | When a :keyword:`return`, :keyword:`break` or :keyword:`continue` statement is |
| 345 | executed in the :keyword:`try` suite of a :keyword:`try`...\ :keyword:`finally` |
| 346 | statement, the :keyword:`finally` clause is also executed 'on the way out.' A |
| 347 | :keyword:`continue` statement is illegal in the :keyword:`finally` clause. (The |
| 348 | reason is a problem with the current implementation --- this restriction may be |
| 349 | lifted in the future). |
| 350 | |
Zachary Ware | 8edd532 | 2014-05-06 09:07:13 -0500 | [diff] [blame] | 351 | The return value of a function is determined by the last :keyword:`return` |
| 352 | statement executed. Since the :keyword:`finally` clause always executes, a |
| 353 | :keyword:`return` statement executed in the :keyword:`finally` clause will |
| 354 | always be the last one executed:: |
| 355 | |
| 356 | >>> def foo(): |
| 357 | ... try: |
| 358 | ... return 'try' |
| 359 | ... finally: |
| 360 | ... return 'finally' |
| 361 | ... |
| 362 | >>> foo() |
| 363 | 'finally' |
| 364 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 365 | Additional information on exceptions can be found in section :ref:`exceptions`, |
| 366 | and information on using the :keyword:`raise` statement to generate exceptions |
| 367 | may be found in section :ref:`raise`. |
| 368 | |
| 369 | |
| 370 | .. _with: |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 371 | .. _as: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 372 | |
| 373 | The :keyword:`with` statement |
| 374 | ============================= |
| 375 | |
Terry Jan Reedy | 7c895ed | 2014-04-29 00:58:56 -0400 | [diff] [blame] | 376 | .. index:: |
| 377 | statement: with |
| 378 | single: as; with statement |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 379 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 380 | The :keyword:`with` statement is used to wrap the execution of a block with |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 381 | methods defined by a context manager (see section :ref:`context-managers`). |
| 382 | This allows common :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` |
| 383 | usage patterns to be encapsulated for convenient reuse. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 384 | |
| 385 | .. productionlist:: |
Georg Brandl | 0c31562 | 2009-05-25 21:10:36 +0000 | [diff] [blame] | 386 | with_stmt: "with" with_item ("," with_item)* ":" `suite` |
| 387 | with_item: `expression` ["as" `target`] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 388 | |
Georg Brandl | 0c31562 | 2009-05-25 21:10:36 +0000 | [diff] [blame] | 389 | The execution of the :keyword:`with` statement with one "item" proceeds as follows: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 390 | |
Georg Brandl | 3387f48 | 2010-09-03 22:40:02 +0000 | [diff] [blame] | 391 | #. The context expression (the expression given in the :token:`with_item`) is |
| 392 | evaluated to obtain a context manager. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 393 | |
Benjamin Peterson | 876b2f2 | 2009-06-28 03:18:59 +0000 | [diff] [blame] | 394 | #. The context manager's :meth:`__exit__` is loaded for later use. |
| 395 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 396 | #. The context manager's :meth:`__enter__` method is invoked. |
| 397 | |
| 398 | #. If a target was included in the :keyword:`with` statement, the return value |
| 399 | from :meth:`__enter__` is assigned to it. |
| 400 | |
| 401 | .. note:: |
| 402 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 403 | The :keyword:`with` statement guarantees that if the :meth:`__enter__` |
| 404 | method returns without an error, then :meth:`__exit__` will always be |
Benjamin Peterson | 876b2f2 | 2009-06-28 03:18:59 +0000 | [diff] [blame] | 405 | called. Thus, if an error occurs during the assignment to the target list, |
| 406 | it will be treated the same as an error occurring within the suite would |
| 407 | be. See step 6 below. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 408 | |
| 409 | #. The suite is executed. |
| 410 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 411 | #. The context manager's :meth:`__exit__` method is invoked. If an exception |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 412 | caused the suite to be exited, its type, value, and traceback are passed as |
| 413 | arguments to :meth:`__exit__`. Otherwise, three :const:`None` arguments are |
| 414 | supplied. |
| 415 | |
| 416 | If the suite was exited due to an exception, and the return value from the |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 417 | :meth:`__exit__` method was false, the exception is reraised. If the return |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 418 | value was true, the exception is suppressed, and execution continues with the |
| 419 | statement following the :keyword:`with` statement. |
| 420 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 421 | If the suite was exited for any reason other than an exception, the return |
| 422 | value from :meth:`__exit__` is ignored, and execution proceeds at the normal |
| 423 | location for the kind of exit that was taken. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 424 | |
Georg Brandl | 0c31562 | 2009-05-25 21:10:36 +0000 | [diff] [blame] | 425 | With more than one item, the context managers are processed as if multiple |
| 426 | :keyword:`with` statements were nested:: |
| 427 | |
| 428 | with A() as a, B() as b: |
| 429 | suite |
| 430 | |
| 431 | is equivalent to :: |
| 432 | |
| 433 | with A() as a: |
| 434 | with B() as b: |
| 435 | suite |
| 436 | |
| 437 | .. versionchanged:: 3.1 |
| 438 | Support for multiple context expressions. |
| 439 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 440 | .. seealso:: |
| 441 | |
Serhiy Storchaka | e4ba872 | 2016-03-31 15:30:54 +0300 | [diff] [blame] | 442 | :pep:`343` - The "with" statement |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 443 | The specification, background, and examples for the Python :keyword:`with` |
| 444 | statement. |
| 445 | |
| 446 | |
Chris Jerdonek | b430994 | 2012-12-25 14:54:44 -0800 | [diff] [blame] | 447 | .. index:: |
| 448 | single: parameter; function definition |
| 449 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 450 | .. _function: |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 451 | .. _def: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 452 | |
| 453 | Function definitions |
| 454 | ==================== |
| 455 | |
| 456 | .. index:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 457 | statement: def |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 458 | pair: function; definition |
| 459 | pair: function; name |
| 460 | pair: name; binding |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 461 | object: user-defined function |
| 462 | object: function |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 463 | pair: function; name |
| 464 | pair: name; binding |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 465 | |
| 466 | A function definition defines a user-defined function object (see section |
| 467 | :ref:`types`): |
| 468 | |
| 469 | .. productionlist:: |
Georg Brandl | 33d1ae8 | 2008-09-21 07:40:25 +0000 | [diff] [blame] | 470 | funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ["->" `expression`] ":" `suite` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 471 | decorators: `decorator`+ |
Benjamin Peterson | bc7ee43 | 2016-05-16 23:18:33 -0700 | [diff] [blame] | 472 | decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 473 | dotted_name: `identifier` ("." `identifier`)* |
| 474 | parameter_list: (`defparameter` ",")* |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 475 | : | "*" [`parameter`] ("," `defparameter`)* ["," "**" `parameter`] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 476 | : | "**" `parameter` |
| 477 | : | `defparameter` [","] ) |
| 478 | parameter: `identifier` [":" `expression`] |
| 479 | defparameter: `parameter` ["=" `expression`] |
| 480 | funcname: `identifier` |
| 481 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 482 | |
| 483 | A function definition is an executable statement. Its execution binds the |
| 484 | function name in the current local namespace to a function object (a wrapper |
| 485 | around the executable code for the function). This function object contains a |
| 486 | reference to the current global namespace as the global namespace to be used |
| 487 | when the function is called. |
| 488 | |
| 489 | The function definition does not execute the function body; this gets executed |
Georg Brandl | 3dbca81 | 2008-07-23 16:10:53 +0000 | [diff] [blame] | 490 | only when the function is called. [#]_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 491 | |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 492 | .. index:: |
| 493 | statement: @ |
| 494 | |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 495 | A function definition may be wrapped by one or more :term:`decorator` expressions. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 496 | Decorator expressions are evaluated when the function is defined, in the scope |
| 497 | that contains the function definition. The result must be a callable, which is |
| 498 | invoked with the function object as the only argument. The returned value is |
| 499 | bound to the function name instead of the function object. Multiple decorators |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 500 | are applied in nested fashion. For example, the following code :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 501 | |
| 502 | @f1(arg) |
| 503 | @f2 |
| 504 | def func(): pass |
| 505 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 506 | is equivalent to :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 507 | |
| 508 | def func(): pass |
| 509 | func = f1(arg)(f2(func)) |
| 510 | |
Chris Jerdonek | b430994 | 2012-12-25 14:54:44 -0800 | [diff] [blame] | 511 | .. index:: |
| 512 | triple: default; parameter; value |
| 513 | single: argument; function definition |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 514 | |
Chris Jerdonek | b430994 | 2012-12-25 14:54:44 -0800 | [diff] [blame] | 515 | When one or more :term:`parameters <parameter>` have the form *parameter* ``=`` |
| 516 | *expression*, the function is said to have "default parameter values." For a |
| 517 | parameter with a default value, the corresponding :term:`argument` may be |
| 518 | omitted from a call, in which |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 519 | case the parameter's default value is substituted. If a parameter has a default |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 520 | value, all following parameters up until the "``*``" must also have a default |
| 521 | value --- this is a syntactic restriction that is not expressed by the grammar. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 522 | |
Benjamin Peterson | 1ef876c | 2013-02-10 09:29:59 -0500 | [diff] [blame] | 523 | **Default parameter values are evaluated from left to right when the function |
| 524 | definition is executed.** This means that the expression is evaluated once, when |
| 525 | the function is defined, and that the same "pre-computed" value is used for each |
| 526 | call. This is especially important to understand when a default parameter is a |
| 527 | mutable object, such as a list or a dictionary: if the function modifies the |
| 528 | object (e.g. by appending an item to a list), the default value is in effect |
| 529 | modified. This is generally not what was intended. A way around this is to use |
| 530 | ``None`` as the default, and explicitly test for it in the body of the function, |
| 531 | e.g.:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 532 | |
| 533 | def whats_on_the_telly(penguin=None): |
| 534 | if penguin is None: |
| 535 | penguin = [] |
| 536 | penguin.append("property of the zoo") |
| 537 | return penguin |
| 538 | |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 539 | .. index:: |
| 540 | statement: * |
| 541 | statement: ** |
| 542 | |
| 543 | Function call semantics are described in more detail in section :ref:`calls`. A |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 544 | function call always assigns values to all parameters mentioned in the parameter |
| 545 | list, either from position arguments, from keyword arguments, or from default |
| 546 | values. If the form "``*identifier``" is present, it is initialized to a tuple |
| 547 | receiving any excess positional parameters, defaulting to the empty tuple. If |
| 548 | the form "``**identifier``" is present, it is initialized to a new dictionary |
| 549 | receiving any excess keyword arguments, defaulting to a new empty dictionary. |
| 550 | Parameters after "``*``" or "``*identifier``" are keyword-only parameters and |
| 551 | may only be passed used keyword arguments. |
| 552 | |
| 553 | .. index:: pair: function; annotations |
| 554 | |
| 555 | Parameters may have annotations of the form "``: expression``" following the |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 556 | parameter name. Any parameter may have an annotation even those of the form |
| 557 | ``*identifier`` or ``**identifier``. Functions may have "return" annotation of |
| 558 | the form "``-> expression``" after the parameter list. These annotations can be |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 559 | any valid Python expression and are evaluated when the function definition is |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 560 | executed. Annotations may be evaluated in a different order than they appear in |
| 561 | the source code. The presence of annotations does not change the semantics of a |
| 562 | function. The annotation values are available as values of a dictionary keyed |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 563 | by the parameters' names in the :attr:`__annotations__` attribute of the |
| 564 | function object. |
| 565 | |
Georg Brandl | 242e6a0 | 2013-10-06 10:28:39 +0200 | [diff] [blame] | 566 | .. index:: pair: lambda; expression |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 567 | |
| 568 | It is also possible to create anonymous functions (functions not bound to a |
Georg Brandl | 242e6a0 | 2013-10-06 10:28:39 +0200 | [diff] [blame] | 569 | name), for immediate use in expressions. This uses lambda expressions, described in |
| 570 | section :ref:`lambda`. Note that the lambda expression is merely a shorthand for a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 571 | simplified function definition; a function defined in a ":keyword:`def`" |
| 572 | statement can be passed around or assigned to another name just like a function |
Georg Brandl | 242e6a0 | 2013-10-06 10:28:39 +0200 | [diff] [blame] | 573 | defined by a lambda expression. The ":keyword:`def`" form is actually more powerful |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 574 | since it allows the execution of multiple statements and annotations. |
| 575 | |
Georg Brandl | 242e6a0 | 2013-10-06 10:28:39 +0200 | [diff] [blame] | 576 | **Programmer's note:** Functions are first-class objects. A "``def``" statement |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 577 | executed inside a function definition defines a local function that can be |
| 578 | returned or passed around. Free variables used in the nested function can |
| 579 | access the local variables of the function containing the def. See section |
| 580 | :ref:`naming` for details. |
| 581 | |
Georg Brandl | 64a4094 | 2012-03-10 09:22:47 +0100 | [diff] [blame] | 582 | .. seealso:: |
| 583 | |
| 584 | :pep:`3107` - Function Annotations |
| 585 | The original specification for function annotations. |
| 586 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 587 | |
| 588 | .. _class: |
| 589 | |
| 590 | Class definitions |
| 591 | ================= |
| 592 | |
| 593 | .. index:: |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 594 | object: class |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 595 | statement: class |
| 596 | pair: class; definition |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 597 | pair: class; name |
| 598 | pair: name; binding |
| 599 | pair: execution; frame |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 600 | single: inheritance |
Georg Brandl | 3dbca81 | 2008-07-23 16:10:53 +0000 | [diff] [blame] | 601 | single: docstring |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 602 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 603 | A class definition defines a class object (see section :ref:`types`): |
| 604 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 605 | .. productionlist:: |
| 606 | classdef: [`decorators`] "class" `classname` [`inheritance`] ":" `suite` |
Benjamin Peterson | 54044d6 | 2016-05-16 23:20:22 -0700 | [diff] [blame] | 607 | inheritance: "(" [`argument_list`] ")" |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 608 | classname: `identifier` |
| 609 | |
Georg Brandl | 65e5f80 | 2010-08-02 18:10:13 +0000 | [diff] [blame] | 610 | A class definition is an executable statement. The inheritance list usually |
| 611 | gives a list of base classes (see :ref:`metaclasses` for more advanced uses), so |
| 612 | each item in the list should evaluate to a class object which allows |
Éric Araujo | 28053fb | 2010-11-22 03:09:19 +0000 | [diff] [blame] | 613 | subclassing. Classes without an inheritance list inherit, by default, from the |
| 614 | base class :class:`object`; hence, :: |
| 615 | |
| 616 | class Foo: |
| 617 | pass |
| 618 | |
| 619 | is equivalent to :: |
| 620 | |
| 621 | class Foo(object): |
| 622 | pass |
Georg Brandl | 65e5f80 | 2010-08-02 18:10:13 +0000 | [diff] [blame] | 623 | |
| 624 | The class's suite is then executed in a new execution frame (see :ref:`naming`), |
| 625 | using a newly created local namespace and the original global namespace. |
| 626 | (Usually, the suite contains mostly function definitions.) When the class's |
| 627 | suite finishes execution, its execution frame is discarded but its local |
| 628 | namespace is saved. [#]_ A class object is then created using the inheritance |
| 629 | list for the base classes and the saved local namespace for the attribute |
| 630 | dictionary. The class name is bound to this class object in the original local |
| 631 | namespace. |
| 632 | |
| 633 | Class creation can be customized heavily using :ref:`metaclasses <metaclasses>`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 634 | |
Georg Brandl | f414272 | 2010-10-17 10:38:20 +0000 | [diff] [blame] | 635 | Classes can also be decorated: just like when decorating functions, :: |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 636 | |
| 637 | @f1(arg) |
| 638 | @f2 |
| 639 | class Foo: pass |
| 640 | |
| 641 | is equivalent to :: |
| 642 | |
| 643 | class Foo: pass |
| 644 | Foo = f1(arg)(f2(Foo)) |
| 645 | |
Georg Brandl | f414272 | 2010-10-17 10:38:20 +0000 | [diff] [blame] | 646 | The evaluation rules for the decorator expressions are the same as for function |
| 647 | decorators. The result must be a class object, which is then bound to the class |
| 648 | name. |
| 649 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 650 | **Programmer's note:** Variables defined in the class definition are class |
Georg Brandl | 65e5f80 | 2010-08-02 18:10:13 +0000 | [diff] [blame] | 651 | attributes; they are shared by instances. Instance attributes can be set in a |
| 652 | method with ``self.name = value``. Both class and instance attributes are |
| 653 | accessible through the notation "``self.name``", and an instance attribute hides |
| 654 | a class attribute with the same name when accessed in this way. Class |
| 655 | attributes can be used as defaults for instance attributes, but using mutable |
| 656 | values there can lead to unexpected results. :ref:`Descriptors <descriptors>` |
| 657 | can be used to create instance variables with different implementation details. |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 658 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 659 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 660 | .. seealso:: |
| 661 | |
Ezio Melotti | 7885833 | 2011-03-11 20:50:42 +0200 | [diff] [blame] | 662 | :pep:`3115` - Metaclasses in Python 3 |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 663 | :pep:`3129` - Class Decorators |
| 664 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 665 | |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 666 | Coroutines |
| 667 | ========== |
| 668 | |
Yury Selivanov | 5376ba9 | 2015-06-22 12:19:30 -0400 | [diff] [blame] | 669 | .. versionadded:: 3.5 |
| 670 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 671 | .. index:: statement: async def |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 672 | .. _`async def`: |
| 673 | |
| 674 | Coroutine function definition |
| 675 | ----------------------------- |
| 676 | |
| 677 | .. productionlist:: |
Yury Selivanov | 75b5ab5 | 2015-08-01 16:19:36 -0400 | [diff] [blame] | 678 | async_funcdef: [`decorators`] "async" "def" `funcname` "(" [`parameter_list`] ")" ["->" `expression`] ":" `suite` |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 679 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 680 | .. index:: |
| 681 | keyword: async |
| 682 | keyword: await |
| 683 | |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 684 | Execution of Python coroutines can be suspended and resumed at many points |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 685 | (see :term:`coroutine`). In the body of a coroutine, any ``await`` and |
| 686 | ``async`` identifiers become reserved keywords; :keyword:`await` expressions, |
| 687 | :keyword:`async for` and :keyword:`async with` can only be used in |
Yury Selivanov | 8fb307c | 2015-07-22 13:33:45 +0300 | [diff] [blame] | 688 | coroutine bodies. |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 689 | |
| 690 | Functions defined with ``async def`` syntax are always coroutine functions, |
| 691 | even if they do not contain ``await`` or ``async`` keywords. |
| 692 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 693 | It is a :exc:`SyntaxError` to use :keyword:`yield` expressions in |
| 694 | ``async def`` coroutines. |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 695 | |
Yury Selivanov | 5376ba9 | 2015-06-22 12:19:30 -0400 | [diff] [blame] | 696 | An example of a coroutine function:: |
| 697 | |
| 698 | async def func(param1, param2): |
| 699 | do_stuff() |
| 700 | await some_coroutine() |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 701 | |
| 702 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 703 | .. index:: statement: async for |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 704 | .. _`async for`: |
| 705 | |
| 706 | The :keyword:`async for` statement |
| 707 | ---------------------------------- |
| 708 | |
| 709 | .. productionlist:: |
| 710 | async_for_stmt: "async" `for_stmt` |
| 711 | |
| 712 | An :term:`asynchronous iterable` is able to call asynchronous code in its |
| 713 | *iter* implementation, and :term:`asynchronous iterator` can call asynchronous |
| 714 | code in its *next* method. |
| 715 | |
| 716 | The ``async for`` statement allows convenient iteration over asynchronous |
| 717 | iterators. |
| 718 | |
| 719 | The following code:: |
| 720 | |
| 721 | async for TARGET in ITER: |
| 722 | BLOCK |
| 723 | else: |
| 724 | BLOCK2 |
| 725 | |
| 726 | Is semantically equivalent to:: |
| 727 | |
| 728 | iter = (ITER) |
| 729 | iter = await type(iter).__aiter__(iter) |
| 730 | running = True |
| 731 | while running: |
| 732 | try: |
| 733 | TARGET = await type(iter).__anext__(iter) |
| 734 | except StopAsyncIteration: |
| 735 | running = False |
| 736 | else: |
| 737 | BLOCK |
| 738 | else: |
| 739 | BLOCK2 |
| 740 | |
| 741 | See also :meth:`__aiter__` and :meth:`__anext__` for details. |
| 742 | |
Yury Selivanov | 5376ba9 | 2015-06-22 12:19:30 -0400 | [diff] [blame] | 743 | It is a :exc:`SyntaxError` to use ``async for`` statement outside of an |
| 744 | :keyword:`async def` function. |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 745 | |
| 746 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 747 | .. index:: statement: async with |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 748 | .. _`async with`: |
| 749 | |
| 750 | The :keyword:`async with` statement |
| 751 | ----------------------------------- |
| 752 | |
| 753 | .. productionlist:: |
| 754 | async_with_stmt: "async" `with_stmt` |
| 755 | |
| 756 | An :term:`asynchronous context manager` is a :term:`context manager` that is |
| 757 | able to suspend execution in its *enter* and *exit* methods. |
| 758 | |
| 759 | The following code:: |
| 760 | |
| 761 | async with EXPR as VAR: |
| 762 | BLOCK |
| 763 | |
| 764 | Is semantically equivalent to:: |
| 765 | |
| 766 | mgr = (EXPR) |
| 767 | aexit = type(mgr).__aexit__ |
| 768 | aenter = type(mgr).__aenter__(mgr) |
| 769 | exc = True |
| 770 | |
| 771 | VAR = await aenter |
| 772 | try: |
| 773 | BLOCK |
| 774 | except: |
| 775 | if not await aexit(mgr, *sys.exc_info()): |
| 776 | raise |
| 777 | else: |
| 778 | await aexit(mgr, None, None, None) |
| 779 | |
| 780 | See also :meth:`__aenter__` and :meth:`__aexit__` for details. |
| 781 | |
Yury Selivanov | 5376ba9 | 2015-06-22 12:19:30 -0400 | [diff] [blame] | 782 | It is a :exc:`SyntaxError` to use ``async with`` statement outside of an |
| 783 | :keyword:`async def` function. |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 784 | |
| 785 | .. seealso:: |
| 786 | |
| 787 | :pep:`492` - Coroutines with async and await syntax |
| 788 | |
| 789 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 790 | .. rubric:: Footnotes |
| 791 | |
Ezio Melotti | fc3db8a | 2011-06-26 11:25:28 +0300 | [diff] [blame] | 792 | .. [#] The exception is propagated to the invocation stack unless |
| 793 | there is a :keyword:`finally` clause which happens to raise another |
| 794 | exception. That new exception causes the old one to be lost. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 795 | |
Georg Brandl | f43713f | 2009-10-22 16:08:10 +0000 | [diff] [blame] | 796 | .. [#] Currently, control "flows off the end" except in the case of an exception |
| 797 | or the execution of a :keyword:`return`, :keyword:`continue`, or |
| 798 | :keyword:`break` statement. |
Georg Brandl | 3dbca81 | 2008-07-23 16:10:53 +0000 | [diff] [blame] | 799 | |
| 800 | .. [#] A string literal appearing as the first statement in the function body is |
| 801 | transformed into the function's ``__doc__`` attribute and therefore the |
| 802 | function's :term:`docstring`. |
| 803 | |
| 804 | .. [#] A string literal appearing as the first statement in the class body is |
| 805 | transformed into the namespace's ``__doc__`` item and therefore the class's |
| 806 | :term:`docstring`. |