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