source: trunk/essentials/dev-lang/python/Doc/ref/ref7.tex@ 3315

\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{with_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 an iterable
object.  An iterator is created for the result of the
{}\code{expression_list}.  The suite is then executed once for each
item provided by the iterator, 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} {try1_stmt | try2_stmt}
  \production{try1_stmt}
             {"try" ":" \token{suite}}
  \productioncont{("except" [\token{expression}
                             ["," \token{target}]] ":" \token{suite})+}
  \productioncont{["else" ":" \token{suite}]}
  \productioncont{["finally" ":" \token{suite}]}
  \production{try2_stmt}
             {"try" ":" \token{suite}}
  \productioncont{"finally" ":" \token{suite}}
\end{productionlist}

\versionchanged[In previous versions of Python,
\keyword{try}...\keyword{except}...\keyword{finally} did not work.
\keyword{try}...\keyword{except} had to be nested in
\keyword{try}...\keyword{finally}]{2.5}

The \keyword{except} clause(s) specify one or more exception handlers.
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 the class or a base class of the exception object, a tuple
containing an item compatible with the exception, or, in the
(deprecated) case of string exceptions, is the raised string itself
(note that the object identities must match, i.e. it must be the same
string object, not just a string 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.
\footnote{The exception is propogated to the invocation stack only if
there is no \keyword{finally} clause that negates the exception.}

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 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