mirror of
https://github.com/python/cpython.git
synced 2025-11-03 19:34:08 +00:00
cb4638a278
this supports a hyperlinked version of the grammar that can make tracking down details and definitions a little easier.
433 lines
18 KiB
TeX
433 lines
18 KiB
TeX
\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} | \token{while_stmt} | \token{for_stmt}
|
|
| \token{try_stmt} | \token{funcdef} | \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}
|
|
( "elif" \token{expression} ":" \token{suite} )*
|
|
["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}
|
|
["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}
|
|
["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}
|
|
|
|
\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{productionlist}
|
|
\production{try_stmt}
|
|
{\token{try_exc_stmt} | \token{try_fin_stmt}}
|
|
\production{try_exc_stmt}
|
|
{"try" ":" \token{suite}
|
|
("except" [\token{expression} ["," \token{target}]] ":"
|
|
\token{suite})+
|
|
["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 -- thsi 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}
|
|
|
|
|
|
\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{productionlist}
|
|
\production{funcdef}
|
|
{"def" \token{funcname} "(" [\token{parameter_list}] ")"
|
|
":" \token{suite}}
|
|
\production{parameter_list}
|
|
{(\token{defparameter} ",")*
|
|
("*" \token{identifier} [, "**" \token{identifier}]
|
|
| "**" \token{identifier}
|
|
| \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.
|
|
|
|
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:} a ``\code{def}'' form executed inside a
|
|
function definition defines a local function that can be returned or
|
|
passed around. The semantics of name resolution in the nested
|
|
function will change in Python 2.2. See the appendix for a
|
|
description of the new semantics.
|
|
|
|
|
|
\section{Class definitions\label{class}}
|
|
\indexii{class}{definition}
|
|
|
|
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. 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.
|