Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | |
| 2 | .. _simple: |
| 3 | |
| 4 | ***************** |
| 5 | Simple statements |
| 6 | ***************** |
| 7 | |
| 8 | .. index:: pair: simple; statement |
| 9 | |
| 10 | Simple statements are comprised within a single logical line. Several simple |
| 11 | statements may occur on a single line separated by semicolons. The syntax for |
| 12 | simple statements is: |
| 13 | |
| 14 | .. productionlist:: |
| 15 | simple_stmt: `expression_stmt` |
| 16 | : | `assert_stmt` |
| 17 | : | `assignment_stmt` |
| 18 | : | `augmented_assignment_stmt` |
| 19 | : | `pass_stmt` |
| 20 | : | `del_stmt` |
| 21 | : | `return_stmt` |
| 22 | : | `yield_stmt` |
| 23 | : | `raise_stmt` |
| 24 | : | `break_stmt` |
| 25 | : | `continue_stmt` |
| 26 | : | `import_stmt` |
| 27 | : | `global_stmt` |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 28 | : | `nonlocal_stmt` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 29 | |
| 30 | |
| 31 | .. _exprstmts: |
| 32 | |
| 33 | Expression statements |
| 34 | ===================== |
| 35 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 36 | .. index:: |
| 37 | pair: expression; statement |
| 38 | pair: expression; list |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 39 | .. index:: pair: expression; list |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 40 | |
| 41 | Expression statements are used (mostly interactively) to compute and write a |
| 42 | value, or (usually) to call a procedure (a function that returns no meaningful |
| 43 | result; in Python, procedures return the value ``None``). Other uses of |
| 44 | expression statements are allowed and occasionally useful. The syntax for an |
| 45 | expression statement is: |
| 46 | |
| 47 | .. productionlist:: |
| 48 | expression_stmt: `expression_list` |
| 49 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 50 | An expression statement evaluates the expression list (which may be a single |
| 51 | expression). |
| 52 | |
| 53 | .. index:: |
| 54 | builtin: repr |
| 55 | object: None |
| 56 | pair: string; conversion |
| 57 | single: output |
| 58 | pair: standard; output |
| 59 | pair: writing; values |
| 60 | pair: procedure; call |
| 61 | |
| 62 | In interactive mode, if the value is not ``None``, it is converted to a string |
| 63 | using the built-in :func:`repr` function and the resulting string is written to |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 64 | standard output on a line by itself (except if the result is ``None``, so that |
| 65 | procedure calls do not cause any output.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 66 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 67 | .. _assignment: |
| 68 | |
| 69 | Assignment statements |
| 70 | ===================== |
| 71 | |
| 72 | .. index:: |
| 73 | pair: assignment; statement |
| 74 | pair: binding; name |
| 75 | pair: rebinding; name |
| 76 | object: mutable |
| 77 | pair: attribute; assignment |
| 78 | |
| 79 | Assignment statements are used to (re)bind names to values and to modify |
| 80 | attributes or items of mutable objects: |
| 81 | |
| 82 | .. productionlist:: |
| 83 | assignment_stmt: (`target_list` "=")+ (`expression_list` | `yield_expression`) |
| 84 | target_list: `target` ("," `target`)* [","] |
| 85 | target: `identifier` |
| 86 | : | "(" `target_list` ")" |
| 87 | : | "[" `target_list` "]" |
| 88 | : | `attributeref` |
| 89 | : | `subscription` |
| 90 | : | `slicing` |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 91 | : | "*" `target` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
| 93 | (See section :ref:`primaries` for the syntax definitions for the last three |
| 94 | symbols.) |
| 95 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 96 | An assignment statement evaluates the expression list (remember that this can be |
| 97 | a single expression or a comma-separated list, the latter yielding a tuple) and |
| 98 | assigns the single resulting object to each of the target lists, from left to |
| 99 | right. |
| 100 | |
| 101 | .. index:: |
| 102 | single: target |
| 103 | pair: target; list |
| 104 | |
| 105 | Assignment is defined recursively depending on the form of the target (list). |
| 106 | When a target is part of a mutable object (an attribute reference, subscription |
| 107 | or slicing), the mutable object must ultimately perform the assignment and |
| 108 | decide about its validity, and may raise an exception if the assignment is |
| 109 | unacceptable. The rules observed by various types and the exceptions raised are |
| 110 | given with the definition of the object types (see section :ref:`types`). |
| 111 | |
| 112 | .. index:: triple: target; list; assignment |
| 113 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 114 | Assignment of an object to a target list, optionally enclosed in parentheses or |
| 115 | square brackets, is recursively defined as follows. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
| 117 | * If the target list is a single target: The object is assigned to that target. |
| 118 | |
Benjamin Peterson | d75fcb4 | 2009-02-19 04:22:03 +0000 | [diff] [blame] | 119 | * If the target list is a comma-separated list of targets: The object must be an |
| 120 | iterable with the same number of items as there are targets in the target list, |
| 121 | and the items are assigned, from left to right, to the corresponding targets. |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 122 | |
| 123 | * If the target list contains one target prefixed with an asterisk, called a |
| 124 | "starred" target: The object must be a sequence with at least as many items |
| 125 | as there are targets in the target list, minus one. The first items of the |
| 126 | sequence are assigned, from left to right, to the targets before the starred |
| 127 | target. The final items of the sequence are assigned to the targets after |
| 128 | the starred target. A list of the remaining items in the sequence is then |
| 129 | assigned to the starred target (the list can be empty). |
| 130 | |
| 131 | * Else: The object must be a sequence with the same number of items as there |
| 132 | are targets in the target list, and the items are assigned, from left to |
| 133 | right, to the corresponding targets. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 134 | |
| 135 | Assignment of an object to a single target is recursively defined as follows. |
| 136 | |
| 137 | * If the target is an identifier (name): |
| 138 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 139 | * If the name does not occur in a :keyword:`global` or :keyword:`nonlocal` |
| 140 | statement in the current code block: the name is bound to the object in the |
| 141 | current local namespace. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 143 | * Otherwise: the name is bound to the object in the global namespace or the |
| 144 | outer namespace determined by :keyword:`nonlocal`, respectively. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 145 | |
Georg Brandl | 482b151 | 2010-03-21 09:02:59 +0000 | [diff] [blame] | 146 | .. index:: single: destructor |
| 147 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 148 | The name is rebound if it was already bound. This may cause the reference |
| 149 | count for the object previously bound to the name to reach zero, causing the |
| 150 | object to be deallocated and its destructor (if it has one) to be called. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 152 | * If the target is a target list enclosed in parentheses or in square brackets: |
Benjamin Peterson | d75fcb4 | 2009-02-19 04:22:03 +0000 | [diff] [blame] | 153 | The object must be an iterable with the same number of items as there are |
| 154 | targets in the target list, and its items are assigned, from left to right, |
| 155 | to the corresponding targets. |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 156 | |
| 157 | .. index:: pair: attribute; assignment |
| 158 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 159 | * If the target is an attribute reference: The primary expression in the |
| 160 | reference is evaluated. It should yield an object with assignable attributes; |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 161 | if this is not the case, :exc:`TypeError` is raised. That object is then |
| 162 | asked to assign the assigned object to the given attribute; if it cannot |
| 163 | perform the assignment, it raises an exception (usually but not necessarily |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 164 | :exc:`AttributeError`). |
| 165 | |
Georg Brandl | ee8783d | 2009-09-16 16:00:31 +0000 | [diff] [blame] | 166 | .. _attr-target-note: |
| 167 | |
| 168 | Note: If the object is a class instance and the attribute reference occurs on |
| 169 | both sides of the assignment operator, the RHS expression, ``a.x`` can access |
| 170 | either an instance attribute or (if no instance attribute exists) a class |
| 171 | attribute. The LHS target ``a.x`` is always set as an instance attribute, |
| 172 | creating it if necessary. Thus, the two occurrences of ``a.x`` do not |
| 173 | necessarily refer to the same attribute: if the RHS expression refers to a |
| 174 | class attribute, the LHS creates a new instance attribute as the target of the |
| 175 | assignment:: |
| 176 | |
| 177 | class Cls: |
| 178 | x = 3 # class variable |
| 179 | inst = Cls() |
| 180 | inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x as 3 |
| 181 | |
| 182 | This description does not necessarily apply to descriptor attributes, such as |
| 183 | properties created with :func:`property`. |
| 184 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 185 | .. index:: |
| 186 | pair: subscription; assignment |
| 187 | object: mutable |
| 188 | |
| 189 | * If the target is a subscription: The primary expression in the reference is |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 190 | evaluated. It should yield either a mutable sequence object (such as a list) |
| 191 | or a mapping object (such as a dictionary). Next, the subscript expression is |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 192 | evaluated. |
| 193 | |
| 194 | .. index:: |
| 195 | object: sequence |
| 196 | object: list |
| 197 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 198 | If the primary is a mutable sequence object (such as a list), the subscript |
| 199 | must yield an integer. If it is negative, the sequence's length is added to |
| 200 | it. The resulting value must be a nonnegative integer less than the |
| 201 | sequence's length, and the sequence is asked to assign the assigned object to |
| 202 | its item with that index. If the index is out of range, :exc:`IndexError` is |
| 203 | raised (assignment to a subscripted sequence cannot add new items to a list). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 204 | |
| 205 | .. index:: |
| 206 | object: mapping |
| 207 | object: dictionary |
| 208 | |
| 209 | If the primary is a mapping object (such as a dictionary), the subscript must |
| 210 | have a type compatible with the mapping's key type, and the mapping is then |
| 211 | asked to create a key/datum pair which maps the subscript to the assigned |
| 212 | object. This can either replace an existing key/value pair with the same key |
| 213 | value, or insert a new key/value pair (if no key with the same value existed). |
| 214 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 215 | For user-defined objects, the :meth:`__setitem__` method is called with |
| 216 | appropriate arguments. |
| 217 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 218 | .. index:: pair: slicing; assignment |
| 219 | |
| 220 | * If the target is a slicing: The primary expression in the reference is |
| 221 | evaluated. It should yield a mutable sequence object (such as a list). The |
| 222 | assigned object should be a sequence object of the same type. Next, the lower |
| 223 | and upper bound expressions are evaluated, insofar they are present; defaults |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 224 | are zero and the sequence's length. The bounds should evaluate to integers. |
| 225 | If either bound is negative, the sequence's length is added to it. The |
| 226 | resulting bounds are clipped to lie between zero and the sequence's length, |
| 227 | inclusive. Finally, the sequence object is asked to replace the slice with |
| 228 | the items of the assigned sequence. The length of the slice may be different |
| 229 | from the length of the assigned sequence, thus changing the length of the |
| 230 | target sequence, if the object allows it. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 231 | |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 232 | .. impl-detail:: |
| 233 | |
| 234 | In the current implementation, the syntax for targets is taken to be the same |
| 235 | as for expressions, and invalid syntax is rejected during the code generation |
| 236 | phase, causing less detailed error messages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 237 | |
| 238 | WARNING: Although the definition of assignment implies that overlaps between the |
| 239 | left-hand side and the right-hand side are 'safe' (for example ``a, b = b, a`` |
| 240 | swaps two variables), overlaps *within* the collection of assigned-to variables |
| 241 | are not safe! For instance, the following program prints ``[0, 2]``:: |
| 242 | |
| 243 | x = [0, 1] |
| 244 | i = 0 |
| 245 | i, x[i] = 1, 2 |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 246 | print(x) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 247 | |
| 248 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 249 | .. seealso:: |
| 250 | |
| 251 | :pep:`3132` - Extended Iterable Unpacking |
| 252 | The specification for the ``*target`` feature. |
| 253 | |
| 254 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 255 | .. _augassign: |
| 256 | |
| 257 | Augmented assignment statements |
| 258 | ------------------------------- |
| 259 | |
| 260 | .. index:: |
| 261 | pair: augmented; assignment |
| 262 | single: statement; assignment, augmented |
| 263 | |
| 264 | Augmented assignment is the combination, in a single statement, of a binary |
| 265 | operation and an assignment statement: |
| 266 | |
| 267 | .. productionlist:: |
Benjamin Peterson | b58dda7 | 2009-01-18 22:27:04 +0000 | [diff] [blame] | 268 | augmented_assignment_stmt: `augtarget` `augop` (`expression_list` | `yield_expression`) |
| 269 | augtarget: `identifier` | `attributeref` | `subscription` | `slicing` |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 270 | augop: "+=" | "-=" | "*=" | "/=" | "//=" | "%=" | "**=" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 271 | : | ">>=" | "<<=" | "&=" | "^=" | "|=" |
| 272 | |
| 273 | (See section :ref:`primaries` for the syntax definitions for the last three |
| 274 | symbols.) |
| 275 | |
| 276 | An augmented assignment evaluates the target (which, unlike normal assignment |
| 277 | statements, cannot be an unpacking) and the expression list, performs the binary |
| 278 | operation specific to the type of assignment on the two operands, and assigns |
| 279 | the result to the original target. The target is only evaluated once. |
| 280 | |
| 281 | An augmented assignment expression like ``x += 1`` can be rewritten as ``x = x + |
| 282 | 1`` to achieve a similar, but not exactly equal effect. In the augmented |
| 283 | version, ``x`` is only evaluated once. Also, when possible, the actual operation |
| 284 | is performed *in-place*, meaning that rather than creating a new object and |
| 285 | assigning that to the target, the old object is modified instead. |
| 286 | |
| 287 | With the exception of assigning to tuples and multiple targets in a single |
| 288 | statement, the assignment done by augmented assignment statements is handled the |
| 289 | same way as normal assignments. Similarly, with the exception of the possible |
| 290 | *in-place* behavior, the binary operation performed by augmented assignment is |
| 291 | the same as the normal binary operations. |
| 292 | |
Georg Brandl | ee8783d | 2009-09-16 16:00:31 +0000 | [diff] [blame] | 293 | For targets which are attribute references, the same :ref:`caveat about class |
| 294 | and instance attributes <attr-target-note>` applies as for regular assignments. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 295 | |
| 296 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 297 | .. _assert: |
| 298 | |
| 299 | The :keyword:`assert` statement |
| 300 | =============================== |
| 301 | |
| 302 | .. index:: |
| 303 | statement: assert |
| 304 | pair: debugging; assertions |
| 305 | |
| 306 | Assert statements are a convenient way to insert debugging assertions into a |
| 307 | program: |
| 308 | |
| 309 | .. productionlist:: |
| 310 | assert_stmt: "assert" `expression` ["," `expression`] |
| 311 | |
| 312 | The simple form, ``assert expression``, is equivalent to :: |
| 313 | |
| 314 | if __debug__: |
| 315 | if not expression: raise AssertionError |
| 316 | |
| 317 | The extended form, ``assert expression1, expression2``, is equivalent to :: |
| 318 | |
| 319 | if __debug__: |
Georg Brandl | 18a499d | 2007-12-29 10:57:11 +0000 | [diff] [blame] | 320 | if not expression1: raise AssertionError(expression2) |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 321 | |
| 322 | .. index:: |
| 323 | single: __debug__ |
| 324 | exception: AssertionError |
| 325 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 326 | These equivalences assume that :const:`__debug__` and :exc:`AssertionError` refer to |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 327 | the built-in variables with those names. In the current implementation, the |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 328 | built-in variable :const:`__debug__` is ``True`` under normal circumstances, |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 329 | ``False`` when optimization is requested (command line option -O). The current |
| 330 | code generator emits no code for an assert statement when optimization is |
| 331 | requested at compile time. Note that it is unnecessary to include the source |
| 332 | code for the expression that failed in the error message; it will be displayed |
| 333 | as part of the stack trace. |
| 334 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 335 | Assignments to :const:`__debug__` are illegal. The value for the built-in variable |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 336 | is determined when the interpreter starts. |
| 337 | |
| 338 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 339 | .. _pass: |
| 340 | |
| 341 | The :keyword:`pass` statement |
| 342 | ============================= |
| 343 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 344 | .. index:: |
| 345 | statement: pass |
| 346 | pair: null; operation |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 347 | pair: null; operation |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 348 | |
| 349 | .. productionlist:: |
| 350 | pass_stmt: "pass" |
| 351 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 352 | :keyword:`pass` is a null operation --- when it is executed, nothing happens. |
| 353 | It is useful as a placeholder when a statement is required syntactically, but no |
| 354 | code needs to be executed, for example:: |
| 355 | |
| 356 | def f(arg): pass # a function that does nothing (yet) |
| 357 | |
| 358 | class C: pass # a class with no methods (yet) |
| 359 | |
| 360 | |
| 361 | .. _del: |
| 362 | |
| 363 | The :keyword:`del` statement |
| 364 | ============================ |
| 365 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 366 | .. index:: |
| 367 | statement: del |
| 368 | pair: deletion; target |
| 369 | triple: deletion; target; list |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 370 | |
| 371 | .. productionlist:: |
| 372 | del_stmt: "del" `target_list` |
| 373 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 374 | Deletion is recursively defined very similar to the way assignment is defined. |
Sandro Tosi | 75c71cc | 2011-12-24 19:56:04 +0100 | [diff] [blame^] | 375 | Rather than spelling it out in full details, here are some hints. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 376 | |
| 377 | Deletion of a target list recursively deletes each target, from left to right. |
| 378 | |
| 379 | .. index:: |
| 380 | statement: global |
| 381 | pair: unbinding; name |
| 382 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 383 | Deletion of a name removes the binding of that name from the local or global |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 384 | namespace, depending on whether the name occurs in a :keyword:`global` statement |
| 385 | in the same code block. If the name is unbound, a :exc:`NameError` exception |
| 386 | will be raised. |
| 387 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 388 | .. index:: pair: attribute; deletion |
| 389 | |
| 390 | Deletion of attribute references, subscriptions and slicings is passed to the |
| 391 | primary object involved; deletion of a slicing is in general equivalent to |
| 392 | assignment of an empty slice of the right type (but even this is determined by |
| 393 | the sliced object). |
| 394 | |
Amaury Forgeot d'Arc | ba117ef | 2010-09-10 21:39:53 +0000 | [diff] [blame] | 395 | .. versionchanged:: 3.2 |
Benjamin Peterson | d032532 | 2010-09-10 21:59:21 +0000 | [diff] [blame] | 396 | |
Amaury Forgeot d'Arc | ba117ef | 2010-09-10 21:39:53 +0000 | [diff] [blame] | 397 | Previously it was illegal to delete a name from the local namespace if it |
| 398 | occurs as a free variable in a nested block. |
| 399 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 400 | |
| 401 | .. _return: |
| 402 | |
| 403 | The :keyword:`return` statement |
| 404 | =============================== |
| 405 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 406 | .. index:: |
| 407 | statement: return |
| 408 | pair: function; definition |
| 409 | pair: class; definition |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 410 | |
| 411 | .. productionlist:: |
| 412 | return_stmt: "return" [`expression_list`] |
| 413 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 414 | :keyword:`return` may only occur syntactically nested in a function definition, |
| 415 | not within a nested class definition. |
| 416 | |
| 417 | If an expression list is present, it is evaluated, else ``None`` is substituted. |
| 418 | |
| 419 | :keyword:`return` leaves the current function call with the expression list (or |
| 420 | ``None``) as return value. |
| 421 | |
| 422 | .. index:: keyword: finally |
| 423 | |
| 424 | When :keyword:`return` passes control out of a :keyword:`try` statement with a |
| 425 | :keyword:`finally` clause, that :keyword:`finally` clause is executed before |
| 426 | really leaving the function. |
| 427 | |
| 428 | In a generator function, the :keyword:`return` statement is not allowed to |
| 429 | include an :token:`expression_list`. In that context, a bare :keyword:`return` |
| 430 | indicates that the generator is done and will cause :exc:`StopIteration` to be |
| 431 | raised. |
| 432 | |
| 433 | |
| 434 | .. _yield: |
| 435 | |
| 436 | The :keyword:`yield` statement |
| 437 | ============================== |
| 438 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 439 | .. index:: |
| 440 | statement: yield |
| 441 | single: generator; function |
| 442 | single: generator; iterator |
| 443 | single: function; generator |
| 444 | exception: StopIteration |
| 445 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 446 | .. productionlist:: |
| 447 | yield_stmt: `yield_expression` |
| 448 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 449 | The :keyword:`yield` statement is only used when defining a generator function, |
| 450 | and is only used in the body of the generator function. Using a :keyword:`yield` |
| 451 | statement in a function definition is sufficient to cause that definition to |
| 452 | create a generator function instead of a normal function. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 453 | When a generator function is called, it returns an iterator known as a generator |
| 454 | iterator, or more commonly, a generator. The body of the generator function is |
Georg Brandl | 6520d82 | 2009-02-05 11:01:54 +0000 | [diff] [blame] | 455 | executed by calling the :func:`next` function on the generator repeatedly until |
| 456 | it raises an exception. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 457 | |
| 458 | When a :keyword:`yield` statement is executed, the state of the generator is |
| 459 | frozen and the value of :token:`expression_list` is returned to :meth:`next`'s |
| 460 | caller. By "frozen" we mean that all local state is retained, including the |
| 461 | current bindings of local variables, the instruction pointer, and the internal |
Georg Brandl | 6520d82 | 2009-02-05 11:01:54 +0000 | [diff] [blame] | 462 | evaluation stack: enough information is saved so that the next time :func:`next` |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 463 | is invoked, the function can proceed exactly as if the :keyword:`yield` |
| 464 | statement were just another external call. |
| 465 | |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 466 | The :keyword:`yield` statement is allowed in the :keyword:`try` clause of a |
| 467 | :keyword:`try` ... :keyword:`finally` construct. If the generator is not |
| 468 | resumed before it is finalized (by reaching a zero reference count or by being |
| 469 | garbage collected), the generator-iterator's :meth:`close` method will be |
| 470 | called, allowing any pending :keyword:`finally` clauses to execute. |
Christian Heimes | 33fe809 | 2008-04-13 13:53:33 +0000 | [diff] [blame] | 471 | |
| 472 | .. seealso:: |
| 473 | |
| 474 | :pep:`0255` - Simple Generators |
| 475 | The proposal for adding generators and the :keyword:`yield` statement to Python. |
| 476 | |
| 477 | :pep:`0342` - Coroutines via Enhanced Generators |
| 478 | The proposal that, among other generator enhancements, proposed allowing |
| 479 | :keyword:`yield` to appear inside a :keyword:`try` ... :keyword:`finally` block. |
| 480 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 481 | |
| 482 | .. _raise: |
| 483 | |
| 484 | The :keyword:`raise` statement |
| 485 | ============================== |
| 486 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 487 | .. index:: |
| 488 | statement: raise |
| 489 | single: exception |
| 490 | pair: raising; exception |
Georg Brandl | 1aea30a | 2008-07-19 15:51:07 +0000 | [diff] [blame] | 491 | single: __traceback__ (exception attribute) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 492 | |
| 493 | .. productionlist:: |
Georg Brandl | e06de8b | 2008-05-05 21:42:51 +0000 | [diff] [blame] | 494 | raise_stmt: "raise" [`expression` ["from" `expression`]] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 495 | |
| 496 | If no expressions are present, :keyword:`raise` re-raises the last exception |
| 497 | that was active in the current scope. If no exception is active in the current |
| 498 | scope, a :exc:`TypeError` exception is raised indicating that this is an error |
Alexandre Vassalotti | f260e44 | 2008-05-11 19:59:59 +0000 | [diff] [blame] | 499 | (if running under IDLE, a :exc:`queue.Empty` exception is raised instead). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 500 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 501 | Otherwise, :keyword:`raise` evaluates the first expression as the exception |
| 502 | object. It must be either a subclass or an instance of :class:`BaseException`. |
| 503 | If it is a class, the exception instance will be obtained when needed by |
| 504 | instantiating the class with no arguments. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 505 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 506 | The :dfn:`type` of the exception is the exception instance's class, the |
| 507 | :dfn:`value` is the instance itself. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 508 | |
| 509 | .. index:: object: traceback |
| 510 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 511 | A traceback object is normally created automatically when an exception is raised |
Georg Brandl | e06de8b | 2008-05-05 21:42:51 +0000 | [diff] [blame] | 512 | and attached to it as the :attr:`__traceback__` attribute, which is writable. |
| 513 | You can create an exception and set your own traceback in one step using the |
| 514 | :meth:`with_traceback` exception method (which returns the same exception |
| 515 | instance, with its traceback set to its argument), like so:: |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 516 | |
Benjamin Peterson | b785169 | 2009-02-16 16:15:34 +0000 | [diff] [blame] | 517 | raise Exception("foo occurred").with_traceback(tracebackobj) |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 518 | |
Georg Brandl | 1aea30a | 2008-07-19 15:51:07 +0000 | [diff] [blame] | 519 | .. index:: pair: exception; chaining |
| 520 | __cause__ (exception attribute) |
| 521 | __context__ (exception attribute) |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 522 | |
Georg Brandl | 1aea30a | 2008-07-19 15:51:07 +0000 | [diff] [blame] | 523 | The ``from`` clause is used for exception chaining: if given, the second |
| 524 | *expression* must be another exception class or instance, which will then be |
| 525 | attached to the raised exception as the :attr:`__cause__` attribute (which is |
| 526 | writable). If the raised exception is not handled, both exceptions will be |
| 527 | printed:: |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 528 | |
Georg Brandl | 1aea30a | 2008-07-19 15:51:07 +0000 | [diff] [blame] | 529 | >>> try: |
| 530 | ... print(1 / 0) |
| 531 | ... except Exception as exc: |
| 532 | ... raise RuntimeError("Something bad happened") from exc |
| 533 | ... |
| 534 | Traceback (most recent call last): |
| 535 | File "<stdin>", line 2, in <module> |
| 536 | ZeroDivisionError: int division or modulo by zero |
| 537 | |
| 538 | The above exception was the direct cause of the following exception: |
| 539 | |
| 540 | Traceback (most recent call last): |
| 541 | File "<stdin>", line 4, in <module> |
| 542 | RuntimeError: Something bad happened |
| 543 | |
| 544 | A similar mechanism works implicitly if an exception is raised inside an |
| 545 | exception handler: the previous exception is then attached as the new |
| 546 | exception's :attr:`__context__` attribute:: |
| 547 | |
| 548 | >>> try: |
| 549 | ... print(1 / 0) |
| 550 | ... except: |
| 551 | ... raise RuntimeError("Something bad happened") |
| 552 | ... |
| 553 | Traceback (most recent call last): |
| 554 | File "<stdin>", line 2, in <module> |
| 555 | ZeroDivisionError: int division or modulo by zero |
| 556 | |
| 557 | During handling of the above exception, another exception occurred: |
| 558 | |
| 559 | Traceback (most recent call last): |
| 560 | File "<stdin>", line 4, in <module> |
| 561 | RuntimeError: Something bad happened |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 562 | |
| 563 | Additional information on exceptions can be found in section :ref:`exceptions`, |
| 564 | and information about handling exceptions is in section :ref:`try`. |
| 565 | |
| 566 | |
| 567 | .. _break: |
| 568 | |
| 569 | The :keyword:`break` statement |
| 570 | ============================== |
| 571 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 572 | .. index:: |
| 573 | statement: break |
| 574 | statement: for |
| 575 | statement: while |
| 576 | pair: loop; statement |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 577 | |
| 578 | .. productionlist:: |
| 579 | break_stmt: "break" |
| 580 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 581 | :keyword:`break` may only occur syntactically nested in a :keyword:`for` or |
| 582 | :keyword:`while` loop, but not nested in a function or class definition within |
| 583 | that loop. |
| 584 | |
| 585 | .. index:: keyword: else |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 586 | pair: loop control; target |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 587 | |
| 588 | It terminates the nearest enclosing loop, skipping the optional :keyword:`else` |
| 589 | clause if the loop has one. |
| 590 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 591 | If a :keyword:`for` loop is terminated by :keyword:`break`, the loop control |
| 592 | target keeps its current value. |
| 593 | |
| 594 | .. index:: keyword: finally |
| 595 | |
| 596 | When :keyword:`break` passes control out of a :keyword:`try` statement with a |
| 597 | :keyword:`finally` clause, that :keyword:`finally` clause is executed before |
| 598 | really leaving the loop. |
| 599 | |
| 600 | |
| 601 | .. _continue: |
| 602 | |
| 603 | The :keyword:`continue` statement |
| 604 | ================================= |
| 605 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 606 | .. index:: |
| 607 | statement: continue |
| 608 | statement: for |
| 609 | statement: while |
| 610 | pair: loop; statement |
| 611 | keyword: finally |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 612 | |
| 613 | .. productionlist:: |
| 614 | continue_stmt: "continue" |
| 615 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 616 | :keyword:`continue` may only occur syntactically nested in a :keyword:`for` or |
| 617 | :keyword:`while` loop, but not nested in a function or class definition or |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 618 | :keyword:`finally` clause within that loop. It continues with the next |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 619 | cycle of the nearest enclosing loop. |
| 620 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 621 | When :keyword:`continue` passes control out of a :keyword:`try` statement with a |
| 622 | :keyword:`finally` clause, that :keyword:`finally` clause is executed before |
| 623 | really starting the next loop cycle. |
| 624 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 625 | |
| 626 | .. _import: |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 627 | .. _from: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 628 | |
| 629 | The :keyword:`import` statement |
| 630 | =============================== |
| 631 | |
| 632 | .. index:: |
| 633 | statement: import |
| 634 | single: module; importing |
| 635 | pair: name; binding |
| 636 | keyword: from |
| 637 | |
| 638 | .. productionlist:: |
| 639 | import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )* |
| 640 | : | "from" `relative_module` "import" `identifier` ["as" `name`] |
| 641 | : ( "," `identifier` ["as" `name`] )* |
| 642 | : | "from" `relative_module` "import" "(" `identifier` ["as" `name`] |
| 643 | : ( "," `identifier` ["as" `name`] )* [","] ")" |
| 644 | : | "from" `module` "import" "*" |
| 645 | module: (`identifier` ".")* `identifier` |
| 646 | relative_module: "."* `module` | "."+ |
| 647 | name: `identifier` |
| 648 | |
| 649 | Import statements are executed in two steps: (1) find a module, and initialize |
| 650 | it if necessary; (2) define a name or names in the local namespace (of the scope |
Brett Cannon | e43b060 | 2009-03-21 03:11:16 +0000 | [diff] [blame] | 651 | where the :keyword:`import` statement occurs). The statement comes in two |
| 652 | forms differing on whether it uses the :keyword:`from` keyword. The first form |
| 653 | (without :keyword:`from`) repeats these steps for each identifier in the list. |
| 654 | The form with :keyword:`from` performs step (1) once, and then performs step |
| 655 | (2) repeatedly. For a reference implementation of step (1), see the |
| 656 | :mod:`importlib` module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 657 | |
| 658 | .. index:: |
Brett Cannon | e43b060 | 2009-03-21 03:11:16 +0000 | [diff] [blame] | 659 | single: package |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 660 | |
Brett Cannon | e43b060 | 2009-03-21 03:11:16 +0000 | [diff] [blame] | 661 | To understand how step (1) occurs, one must first understand how Python handles |
| 662 | hierarchical naming of modules. To help organize modules and provide a |
| 663 | hierarchy in naming, Python has a concept of packages. A package can contain |
| 664 | other packages and modules while modules cannot contain other modules or |
| 665 | packages. From a file system perspective, packages are directories and modules |
| 666 | are files. The original `specification for packages |
| 667 | <http://www.python.org/doc/essays/packages.html>`_ is still available to read, |
| 668 | although minor details have changed since the writing of that document. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 669 | |
| 670 | .. index:: |
Brett Cannon | e43b060 | 2009-03-21 03:11:16 +0000 | [diff] [blame] | 671 | single: sys.modules |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 672 | |
Brett Cannon | e43b060 | 2009-03-21 03:11:16 +0000 | [diff] [blame] | 673 | Once the name of the module is known (unless otherwise specified, the term |
| 674 | "module" will refer to both packages and modules), searching |
| 675 | for the module or package can begin. The first place checked is |
| 676 | :data:`sys.modules`, the cache of all modules that have been imported |
Brett Cannon | 757df6e | 2009-08-30 04:00:12 +0000 | [diff] [blame] | 677 | previously. If the module is found there then it is used in step (2) of import |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 678 | unless ``None`` is found in :data:`sys.modules`, in which case |
Brett Cannon | 757df6e | 2009-08-30 04:00:12 +0000 | [diff] [blame] | 679 | :exc:`ImportError` is raised. |
Brett Cannon | e43b060 | 2009-03-21 03:11:16 +0000 | [diff] [blame] | 680 | |
| 681 | .. index:: |
| 682 | single: sys.meta_path |
| 683 | single: finder |
| 684 | pair: finder; find_module |
| 685 | single: __path__ |
| 686 | |
| 687 | If the module is not found in the cache, then :data:`sys.meta_path` is searched |
| 688 | (the specification for :data:`sys.meta_path` can be found in :pep:`302`). |
| 689 | The object is a list of :term:`finder` objects which are queried in order as to |
| 690 | whether they know how to load the module by calling their :meth:`find_module` |
| 691 | method with the name of the module. If the module happens to be contained |
| 692 | within a package (as denoted by the existence of a dot in the name), then a |
| 693 | second argument to :meth:`find_module` is given as the value of the |
| 694 | :attr:`__path__` attribute from the parent package (everything up to the last |
| 695 | dot in the name of the module being imported). If a finder can find the module |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 696 | it returns a :term:`loader` (discussed later) or returns ``None``. |
Brett Cannon | e43b060 | 2009-03-21 03:11:16 +0000 | [diff] [blame] | 697 | |
| 698 | .. index:: |
| 699 | single: sys.path_hooks |
| 700 | single: sys.path_importer_cache |
| 701 | single: sys.path |
| 702 | |
| 703 | If none of the finders on :data:`sys.meta_path` are able to find the module |
| 704 | then some implicitly defined finders are queried. Implementations of Python |
| 705 | vary in what implicit meta path finders are defined. The one they all do |
| 706 | define, though, is one that handles :data:`sys.path_hooks`, |
| 707 | :data:`sys.path_importer_cache`, and :data:`sys.path`. |
| 708 | |
| 709 | The implicit finder searches for the requested module in the "paths" specified |
| 710 | in one of two places ("paths" do not have to be file system paths). If the |
| 711 | module being imported is supposed to be contained within a package then the |
| 712 | second argument passed to :meth:`find_module`, :attr:`__path__` on the parent |
| 713 | package, is used as the source of paths. If the module is not contained in a |
| 714 | package then :data:`sys.path` is used as the source of paths. |
| 715 | |
| 716 | Once the source of paths is chosen it is iterated over to find a finder that |
| 717 | can handle that path. The dict at :data:`sys.path_importer_cache` caches |
| 718 | finders for paths and is checked for a finder. If the path does not have a |
| 719 | finder cached then :data:`sys.path_hooks` is searched by calling each object in |
| 720 | the list with a single argument of the path, returning a finder or raises |
| 721 | :exc:`ImportError`. If a finder is returned then it is cached in |
| 722 | :data:`sys.path_importer_cache` and then used for that path entry. If no finder |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 723 | can be found but the path exists then a value of ``None`` is |
Brett Cannon | e43b060 | 2009-03-21 03:11:16 +0000 | [diff] [blame] | 724 | stored in :data:`sys.path_importer_cache` to signify that an implicit, |
| 725 | file-based finder that handles modules stored as individual files should be |
| 726 | used for that path. If the path does not exist then a finder which always |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 727 | returns ``None`` is placed in the cache for the path. |
Brett Cannon | e43b060 | 2009-03-21 03:11:16 +0000 | [diff] [blame] | 728 | |
| 729 | .. index:: |
| 730 | single: loader |
| 731 | pair: loader; load_module |
| 732 | exception: ImportError |
| 733 | |
| 734 | If no finder can find the module then :exc:`ImportError` is raised. Otherwise |
| 735 | some finder returned a loader whose :meth:`load_module` method is called with |
| 736 | the name of the module to load (see :pep:`302` for the original definition of |
| 737 | loaders). A loader has several responsibilities to perform on a module it |
| 738 | loads. First, if the module already exists in :data:`sys.modules` (a |
| 739 | possibility if the loader is called outside of the import machinery) then it |
| 740 | is to use that module for initialization and not a new module. But if the |
| 741 | module does not exist in :data:`sys.modules` then it is to be added to that |
| 742 | dict before initialization begins. If an error occurs during loading of the |
| 743 | module and it was added to :data:`sys.modules` it is to be removed from the |
| 744 | dict. If an error occurs but the module was already in :data:`sys.modules` it |
| 745 | is left in the dict. |
| 746 | |
| 747 | .. index:: |
| 748 | single: __name__ |
| 749 | single: __file__ |
| 750 | single: __path__ |
| 751 | single: __package__ |
| 752 | single: __loader__ |
| 753 | |
| 754 | The loader must set several attributes on the module. :data:`__name__` is to be |
| 755 | set to the name of the module. :data:`__file__` is to be the "path" to the file |
| 756 | unless the module is built-in (and thus listed in |
| 757 | :data:`sys.builtin_module_names`) in which case the attribute is not set. |
| 758 | If what is being imported is a package then :data:`__path__` is to be set to a |
| 759 | list of paths to be searched when looking for modules and packages contained |
| 760 | within the package being imported. :data:`__package__` is optional but should |
| 761 | be set to the name of package that contains the module or package (the empty |
| 762 | string is used for module not contained in a package). :data:`__loader__` is |
| 763 | also optional but should be set to the loader object that is loading the |
| 764 | module. |
| 765 | |
| 766 | .. index:: |
| 767 | exception: ImportError |
| 768 | |
| 769 | If an error occurs during loading then the loader raises :exc:`ImportError` if |
| 770 | some other exception is not already being propagated. Otherwise the loader |
| 771 | returns the module that was loaded and initialized. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 772 | |
| 773 | When step (1) finishes without raising an exception, step (2) can begin. |
| 774 | |
| 775 | The first form of :keyword:`import` statement binds the module name in the local |
| 776 | namespace to the module object, and then goes on to import the next identifier, |
| 777 | if any. If the module name is followed by :keyword:`as`, the name following |
| 778 | :keyword:`as` is used as the local name for the module. |
| 779 | |
| 780 | .. index:: |
| 781 | pair: name; binding |
| 782 | exception: ImportError |
| 783 | |
| 784 | The :keyword:`from` form does not bind the module name: it goes through the list |
| 785 | of identifiers, looks each one of them up in the module found in step (1), and |
| 786 | binds the name in the local namespace to the object thus found. As with the |
| 787 | first form of :keyword:`import`, an alternate local name can be supplied by |
| 788 | specifying ":keyword:`as` localname". If a name is not found, |
| 789 | :exc:`ImportError` is raised. If the list of identifiers is replaced by a star |
| 790 | (``'*'``), all public names defined in the module are bound in the local |
Michael Foord | bcc4810 | 2010-11-18 11:02:50 +0000 | [diff] [blame] | 791 | namespace of the :keyword:`import` statement. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 792 | |
| 793 | .. index:: single: __all__ (optional module attribute) |
| 794 | |
| 795 | The *public names* defined by a module are determined by checking the module's |
| 796 | namespace for a variable named ``__all__``; if defined, it must be a sequence of |
| 797 | strings which are names defined or imported by that module. The names given in |
| 798 | ``__all__`` are all considered public and are required to exist. If ``__all__`` |
| 799 | is not defined, the set of public names includes all names found in the module's |
| 800 | namespace which do not begin with an underscore character (``'_'``). |
| 801 | ``__all__`` should contain the entire public API. It is intended to avoid |
| 802 | accidentally exporting items that are not part of the API (such as library |
| 803 | modules which were imported and used within the module). |
| 804 | |
Benjamin Peterson | 9611b5e | 2009-03-25 21:50:43 +0000 | [diff] [blame] | 805 | The :keyword:`from` form with ``*`` may only occur in a module scope. The wild |
| 806 | card form of import --- ``import *`` --- is only allowed at the module level. |
Ezio Melotti | 4bbfa2a | 2009-09-16 01:18:27 +0000 | [diff] [blame] | 807 | Attempting to use it in class or function definitions will raise a |
Benjamin Peterson | 9611b5e | 2009-03-25 21:50:43 +0000 | [diff] [blame] | 808 | :exc:`SyntaxError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 809 | |
| 810 | .. index:: |
Brett Cannon | e43b060 | 2009-03-21 03:11:16 +0000 | [diff] [blame] | 811 | single: relative; import |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 812 | |
Brett Cannon | e43b060 | 2009-03-21 03:11:16 +0000 | [diff] [blame] | 813 | When specifying what module to import you do not have to specify the absolute |
| 814 | name of the module. When a module or package is contained within another |
| 815 | package it is possible to make a relative import within the same top package |
| 816 | without having to mention the package name. By using leading dots in the |
| 817 | specified module or package after :keyword:`from` you can specify how high to |
| 818 | traverse up the current package hierarchy without specifying exact names. One |
| 819 | leading dot means the current package where the module making the import |
| 820 | exists. Two dots means up one package level. Three dots is up two levels, etc. |
| 821 | So if you execute ``from . import mod`` from a module in the ``pkg`` package |
| 822 | then you will end up importing ``pkg.mod``. If you execute ``from ..subpkg2 |
Florent Xicluna | 0c8414e | 2010-09-03 20:23:40 +0000 | [diff] [blame] | 823 | import mod`` from within ``pkg.subpkg1`` you will import ``pkg.subpkg2.mod``. |
Brett Cannon | e43b060 | 2009-03-21 03:11:16 +0000 | [diff] [blame] | 824 | The specification for relative imports is contained within :pep:`328`. |
Georg Brandl | 5b318c0 | 2008-08-03 09:47:27 +0000 | [diff] [blame] | 825 | |
Benjamin Peterson | fa0d703 | 2009-06-01 22:42:33 +0000 | [diff] [blame] | 826 | :func:`importlib.import_module` is provided to support applications that |
| 827 | determine which modules need to be loaded dynamically. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 828 | |
| 829 | |
| 830 | .. _future: |
| 831 | |
| 832 | Future statements |
| 833 | ----------------- |
| 834 | |
| 835 | .. index:: pair: future; statement |
| 836 | |
| 837 | A :dfn:`future statement` is a directive to the compiler that a particular |
| 838 | module should be compiled using syntax or semantics that will be available in a |
| 839 | specified future release of Python. The future statement is intended to ease |
| 840 | migration to future versions of Python that introduce incompatible changes to |
| 841 | the language. It allows use of the new features on a per-module basis before |
| 842 | the release in which the feature becomes standard. |
| 843 | |
| 844 | .. productionlist:: * |
| 845 | future_statement: "from" "__future__" "import" feature ["as" name] |
| 846 | : ("," feature ["as" name])* |
| 847 | : | "from" "__future__" "import" "(" feature ["as" name] |
| 848 | : ("," feature ["as" name])* [","] ")" |
| 849 | feature: identifier |
| 850 | name: identifier |
| 851 | |
| 852 | A future statement must appear near the top of the module. The only lines that |
| 853 | can appear before a future statement are: |
| 854 | |
| 855 | * the module docstring (if any), |
| 856 | * comments, |
| 857 | * blank lines, and |
| 858 | * other future statements. |
| 859 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 860 | .. XXX change this if future is cleaned out |
| 861 | |
| 862 | The features recognized by Python 3.0 are ``absolute_import``, ``division``, |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 863 | ``generators``, ``unicode_literals``, ``print_function``, ``nested_scopes`` and |
| 864 | ``with_statement``. They are all redundant because they are always enabled, and |
| 865 | only kept for backwards compatibility. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 866 | |
| 867 | A future statement is recognized and treated specially at compile time: Changes |
| 868 | to the semantics of core constructs are often implemented by generating |
| 869 | different code. It may even be the case that a new feature introduces new |
| 870 | incompatible syntax (such as a new reserved word), in which case the compiler |
| 871 | may need to parse the module differently. Such decisions cannot be pushed off |
| 872 | until runtime. |
| 873 | |
| 874 | For any given release, the compiler knows which feature names have been defined, |
| 875 | and raises a compile-time error if a future statement contains a feature not |
| 876 | known to it. |
| 877 | |
| 878 | The direct runtime semantics are the same as for any import statement: there is |
| 879 | a standard module :mod:`__future__`, described later, and it will be imported in |
| 880 | the usual way at the time the future statement is executed. |
| 881 | |
| 882 | The interesting runtime semantics depend on the specific feature enabled by the |
| 883 | future statement. |
| 884 | |
| 885 | Note that there is nothing special about the statement:: |
| 886 | |
| 887 | import __future__ [as name] |
| 888 | |
| 889 | That is not a future statement; it's an ordinary import statement with no |
| 890 | special semantics or syntax restrictions. |
| 891 | |
Georg Brandl | 22b3431 | 2009-07-26 14:54:51 +0000 | [diff] [blame] | 892 | Code compiled by calls to the built-in functions :func:`exec` and :func:`compile` |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 893 | that occur in a module :mod:`M` containing a future statement will, by default, |
| 894 | use the new syntax or semantics associated with the future statement. This can |
| 895 | be controlled by optional arguments to :func:`compile` --- see the documentation |
| 896 | of that function for details. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 897 | |
| 898 | A future statement typed at an interactive interpreter prompt will take effect |
| 899 | for the rest of the interpreter session. If an interpreter is started with the |
| 900 | :option:`-i` option, is passed a script name to execute, and the script includes |
| 901 | a future statement, it will be in effect in the interactive session started |
| 902 | after the script is executed. |
| 903 | |
Georg Brandl | ff2ad0e | 2009-04-27 16:51:45 +0000 | [diff] [blame] | 904 | .. seealso:: |
| 905 | |
| 906 | :pep:`236` - Back to the __future__ |
| 907 | The original proposal for the __future__ mechanism. |
| 908 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 909 | |
| 910 | .. _global: |
| 911 | |
| 912 | The :keyword:`global` statement |
| 913 | =============================== |
| 914 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 915 | .. index:: |
| 916 | statement: global |
| 917 | triple: global; name; binding |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 918 | |
| 919 | .. productionlist:: |
| 920 | global_stmt: "global" `identifier` ("," `identifier`)* |
| 921 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 922 | The :keyword:`global` statement is a declaration which holds for the entire |
| 923 | current code block. It means that the listed identifiers are to be interpreted |
| 924 | as globals. It would be impossible to assign to a global variable without |
| 925 | :keyword:`global`, although free variables may refer to globals without being |
| 926 | declared global. |
| 927 | |
| 928 | Names listed in a :keyword:`global` statement must not be used in the same code |
| 929 | block textually preceding that :keyword:`global` statement. |
| 930 | |
| 931 | Names listed in a :keyword:`global` statement must not be defined as formal |
| 932 | parameters or in a :keyword:`for` loop control target, :keyword:`class` |
| 933 | definition, function definition, or :keyword:`import` statement. |
| 934 | |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 935 | .. impl-detail:: |
| 936 | |
| 937 | The current implementation does not enforce the latter two restrictions, but |
| 938 | programs should not abuse this freedom, as future implementations may enforce |
| 939 | them or silently change the meaning of the program. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 940 | |
| 941 | .. index:: |
| 942 | builtin: exec |
| 943 | builtin: eval |
| 944 | builtin: compile |
| 945 | |
| 946 | **Programmer's note:** the :keyword:`global` is a directive to the parser. It |
| 947 | applies only to code parsed at the same time as the :keyword:`global` statement. |
| 948 | In particular, a :keyword:`global` statement contained in a string or code |
Georg Brandl | c4a55fc | 2010-02-06 18:46:57 +0000 | [diff] [blame] | 949 | object supplied to the built-in :func:`exec` function does not affect the code |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 950 | block *containing* the function call, and code contained in such a string is |
| 951 | unaffected by :keyword:`global` statements in the code containing the function |
| 952 | call. The same applies to the :func:`eval` and :func:`compile` functions. |
| 953 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 954 | |
| 955 | .. _nonlocal: |
| 956 | |
| 957 | The :keyword:`nonlocal` statement |
| 958 | ================================= |
| 959 | |
| 960 | .. index:: statement: nonlocal |
| 961 | |
| 962 | .. productionlist:: |
| 963 | nonlocal_stmt: "nonlocal" `identifier` ("," `identifier`)* |
| 964 | |
Georg Brandl | c5d98b4 | 2007-12-04 18:11:03 +0000 | [diff] [blame] | 965 | .. XXX add when implemented |
Georg Brandl | 06788c9 | 2009-01-03 21:31:47 +0000 | [diff] [blame] | 966 | : ["=" (`target_list` "=")+ expression_list] |
| 967 | : | "nonlocal" identifier augop expression_list |
Georg Brandl | c5d98b4 | 2007-12-04 18:11:03 +0000 | [diff] [blame] | 968 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 969 | The :keyword:`nonlocal` statement causes the listed identifiers to refer to |
| 970 | previously bound variables in the nearest enclosing scope. This is important |
| 971 | because the default behavior for binding is to search the local namespace |
Georg Brandl | c5d98b4 | 2007-12-04 18:11:03 +0000 | [diff] [blame] | 972 | first. The statement allows encapsulated code to rebind variables outside of |
| 973 | the local scope besides the global (module) scope. |
| 974 | |
Georg Brandl | c5d98b4 | 2007-12-04 18:11:03 +0000 | [diff] [blame] | 975 | .. XXX not implemented |
| 976 | The :keyword:`nonlocal` statement may prepend an assignment or augmented |
| 977 | assignment, but not an expression. |
| 978 | |
| 979 | Names listed in a :keyword:`nonlocal` statement, unlike to those listed in a |
| 980 | :keyword:`global` statement, must refer to pre-existing bindings in an |
| 981 | enclosing scope (the scope in which a new binding should be created cannot |
| 982 | be determined unambiguously). |
| 983 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 984 | Names listed in a :keyword:`nonlocal` statement must not collide with |
Georg Brandl | c5d98b4 | 2007-12-04 18:11:03 +0000 | [diff] [blame] | 985 | pre-existing bindings in the local scope. |
| 986 | |
| 987 | .. seealso:: |
| 988 | |
| 989 | :pep:`3104` - Access to Names in Outer Scopes |
| 990 | The specification for the :keyword:`nonlocal` statement. |