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