| \chapter{Compound statements\label{compound}} |
| \indexii{compound}{statement} |
| |
| Compound statements contain (groups of) other statements; they affect |
| or control the execution of those other statements in some way. In |
| general, compound statements span multiple lines, although in simple |
| incarnations a whole compound statement may be contained in one line. |
| |
| The \keyword{if}, \keyword{while} and \keyword{for} statements implement |
| traditional control flow constructs. \keyword{try} specifies exception |
| handlers and/or cleanup code for a group of statements. Function and |
| class definitions are also syntactically compound statements. |
| |
| Compound statements consist of one or more `clauses.' A clause |
| consists of a header and a `suite.' The clause headers of a |
| particular compound statement are all at the same indentation level. |
| Each clause header begins with a uniquely identifying keyword and ends |
| with a colon. A suite is a group of statements controlled by a |
| clause. A suite can be one or more semicolon-separated simple |
| statements on the same line as the header, following the header's |
| colon, or it can be one or more indented statements on subsequent |
| lines. Only the latter form of suite can contain nested compound |
| statements; the following is illegal, mostly because it wouldn't be |
| clear to which \keyword{if} clause a following \keyword{else} clause would |
| belong: |
| \index{clause} |
| \index{suite} |
| |
| \begin{verbatim} |
| if test1: if test2: print x |
| \end{verbatim} |
| |
| Also note that the semicolon binds tighter than the colon in this |
| context, so that in the following example, either all or none of the |
| \keyword{print} statements are executed: |
| |
| \begin{verbatim} |
| if x < y < z: print x; print y; print z |
| \end{verbatim} |
| |
| Summarizing: |
| |
| \begin{productionlist} |
| \production{compound_stmt} |
| {\token{if_stmt}} |
| \productioncont{| \token{while_stmt}} |
| \productioncont{| \token{for_stmt}} |
| \productioncont{| \token{try_stmt}} |
| \productioncont{| \token{funcdef}} |
| \productioncont{| \token{classdef}} |
| \production{suite} |
| {\token{stmt_list} NEWLINE |
| | NEWLINE INDENT \token{statement}+ DEDENT} |
| \production{statement} |
| {\token{stmt_list} NEWLINE | \token{compound_stmt}} |
| \production{stmt_list} |
| {\token{simple_stmt} (";" \token{simple_stmt})* [";"]} |
| \end{productionlist} |
| |
| Note that statements always end in a |
| \code{NEWLINE}\index{NEWLINE token} possibly followed by a |
| \code{DEDENT}.\index{DEDENT token} Also note that optional |
| continuation clauses always begin with a keyword that cannot start a |
| statement, thus there are no ambiguities (the `dangling |
| \keyword{else}' problem is solved in Python by requiring nested |
| \keyword{if} statements to be indented). |
| \indexii{dangling}{else} |
| |
| The formatting of the grammar rules in the following sections places |
| each clause on a separate line for clarity. |
| |
| |
| \section{The \keyword{if} statement\label{if}} |
| \stindex{if} |
| |
| The \keyword{if} statement is used for conditional execution: |
| |
| \begin{productionlist} |
| \production{if_stmt} |
| {"if" \token{expression} ":" \token{suite}} |
| \productioncont{( "elif" \token{expression} ":" \token{suite} )*} |
| \productioncont{["else" ":" \token{suite}]} |
| \end{productionlist} |
| |
| It selects exactly one of the suites by evaluating the expressions one |
| by one until one is found to be true (see section~\ref{Booleans} for |
| the definition of true and false); then that suite is executed (and no |
| other part of the \keyword{if} statement is executed or evaluated). If |
| all expressions are false, the suite of the \keyword{else} clause, if |
| present, is executed. |
| \kwindex{elif} |
| \kwindex{else} |
| |
| |
| \section{The \keyword{while} statement\label{while}} |
| \stindex{while} |
| \indexii{loop}{statement} |
| |
| The \keyword{while} statement is used for repeated execution as long |
| as an expression is true: |
| |
| \begin{productionlist} |
| \production{while_stmt} |
| {"while" \token{expression} ":" \token{suite}} |
| \productioncont{["else" ":" \token{suite}]} |
| \end{productionlist} |
| |
| This repeatedly tests the expression and, if it is true, executes the |
| first suite; if the expression is false (which may be the first time it |
| is tested) the suite of the \keyword{else} clause, if present, is |
| executed and the loop terminates. |
| \kwindex{else} |
| |
| A \keyword{break} statement executed in the first suite terminates the |
| loop without executing the \keyword{else} clause's suite. A |
| \keyword{continue} statement executed in the first suite skips the rest |
| of the suite and goes back to testing the expression. |
| \stindex{break} |
| \stindex{continue} |
| |
| |
| \section{The \keyword{for} statement\label{for}} |
| \stindex{for} |
| \indexii{loop}{statement} |
| |
| The \keyword{for} statement is used to iterate over the elements of a |
| sequence (such as a string, tuple or list) or other iterable object: |
| \obindex{sequence} |
| |
| \begin{productionlist} |
| \production{for_stmt} |
| {"for" \token{target_list} "in" \token{expression_list} |
| ":" \token{suite}} |
| \productioncont{["else" ":" \token{suite}]} |
| \end{productionlist} |
| |
| The expression list is evaluated once; it should yield a sequence. The |
| suite is then executed once for each item in the sequence, in the |
| order of ascending indices. Each item in turn is assigned to the |
| target list using the standard rules for assignments, and then the |
| suite is executed. When the items are exhausted (which is immediately |
| when the sequence is empty), the suite in the \keyword{else} clause, if |
| present, is executed, and the loop terminates. |
| \kwindex{in} |
| \kwindex{else} |
| \indexii{target}{list} |
| |
| A \keyword{break} statement executed in the first suite terminates the |
| loop without executing the \keyword{else} clause's suite. A |
| \keyword{continue} statement executed in the first suite skips the rest |
| of the suite and continues with the next item, or with the \keyword{else} |
| clause if there was no next item. |
| \stindex{break} |
| \stindex{continue} |
| |
| The suite may assign to the variable(s) in the target list; this does |
| not affect the next item assigned to it. |
| |
| The target list is not deleted when the loop is finished, but if the |
| sequence is empty, it will not have been assigned to at all by the |
| loop. Hint: the built-in function \function{range()} returns a |
| sequence of integers suitable to emulate the effect of Pascal's |
| \code{for i := a to b do}; |
| e.g., \code{range(3)} returns the list \code{[0, 1, 2]}. |
| \bifuncindex{range} |
| \indexii{Pascal}{language} |
| |
| \warning{There is a subtlety when the sequence is being modified |
| by the loop (this can only occur for mutable sequences, i.e. lists). |
| An internal counter is used to keep track of which item is used next, |
| and this is incremented on each iteration. When this counter has |
| reached the length of the sequence the loop terminates. This means that |
| if the suite deletes the current (or a previous) item from the |
| sequence, the next item will be skipped (since it gets the index of |
| the current item which has already been treated). Likewise, if the |
| suite inserts an item in the sequence before the current item, the |
| current item will be treated again the next time through the loop. |
| This can lead to nasty bugs that can be avoided by making a temporary |
| copy using a slice of the whole sequence, e.g., |
| \index{loop!over mutable sequence} |
| \index{mutable sequence!loop over}} |
| |
| \begin{verbatim} |
| for x in a[:]: |
| if x < 0: a.remove(x) |
| \end{verbatim} |
| |
| |
| \section{The \keyword{try} statement\label{try}} |
| \stindex{try} |
| |
| The \keyword{try} statement specifies exception handlers and/or cleanup |
| code for a group of statements: |
| |
| \begin{productionlist} |
| \production{try_stmt} |
| {\token{try_exc_stmt} | \token{try_fin_stmt}} |
| \production{try_exc_stmt} |
| {"try" ":" \token{suite}} |
| \productioncont{("except" [\token{expression} |
| ["," \token{target}]] ":" \token{suite})+} |
| \productioncont{["else" ":" \token{suite}]} |
| \production{try_fin_stmt} |
| {"try" ":" \token{suite} |
| "finally" ":" \token{suite}} |
| \end{productionlist} |
| |
| There are two forms of \keyword{try} statement: |
| \keyword{try}...\keyword{except} and |
| \keyword{try}...\keyword{finally}. These forms cannot be mixed (but |
| they can be nested in each other). |
| |
| The \keyword{try}...\keyword{except} form specifies one or more |
| exception handlers |
| (the \keyword{except} clauses). When no exception occurs in the |
| \keyword{try} clause, no exception handler is executed. When an |
| exception occurs in the \keyword{try} suite, a search for an exception |
| handler is started. This search inspects the except clauses in turn until |
| one is found that matches the exception. An expression-less except |
| clause, if present, must be last; it matches any exception. For an |
| except clause with an expression, that expression is evaluated, and the |
| clause matches the exception if the resulting object is ``compatible'' |
| with the exception. An object is compatible with an exception if it |
| is either the object that identifies the exception, or (for exceptions |
| that are classes) it is a base class of the exception, or it is a |
| tuple containing an item that is compatible with the exception. Note |
| that the object identities must match, i.e. it must be the same |
| object, not just an object with the same value. |
| \kwindex{except} |
| |
| If no except clause matches the exception, the search for an exception |
| handler continues in the surrounding code and on the invocation stack. |
| |
| If the evaluation of an expression in the header of an except clause |
| raises an exception, the original search for a handler is canceled |
| and a search starts for the new exception in the surrounding code and |
| on the call stack (it is treated as if the entire \keyword{try} statement |
| raised the exception). |
| |
| When a matching except clause is found, the exception's parameter is |
| assigned to the target specified in that except clause, if present, |
| and the except clause's suite is executed. All except clauses must |
| have an executable block. When the end of this block |
| is reached, execution continues normally after the entire try |
| statement. (This means that if two nested handlers exist for the same |
| exception, and the exception occurs in the try clause of the inner |
| handler, the outer handler will not handle the exception.) |
| |
| Before an except clause's suite is executed, details about the |
| exception are assigned to three variables in the |
| \module{sys}\refbimodindex{sys} module: \code{sys.exc_type} receives |
| the object identifying the exception; \code{sys.exc_value} receives |
| the exception's parameter; \code{sys.exc_traceback} receives a |
| traceback object\obindex{traceback} (see section~\ref{traceback}) |
| identifying the point in the program where the exception occurred. |
| These details are also available through the \function{sys.exc_info()} |
| function, which returns a tuple \code{(\var{exc_type}, \var{exc_value}, |
| \var{exc_traceback})}. Use of the corresponding variables is |
| deprecated in favor of this function, since their use is unsafe in a |
| threaded program. As of Python 1.5, the variables are restored to |
| their previous values (before the call) when returning from a function |
| that handled an exception. |
| \withsubitem{(in module sys)}{\ttindex{exc_type} |
| \ttindex{exc_value}\ttindex{exc_traceback}} |
| |
| The optional \keyword{else} clause is executed if and when control |
| flows off the end of the \keyword{try} clause.\footnote{ |
| Currently, control ``flows off the end'' except in the case of an |
| exception or the execution of a \keyword{return}, |
| \keyword{continue}, or \keyword{break} statement. |
| } Exceptions in the \keyword{else} clause are not handled by the |
| preceding \keyword{except} clauses. |
| \kwindex{else} |
| \stindex{return} |
| \stindex{break} |
| \stindex{continue} |
| |
| The \keyword{try}...\keyword{finally} form specifies a `cleanup' handler. The |
| \keyword{try} clause is executed. When no exception occurs, the |
| \keyword{finally} clause is executed. When an exception occurs in the |
| \keyword{try} clause, the exception is temporarily saved, the |
| \keyword{finally} clause is executed, and then the saved exception is |
| re-raised. If the \keyword{finally} clause raises another exception or |
| executes a \keyword{return} or \keyword{break} statement, the saved |
| exception is lost. A \keyword{continue} statement is illegal in the |
| \keyword{finally} clause. (The reason is a problem with the current |
| implementation -- this restriction may be lifted in the future). The |
| exception information is not available to the program during execution of |
| the \keyword{finally} clause. |
| \kwindex{finally} |
| |
| When a \keyword{return}, \keyword{break} or \keyword{continue} statement is |
| executed in the \keyword{try} suite of a \keyword{try}...\keyword{finally} |
| statement, the \keyword{finally} clause is also executed `on the way out.' A |
| \keyword{continue} statement is illegal in the \keyword{finally} clause. |
| (The reason is a problem with the current implementation --- this |
| restriction may be lifted in the future). |
| \stindex{return} |
| \stindex{break} |
| \stindex{continue} |
| |
| Additional information on exceptions can be found in |
| section~\ref{exceptions}, and information on using the \keyword{raise} |
| statement to generate exceptions may be found in section~\ref{raise}. |
| |
| |
| \section{Function definitions\label{function}} |
| \indexii{function}{definition} |
| \stindex{def} |
| |
| A function definition defines a user-defined function object (see |
| section~\ref{types}): |
| \obindex{user-defined function} |
| \obindex{function} |
| |
| \begin{productionlist} |
| \production{funcdef} |
| {[\token{decorators}] "def" \token{funcname} "(" [\token{parameter_list}] ")" |
| ":" \token{suite}} |
| \production{decorators} |
| {\token{decorator}+} |
| \production{decorator} |
| {"@" \token{dotted_name} ["(" [\token{argument_list} [","]] ")"] NEWLINE} |
| \production{parameter_list} |
| {(\token{defparameter} ",")*} |
| \productioncont{(~~"*" \token{identifier} [, "**" \token{identifier}]} |
| \productioncont{ | "**" \token{identifier}} |
| \productioncont{ | \token{defparameter} [","] )} |
| \production{defparameter} |
| {\token{parameter} ["=" \token{expression}]} |
| \production{sublist} |
| {\token{parameter} ("," \token{parameter})* [","]} |
| \production{parameter} |
| {\token{identifier} | "(" \token{sublist} ")"} |
| \production{funcname} |
| {\token{identifier}} |
| \end{productionlist} |
| |
| A function definition is an executable statement. Its execution binds |
| the function name in the current local namespace to a function object |
| (a wrapper around the executable code for the function). This |
| function object contains a reference to the current global namespace |
| as the global namespace to be used when the function is called. |
| \indexii{function}{name} |
| \indexii{name}{binding} |
| |
| The function definition does not execute the function body; this gets |
| executed only when the function is called. |
| |
| A function definition may be wrapped by one or more decorator expressions. |
| Decorator expressions are evaluated when the function is defined, in the scope |
| that contains the function definition. The result must be a callable, |
| which is invoked with the function object as the only argument. |
| The returned value is bound to the function name instead of the function |
| object. Multiple decorators are applied in nested fashion. |
| For example, the following code: |
| |
| \begin{verbatim} |
| @f1(arg) |
| @f2 |
| def func(): pass |
| \end{verbatim} |
| |
| is equivalent to: |
| |
| \begin{verbatim} |
| def func(): pass |
| func = f1(arg)(f2(func)) |
| \end{verbatim} |
| |
| When one or more top-level parameters have the form \var{parameter} |
| \code{=} \var{expression}, the function is said to have ``default |
| parameter values.'' For a parameter with a |
| default value, the corresponding argument may be omitted from a call, |
| in which case the parameter's default value is substituted. If a |
| parameter has a default value, all following parameters must also have |
| a default value --- this is a syntactic restriction that is not |
| expressed by the grammar. |
| \indexiii{default}{parameter}{value} |
| |
| \strong{Default parameter values are evaluated when the function |
| definition is executed.} This means that the expression is evaluated |
| once, when the function is defined, and that that same |
| ``pre-computed'' value is used for each call. This is especially |
| important to understand when a default parameter is a mutable object, |
| such as a list or a dictionary: if the function modifies the object |
| (e.g. by appending an item to a list), the default value is in effect |
| modified. This is generally not what was intended. A way around this |
| is to use \code{None} as the default, and explicitly test for it in |
| the body of the function, e.g.: |
| |
| \begin{verbatim} |
| def whats_on_the_telly(penguin=None): |
| if penguin is None: |
| penguin = [] |
| penguin.append("property of the zoo") |
| return penguin |
| \end{verbatim} |
| |
| Function call semantics are described in more detail in |
| section~\ref{calls}. |
| A function call always assigns values to all parameters mentioned in |
| the parameter list, either from position arguments, from keyword |
| arguments, or from default values. If the form ``\code{*identifier}'' |
| is present, it is initialized to a tuple receiving any excess |
| positional parameters, defaulting to the empty tuple. If the form |
| ``\code{**identifier}'' is present, it is initialized to a new |
| dictionary receiving any excess keyword arguments, defaulting to a |
| new empty dictionary. |
| |
| It is also possible to create anonymous functions (functions not bound |
| to a name), for immediate use in expressions. This uses lambda forms, |
| described in section~\ref{lambda}. Note that the lambda form is |
| merely a shorthand for a simplified function definition; a function |
| defined in a ``\keyword{def}'' statement can be passed around or |
| assigned to another name just like a function defined by a lambda |
| form. The ``\keyword{def}'' form is actually more powerful since it |
| allows the execution of multiple statements. |
| \indexii{lambda}{form} |
| |
| \strong{Programmer's note:} Functions are first-class objects. A |
| ``\code{def}'' form executed inside a function definition defines a |
| local function that can be returned or passed around. Free variables |
| used in the nested function can access the local variables of the |
| function containing the def. See section~\ref{naming} for details. |
| |
| |
| \section{Class definitions\label{class}} |
| \indexii{class}{definition} |
| \stindex{class} |
| |
| A class definition defines a class object (see section~\ref{types}): |
| \obindex{class} |
| |
| \begin{productionlist} |
| \production{classdef} |
| {"class" \token{classname} [\token{inheritance}] ":" |
| \token{suite}} |
| \production{inheritance} |
| {"(" \token{expression_list} ")"} |
| \production{classname} |
| {\token{identifier}} |
| \end{productionlist} |
| |
| A class definition is an executable statement. It first evaluates the |
| inheritance list, if present. Each item in the inheritance list |
| should evaluate to a class object or class type which allows |
| subclassing. The class's suite is then executed |
| in a new execution frame (see section~\ref{naming}), using a newly |
| created local namespace and the original global namespace. |
| (Usually, the suite contains only function definitions.) When the |
| class's suite finishes execution, its execution frame is discarded but |
| its local namespace is saved. A class object is then created using |
| the inheritance list for the base classes and the saved local |
| namespace for the attribute dictionary. The class name is bound to this |
| class object in the original local namespace. |
| \index{inheritance} |
| \indexii{class}{name} |
| \indexii{name}{binding} |
| \indexii{execution}{frame} |
| |
| \strong{Programmer's note:} Variables defined in the class definition |
| are class variables; they are shared by all instances. To define |
| instance variables, they must be given a value in the |
| \method{__init__()} method or in another method. Both class and |
| instance variables are accessible through the notation |
| ``\code{self.name}'', and an instance variable hides a class variable |
| with the same name when accessed in this way. Class variables with |
| immutable values can be used as defaults for instance variables. |
| For new-style classes, descriptors can be used to create instance |
| variables with different implementation details. |