| \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{verbatim} |
| compound_stmt: if_stmt | while_stmt | for_stmt |
| | try_stmt | funcdef | classdef |
| suite: stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT |
| statement: stmt_list NEWLINE | compound_stmt |
| stmt_list: simple_stmt (";" simple_stmt)* [";"] |
| \end{verbatim} |
| |
| 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{verbatim} |
| if_stmt: "if" expression ":" suite |
| ("elif" expression ":" suite)* |
| ["else" ":" suite] |
| \end{verbatim} |
| |
| 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{verbatim} |
| while_stmt: "while" expression ":" suite |
| ["else" ":" suite] |
| \end{verbatim} |
| |
| 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 (string, tuple or list): |
| \obindex{sequence} |
| |
| \begin{verbatim} |
| for_stmt: "for" target_list "in" expression_list ":" suite |
| ["else" ":" suite] |
| \end{verbatim} |
| |
| 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} |
| |
| \strong{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{verbatim} |
| try_stmt: try_exc_stmt | try_fin_stmt |
| try_exc_stmt: "try" ":" suite |
| ("except" [expression ["," target]] ":" suite)+ |
| ["else" ":" suite] |
| try_fin_stmt: "try" ":" suite |
| "finally" ":" suite |
| \end{verbatim} |
| |
| 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 cancelled |
| 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. When the end of this suite |
| 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 when no exception occurs |
| in the \keyword{try} clause. Exceptions in the \keyword{else} clause are |
| not handled by the preceding \keyword{except} clauses. |
| \kwindex{else} |
| |
| 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}, \keyword{break} or \keyword{continue} statement, |
| the saved exception is lost. The exception information is not |
| available to the program during execution of the \keyword{finally} |
| clause. |
| \kwindex{finally} |
| |
| When a \keyword{return} or \keyword{break} 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{try} clause. (The |
| reason is a problem with the current implementation --- this |
| restriction may be lifted in the future). |
| \stindex{return} |
| \stindex{break} |
| \stindex{continue} |
| |
| \section{Function definitions\label{function}} |
| \indexii{function}{definition} |
| |
| A function definition defines a user-defined function object (see |
| section \ref{types}): |
| \obindex{user-defined function} |
| \obindex{function} |
| |
| \begin{verbatim} |
| funcdef: "def" funcname "(" [parameter_list] ")" ":" suite |
| parameter_list: (defparameter ",")* ("*" identifier [, "**" identifier] |
| | "**" identifier |
| | defparameter [","]) |
| defparameter: parameter ["=" expression] |
| sublist: parameter ("," parameter)* [","] |
| parameter: identifier | "(" sublist ")" |
| funcname: identifier |
| \end{verbatim} |
| |
| 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. |
| |
| 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.% |
| \footnote{Currently this is not checked; instead, |
| \code{def f(a=1, b)} is interpreted as \code{def f(a=1, b=None)}.} |
| \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:} a ``\code{def}'' form executed inside a |
| function definition defines a local function that can be returned or |
| passed around. Because of Python's two-scope philosophy, a local |
| function defined in this way does not have access to the local |
| variables of the function that contains its definition; the same rule |
| applies to functions defined by a lambda form. A standard trick to |
| pass selected local variables into a locally defined function is to |
| use default argument values, like this: |
| |
| \begin{verbatim} |
| # Return a function that returns its argument incremented by 'n' |
| def make_incrementer(n): |
| def increment(x, n=n): |
| return x+n |
| return increment |
| |
| add1 = make_incrementer(1) |
| print add1(3) # This prints '4' |
| \end{verbatim} |
| |
| \section{Class definitions\label{class}} |
| \indexii{class}{definition} |
| |
| A class definition defines a class object (see section \ref{types}): |
| \obindex{class} |
| |
| \begin{verbatim} |
| classdef: "class" classname [inheritance] ":" suite |
| inheritance: "(" [expression_list] ")" |
| classname: identifier |
| \end{verbatim} |
| |
| 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. The class's suite is then executed |
| in a new execution frame (see section \ref{execframes}), 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 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. |