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 | |
| 25 | Compound statements consist of one or more 'clauses.' A clause consists of a |
| 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 |
| 32 | form of suite can contain nested compound statements; the following is illegal, |
| 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` |
| 54 | suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT |
| 55 | statement: `stmt_list` NEWLINE | `compound_stmt` |
| 56 | stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"] |
| 57 | |
| 58 | .. index:: |
| 59 | single: NEWLINE token |
| 60 | single: DEDENT token |
| 61 | pair: dangling; else |
| 62 | |
| 63 | Note that statements always end in a ``NEWLINE`` possibly followed by a |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 64 | ``DEDENT``. Also note that optional continuation clauses always begin with a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | keyword that cannot start a statement, thus there are no ambiguities (the |
| 66 | 'dangling :keyword:`else`' problem is solved in Python by requiring nested |
| 67 | :keyword:`if` statements to be indented). |
| 68 | |
| 69 | The formatting of the grammar rules in the following sections places each clause |
| 70 | on a separate line for clarity. |
| 71 | |
| 72 | |
| 73 | .. _if: |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 74 | .. _elif: |
| 75 | .. _else: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 76 | |
| 77 | The :keyword:`if` statement |
| 78 | =========================== |
| 79 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 80 | .. index:: |
| 81 | statement: if |
| 82 | keyword: elif |
| 83 | keyword: else |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 84 | keyword: elif |
| 85 | keyword: else |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 86 | |
| 87 | The :keyword:`if` statement is used for conditional execution: |
| 88 | |
| 89 | .. productionlist:: |
| 90 | if_stmt: "if" `expression` ":" `suite` |
| 91 | : ( "elif" `expression` ":" `suite` )* |
| 92 | : ["else" ":" `suite`] |
| 93 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 94 | It selects exactly one of the suites by evaluating the expressions one by one |
| 95 | until one is found to be true (see section :ref:`booleans` for the definition of |
| 96 | true and false); then that suite is executed (and no other part of the |
| 97 | :keyword:`if` statement is executed or evaluated). If all expressions are |
| 98 | false, the suite of the :keyword:`else` clause, if present, is executed. |
| 99 | |
| 100 | |
| 101 | .. _while: |
| 102 | |
| 103 | The :keyword:`while` statement |
| 104 | ============================== |
| 105 | |
| 106 | .. index:: |
| 107 | statement: while |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 108 | keyword: else |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 109 | pair: loop; statement |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 110 | keyword: else |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 111 | |
| 112 | The :keyword:`while` statement is used for repeated execution as long as an |
| 113 | expression is true: |
| 114 | |
| 115 | .. productionlist:: |
| 116 | while_stmt: "while" `expression` ":" `suite` |
| 117 | : ["else" ":" `suite`] |
| 118 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 119 | This repeatedly tests the expression and, if it is true, executes the first |
| 120 | suite; if the expression is false (which may be the first time it is tested) the |
| 121 | suite of the :keyword:`else` clause, if present, is executed and the loop |
| 122 | terminates. |
| 123 | |
| 124 | .. index:: |
| 125 | statement: break |
| 126 | statement: continue |
| 127 | |
| 128 | A :keyword:`break` statement executed in the first suite terminates the loop |
| 129 | without executing the :keyword:`else` clause's suite. A :keyword:`continue` |
| 130 | statement executed in the first suite skips the rest of the suite and goes back |
| 131 | to testing the expression. |
| 132 | |
| 133 | |
| 134 | .. _for: |
| 135 | |
| 136 | The :keyword:`for` statement |
| 137 | ============================ |
| 138 | |
| 139 | .. index:: |
| 140 | statement: for |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 141 | keyword: in |
| 142 | keyword: else |
| 143 | pair: target; list |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 144 | pair: loop; statement |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 145 | keyword: in |
| 146 | keyword: else |
| 147 | pair: target; list |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 148 | object: sequence |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 149 | |
| 150 | The :keyword:`for` statement is used to iterate over the elements of a sequence |
| 151 | (such as a string, tuple or list) or other iterable object: |
| 152 | |
| 153 | .. productionlist:: |
| 154 | for_stmt: "for" `target_list` "in" `expression_list` ":" `suite` |
| 155 | : ["else" ":" `suite`] |
| 156 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 157 | The expression list is evaluated once; it should yield an iterable object. An |
| 158 | iterator is created for the result of the ``expression_list``. The suite is |
| 159 | then executed once for each item provided by the iterator, in the order of |
| 160 | ascending indices. Each item in turn is assigned to the target list using the |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 161 | standard rules for assignments (see :ref:`assignment`), and then the suite is |
| 162 | executed. When the items are exhausted (which is immediately when the sequence |
| 163 | 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] | 164 | the :keyword:`else` clause, if present, is executed, and the loop terminates. |
| 165 | |
| 166 | .. index:: |
| 167 | statement: break |
| 168 | statement: continue |
| 169 | |
| 170 | A :keyword:`break` statement executed in the first suite terminates the loop |
| 171 | without executing the :keyword:`else` clause's suite. A :keyword:`continue` |
| 172 | statement executed in the first suite skips the rest of the suite and continues |
| 173 | with the next item, or with the :keyword:`else` clause if there was no next |
| 174 | item. |
| 175 | |
| 176 | The suite may assign to the variable(s) in the target list; this does not affect |
| 177 | the next item assigned to it. |
| 178 | |
| 179 | .. index:: |
| 180 | builtin: range |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 181 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 182 | Names in the target list are not deleted when the loop is finished, but if the |
| 183 | sequence is empty, it will not have been assigned to at all by the loop. Hint: |
| 184 | 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] | 185 | 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] | 186 | returns the list ``[0, 1, 2]``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 187 | |
Georg Brandl | e720c0a | 2009-04-27 16:20:50 +0000 | [diff] [blame] | 188 | .. note:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 189 | |
| 190 | .. index:: |
| 191 | single: loop; over mutable sequence |
| 192 | single: mutable sequence; loop over |
| 193 | |
| 194 | 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] | 195 | only occur for mutable sequences, i.e. lists). An internal counter is used |
| 196 | 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] | 197 | iteration. When this counter has reached the length of the sequence the loop |
| 198 | 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] | 199 | item from the sequence, the next item will be skipped (since it gets the |
| 200 | index of the current item which has already been treated). Likewise, if the |
| 201 | suite inserts an item in the sequence before the current item, the current |
| 202 | item will be treated again the next time through the loop. This can lead to |
| 203 | nasty bugs that can be avoided by making a temporary copy using a slice of |
| 204 | the whole sequence, e.g., :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 205 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 206 | for x in a[:]: |
| 207 | if x < 0: a.remove(x) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 208 | |
| 209 | |
| 210 | .. _try: |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 211 | .. _except: |
| 212 | .. _finally: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 213 | |
| 214 | The :keyword:`try` statement |
| 215 | ============================ |
| 216 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 217 | .. index:: |
| 218 | statement: try |
| 219 | keyword: except |
| 220 | keyword: finally |
Georg Brandl | 1617457 | 2007-09-01 12:38:06 +0000 | [diff] [blame] | 221 | .. index:: keyword: except |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 222 | |
| 223 | The :keyword:`try` statement specifies exception handlers and/or cleanup code |
| 224 | for a group of statements: |
| 225 | |
| 226 | .. productionlist:: |
| 227 | try_stmt: try1_stmt | try2_stmt |
| 228 | try1_stmt: "try" ":" `suite` |
Georg Brandl | 0068e2c | 2007-09-06 14:03:41 +0000 | [diff] [blame] | 229 | : ("except" [`expression` ["as" `target`]] ":" `suite`)+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 230 | : ["else" ":" `suite`] |
| 231 | : ["finally" ":" `suite`] |
| 232 | try2_stmt: "try" ":" `suite` |
| 233 | : "finally" ":" `suite` |
| 234 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 235 | |
| 236 | 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] | 237 | exception occurs in the :keyword:`try` clause, no exception handler is executed. |
| 238 | When an exception occurs in the :keyword:`try` suite, a search for an exception |
| 239 | handler is started. This search inspects the except clauses in turn until one |
| 240 | is found that matches the exception. An expression-less except clause, if |
| 241 | present, must be last; it matches any exception. For an except clause with an |
| 242 | expression, that expression is evaluated, and the clause matches the exception |
| 243 | if the resulting object is "compatible" with the exception. An object is |
| 244 | compatible with an exception if it is the class or a base class of the exception |
| 245 | object or a tuple containing an item compatible with the exception. |
| 246 | |
| 247 | If no except clause matches the exception, the search for an exception handler |
| 248 | continues in the surrounding code and on the invocation stack. [#]_ |
| 249 | |
| 250 | If the evaluation of an expression in the header of an except clause raises an |
| 251 | exception, the original search for a handler is canceled and a search starts for |
| 252 | the new exception in the surrounding code and on the call stack (it is treated |
| 253 | as if the entire :keyword:`try` statement raised the exception). |
| 254 | |
| 255 | 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] | 256 | specified after the :keyword:`as` keyword in that except clause, if present, and |
| 257 | the except clause's suite is executed. All except clauses must have an |
| 258 | executable block. When the end of this block is reached, execution continues |
| 259 | normally after the entire try statement. (This means that if two nested |
| 260 | handlers exist for the same exception, and the exception occurs in the try |
| 261 | clause of the inner handler, the outer handler will not handle the exception.) |
| 262 | |
| 263 | When an exception has been assigned using ``as target``, it is cleared at the |
| 264 | end of the except clause. This is as if :: |
| 265 | |
| 266 | except E as N: |
| 267 | foo |
| 268 | |
| 269 | was translated to :: |
| 270 | |
| 271 | except E as N: |
| 272 | try: |
| 273 | foo |
| 274 | finally: |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 275 | del N |
| 276 | |
Benjamin Peterson | fb288da | 2010-06-29 01:27:35 +0000 | [diff] [blame] | 277 | This means the exception must be assigned to a different name to be able to |
| 278 | refer to it after the except clause. Exceptions are cleared because with the |
| 279 | traceback attached to them, they form a reference cycle with the stack frame, |
| 280 | 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] | 281 | |
| 282 | .. index:: |
| 283 | module: sys |
| 284 | object: traceback |
| 285 | |
| 286 | Before an except clause's suite is executed, details about the exception are |
| 287 | stored in the :mod:`sys` module and can be access via :func:`sys.exc_info`. |
Georg Brandl | b30f330 | 2011-01-06 09:23:56 +0000 | [diff] [blame] | 288 | :func:`sys.exc_info` returns a 3-tuple consisting of the exception class, the |
| 289 | exception instance and a traceback object (see section :ref:`types`) identifying |
| 290 | the point in the program where the exception occurred. :func:`sys.exc_info` |
| 291 | values are restored to their previous values (before the call) when returning |
| 292 | from a function that handled an exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 293 | |
| 294 | .. index:: |
| 295 | keyword: else |
| 296 | statement: return |
| 297 | statement: break |
| 298 | statement: continue |
| 299 | |
| 300 | The optional :keyword:`else` clause is executed if and when control flows off |
| 301 | the end of the :keyword:`try` clause. [#]_ Exceptions in the :keyword:`else` |
| 302 | clause are not handled by the preceding :keyword:`except` clauses. |
| 303 | |
| 304 | .. index:: keyword: finally |
| 305 | |
| 306 | If :keyword:`finally` is present, it specifies a 'cleanup' handler. The |
| 307 | :keyword:`try` clause is executed, including any :keyword:`except` and |
| 308 | :keyword:`else` clauses. If an exception occurs in any of the clauses and is |
| 309 | not handled, the exception is temporarily saved. The :keyword:`finally` clause |
| 310 | is executed. If there is a saved exception, it is re-raised at the end of the |
| 311 | :keyword:`finally` clause. If the :keyword:`finally` clause raises another |
| 312 | exception or executes a :keyword:`return` or :keyword:`break` statement, the |
| 313 | saved exception is lost. The exception information is not available to the |
| 314 | program during execution of the :keyword:`finally` clause. |
| 315 | |
| 316 | .. index:: |
| 317 | statement: return |
| 318 | statement: break |
| 319 | statement: continue |
| 320 | |
| 321 | When a :keyword:`return`, :keyword:`break` or :keyword:`continue` statement is |
| 322 | executed in the :keyword:`try` suite of a :keyword:`try`...\ :keyword:`finally` |
| 323 | statement, the :keyword:`finally` clause is also executed 'on the way out.' A |
| 324 | :keyword:`continue` statement is illegal in the :keyword:`finally` clause. (The |
| 325 | reason is a problem with the current implementation --- this restriction may be |
| 326 | lifted in the future). |
| 327 | |
| 328 | Additional information on exceptions can be found in section :ref:`exceptions`, |
| 329 | and information on using the :keyword:`raise` statement to generate exceptions |
| 330 | may be found in section :ref:`raise`. |
| 331 | |
| 332 | |
| 333 | .. _with: |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 334 | .. _as: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 335 | |
| 336 | The :keyword:`with` statement |
| 337 | ============================= |
| 338 | |
| 339 | .. index:: statement: with |
| 340 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 341 | 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] | 342 | methods defined by a context manager (see section :ref:`context-managers`). |
| 343 | This allows common :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` |
| 344 | usage patterns to be encapsulated for convenient reuse. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 345 | |
| 346 | .. productionlist:: |
Georg Brandl | 0c31562 | 2009-05-25 21:10:36 +0000 | [diff] [blame] | 347 | with_stmt: "with" with_item ("," with_item)* ":" `suite` |
| 348 | with_item: `expression` ["as" `target`] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 349 | |
Georg Brandl | 0c31562 | 2009-05-25 21:10:36 +0000 | [diff] [blame] | 350 | 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] | 351 | |
Georg Brandl | 3387f48 | 2010-09-03 22:40:02 +0000 | [diff] [blame] | 352 | #. The context expression (the expression given in the :token:`with_item`) is |
| 353 | evaluated to obtain a context manager. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 354 | |
Benjamin Peterson | 876b2f2 | 2009-06-28 03:18:59 +0000 | [diff] [blame] | 355 | #. The context manager's :meth:`__exit__` is loaded for later use. |
| 356 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 357 | #. The context manager's :meth:`__enter__` method is invoked. |
| 358 | |
| 359 | #. If a target was included in the :keyword:`with` statement, the return value |
| 360 | from :meth:`__enter__` is assigned to it. |
| 361 | |
| 362 | .. note:: |
| 363 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 364 | The :keyword:`with` statement guarantees that if the :meth:`__enter__` |
| 365 | method returns without an error, then :meth:`__exit__` will always be |
Benjamin Peterson | 876b2f2 | 2009-06-28 03:18:59 +0000 | [diff] [blame] | 366 | called. Thus, if an error occurs during the assignment to the target list, |
| 367 | it will be treated the same as an error occurring within the suite would |
| 368 | be. See step 6 below. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 369 | |
| 370 | #. The suite is executed. |
| 371 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 372 | #. The context manager's :meth:`__exit__` method is invoked. If an exception |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 373 | caused the suite to be exited, its type, value, and traceback are passed as |
| 374 | arguments to :meth:`__exit__`. Otherwise, three :const:`None` arguments are |
| 375 | supplied. |
| 376 | |
| 377 | 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] | 378 | :meth:`__exit__` method was false, the exception is reraised. If the return |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 379 | value was true, the exception is suppressed, and execution continues with the |
| 380 | statement following the :keyword:`with` statement. |
| 381 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 382 | If the suite was exited for any reason other than an exception, the return |
| 383 | value from :meth:`__exit__` is ignored, and execution proceeds at the normal |
| 384 | location for the kind of exit that was taken. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 385 | |
Georg Brandl | 0c31562 | 2009-05-25 21:10:36 +0000 | [diff] [blame] | 386 | With more than one item, the context managers are processed as if multiple |
| 387 | :keyword:`with` statements were nested:: |
| 388 | |
| 389 | with A() as a, B() as b: |
| 390 | suite |
| 391 | |
| 392 | is equivalent to :: |
| 393 | |
| 394 | with A() as a: |
| 395 | with B() as b: |
| 396 | suite |
| 397 | |
| 398 | .. versionchanged:: 3.1 |
| 399 | Support for multiple context expressions. |
| 400 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 401 | .. seealso:: |
| 402 | |
| 403 | :pep:`0343` - The "with" statement |
| 404 | The specification, background, and examples for the Python :keyword:`with` |
| 405 | statement. |
| 406 | |
| 407 | |
| 408 | .. _function: |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 409 | .. _def: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 410 | |
| 411 | Function definitions |
| 412 | ==================== |
| 413 | |
| 414 | .. index:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 415 | statement: def |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 416 | pair: function; definition |
| 417 | pair: function; name |
| 418 | pair: name; binding |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 419 | object: user-defined function |
| 420 | object: function |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 421 | pair: function; name |
| 422 | pair: name; binding |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 423 | |
| 424 | A function definition defines a user-defined function object (see section |
| 425 | :ref:`types`): |
| 426 | |
| 427 | .. productionlist:: |
Georg Brandl | 33d1ae8 | 2008-09-21 07:40:25 +0000 | [diff] [blame] | 428 | funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ["->" `expression`] ":" `suite` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 429 | decorators: `decorator`+ |
| 430 | decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE |
| 431 | dotted_name: `identifier` ("." `identifier`)* |
| 432 | parameter_list: (`defparameter` ",")* |
| 433 | : ( "*" [`parameter`] ("," `defparameter`)* |
| 434 | : [, "**" `parameter`] |
| 435 | : | "**" `parameter` |
| 436 | : | `defparameter` [","] ) |
| 437 | parameter: `identifier` [":" `expression`] |
| 438 | defparameter: `parameter` ["=" `expression`] |
| 439 | funcname: `identifier` |
| 440 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 441 | |
| 442 | A function definition is an executable statement. Its execution binds the |
| 443 | function name in the current local namespace to a function object (a wrapper |
| 444 | around the executable code for the function). This function object contains a |
| 445 | reference to the current global namespace as the global namespace to be used |
| 446 | when the function is called. |
| 447 | |
| 448 | The function definition does not execute the function body; this gets executed |
Georg Brandl | 3dbca81 | 2008-07-23 16:10:53 +0000 | [diff] [blame] | 449 | only when the function is called. [#]_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 450 | |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 451 | .. index:: |
| 452 | statement: @ |
| 453 | |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 454 | 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] | 455 | Decorator expressions are evaluated when the function is defined, in the scope |
| 456 | that contains the function definition. The result must be a callable, which is |
| 457 | invoked with the function object as the only argument. The returned value is |
| 458 | bound to the function name instead of the function object. Multiple decorators |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 459 | are applied in nested fashion. For example, the following code :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 460 | |
| 461 | @f1(arg) |
| 462 | @f2 |
| 463 | def func(): pass |
| 464 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 465 | is equivalent to :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 466 | |
| 467 | def func(): pass |
| 468 | func = f1(arg)(f2(func)) |
| 469 | |
| 470 | .. index:: triple: default; parameter; value |
| 471 | |
| 472 | When one or more parameters have the form *parameter* ``=`` *expression*, the |
| 473 | function is said to have "default parameter values." For a parameter with a |
| 474 | default value, the corresponding argument may be omitted from a call, in which |
| 475 | 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] | 476 | value, all following parameters up until the "``*``" must also have a default |
| 477 | 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] | 478 | |
| 479 | **Default parameter values are evaluated when the function definition is |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 480 | executed.** This means that the expression is evaluated once, when the function |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 481 | is defined, and that that same "pre-computed" value is used for each call. This |
| 482 | is especially important to understand when a default parameter is a mutable |
| 483 | object, such as a list or a dictionary: if the function modifies the object |
| 484 | (e.g. by appending an item to a list), the default value is in effect modified. |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 485 | This is generally not what was intended. A way around this is to use ``None`` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 486 | as the default, and explicitly test for it in the body of the function, e.g.:: |
| 487 | |
| 488 | def whats_on_the_telly(penguin=None): |
| 489 | if penguin is None: |
| 490 | penguin = [] |
| 491 | penguin.append("property of the zoo") |
| 492 | return penguin |
| 493 | |
Christian Heimes | dae2a89 | 2008-04-19 00:55:37 +0000 | [diff] [blame] | 494 | .. index:: |
| 495 | statement: * |
| 496 | statement: ** |
| 497 | |
| 498 | 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] | 499 | function call always assigns values to all parameters mentioned in the parameter |
| 500 | list, either from position arguments, from keyword arguments, or from default |
| 501 | values. If the form "``*identifier``" is present, it is initialized to a tuple |
| 502 | receiving any excess positional parameters, defaulting to the empty tuple. If |
| 503 | the form "``**identifier``" is present, it is initialized to a new dictionary |
| 504 | receiving any excess keyword arguments, defaulting to a new empty dictionary. |
| 505 | Parameters after "``*``" or "``*identifier``" are keyword-only parameters and |
| 506 | may only be passed used keyword arguments. |
| 507 | |
| 508 | .. index:: pair: function; annotations |
| 509 | |
| 510 | Parameters may have annotations of the form "``: expression``" following the |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 511 | parameter name. Any parameter may have an annotation even those of the form |
| 512 | ``*identifier`` or ``**identifier``. Functions may have "return" annotation of |
| 513 | the form "``-> expression``" after the parameter list. These annotations can be |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 514 | any valid Python expression and are evaluated when the function definition is |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 515 | executed. Annotations may be evaluated in a different order than they appear in |
| 516 | the source code. The presence of annotations does not change the semantics of a |
| 517 | function. The annotation values are available as values of a dictionary keyed |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 518 | by the parameters' names in the :attr:`__annotations__` attribute of the |
| 519 | function object. |
| 520 | |
| 521 | .. index:: pair: lambda; form |
| 522 | |
| 523 | It is also possible to create anonymous functions (functions not bound to a |
| 524 | name), for immediate use in expressions. This uses lambda forms, described in |
| 525 | section :ref:`lambda`. Note that the lambda form is merely a shorthand for a |
| 526 | simplified function definition; a function defined in a ":keyword:`def`" |
| 527 | statement can be passed around or assigned to another name just like a function |
| 528 | defined by a lambda form. The ":keyword:`def`" form is actually more powerful |
| 529 | since it allows the execution of multiple statements and annotations. |
| 530 | |
| 531 | **Programmer's note:** Functions are first-class objects. A "``def``" form |
| 532 | executed inside a function definition defines a local function that can be |
| 533 | returned or passed around. Free variables used in the nested function can |
| 534 | access the local variables of the function containing the def. See section |
| 535 | :ref:`naming` for details. |
| 536 | |
| 537 | |
| 538 | .. _class: |
| 539 | |
| 540 | Class definitions |
| 541 | ================= |
| 542 | |
| 543 | .. index:: |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 544 | object: class |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 545 | statement: class |
| 546 | pair: class; definition |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 547 | pair: class; name |
| 548 | pair: name; binding |
| 549 | pair: execution; frame |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 550 | single: inheritance |
Georg Brandl | 3dbca81 | 2008-07-23 16:10:53 +0000 | [diff] [blame] | 551 | single: docstring |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 552 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 553 | A class definition defines a class object (see section :ref:`types`): |
| 554 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 555 | .. productionlist:: |
| 556 | classdef: [`decorators`] "class" `classname` [`inheritance`] ":" `suite` |
Georg Brandl | f414272 | 2010-10-17 10:38:20 +0000 | [diff] [blame] | 557 | inheritance: "(" [`argument_list` [","] | `comprehension`] ")" |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 558 | classname: `identifier` |
| 559 | |
Georg Brandl | 65e5f80 | 2010-08-02 18:10:13 +0000 | [diff] [blame] | 560 | A class definition is an executable statement. The inheritance list usually |
| 561 | gives a list of base classes (see :ref:`metaclasses` for more advanced uses), so |
| 562 | 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] | 563 | subclassing. Classes without an inheritance list inherit, by default, from the |
| 564 | base class :class:`object`; hence, :: |
| 565 | |
| 566 | class Foo: |
| 567 | pass |
| 568 | |
| 569 | is equivalent to :: |
| 570 | |
| 571 | class Foo(object): |
| 572 | pass |
Georg Brandl | 65e5f80 | 2010-08-02 18:10:13 +0000 | [diff] [blame] | 573 | |
| 574 | The class's suite is then executed in a new execution frame (see :ref:`naming`), |
| 575 | using a newly created local namespace and the original global namespace. |
| 576 | (Usually, the suite contains mostly function definitions.) When the class's |
| 577 | suite finishes execution, its execution frame is discarded but its local |
| 578 | namespace is saved. [#]_ A class object is then created using the inheritance |
| 579 | list for the base classes and the saved local namespace for the attribute |
| 580 | dictionary. The class name is bound to this class object in the original local |
| 581 | namespace. |
| 582 | |
| 583 | Class creation can be customized heavily using :ref:`metaclasses <metaclasses>`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 584 | |
Georg Brandl | f414272 | 2010-10-17 10:38:20 +0000 | [diff] [blame] | 585 | Classes can also be decorated: just like when decorating functions, :: |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 586 | |
| 587 | @f1(arg) |
| 588 | @f2 |
| 589 | class Foo: pass |
| 590 | |
| 591 | is equivalent to :: |
| 592 | |
| 593 | class Foo: pass |
| 594 | Foo = f1(arg)(f2(Foo)) |
| 595 | |
Georg Brandl | f414272 | 2010-10-17 10:38:20 +0000 | [diff] [blame] | 596 | The evaluation rules for the decorator expressions are the same as for function |
| 597 | decorators. The result must be a class object, which is then bound to the class |
| 598 | name. |
| 599 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 600 | **Programmer's note:** Variables defined in the class definition are class |
Georg Brandl | 65e5f80 | 2010-08-02 18:10:13 +0000 | [diff] [blame] | 601 | attributes; they are shared by instances. Instance attributes can be set in a |
| 602 | method with ``self.name = value``. Both class and instance attributes are |
| 603 | accessible through the notation "``self.name``", and an instance attribute hides |
| 604 | a class attribute with the same name when accessed in this way. Class |
| 605 | attributes can be used as defaults for instance attributes, but using mutable |
| 606 | values there can lead to unexpected results. :ref:`Descriptors <descriptors>` |
| 607 | can be used to create instance variables with different implementation details. |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 608 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 609 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 610 | .. seealso:: |
| 611 | |
Ezio Melotti | 7885833 | 2011-03-11 20:50:42 +0200 | [diff] [blame] | 612 | :pep:`3115` - Metaclasses in Python 3 |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 613 | :pep:`3129` - Class Decorators |
| 614 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 615 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 616 | .. rubric:: Footnotes |
| 617 | |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 618 | .. [#] The exception is propagated to the invocation stack only if there is no |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 619 | :keyword:`finally` clause that negates the exception. |
| 620 | |
Georg Brandl | f43713f | 2009-10-22 16:08:10 +0000 | [diff] [blame] | 621 | .. [#] Currently, control "flows off the end" except in the case of an exception |
| 622 | or the execution of a :keyword:`return`, :keyword:`continue`, or |
| 623 | :keyword:`break` statement. |
Georg Brandl | 3dbca81 | 2008-07-23 16:10:53 +0000 | [diff] [blame] | 624 | |
| 625 | .. [#] A string literal appearing as the first statement in the function body is |
| 626 | transformed into the function's ``__doc__`` attribute and therefore the |
| 627 | function's :term:`docstring`. |
| 628 | |
| 629 | .. [#] A string literal appearing as the first statement in the class body is |
| 630 | transformed into the namespace's ``__doc__`` item and therefore the class's |
| 631 | :term:`docstring`. |