1 

     2 .. _compound:

     3 

     4 *******************

     5 Compound statements

     6 *******************

     7 

     8 .. index:: pair: compound; statement

     9 

    10 Compound statements contain (groups of) other statements; they affect or control

    11 the execution of those other statements in some way.  In general, compound

    12 statements span multiple lines, although in simple incarnations a whole compound

    13 statement may be contained in one line.

    14 

    15 The :keyword:`if`, :keyword:`while` and :keyword:`for` statements implement

    16 traditional control flow constructs.  :keyword:`try` specifies exception

    17 handlers and/or cleanup code for a group of statements.  Function and class

    18 definitions are also syntactically compound statements.

    19 

    20 .. index::

    21    single: clause

    22    single: suite

    23 

    24 Compound statements consist of one or more 'clauses.'  A clause consists of a

    25 header and a 'suite.'  The clause headers of a particular compound statement are

    26 all at the same indentation level. Each clause header begins with a uniquely

    27 identifying keyword and ends with a colon.  A suite is a group of statements

    28 controlled by a clause.  A suite can be one or more semicolon-separated simple

    29 statements on the same line as the header, following the header's colon, or it

    30 can be one or more indented statements on subsequent lines.  Only the latter

    31 form of suite can contain nested compound statements; the following is illegal,

    32 mostly because it wouldn't be clear to which :keyword:`if` clause a following

    33 :keyword:`else` clause would belong:   ::

    34 

    35    if test1: if test2: print x

    36 

    37 Also note that the semicolon binds tighter than the colon in this context, so

    38 that in the following example, either all or none of the :keyword:`print`

    39 statements are executed::

    40 

    41    if x < y < z: print x; print y; print z

    42 

    43 Summarizing:

    44 

    45 .. productionlist::

    46    compound_stmt: `if_stmt`

    47                 : | `while_stmt`

    48                 : | `for_stmt`

    49                 : | `try_stmt`

    50                 : | `with_stmt`

    51                 : | `funcdef`

    52                 : | `classdef`

    53                 : | `decorated`

    54    suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT

    55    statement: `stmt_list` NEWLINE | `compound_stmt`

    56    stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"]

    57 

    58 .. index::

    59    single: NEWLINE token

    60    single: DEDENT token

    61    pair: dangling; else

    62 

    63 Note that statements always end in a ``NEWLINE`` possibly followed by a

    64 ``DEDENT``. Also note that optional continuation clauses always begin with a

    65 keyword that cannot start a statement, thus there are no ambiguities (the

    66 'dangling :keyword:`else`' problem is solved in Python by requiring nested

    67 :keyword:`if` statements to be indented).

    68 

    69 The formatting of the grammar rules in the following sections places each clause

    70 on a separate line for clarity.

    71 

    72 

    73 .. _if:

    74 .. _elif:

    75 .. _else:

    76 

    77 The :keyword:`if` statement

    78 ===========================

    79 

    80 .. index::

    81    statement: if

    82    keyword: elif

    83    keyword: else

    84 

    85 The :keyword:`if` statement is used for conditional execution:

    86 

    87 .. productionlist::

    88    if_stmt: "if" `expression` ":" `suite`

    89           : ( "elif" `expression` ":" `suite` )*

    90           : ["else" ":" `suite`]

    91 

    92 It selects exactly one of the suites by evaluating the expressions one by one

    93 until one is found to be true (see section :ref:`booleans` for the definition of

    94 true and false); then that suite is executed (and no other part of the

    95 :keyword:`if` statement is executed or evaluated).  If all expressions are

    96 false, the suite of the :keyword:`else` clause, if present, is executed.

    97 

    98 

    99 .. _while:

   100 

   101 The :keyword:`while` statement

   102 ==============================

   103 

   104 .. index::

   105    statement: while

   106    pair: loop; statement

   107    keyword: else

   108 

   109 The :keyword:`while` statement is used for repeated execution as long as an

   110 expression is true:

   111 

   112 .. productionlist::

   113    while_stmt: "while" `expression` ":" `suite`

   114              : ["else" ":" `suite`]

   115 

   116 This repeatedly tests the expression and, if it is true, executes the first

   117 suite; if the expression is false (which may be the first time it is tested) the

   118 suite of the :keyword:`else` clause, if present, is executed and the loop

   119 terminates.

   120 

   121 .. index::

   122    statement: break

   123    statement: continue

   124 

   125 A :keyword:`break` statement executed in the first suite terminates the loop

   126 without executing the :keyword:`else` clause's suite.  A :keyword:`continue`

   127 statement executed in the first suite skips the rest of the suite and goes back

   128 to testing the expression.

   129 

   130 

   131 .. _for:

   132 

   133 The :keyword:`for` statement

   134 ============================

   135 

   136 .. index::

   137    statement: for

   138    pair: loop; statement

   139    keyword: in

   140    keyword: else

   141    pair: target; list

   142    object: sequence

   143 

   144 The :keyword:`for` statement is used to iterate over the elements of a sequence

   145 (such as a string, tuple or list) or other iterable object:

   146 

   147 .. productionlist::

   148    for_stmt: "for" `target_list` "in" `expression_list` ":" `suite`

   149            : ["else" ":" `suite`]

   150 

   151 The expression list is evaluated once; it should yield an iterable object.  An

   152 iterator is created for the result of the ``expression_list``.  The suite is

   153 then executed once for each item provided by the iterator, in the order of

   154 ascending indices.  Each item in turn is assigned to the target list using the

   155 standard rules for assignments, and then the suite is executed.  When the items

   156 are exhausted (which is immediately when the sequence is empty), the suite in

   157 the :keyword:`else` clause, if present, is executed, and the loop terminates.

   158 

   159 .. index::

   160    statement: break

   161    statement: continue

   162 

   163 A :keyword:`break` statement executed in the first suite terminates the loop

   164 without executing the :keyword:`else` clause's suite.  A :keyword:`continue`

   165 statement executed in the first suite skips the rest of the suite and continues

   166 with the next item, or with the :keyword:`else` clause if there was no next

   167 item.

   168 

   169 The suite may assign to the variable(s) in the target list; this does not affect

   170 the next item assigned to it.

   171 

   172 .. index::

   173    builtin: range

   174    pair: Pascal; language

   175 

   176 The target list is not deleted when the loop is finished, but if the sequence is

   177 empty, it will not have been assigned to at all by the loop.  Hint: the built-in

   178 function :func:`range` returns a sequence of integers suitable to emulate the

   179 effect of Pascal's ``for i := a to b do``; e.g., ``range(3)`` returns the list

   180 ``[0, 1, 2]``.

   181 

   182 .. warning::

   183 

   184    .. index::

   185       single: loop; over mutable sequence

   186       single: mutable sequence; loop over

   187 

   188    There is a subtlety when the sequence is being modified by the loop (this can

   189    only occur for mutable sequences, i.e. lists). An internal counter is used to

   190    keep track of which item is used next, and this is incremented on each

   191    iteration.  When this counter has reached the length of the sequence the loop

   192    terminates.  This means that if the suite deletes the current (or a previous)

   193    item from the sequence, the next item will be skipped (since it gets the index

   194    of the current item which has already been treated).  Likewise, if the suite

   195    inserts an item in the sequence before the current item, the current item will

   196    be treated again the next time through the loop. This can lead to nasty bugs

   197    that can be avoided by making a temporary copy using a slice of the whole

   198    sequence, e.g.,

   199 

   200 ::

   201 

   202    for x in a[:]:

   203        if x < 0: a.remove(x)

   204 

   205 

   206 .. _try:

   207 .. _except:

   208 .. _finally:

   209 

   210 The :keyword:`try` statement

   211 ============================

   212 

   213 .. index::

   214    statement: try

   215    keyword: except

   216    keyword: finally

   217 

   218 The :keyword:`try` statement specifies exception handlers and/or cleanup code

   219 for a group of statements:

   220 

   221 .. productionlist::

   222    try_stmt: try1_stmt | try2_stmt

   223    try1_stmt: "try" ":" `suite`

   224             : ("except" [`expression` [("as" | ",") `target`]] ":" `suite`)+

   225             : ["else" ":" `suite`]

   226             : ["finally" ":" `suite`]

   227    try2_stmt: "try" ":" `suite`

   228             : "finally" ":" `suite`

   229 

   230 .. versionchanged:: 2.5

   231    In previous versions of Python, :keyword:`try`...\ :keyword:`except`...\

   232    :keyword:`finally` did not work. :keyword:`try`...\ :keyword:`except` had to be

   233    nested in :keyword:`try`...\ :keyword:`finally`.

   234 

   235 The :keyword:`except` clause(s) specify one or more exception handlers. When no

   236 exception occurs in the :keyword:`try` clause, no exception handler is executed.

   237 When an exception occurs in the :keyword:`try` suite, a search for an exception

   238 handler is started.  This search inspects the except clauses in turn until one

   239 is found that matches the exception.  An expression-less except clause, if

   240 present, must be last; it matches any exception.  For an except clause with an

   241 expression, that expression is evaluated, and the clause matches the exception

   242 if the resulting object is "compatible" with the exception.  An object is

   243 compatible with an exception if it is the class or a base class of the exception

   244 object, a tuple containing an item compatible with the exception, or, in the

   245 (deprecated) case of string exceptions, is the raised string itself (note that

   246 the object identities must match, i.e. it must be the same string object, not

   247 just a string with the same value).

   248 

   249 If no except clause matches the exception, the search for an exception handler

   250 continues in the surrounding code and on the invocation stack.  [#]_

   251 

   252 If the evaluation of an expression in the header of an except clause raises an

   253 exception, the original search for a handler is canceled and a search starts for

   254 the new exception in the surrounding code and on the call stack (it is treated

   255 as if the entire :keyword:`try` statement raised the exception).

   256 

   257 When a matching except clause is found, the exception is assigned to the target

   258 specified in that except clause, if present, and the except clause's suite is

   259 executed.  All except clauses must have an executable block.  When the end of

   260 this block is reached, execution continues normally after the entire try

   261 statement.  (This means that if two nested handlers exist for the same

   262 exception, and the exception occurs in the try clause of the inner handler, the

   263 outer handler will not handle the exception.)

   264 

   265 .. index::

   266    module: sys

   267    object: traceback

   268    single: exc_type (in module sys)

   269    single: exc_value (in module sys)

   270    single: exc_traceback (in module sys)

   271 

   272 Before an except clause's suite is executed, details about the exception are

   273 assigned to three variables in the :mod:`sys` module: ``sys.exc_type`` receives

   274 the object identifying the exception; ``sys.exc_value`` receives the exception's

   275 parameter; ``sys.exc_traceback`` receives a traceback object (see section

   276 :ref:`types`) identifying the point in the program where the exception

   277 occurred. These details are also available through the :func:`sys.exc_info`

   278 function, which returns a tuple ``(exc_type, exc_value, exc_traceback)``.  Use

   279 of the corresponding variables is deprecated in favor of this function, since

   280 their use is unsafe in a threaded program.  As of Python 1.5, the variables are

   281 restored to their previous values (before the call) when returning from a

   282 function that handled an exception.

   283 

   284 .. index::

   285    keyword: else

   286    statement: return

   287    statement: break

   288    statement: continue

   289 

   290 The optional :keyword:`else` clause is executed if and when control flows off

   291 the end of the :keyword:`try` clause. [#]_ Exceptions in the :keyword:`else`

   292 clause are not handled by the preceding :keyword:`except` clauses.

   293 

   294 .. index:: keyword: finally

   295 

   296 If :keyword:`finally` is present, it specifies a 'cleanup' handler.  The

   297 :keyword:`try` clause is executed, including any :keyword:`except` and

   298 :keyword:`else` clauses.  If an exception occurs in any of the clauses and is

   299 not handled, the exception is temporarily saved. The :keyword:`finally` clause

   300 is executed.  If there is a saved exception, it is re-raised at the end of the

   301 :keyword:`finally` clause. If the :keyword:`finally` clause raises another

   302 exception or executes a :keyword:`return` or :keyword:`break` statement, the

   303 saved exception is lost.  The exception information is not available to the

   304 program during execution of the :keyword:`finally` clause.

   305 

   306 .. index::

   307    statement: return

   308    statement: break

   309    statement: continue

   310 

   311 When a :keyword:`return`, :keyword:`break` or :keyword:`continue` statement is

   312 executed in the :keyword:`try` suite of a :keyword:`try`...\ :keyword:`finally`

   313 statement, the :keyword:`finally` clause is also executed 'on the way out.' A

   314 :keyword:`continue` statement is illegal in the :keyword:`finally` clause. (The

   315 reason is a problem with the current implementation --- this restriction may be

   316 lifted in the future).

   317 

   318 Additional information on exceptions can be found in section :ref:`exceptions`,

   319 and information on using the :keyword:`raise` statement to generate exceptions

   320 may be found in section :ref:`raise`.

   321 

   322 

   323 .. _with:

   324 .. _as:

   325 

   326 The :keyword:`with` statement

   327 =============================

   328 

   329 .. index:: statement: with

   330 

   331 .. versionadded:: 2.5

   332 

   333 The :keyword:`with` statement is used to wrap the execution of a block with

   334 methods defined by a context manager (see section :ref:`context-managers`). This

   335 allows common :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` usage

   336 patterns to be encapsulated for convenient reuse.

   337 

   338 .. productionlist::

   339    with_stmt: "with" `expression` ["as" `target`] ":" `suite`

   340 

   341 The execution of the :keyword:`with` statement proceeds as follows:

   342 

   343 #. The context expression is evaluated to obtain a context manager.

   344 

   345 #. The context manager's :meth:`__enter__` method is invoked.

   346 

   347 #. If a target was included in the :keyword:`with` statement, the return value

   348    from :meth:`__enter__` is assigned to it.

   349 

   350    .. note::

   351 

   352       The :keyword:`with` statement guarantees that if the :meth:`__enter__` method

   353       returns without an error, then :meth:`__exit__` will always be called. Thus, if

   354       an error occurs during the assignment to the target list, it will be treated the

   355       same as an error occurring within the suite would be. See step 5 below.

   356 

   357 #. The suite is executed.

   358 

   359 #. The context manager's :meth:`__exit__` method is invoked. If an exception

   360    caused the suite to be exited, its type, value, and traceback are passed as

   361    arguments to :meth:`__exit__`. Otherwise, three :const:`None` arguments are

   362    supplied.

   363 

   364    If the suite was exited due to an exception, and the return value from the

   365    :meth:`__exit__` method was false, the exception is reraised. If the return

   366    value was true, the exception is suppressed, and execution continues with the

   367    statement following the :keyword:`with` statement.

   368 

   369    If the suite was exited for any reason other than an exception, the return value

   370    from :meth:`__exit__` is ignored, and execution proceeds at the normal location

   371    for the kind of exit that was taken.

   372 

   373 .. note::

   374 

   375    In Python 2.5, the :keyword:`with` statement is only allowed when the

   376    ``with_statement`` feature has been enabled.  It is always enabled in

   377    Python 2.6.

   378 

   379 .. seealso::

   380 

   381    :pep:`0343` - The "with" statement

   382       The specification, background, and examples for the Python :keyword:`with`

   383       statement.

   384 

   385 

   386 .. _function:

   387 .. _def:

   388 

   389 Function definitions

   390 ====================

   391 

   392 .. index::

   393    statement: def

   394    pair: function; definition

   395    pair: function; name

   396    pair: name; binding

   397    object: user-defined function

   398    object: function

   399 

   400 A function definition defines a user-defined function object (see section

   401 :ref:`types`):

   402 

   403 .. productionlist::

   404    decorated: decorators (classdef | funcdef)

   405    decorators: `decorator`+

   406    decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE

   407    funcdef: "def" `funcname` "(" [`parameter_list`] ")" ":" `suite`

   408    dotted_name: `identifier` ("." `identifier`)*

   409    parameter_list: (`defparameter` ",")*

   410                  : (  "*" `identifier` [, "**" `identifier`]

   411                  : | "**" `identifier`

   412                  : | `defparameter` [","] )

   413    defparameter: `parameter` ["=" `expression`]

   414    sublist: `parameter` ("," `parameter`)* [","]

   415    parameter: `identifier` | "(" `sublist` ")"

   416    funcname: `identifier`

   417 

   418 A function definition is an executable statement.  Its execution binds the

   419 function name in the current local namespace to a function object (a wrapper

   420 around the executable code for the function).  This function object contains a

   421 reference to the current global namespace as the global namespace to be used

   422 when the function is called.

   423 

   424 The function definition does not execute the function body; this gets executed

   425 only when the function is called. [#]_

   426 

   427 .. index::

   428   statement: @

   429 

   430 A function definition may be wrapped by one or more :term:`decorator` expressions.

   431 Decorator expressions are evaluated when the function is defined, in the scope

   432 that contains the function definition.  The result must be a callable, which is

   433 invoked with the function object as the only argument. The returned value is

   434 bound to the function name instead of the function object.  Multiple decorators

   435 are applied in nested fashion. For example, the following code::

   436 

   437    @f1(arg)

   438    @f2

   439    def func(): pass

   440 

   441 is equivalent to::

   442 

   443    def func(): pass

   444    func = f1(arg)(f2(func))

   445 

   446 .. index:: triple: default; parameter; value

   447 

   448 When one or more top-level parameters have the form *parameter* ``=``

   449 *expression*, the function is said to have "default parameter values."  For a

   450 parameter with a default value, the corresponding argument may be omitted from a

   451 call, in which case the parameter's default value is substituted.  If a

   452 parameter has a default value, all following parameters must also have a default

   453 value --- this is a syntactic restriction that is not expressed by the grammar.

   454 

   455 **Default parameter values are evaluated when the function definition is

   456 executed.**  This means that the expression is evaluated once, when the function

   457 is defined, and that that same "pre-computed" value is used for each call.  This

   458 is especially important to understand when a default parameter is a mutable

   459 object, such as a list or a dictionary: if the function modifies the object

   460 (e.g. by appending an item to a list), the default value is in effect modified.

   461 This is generally not what was intended.  A way around this  is to use ``None``

   462 as the default, and explicitly test for it in the body of the function, e.g.::

   463 

   464    def whats_on_the_telly(penguin=None):

   465        if penguin is None:

   466            penguin = []

   467        penguin.append("property of the zoo")

   468        return penguin

   469 

   470 .. index::

   471   statement: *

   472   statement: **

   473 

   474 Function call semantics are described in more detail in section :ref:`calls`. A

   475 function call always assigns values to all parameters mentioned in the parameter

   476 list, either from position arguments, from keyword arguments, or from default

   477 values.  If the form "``*identifier``" is present, it is initialized to a tuple

   478 receiving any excess positional parameters, defaulting to the empty tuple.  If

   479 the form "``**identifier``" is present, it is initialized to a new dictionary

   480 receiving any excess keyword arguments, defaulting to a new empty dictionary.

   481 

   482 .. index:: pair: lambda; form

   483 

   484 It is also possible to create anonymous functions (functions not bound to a

   485 name), for immediate use in expressions.  This uses lambda forms, described in

   486 section :ref:`lambda`.  Note that the lambda form is merely a shorthand for a

   487 simplified function definition; a function defined in a ":keyword:`def`"

   488 statement can be passed around or assigned to another name just like a function

   489 defined by a lambda form.  The ":keyword:`def`" form is actually more powerful

   490 since it allows the execution of multiple statements.

   491 

   492 **Programmer's note:** Functions are first-class objects.  A "``def``" form

   493 executed inside a function definition defines a local function that can be

   494 returned or passed around.  Free variables used in the nested function can

   495 access the local variables of the function containing the def.  See section

   496 :ref:`naming` for details.

   497 

   498 

   499 .. _class:

   500 

   501 Class definitions

   502 =================

   503 

   504 .. index::

   505    object: class

   506    statement: class

   507    pair: class; definition

   508    pair: class; name

   509    pair: name; binding

   510    pair: execution; frame

   511    single: inheritance

   512    single: docstring

   513 

   514 A class definition defines a class object (see section :ref:`types`):

   515 

   516 .. productionlist::

   517    classdef: "class" `classname` [`inheritance`] ":" `suite`

   518    inheritance: "(" [`expression_list`] ")"

   519    classname: `identifier`

   520 

   521 A class definition is an executable statement.  It first evaluates the

   522 inheritance list, if present.  Each item in the inheritance list should evaluate

   523 to a class object or class type which allows subclassing.  The class's suite is

   524 then executed in a new execution frame (see section :ref:`naming`), using a

   525 newly created local namespace and the original global namespace. (Usually, the

   526 suite contains only function definitions.)  When the class's suite finishes

   527 execution, its execution frame is discarded but its local namespace is

   528 saved. [#]_ A class object is then created using the inheritance list for the

   529 base classes and the saved local namespace for the attribute dictionary.  The

   530 class name is bound to this class object in the original local namespace.

   531 

   532 **Programmer's note:** Variables defined in the class definition are class

   533 variables; they are shared by all instances.  To create instance variables, they

   534 can be set in a method with ``self.name = value``.  Both class and instance

   535 variables are accessible through the notation "``self.name``", and an instance

   536 variable hides a class variable with the same name when accessed in this way.

   537 Class variables can be used as defaults for instance variables, but using

   538 mutable values there can lead to unexpected results.  For :term:`new-style

   539 class`\es, descriptors can be used to create instance variables with different

   540 implementation details.

   541 

   542 Class definitions, like function definitions, may be wrapped by one or more

   543 :term:`decorator` expressions.  The evaluation rules for the decorator

   544 expressions are the same as for functions.  The result must be a class object,

   545 which is then bound to the class name.

   546 

   547 .. rubric:: Footnotes

   548 

   549 .. [#] The exception is propagated to the invocation stack only if there is no

   550    :keyword:`finally` clause that negates the exception.

   551 

   552 .. [#] Currently, control "flows off the end" except in the case of an exception or the

   553    execution of a :keyword:`return`, :keyword:`continue`, or :keyword:`break`

   554    statement.

   555 

   556 .. [#] A string literal appearing as the first statement in the function body is

   557    transformed into the function's ``__doc__`` attribute and therefore the

   558    function's :term:`docstring`.

   559 

   560 .. [#] A string literal appearing as the first statement in the class body is

   561    transformed into the namespace's ``__doc__`` item and therefore the class's

   562    :term:`docstring`.