1 .. _compound: 2 3 ******************* 4 Compound statements 5 ******************* 6 7 .. index:: pair: compound; statement 8 9 Compound statements contain (groups of) other statements; they affect or control 10 the execution of those other statements in some way. In general, compound 11 statements span multiple lines, although in simple incarnations a whole compound 12 statement may be contained in one line. 13 14 The :keyword:`if`, :keyword:`while` and :keyword:`for` statements implement 15 traditional control flow constructs. :keyword:`try` specifies exception 16 handlers and/or cleanup code for a group of statements, while the 17 :keyword:`with` statement allows the execution of initialization and 18 finalization code around a block of code. Function and class definitions are 19 also syntactically compound statements. 20 21 .. index:: 22 single: clause 23 single: suite 24 25 A compound statement consists of one or more 'clauses.' A clause consists of a 26 header and a 'suite.' The clause headers of a particular compound statement are 27 all at the same indentation level. Each clause header begins with a uniquely 28 identifying keyword and ends with a colon. A suite is a group of statements 29 controlled by a clause. A suite can be one or more semicolon-separated simple 30 statements on the same line as the header, following the header's colon, or it 31 can be one or more indented statements on subsequent lines. Only the latter 32 form of a suite can contain nested compound statements; the following is illegal, 33 mostly because it wouldn't be clear to which :keyword:`if` clause a following 34 :keyword:`else` clause would belong:: 35 36 if test1: if test2: print(x) 37 38 Also note that the semicolon binds tighter than the colon in this context, so 39 that in the following example, either all or none of the :func:`print` calls are 40 executed:: 41 42 if x < y < z: print(x); print(y); print(z) 43 44 Summarizing: 45 46 .. productionlist:: 47 compound_stmt: `if_stmt` 48 : | `while_stmt` 49 : | `for_stmt` 50 : | `try_stmt` 51 : | `with_stmt` 52 : | `funcdef` 53 : | `classdef` 54 : | `async_with_stmt` 55 : | `async_for_stmt` 56 : | `async_funcdef` 57 suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT 58 statement: `stmt_list` NEWLINE | `compound_stmt` 59 stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"] 60 61 .. index:: 62 single: NEWLINE token 63 single: DEDENT token 64 pair: dangling; else 65 66 Note that statements always end in a ``NEWLINE`` possibly followed by a 67 ``DEDENT``. Also note that optional continuation clauses always begin with a 68 keyword that cannot start a statement, thus there are no ambiguities (the 69 'dangling :keyword:`else`' problem is solved in Python by requiring nested 70 :keyword:`if` statements to be indented). 71 72 The formatting of the grammar rules in the following sections places each clause 73 on a separate line for clarity. 74 75 76 .. _if: 77 .. _elif: 78 .. _else: 79 80 The :keyword:`if` statement 81 =========================== 82 83 .. index:: 84 statement: if 85 keyword: elif 86 keyword: else 87 keyword: elif 88 keyword: else 89 90 The :keyword:`if` statement is used for conditional execution: 91 92 .. productionlist:: 93 if_stmt: "if" `expression` ":" `suite` 94 : ( "elif" `expression` ":" `suite` )* 95 : ["else" ":" `suite`] 96 97 It selects exactly one of the suites by evaluating the expressions one by one 98 until one is found to be true (see section :ref:`booleans` for the definition of 99 true and false); then that suite is executed (and no other part of the 100 :keyword:`if` statement is executed or evaluated). If all expressions are 101 false, the suite of the :keyword:`else` clause, if present, is executed. 102 103 104 .. _while: 105 106 The :keyword:`while` statement 107 ============================== 108 109 .. index:: 110 statement: while 111 keyword: else 112 pair: loop; statement 113 keyword: else 114 115 The :keyword:`while` statement is used for repeated execution as long as an 116 expression is true: 117 118 .. productionlist:: 119 while_stmt: "while" `expression` ":" `suite` 120 : ["else" ":" `suite`] 121 122 This repeatedly tests the expression and, if it is true, executes the first 123 suite; if the expression is false (which may be the first time it is tested) the 124 suite of the :keyword:`else` clause, if present, is executed and the loop 125 terminates. 126 127 .. index:: 128 statement: break 129 statement: continue 130 131 A :keyword:`break` statement executed in the first suite terminates the loop 132 without executing the :keyword:`else` clause's suite. A :keyword:`continue` 133 statement executed in the first suite skips the rest of the suite and goes back 134 to testing the expression. 135 136 137 .. _for: 138 139 The :keyword:`for` statement 140 ============================ 141 142 .. index:: 143 statement: for 144 keyword: in 145 keyword: else 146 pair: target; list 147 pair: loop; statement 148 keyword: in 149 keyword: else 150 pair: target; list 151 object: sequence 152 153 The :keyword:`for` statement is used to iterate over the elements of a sequence 154 (such as a string, tuple or list) or other iterable object: 155 156 .. productionlist:: 157 for_stmt: "for" `target_list` "in" `expression_list` ":" `suite` 158 : ["else" ":" `suite`] 159 160 The expression list is evaluated once; it should yield an iterable object. An 161 iterator is created for the result of the ``expression_list``. The suite is 162 then executed once for each item provided by the iterator, in the order returned 163 by the iterator. Each item in turn is assigned to the target list using the 164 standard rules for assignments (see :ref:`assignment`), and then the suite is 165 executed. When the items are exhausted (which is immediately when the sequence 166 is empty or an iterator raises a :exc:`StopIteration` exception), the suite in 167 the :keyword:`else` clause, if present, is executed, and the loop terminates. 168 169 .. index:: 170 statement: break 171 statement: continue 172 173 A :keyword:`break` statement executed in the first suite terminates the loop 174 without executing the :keyword:`else` clause's suite. A :keyword:`continue` 175 statement executed in the first suite skips the rest of the suite and continues 176 with the next item, or with the :keyword:`else` clause if there is no next 177 item. 178 179 The for-loop makes assignments to the variables(s) in the target list. 180 This overwrites all previous assignments to those variables including 181 those made in the suite of the for-loop:: 182 183 for i in range(10): 184 print(i) 185 i = 5 # this will not affect the for-loop 186 # because i will be overwritten with the next 187 # index in the range 188 189 190 .. index:: 191 builtin: range 192 193 Names in the target list are not deleted when the loop is finished, but if the 194 sequence is empty, they will not have been assigned to at all by the loop. Hint: 195 the built-in function :func:`range` returns an iterator of integers suitable to 196 emulate the effect of Pascal's ``for i := a to b do``; e.g., ``list(range(3))`` 197 returns the list ``[0, 1, 2]``. 198 199 .. note:: 200 201 .. index:: 202 single: loop; over mutable sequence 203 single: mutable sequence; loop over 204 205 There is a subtlety when the sequence is being modified by the loop (this can 206 only occur for mutable sequences, i.e. lists). An internal counter is used 207 to keep track of which item is used next, and this is incremented on each 208 iteration. When this counter has reached the length of the sequence the loop 209 terminates. This means that if the suite deletes the current (or a previous) 210 item from the sequence, the next item will be skipped (since it gets the 211 index of the current item which has already been treated). Likewise, if the 212 suite inserts an item in the sequence before the current item, the current 213 item will be treated again the next time through the loop. This can lead to 214 nasty bugs that can be avoided by making a temporary copy using a slice of 215 the whole sequence, e.g., :: 216 217 for x in a[:]: 218 if x < 0: a.remove(x) 219 220 221 .. _try: 222 .. _except: 223 .. _finally: 224 225 The :keyword:`try` statement 226 ============================ 227 228 .. index:: 229 statement: try 230 keyword: except 231 keyword: finally 232 .. index:: keyword: except 233 234 The :keyword:`try` statement specifies exception handlers and/or cleanup code 235 for a group of statements: 236 237 .. productionlist:: 238 try_stmt: try1_stmt | try2_stmt 239 try1_stmt: "try" ":" `suite` 240 : ("except" [`expression` ["as" `identifier`]] ":" `suite`)+ 241 : ["else" ":" `suite`] 242 : ["finally" ":" `suite`] 243 try2_stmt: "try" ":" `suite` 244 : "finally" ":" `suite` 245 246 247 The :keyword:`except` clause(s) specify one or more exception handlers. When no 248 exception occurs in the :keyword:`try` clause, no exception handler is executed. 249 When an exception occurs in the :keyword:`try` suite, a search for an exception 250 handler is started. This search inspects the except clauses in turn until one 251 is found that matches the exception. An expression-less except clause, if 252 present, must be last; it matches any exception. For an except clause with an 253 expression, that expression is evaluated, and the clause matches the exception 254 if the resulting object is "compatible" with the exception. An object is 255 compatible with an exception if it is the class or a base class of the exception 256 object or a tuple containing an item compatible with the exception. 257 258 If no except clause matches the exception, the search for an exception handler 259 continues in the surrounding code and on the invocation stack. [#]_ 260 261 If the evaluation of an expression in the header of an except clause raises an 262 exception, the original search for a handler is canceled and a search starts for 263 the new exception in the surrounding code and on the call stack (it is treated 264 as if the entire :keyword:`try` statement raised the exception). 265 266 When a matching except clause is found, the exception is assigned to the target 267 specified after the :keyword:`as` keyword in that except clause, if present, and 268 the except clause's suite is executed. All except clauses must have an 269 executable block. When the end of this block is reached, execution continues 270 normally after the entire try statement. (This means that if two nested 271 handlers exist for the same exception, and the exception occurs in the try 272 clause of the inner handler, the outer handler will not handle the exception.) 273 274 When an exception has been assigned using ``as target``, it is cleared at the 275 end of the except clause. This is as if :: 276 277 except E as N: 278 foo 279 280 was translated to :: 281 282 except E as N: 283 try: 284 foo 285 finally: 286 del N 287 288 This means the exception must be assigned to a different name to be able to 289 refer to it after the except clause. Exceptions are cleared because with the 290 traceback attached to them, they form a reference cycle with the stack frame, 291 keeping all locals in that frame alive until the next garbage collection occurs. 292 293 .. index:: 294 module: sys 295 object: traceback 296 297 Before an except clause's suite is executed, details about the exception are 298 stored in the :mod:`sys` module and can be accessed via :func:`sys.exc_info`. 299 :func:`sys.exc_info` returns a 3-tuple consisting of the exception class, the 300 exception instance and a traceback object (see section :ref:`types`) identifying 301 the point in the program where the exception occurred. :func:`sys.exc_info` 302 values are restored to their previous values (before the call) when returning 303 from a function that handled an exception. 304 305 .. index:: 306 keyword: else 307 statement: return 308 statement: break 309 statement: continue 310 311 The optional :keyword:`else` clause is executed if and when control flows off 312 the end of the :keyword:`try` clause. [#]_ Exceptions in the :keyword:`else` 313 clause are not handled by the preceding :keyword:`except` clauses. 314 315 .. index:: keyword: finally 316 317 If :keyword:`finally` is present, it specifies a 'cleanup' handler. The 318 :keyword:`try` clause is executed, including any :keyword:`except` and 319 :keyword:`else` clauses. If an exception occurs in any of the clauses and is 320 not handled, the exception is temporarily saved. The :keyword:`finally` clause 321 is executed. If there is a saved exception it is re-raised at the end of the 322 :keyword:`finally` clause. If the :keyword:`finally` clause raises another 323 exception, the saved exception is set as the context of the new exception. 324 If the :keyword:`finally` clause executes a :keyword:`return` or :keyword:`break` 325 statement, the saved exception is discarded:: 326 327 >>> def f(): 328 ... try: 329 ... 1/0 330 ... finally: 331 ... return 42 332 ... 333 >>> f() 334 42 335 336 The exception information is not available to the program during execution of 337 the :keyword:`finally` clause. 338 339 .. index:: 340 statement: return 341 statement: break 342 statement: continue 343 344 When a :keyword:`return`, :keyword:`break` or :keyword:`continue` statement is 345 executed in the :keyword:`try` suite of a :keyword:`try`...\ :keyword:`finally` 346 statement, the :keyword:`finally` clause is also executed 'on the way out.' A 347 :keyword:`continue` statement is illegal in the :keyword:`finally` clause. (The 348 reason is a problem with the current implementation --- this restriction may be 349 lifted in the future). 350 351 The return value of a function is determined by the last :keyword:`return` 352 statement executed. Since the :keyword:`finally` clause always executes, a 353 :keyword:`return` statement executed in the :keyword:`finally` clause will 354 always be the last one executed:: 355 356 >>> def foo(): 357 ... try: 358 ... return 'try' 359 ... finally: 360 ... return 'finally' 361 ... 362 >>> foo() 363 'finally' 364 365 Additional information on exceptions can be found in section :ref:`exceptions`, 366 and information on using the :keyword:`raise` statement to generate exceptions 367 may be found in section :ref:`raise`. 368 369 370 .. _with: 371 .. _as: 372 373 The :keyword:`with` statement 374 ============================= 375 376 .. index:: 377 statement: with 378 single: as; with statement 379 380 The :keyword:`with` statement is used to wrap the execution of a block with 381 methods defined by a context manager (see section :ref:`context-managers`). 382 This allows common :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` 383 usage patterns to be encapsulated for convenient reuse. 384 385 .. productionlist:: 386 with_stmt: "with" with_item ("," with_item)* ":" `suite` 387 with_item: `expression` ["as" `target`] 388 389 The execution of the :keyword:`with` statement with one "item" proceeds as follows: 390 391 #. The context expression (the expression given in the :token:`with_item`) is 392 evaluated to obtain a context manager. 393 394 #. The context manager's :meth:`__exit__` is loaded for later use. 395 396 #. The context manager's :meth:`__enter__` method is invoked. 397 398 #. If a target was included in the :keyword:`with` statement, the return value 399 from :meth:`__enter__` is assigned to it. 400 401 .. note:: 402 403 The :keyword:`with` statement guarantees that if the :meth:`__enter__` 404 method returns without an error, then :meth:`__exit__` will always be 405 called. Thus, if an error occurs during the assignment to the target list, 406 it will be treated the same as an error occurring within the suite would 407 be. See step 6 below. 408 409 #. The suite is executed. 410 411 #. The context manager's :meth:`__exit__` method is invoked. If an exception 412 caused the suite to be exited, its type, value, and traceback are passed as 413 arguments to :meth:`__exit__`. Otherwise, three :const:`None` arguments are 414 supplied. 415 416 If the suite was exited due to an exception, and the return value from the 417 :meth:`__exit__` method was false, the exception is reraised. If the return 418 value was true, the exception is suppressed, and execution continues with the 419 statement following the :keyword:`with` statement. 420 421 If the suite was exited for any reason other than an exception, the return 422 value from :meth:`__exit__` is ignored, and execution proceeds at the normal 423 location for the kind of exit that was taken. 424 425 With more than one item, the context managers are processed as if multiple 426 :keyword:`with` statements were nested:: 427 428 with A() as a, B() as b: 429 suite 430 431 is equivalent to :: 432 433 with A() as a: 434 with B() as b: 435 suite 436 437 .. versionchanged:: 3.1 438 Support for multiple context expressions. 439 440 .. seealso:: 441 442 :pep:`343` - The "with" statement 443 The specification, background, and examples for the Python :keyword:`with` 444 statement. 445 446 447 .. index:: 448 single: parameter; function definition 449 450 .. _function: 451 .. _def: 452 453 Function definitions 454 ==================== 455 456 .. index:: 457 statement: def 458 pair: function; definition 459 pair: function; name 460 pair: name; binding 461 object: user-defined function 462 object: function 463 pair: function; name 464 pair: name; binding 465 466 A function definition defines a user-defined function object (see section 467 :ref:`types`): 468 469 .. productionlist:: 470 funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ["->" `expression`] ":" `suite` 471 decorators: `decorator`+ 472 decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE 473 dotted_name: `identifier` ("." `identifier`)* 474 parameter_list: `defparameter` ("," `defparameter`)* ["," [`parameter_list_starargs`]] 475 : | `parameter_list_starargs` 476 parameter_list_starargs: "*" [`parameter`] ("," `defparameter`)* ["," ["**" `parameter` [","]]] 477 : | "**" `parameter` [","] 478 parameter: `identifier` [":" `expression`] 479 defparameter: `parameter` ["=" `expression`] 480 funcname: `identifier` 481 482 483 A function definition is an executable statement. Its execution binds the 484 function name in the current local namespace to a function object (a wrapper 485 around the executable code for the function). This function object contains a 486 reference to the current global namespace as the global namespace to be used 487 when the function is called. 488 489 The function definition does not execute the function body; this gets executed 490 only when the function is called. [#]_ 491 492 .. index:: 493 statement: @ 494 495 A function definition may be wrapped by one or more :term:`decorator` expressions. 496 Decorator expressions are evaluated when the function is defined, in the scope 497 that contains the function definition. The result must be a callable, which is 498 invoked with the function object as the only argument. The returned value is 499 bound to the function name instead of the function object. Multiple decorators 500 are applied in nested fashion. For example, the following code :: 501 502 @f1(arg) 503 @f2 504 def func(): pass 505 506 is roughly equivalent to :: 507 508 def func(): pass 509 func = f1(arg)(f2(func)) 510 511 except that the original function is not temporarily bound to the name ``func``. 512 513 .. index:: 514 triple: default; parameter; value 515 single: argument; function definition 516 517 When one or more :term:`parameters <parameter>` have the form *parameter* ``=`` 518 *expression*, the function is said to have "default parameter values." For a 519 parameter with a default value, the corresponding :term:`argument` may be 520 omitted from a call, in which 521 case the parameter's default value is substituted. If a parameter has a default 522 value, all following parameters up until the "``*``" must also have a default 523 value --- this is a syntactic restriction that is not expressed by the grammar. 524 525 **Default parameter values are evaluated from left to right when the function 526 definition is executed.** This means that the expression is evaluated once, when 527 the function is defined, and that the same "pre-computed" value is used for each 528 call. This is especially important to understand when a default parameter is a 529 mutable object, such as a list or a dictionary: if the function modifies the 530 object (e.g. by appending an item to a list), the default value is in effect 531 modified. This is generally not what was intended. A way around this is to use 532 ``None`` as the default, and explicitly test for it in the body of the function, 533 e.g.:: 534 535 def whats_on_the_telly(penguin=None): 536 if penguin is None: 537 penguin = [] 538 penguin.append("property of the zoo") 539 return penguin 540 541 .. index:: 542 statement: * 543 statement: ** 544 545 Function call semantics are described in more detail in section :ref:`calls`. A 546 function call always assigns values to all parameters mentioned in the parameter 547 list, either from position arguments, from keyword arguments, or from default 548 values. If the form "``*identifier``" is present, it is initialized to a tuple 549 receiving any excess positional parameters, defaulting to the empty tuple. 550 If the form "``**identifier``" is present, it is initialized to a new 551 ordered mapping receiving any excess keyword arguments, defaulting to a 552 new empty mapping of the same type. Parameters after "``*``" or 553 "``*identifier``" are keyword-only parameters and may only be passed 554 used keyword arguments. 555 556 .. index:: pair: function; annotations 557 558 Parameters may have annotations of the form "``: expression``" following the 559 parameter name. Any parameter may have an annotation even those of the form 560 ``*identifier`` or ``**identifier``. Functions may have "return" annotation of 561 the form "``-> expression``" after the parameter list. These annotations can be 562 any valid Python expression and are evaluated when the function definition is 563 executed. Annotations may be evaluated in a different order than they appear in 564 the source code. The presence of annotations does not change the semantics of a 565 function. The annotation values are available as values of a dictionary keyed 566 by the parameters' names in the :attr:`__annotations__` attribute of the 567 function object. 568 569 .. index:: pair: lambda; expression 570 571 It is also possible to create anonymous functions (functions not bound to a 572 name), for immediate use in expressions. This uses lambda expressions, described in 573 section :ref:`lambda`. Note that the lambda expression is merely a shorthand for a 574 simplified function definition; a function defined in a ":keyword:`def`" 575 statement can be passed around or assigned to another name just like a function 576 defined by a lambda expression. The ":keyword:`def`" form is actually more powerful 577 since it allows the execution of multiple statements and annotations. 578 579 **Programmer's note:** Functions are first-class objects. A "``def``" statement 580 executed inside a function definition defines a local function that can be 581 returned or passed around. Free variables used in the nested function can 582 access the local variables of the function containing the def. See section 583 :ref:`naming` for details. 584 585 .. seealso:: 586 587 :pep:`3107` - Function Annotations 588 The original specification for function annotations. 589 590 591 .. _class: 592 593 Class definitions 594 ================= 595 596 .. index:: 597 object: class 598 statement: class 599 pair: class; definition 600 pair: class; name 601 pair: name; binding 602 pair: execution; frame 603 single: inheritance 604 single: docstring 605 606 A class definition defines a class object (see section :ref:`types`): 607 608 .. productionlist:: 609 classdef: [`decorators`] "class" `classname` [`inheritance`] ":" `suite` 610 inheritance: "(" [`argument_list`] ")" 611 classname: `identifier` 612 613 A class definition is an executable statement. The inheritance list usually 614 gives a list of base classes (see :ref:`metaclasses` for more advanced uses), so 615 each item in the list should evaluate to a class object which allows 616 subclassing. Classes without an inheritance list inherit, by default, from the 617 base class :class:`object`; hence, :: 618 619 class Foo: 620 pass 621 622 is equivalent to :: 623 624 class Foo(object): 625 pass 626 627 The class's suite is then executed in a new execution frame (see :ref:`naming`), 628 using a newly created local namespace and the original global namespace. 629 (Usually, the suite contains mostly function definitions.) When the class's 630 suite finishes execution, its execution frame is discarded but its local 631 namespace is saved. [#]_ A class object is then created using the inheritance 632 list for the base classes and the saved local namespace for the attribute 633 dictionary. The class name is bound to this class object in the original local 634 namespace. 635 636 The order in which attributes are defined in the class body is preserved 637 in the new class's ``__dict__``. Note that this is reliable only right 638 after the class is created and only for classes that were defined using 639 the definition syntax. 640 641 Class creation can be customized heavily using :ref:`metaclasses <metaclasses>`. 642 643 Classes can also be decorated: just like when decorating functions, :: 644 645 @f1(arg) 646 @f2 647 class Foo: pass 648 649 is roughly equivalent to :: 650 651 class Foo: pass 652 Foo = f1(arg)(f2(Foo)) 653 654 The evaluation rules for the decorator expressions are the same as for function 655 decorators. The result is then bound to the class name. 656 657 **Programmer's note:** Variables defined in the class definition are class 658 attributes; they are shared by instances. Instance attributes can be set in a 659 method with ``self.name = value``. Both class and instance attributes are 660 accessible through the notation "``self.name``", and an instance attribute hides 661 a class attribute with the same name when accessed in this way. Class 662 attributes can be used as defaults for instance attributes, but using mutable 663 values there can lead to unexpected results. :ref:`Descriptors <descriptors>` 664 can be used to create instance variables with different implementation details. 665 666 667 .. seealso:: 668 669 :pep:`3115` - Metaclasses in Python 3 670 :pep:`3129` - Class Decorators 671 672 673 Coroutines 674 ========== 675 676 .. versionadded:: 3.5 677 678 .. index:: statement: async def 679 .. _`async def`: 680 681 Coroutine function definition 682 ----------------------------- 683 684 .. productionlist:: 685 async_funcdef: [`decorators`] "async" "def" `funcname` "(" [`parameter_list`] ")" ["->" `expression`] ":" `suite` 686 687 .. index:: 688 keyword: async 689 keyword: await 690 691 Execution of Python coroutines can be suspended and resumed at many points 692 (see :term:`coroutine`). In the body of a coroutine, any ``await`` and 693 ``async`` identifiers become reserved keywords; :keyword:`await` expressions, 694 :keyword:`async for` and :keyword:`async with` can only be used in 695 coroutine bodies. 696 697 Functions defined with ``async def`` syntax are always coroutine functions, 698 even if they do not contain ``await`` or ``async`` keywords. 699 700 It is a :exc:`SyntaxError` to use ``yield from`` expressions in 701 ``async def`` coroutines. 702 703 An example of a coroutine function:: 704 705 async def func(param1, param2): 706 do_stuff() 707 await some_coroutine() 708 709 710 .. index:: statement: async for 711 .. _`async for`: 712 713 The :keyword:`async for` statement 714 ---------------------------------- 715 716 .. productionlist:: 717 async_for_stmt: "async" `for_stmt` 718 719 An :term:`asynchronous iterable` is able to call asynchronous code in its 720 *iter* implementation, and :term:`asynchronous iterator` can call asynchronous 721 code in its *next* method. 722 723 The ``async for`` statement allows convenient iteration over asynchronous 724 iterators. 725 726 The following code:: 727 728 async for TARGET in ITER: 729 BLOCK 730 else: 731 BLOCK2 732 733 Is semantically equivalent to:: 734 735 iter = (ITER) 736 iter = type(iter).__aiter__(iter) 737 running = True 738 while running: 739 try: 740 TARGET = await type(iter).__anext__(iter) 741 except StopAsyncIteration: 742 running = False 743 else: 744 BLOCK 745 else: 746 BLOCK2 747 748 See also :meth:`__aiter__` and :meth:`__anext__` for details. 749 750 It is a :exc:`SyntaxError` to use ``async for`` statement outside of an 751 :keyword:`async def` function. 752 753 754 .. index:: statement: async with 755 .. _`async with`: 756 757 The :keyword:`async with` statement 758 ----------------------------------- 759 760 .. productionlist:: 761 async_with_stmt: "async" `with_stmt` 762 763 An :term:`asynchronous context manager` is a :term:`context manager` that is 764 able to suspend execution in its *enter* and *exit* methods. 765 766 The following code:: 767 768 async with EXPR as VAR: 769 BLOCK 770 771 Is semantically equivalent to:: 772 773 mgr = (EXPR) 774 aexit = type(mgr).__aexit__ 775 aenter = type(mgr).__aenter__(mgr) 776 exc = True 777 778 VAR = await aenter 779 try: 780 BLOCK 781 except: 782 if not await aexit(mgr, *sys.exc_info()): 783 raise 784 else: 785 await aexit(mgr, None, None, None) 786 787 See also :meth:`__aenter__` and :meth:`__aexit__` for details. 788 789 It is a :exc:`SyntaxError` to use ``async with`` statement outside of an 790 :keyword:`async def` function. 791 792 .. seealso:: 793 794 :pep:`492` - Coroutines with async and await syntax 795 796 797 .. rubric:: Footnotes 798 799 .. [#] The exception is propagated to the invocation stack unless 800 there is a :keyword:`finally` clause which happens to raise another 801 exception. That new exception causes the old one to be lost. 802 803 .. [#] Currently, control "flows off the end" except in the case of an exception 804 or the execution of a :keyword:`return`, :keyword:`continue`, or 805 :keyword:`break` statement. 806 807 .. [#] A string literal appearing as the first statement in the function body is 808 transformed into the function's ``__doc__`` attribute and therefore the 809 function's :term:`docstring`. 810 811 .. [#] A string literal appearing as the first statement in the class body is 812 transformed into the namespace's ``__doc__`` item and therefore the class's 813 :term:`docstring`. 814