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