1999-04-14 12:52:14 +00:00
|
|
|
\chapter{Simple statements \label{simple}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexii{simple}{statement}
|
|
|
|
|
|
|
|
Simple statements are comprised within a single logical line.
|
|
|
|
Several simple statements may occur on a single line separated
|
|
|
|
by semicolons. The syntax for simple statements is:
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
simple_stmt: expression_stmt
|
1998-07-24 18:25:38 +00:00
|
|
|
| assert_stmt
|
1998-05-06 19:52:49 +00:00
|
|
|
| assignment_stmt
|
|
|
|
| pass_stmt
|
|
|
|
| del_stmt
|
|
|
|
| print_stmt
|
|
|
|
| return_stmt
|
|
|
|
| raise_stmt
|
|
|
|
| break_stmt
|
|
|
|
| continue_stmt
|
|
|
|
| import_stmt
|
|
|
|
| global_stmt
|
|
|
|
| exec_stmt
|
|
|
|
\end{verbatim}
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
\section{Expression statements \label{exprstmts}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexii{expression}{statement}
|
|
|
|
|
|
|
|
Expression statements are used (mostly interactively) to compute and
|
|
|
|
write a value, or (usually) to call a procedure (a function that
|
|
|
|
returns no meaningful result; in Python, procedures return the value
|
1998-07-24 18:25:38 +00:00
|
|
|
\code{None}). Other uses of expression statements are allowed and
|
|
|
|
occasionally useful. The syntax for an expression statement is:
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\begin{verbatim}
|
1998-07-24 18:25:38 +00:00
|
|
|
expression_stmt: expression_list
|
1998-05-06 19:52:49 +00:00
|
|
|
\end{verbatim}
|
|
|
|
|
1998-07-24 18:25:38 +00:00
|
|
|
An expression statement evaluates the expression list (which may be a
|
|
|
|
single expression).
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexii{expression}{list}
|
|
|
|
|
|
|
|
In interactive mode, if the value is not \code{None}, it is converted
|
1998-07-24 18:25:38 +00:00
|
|
|
to a string using the built-in \function{repr()}\bifuncindex{repr}
|
|
|
|
function and the resulting string is written to standard output (see
|
|
|
|
section \ref{print}) on a line by itself. (Expression statements
|
|
|
|
yielding None are not written, so that procedure calls do not cause
|
|
|
|
any output.)
|
1998-05-06 19:52:49 +00:00
|
|
|
\ttindex{None}
|
|
|
|
\indexii{string}{conversion}
|
|
|
|
\index{output}
|
|
|
|
\indexii{standard}{output}
|
|
|
|
\indexii{writing}{values}
|
|
|
|
\indexii{procedure}{call}
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
\section{Assert statements \label{assert}}
|
1998-07-24 18:25:38 +00:00
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
Assert statements\stindex{assert} are a convenient way to insert
|
|
|
|
debugging assertions\indexii{debugging}{assertions} into a program:
|
1998-07-24 18:25:38 +00:00
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
assert_statement: "assert" expression ["," expression]
|
|
|
|
\end{verbatim}
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
The simple form, \samp{assert expression}, is equivalent to
|
1998-07-24 18:25:38 +00:00
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
if __debug__:
|
|
|
|
if not expression: raise AssertionError
|
|
|
|
\end{verbatim}
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
The extended form, \samp{assert expression1, expression2}, is
|
1998-07-24 18:25:38 +00:00
|
|
|
equivalent to
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
if __debug__:
|
|
|
|
if not expression1: raise AssertionError, expression2
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
These equivalences assume that \code{__debug__}\ttindex{__debug__} and
|
1999-04-14 12:52:14 +00:00
|
|
|
\exception{AssertionError}\exindex{AssertionError} refer to the built-in
|
1998-07-24 18:25:38 +00:00
|
|
|
variables with those names. In the current implementation, the
|
|
|
|
built-in variable \code{__debug__} is 1 under normal circumstances, 0
|
|
|
|
when optimization is requested (command line option -O). The current
|
|
|
|
code generator emits no code for an assert statement when optimization
|
|
|
|
is requested at compile time. Note that it is unnecessary to include
|
|
|
|
the source code for the expression that failed in the error message;
|
|
|
|
it will be displayed as part of the stack trace.
|
|
|
|
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
\section{Assignment statements \label{assignment}}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
Assignment statements\indexii{assignment}{statement} are used to
|
|
|
|
(re)bind names to values and to modify attributes or items of mutable
|
|
|
|
objects:
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexii{binding}{name}
|
|
|
|
\indexii{rebinding}{name}
|
|
|
|
\obindex{mutable}
|
|
|
|
\indexii{attribute}{assignment}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
assignment_stmt: (target_list "=")+ expression_list
|
|
|
|
target_list: target ("," target)* [","]
|
|
|
|
target: identifier | "(" target_list ")" | "[" target_list "]"
|
|
|
|
| attributeref | subscription | slicing
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
(See section \ref{primaries} for the syntax definitions for the last
|
|
|
|
three symbols.)
|
|
|
|
|
|
|
|
An assignment statement evaluates the expression list (remember that
|
|
|
|
this can be a single expression or a comma-separated list, the latter
|
|
|
|
yielding a tuple) and assigns the single resulting object to each of
|
|
|
|
the target lists, from left to right.
|
|
|
|
\indexii{expression}{list}
|
|
|
|
|
|
|
|
Assignment is defined recursively depending on the form of the target
|
|
|
|
(list). When a target is part of a mutable object (an attribute
|
|
|
|
reference, subscription or slicing), the mutable object must
|
|
|
|
ultimately perform the assignment and decide about its validity, and
|
|
|
|
may raise an exception if the assignment is unacceptable. The rules
|
|
|
|
observed by various types and the exceptions raised are given with the
|
|
|
|
definition of the object types (see section \ref{types}).
|
|
|
|
\index{target}
|
|
|
|
\indexii{target}{list}
|
|
|
|
|
|
|
|
Assignment of an object to a target list is recursively defined as
|
|
|
|
follows.
|
|
|
|
\indexiii{target}{list}{assignment}
|
|
|
|
|
|
|
|
\begin{itemize}
|
|
|
|
\item
|
1998-07-24 18:25:38 +00:00
|
|
|
If the target list is a single target: The object is assigned to that
|
1998-05-06 19:52:49 +00:00
|
|
|
target.
|
|
|
|
|
|
|
|
\item
|
1998-07-24 18:25:38 +00:00
|
|
|
If the target list is a comma-separated list of targets: The object
|
|
|
|
must be a sequence with the same number of items as the there are
|
|
|
|
targets in the target list, and the items are assigned, from left to
|
|
|
|
right, to the corresponding targets. (This rule is relaxed as of
|
|
|
|
Python 1.5; in earlier versions, the object had to be a tuple. Since
|
1999-04-14 12:52:14 +00:00
|
|
|
strings are sequences, an assignment like \samp{a, b = "xy"} is
|
1998-07-24 18:25:38 +00:00
|
|
|
now legal as long as the string has the right length.)
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\end{itemize}
|
|
|
|
|
|
|
|
Assignment of an object to a single target is recursively defined as
|
|
|
|
follows.
|
|
|
|
|
|
|
|
\begin{itemize} % nested
|
|
|
|
|
|
|
|
\item
|
|
|
|
If the target is an identifier (name):
|
|
|
|
|
|
|
|
\begin{itemize}
|
|
|
|
|
|
|
|
\item
|
|
|
|
If the name does not occur in a \keyword{global} statement in the current
|
1998-07-24 18:25:38 +00:00
|
|
|
code block: the name is bound to the object in the current local
|
|
|
|
namespace.
|
1998-05-06 19:52:49 +00:00
|
|
|
\stindex{global}
|
|
|
|
|
|
|
|
\item
|
1998-07-24 18:25:38 +00:00
|
|
|
Otherwise: the name is bound to the object in the current global
|
|
|
|
namespace.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\end{itemize} % nested
|
|
|
|
|
1998-07-24 18:25:38 +00:00
|
|
|
The name is rebound if it was already bound. This may cause the
|
|
|
|
reference count for the object previously bound to the name to reach
|
|
|
|
zero, causing the object to be deallocated and its
|
|
|
|
destructor\index{destructor} (if it has one) to be called.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\item
|
1998-07-24 18:25:38 +00:00
|
|
|
If the target is a target list enclosed in parentheses or in square
|
|
|
|
brackets: The object must be a sequence with the same number of items
|
|
|
|
as there are targets in the target list, and its items are assigned,
|
|
|
|
from left to right, to the corresponding targets.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\item
|
|
|
|
If the target is an attribute reference: The primary expression in the
|
|
|
|
reference is evaluated. It should yield an object with assignable
|
|
|
|
attributes; if this is not the case, \exception{TypeError} is raised. That
|
|
|
|
object is then asked to assign the assigned object to the given
|
|
|
|
attribute; if it cannot perform the assignment, it raises an exception
|
|
|
|
(usually but not necessarily \exception{AttributeError}).
|
|
|
|
\indexii{attribute}{assignment}
|
|
|
|
|
|
|
|
\item
|
|
|
|
If the target is a subscription: The primary expression in the
|
|
|
|
reference is evaluated. It should yield either a mutable sequence
|
1998-07-24 18:25:38 +00:00
|
|
|
object (e.g., a list) or a mapping object (e.g., a dictionary). Next,
|
|
|
|
the subscript expression is evaluated.
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexii{subscription}{assignment}
|
|
|
|
\obindex{mutable}
|
|
|
|
|
1998-07-24 18:25:38 +00:00
|
|
|
If the primary is a mutable sequence object (e.g., a list), the subscript
|
1998-05-06 19:52:49 +00:00
|
|
|
must yield a plain integer. If it is negative, the sequence's length
|
|
|
|
is added to it. The resulting value must be a nonnegative integer
|
|
|
|
less than the sequence's length, and the sequence is asked to assign
|
|
|
|
the assigned object to its item with that index. If the index is out
|
|
|
|
of range, \exception{IndexError} is raised (assignment to a subscripted
|
|
|
|
sequence cannot add new items to a list).
|
|
|
|
\obindex{sequence}
|
|
|
|
\obindex{list}
|
|
|
|
|
1998-07-24 18:25:38 +00:00
|
|
|
If the primary is a mapping object (e.g., a dictionary), the subscript must
|
1998-05-06 19:52:49 +00:00
|
|
|
have a type compatible with the mapping's key type, and the mapping is
|
|
|
|
then asked to create a key/datum pair which maps the subscript to
|
|
|
|
the assigned object. This can either replace an existing key/value
|
|
|
|
pair with the same key value, or insert a new key/value pair (if no
|
|
|
|
key with the same value existed).
|
|
|
|
\obindex{mapping}
|
|
|
|
\obindex{dictionary}
|
|
|
|
|
|
|
|
\item
|
|
|
|
If the target is a slicing: The primary expression in the reference is
|
1998-07-24 18:25:38 +00:00
|
|
|
evaluated. It should yield a mutable sequence object (e.g., a list). The
|
1998-05-06 19:52:49 +00:00
|
|
|
assigned object should be a sequence object of the same type. Next,
|
|
|
|
the lower and upper bound expressions are evaluated, insofar they are
|
|
|
|
present; defaults are zero and the sequence's length. The bounds
|
|
|
|
should evaluate to (small) integers. If either bound is negative, the
|
|
|
|
sequence's length is added to it. The resulting bounds are clipped to
|
|
|
|
lie between zero and the sequence's length, inclusive. Finally, the
|
|
|
|
sequence object is asked to replace the slice with the items of the
|
|
|
|
assigned sequence. The length of the slice may be different from the
|
|
|
|
length of the assigned sequence, thus changing the length of the
|
|
|
|
target sequence, if the object allows it.
|
|
|
|
\indexii{slicing}{assignment}
|
|
|
|
|
|
|
|
\end{itemize}
|
2000-04-27 18:32:02 +00:00
|
|
|
|
1998-05-06 19:52:49 +00:00
|
|
|
(In the current implementation, the syntax for targets is taken
|
|
|
|
to be the same as for expressions, and invalid syntax is rejected
|
|
|
|
during the code generation phase, causing less detailed error
|
|
|
|
messages.)
|
|
|
|
|
|
|
|
WARNING: Although the definition of assignment implies that overlaps
|
1998-07-24 18:25:38 +00:00
|
|
|
between the left-hand side and the right-hand side are `safe' (e.g.,
|
1999-04-14 12:52:14 +00:00
|
|
|
\samp{a, b = b, a} swaps two variables), overlaps \emph{within} the
|
1998-05-06 19:52:49 +00:00
|
|
|
collection of assigned-to variables are not safe! For instance, the
|
1999-04-14 12:52:14 +00:00
|
|
|
following program prints \samp{[0, 2]}:
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
x = [0, 1]
|
|
|
|
i = 0
|
|
|
|
i, x[i] = 1, 2
|
|
|
|
print x
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
\section{The \keyword{pass} statement \label{pass}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\stindex{pass}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
pass_stmt: "pass"
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
\keyword{pass} is a null operation --- when it is executed, nothing
|
|
|
|
happens. It is useful as a placeholder when a statement is
|
|
|
|
required syntactically, but no code needs to be executed, for example:
|
|
|
|
\indexii{null}{operation}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
def f(arg): pass # a function that does nothing (yet)
|
|
|
|
|
|
|
|
class C: pass # a class with no methods (yet)
|
|
|
|
\end{verbatim}
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
\section{The \keyword{del} statement \label{del}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\stindex{del}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
del_stmt: "del" target_list
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
Deletion is recursively defined very similar to the way assignment is
|
|
|
|
defined. Rather that spelling it out in full details, here are some
|
|
|
|
hints.
|
|
|
|
\indexii{deletion}{target}
|
|
|
|
\indexiii{deletion}{target}{list}
|
|
|
|
|
|
|
|
Deletion of a target list recursively deletes each target, from left
|
|
|
|
to right.
|
|
|
|
|
|
|
|
Deletion of a name removes the binding of that name (which must exist)
|
1998-07-24 18:25:38 +00:00
|
|
|
from the local or global namespace, depending on whether the name
|
1998-05-06 19:52:49 +00:00
|
|
|
occurs in a \keyword{global} statement in the same code block.
|
|
|
|
\stindex{global}
|
|
|
|
\indexii{unbinding}{name}
|
|
|
|
|
|
|
|
Deletion of attribute references, subscriptions and slicings
|
|
|
|
is passed to the primary object involved; deletion of a slicing
|
|
|
|
is in general equivalent to assignment of an empty slice of the
|
|
|
|
right type (but even this is determined by the sliced object).
|
|
|
|
\indexii{attribute}{deletion}
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
\section{The \keyword{print} statement \label{print}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\stindex{print}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
1998-07-24 18:25:38 +00:00
|
|
|
print_stmt: "print" [ expression ("," expression)* [","] ]
|
1998-05-06 19:52:49 +00:00
|
|
|
\end{verbatim}
|
|
|
|
|
1998-10-01 20:39:47 +00:00
|
|
|
\keyword{print} evaluates each expression in turn and writes the
|
|
|
|
resulting object to standard output (see below). If an object is not
|
|
|
|
a string, it is first converted to a string using the rules for string
|
1998-05-06 19:52:49 +00:00
|
|
|
conversions. The (resulting or original) string is then written. A
|
1998-10-01 20:39:47 +00:00
|
|
|
space is written before each object is (converted and) written, unless
|
1998-05-06 19:52:49 +00:00
|
|
|
the output system believes it is positioned at the beginning of a
|
1998-07-24 18:25:38 +00:00
|
|
|
line. This is the case (1) when no characters have yet been written
|
|
|
|
to standard output, (2) when the last character written to standard
|
1998-10-01 20:39:47 +00:00
|
|
|
output is \character{\e n}, or (3) when the last write operation on
|
|
|
|
standard output was not a \keyword{print} statement. (In some cases
|
|
|
|
it may be functional to write an empty string to standard output for
|
|
|
|
this reason.)
|
1998-05-06 19:52:49 +00:00
|
|
|
\index{output}
|
|
|
|
\indexii{writing}{values}
|
|
|
|
|
1998-10-01 20:39:47 +00:00
|
|
|
A \character{\e n} character is written at the end, unless the
|
|
|
|
\keyword{print} statement ends with a comma. This is the only action
|
|
|
|
if the statement contains just the keyword \keyword{print}.
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexii{trailing}{comma}
|
|
|
|
\indexii{newline}{suppression}
|
|
|
|
|
1998-05-06 20:59:46 +00:00
|
|
|
Standard output is defined as the file object named \code{stdout}
|
1998-07-24 18:25:38 +00:00
|
|
|
in the built-in module \module{sys}. If no such object exists, or if
|
|
|
|
it does not have a \method{write()} method, a \exception{RuntimeError}
|
|
|
|
exception is raised.
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexii{standard}{output}
|
|
|
|
\refbimodindex{sys}
|
1998-11-25 17:40:00 +00:00
|
|
|
\withsubitem{(in module sys)}{\ttindex{stdout}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\exindex{RuntimeError}
|
|
|
|
|
2000-08-21 15:45:16 +00:00
|
|
|
\keyword{print} also has an extended form, defined as
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
print_stmt: '>>' expression [ (',' expression)+ [','] ] )
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
In this form, the first expression after the \keyword{>>} must
|
|
|
|
evaluate to a ``file-like'' object, specifically an object that has a
|
2000-08-29 04:57:34 +00:00
|
|
|
\method{write()} method as described above. With this extended form,
|
|
|
|
the subsequent expressions are printed to this file object. If the
|
|
|
|
first expression evaluates to \code{None}, then \code{sys.stdout} is
|
|
|
|
used as the file for output.
|
2000-08-21 15:45:16 +00:00
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
\section{The \keyword{return} statement \label{return}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\stindex{return}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
1998-07-24 18:25:38 +00:00
|
|
|
return_stmt: "return" [expression_list]
|
1998-05-06 19:52:49 +00:00
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
\keyword{return} may only occur syntactically nested in a function
|
|
|
|
definition, not within a nested class definition.
|
|
|
|
\indexii{function}{definition}
|
|
|
|
\indexii{class}{definition}
|
|
|
|
|
1998-07-24 18:25:38 +00:00
|
|
|
If an expression list is present, it is evaluated, else \code{None}
|
1998-05-06 19:52:49 +00:00
|
|
|
is substituted.
|
|
|
|
|
1998-07-24 18:25:38 +00:00
|
|
|
\keyword{return} leaves the current function call with the expression
|
1998-05-06 19:52:49 +00:00
|
|
|
list (or \code{None}) as return value.
|
|
|
|
|
|
|
|
When \keyword{return} passes control out of a \keyword{try} statement
|
1998-07-24 18:25:38 +00:00
|
|
|
with a \keyword{finally} clause, that \keyword{finally} clause is executed
|
1998-05-06 19:52:49 +00:00
|
|
|
before really leaving the function.
|
|
|
|
\kwindex{finally}
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
\section{The \keyword{raise} statement \label{raise}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\stindex{raise}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
1998-07-24 18:25:38 +00:00
|
|
|
raise_stmt: "raise" [expression ["," expression ["," expression]]]
|
1998-05-06 19:52:49 +00:00
|
|
|
\end{verbatim}
|
|
|
|
|
1998-07-24 18:25:38 +00:00
|
|
|
If no expressions are present, \keyword{raise} re-raises the last
|
|
|
|
expression that was raised in the current scope.
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
Otherwise, \keyword{raise} evaluates its first expression, which must yield
|
1998-07-24 18:25:38 +00:00
|
|
|
a string, class, or instance object. If there is a second expression,
|
1998-05-06 19:52:49 +00:00
|
|
|
this is evaluated, else \code{None} is substituted. If the first
|
1998-08-25 14:45:41 +00:00
|
|
|
expression is a class object, then the second expression may be an
|
|
|
|
instance of that class or one of its derivatives, and then that
|
|
|
|
instance is raised. If the second expression is not such an instance,
|
|
|
|
the given class is instantiated. The argument list for the
|
|
|
|
instantiation is determined as follows: if the second expression is a
|
|
|
|
tuple, it is used as the argument list; if it is \code{None}, the
|
|
|
|
argument list is empty; otherwise, the argument list consists of a
|
|
|
|
single argument which is the second expression. If the first
|
1998-07-24 18:25:38 +00:00
|
|
|
expression is an instance object, the second expression must be
|
1998-05-06 19:52:49 +00:00
|
|
|
\code{None}.
|
|
|
|
\index{exception}
|
|
|
|
\indexii{raising}{exception}
|
|
|
|
|
1998-08-25 14:45:41 +00:00
|
|
|
If the first object is a string, it then raises the exception
|
1998-05-06 19:52:49 +00:00
|
|
|
identified by the first object, with the second one (or \code{None})
|
1998-08-25 14:45:41 +00:00
|
|
|
as its parameter. If the first object is a class or instance,
|
|
|
|
it raises the exception identified by the class of the instance
|
|
|
|
determined in the previous step, with the instance as
|
|
|
|
its parameter.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
1998-07-24 18:25:38 +00:00
|
|
|
If a third object is present, and it is not \code{None}, it should be
|
1998-05-06 19:52:49 +00:00
|
|
|
a traceback object (see section \ref{traceback}), and it is
|
|
|
|
substituted instead of the current location as the place where the
|
|
|
|
exception occurred. This is useful to re-raise an exception
|
|
|
|
transparently in an except clause.
|
|
|
|
\obindex{traceback}
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
\section{The \keyword{break} statement \label{break}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\stindex{break}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
break_stmt: "break"
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
\keyword{break} may only occur syntactically nested in a \keyword{for}
|
|
|
|
or \keyword{while} loop, but not nested in a function or class definition
|
|
|
|
within that loop.
|
|
|
|
\stindex{for}
|
|
|
|
\stindex{while}
|
|
|
|
\indexii{loop}{statement}
|
|
|
|
|
|
|
|
It terminates the nearest enclosing loop, skipping the optional
|
1998-07-24 18:25:38 +00:00
|
|
|
\keyword{else} clause if the loop has one.
|
1998-05-06 19:52:49 +00:00
|
|
|
\kwindex{else}
|
|
|
|
|
|
|
|
If a \keyword{for} loop is terminated by \keyword{break}, the loop control
|
|
|
|
target keeps its current value.
|
|
|
|
\indexii{loop control}{target}
|
|
|
|
|
|
|
|
When \keyword{break} passes control out of a \keyword{try} statement
|
1998-07-24 18:25:38 +00:00
|
|
|
with a \keyword{finally} clause, that \keyword{finally} clause is executed
|
1998-05-06 19:52:49 +00:00
|
|
|
before really leaving the loop.
|
|
|
|
\kwindex{finally}
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
\section{The \keyword{continue} statement \label{continue}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\stindex{continue}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
continue_stmt: "continue"
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
\keyword{continue} may only occur syntactically nested in a \keyword{for} or
|
|
|
|
\keyword{while} loop, but not nested in a function or class definition or
|
1998-07-24 18:25:38 +00:00
|
|
|
\keyword{try} statement within that loop.\footnote{It may
|
|
|
|
occur within an \keyword{except} or \keyword{else} clause. The
|
2000-07-16 19:05:38 +00:00
|
|
|
restriction on occurring in the \keyword{try} clause is implementor's
|
1998-07-24 18:25:38 +00:00
|
|
|
laziness and will eventually be lifted.}
|
|
|
|
It continues with the next cycle of the nearest enclosing loop.
|
1998-05-06 19:52:49 +00:00
|
|
|
\stindex{for}
|
|
|
|
\stindex{while}
|
|
|
|
\indexii{loop}{statement}
|
|
|
|
\kwindex{finally}
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
\section{The \keyword{import} statement \label{import}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\stindex{import}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
2000-08-17 22:55:00 +00:00
|
|
|
import_stmt: "import" module ["as" name] ("," module ["as" name] )*
|
|
|
|
| "from" module "import" identifier ["as" name]
|
|
|
|
("," identifier ["as" name] )*
|
1998-07-24 18:25:38 +00:00
|
|
|
| "from" module "import" "*"
|
|
|
|
module: (identifier ".")* identifier
|
1998-05-06 19:52:49 +00:00
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
Import statements are executed in two steps: (1) find a module, and
|
|
|
|
initialize it if necessary; (2) define a name or names in the local
|
1998-07-24 18:25:38 +00:00
|
|
|
namespace (of the scope where the \keyword{import} statement occurs).
|
1998-05-06 19:52:49 +00:00
|
|
|
The first form (without \keyword{from}) repeats these steps for each
|
1998-07-24 18:25:38 +00:00
|
|
|
identifier in the list. The form with \keyword{from} performs step
|
|
|
|
(1) once, and then performs step (2) repeatedly.
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexii{importing}{module}
|
|
|
|
\indexii{name}{binding}
|
|
|
|
\kwindex{from}
|
1998-12-21 18:57:36 +00:00
|
|
|
% XXX Need to define what ``initialize'' means here
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
The system maintains a table of modules that have been initialized,
|
2000-07-06 00:50:42 +00:00
|
|
|
indexed by module name. This table is
|
1998-07-24 18:25:38 +00:00
|
|
|
accessible as \code{sys.modules}. When a module name is found in
|
1998-05-06 19:52:49 +00:00
|
|
|
this table, step (1) is finished. If not, a search for a module
|
1998-07-24 18:25:38 +00:00
|
|
|
definition is started. When a module is found, it is loaded. Details
|
|
|
|
of the module searching and loading process are implementation and
|
|
|
|
platform specific. It generally involves searching for a ``built-in''
|
|
|
|
module with the given name and then searching a list of locations
|
|
|
|
given as \code{sys.path}.
|
1998-11-25 17:40:00 +00:00
|
|
|
\withsubitem{(in module sys)}{\ttindex{modules}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\ttindex{sys.modules}
|
|
|
|
\indexii{module}{name}
|
|
|
|
\indexii{built-in}{module}
|
|
|
|
\indexii{user-defined}{module}
|
|
|
|
\refbimodindex{sys}
|
|
|
|
\indexii{filename}{extension}
|
1998-05-06 20:59:46 +00:00
|
|
|
\indexiii{module}{search}{path}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
If a built-in module is found, its built-in initialization code is
|
|
|
|
executed and step (1) is finished. If no matching file is found,
|
|
|
|
\exception{ImportError} is raised. If a file is found, it is parsed,
|
|
|
|
yielding an executable code block. If a syntax error occurs,
|
|
|
|
\exception{SyntaxError} is raised. Otherwise, an empty module of the given
|
|
|
|
name is created and inserted in the module table, and then the code
|
|
|
|
block is executed in the context of this module. Exceptions during
|
|
|
|
this execution terminate step (1).
|
|
|
|
\indexii{module}{initialization}
|
|
|
|
\exindex{SyntaxError}
|
|
|
|
\exindex{ImportError}
|
|
|
|
\index{code block}
|
|
|
|
|
|
|
|
When step (1) finishes without raising an exception, step (2) can
|
|
|
|
begin.
|
|
|
|
|
|
|
|
The first form of \keyword{import} statement binds the module name in the
|
1998-07-24 18:25:38 +00:00
|
|
|
local namespace to the module object, and then goes on to import the
|
2000-08-17 22:55:00 +00:00
|
|
|
next identifier, if any. If the module name is followed by \keyword{as},
|
2000-08-19 20:55:02 +00:00
|
|
|
the name following \keyword{as} is used as the local name for the module. To
|
|
|
|
avoid confusion, you cannot import sub-modules 'as' a different
|
|
|
|
local name. So 'import module as m' is legal, but 'import module.submod as
|
|
|
|
s' is not. The latter should be written as 'from module import submod as s',
|
|
|
|
see below.
|
|
|
|
|
2000-08-17 22:55:00 +00:00
|
|
|
The \keyword{from} form does not bind the module name: it goes through the
|
|
|
|
list of identifiers, looks each one of them up in the module found in step
|
|
|
|
(1), and binds the name in the local namespace to the object thus found.
|
|
|
|
Like with the first form of \keyword{import}, an alternate local name can be
|
|
|
|
supplied by specifying "\keyword{as} localname". If a name is not found,
|
1998-05-06 19:52:49 +00:00
|
|
|
\exception{ImportError} is raised. If the list of identifiers is replaced
|
2000-08-17 22:55:00 +00:00
|
|
|
by a star (\samp{*}), all names defined in the module are bound, except
|
|
|
|
those beginning with an underscore (\character{_}).
|
1998-05-06 19:52:49 +00:00
|
|
|
\indexii{name}{binding}
|
|
|
|
\exindex{ImportError}
|
|
|
|
|
1998-07-24 18:25:38 +00:00
|
|
|
Names bound by \keyword{import} statements may not occur in
|
|
|
|
\keyword{global} statements in the same scope.
|
1998-05-06 19:52:49 +00:00
|
|
|
\stindex{global}
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
The \keyword{from} form with \samp{*} may only occur in a module scope.
|
1998-05-06 19:52:49 +00:00
|
|
|
\kwindex{from}
|
1998-11-25 17:40:00 +00:00
|
|
|
\stindex{from}
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
(The current implementation does not enforce the latter two
|
|
|
|
restrictions, but programs should not abuse this freedom, as future
|
|
|
|
implementations may enforce them or silently change the meaning of the
|
|
|
|
program.)
|
|
|
|
|
1998-07-24 20:28:22 +00:00
|
|
|
\strong{Hierarchical module names:}\indexiii{hierarchical}{module}{names}
|
1998-07-24 18:25:38 +00:00
|
|
|
when the module names contains one or more dots, the module search
|
|
|
|
path is carried out differently. The sequence of identifiers up to
|
|
|
|
the last dot is used to find a ``package''\index{packages}; the final
|
|
|
|
identifier is then searched inside the package. A package is
|
|
|
|
generally a subdirectory of a directory on \code{sys.path} that has a
|
|
|
|
file \file{__init__.py}.\ttindex{__init__.py}
|
|
|
|
%
|
|
|
|
[XXX Can't be bothered to spell this out right now; see the URL
|
1998-08-07 17:40:20 +00:00
|
|
|
\url{http://www.python.org/doc/essays/packages.html} for more details, also
|
1998-07-24 18:25:38 +00:00
|
|
|
about how the module search works from inside a package.]
|
|
|
|
|
|
|
|
[XXX Also should mention __import__().]
|
|
|
|
\bifuncindex{__import__}
|
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
\section{The \keyword{global} statement \label{global}}
|
1998-05-06 19:52:49 +00:00
|
|
|
\stindex{global}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
global_stmt: "global" identifier ("," identifier)*
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
The \keyword{global} statement is a declaration which holds for the
|
|
|
|
entire current code block. It means that the listed identifiers are to be
|
1998-05-06 20:59:46 +00:00
|
|
|
interpreted as globals. While \emph{using} global names is automatic
|
|
|
|
if they are not defined in the local scope, \emph{assigning} to global
|
1998-05-06 19:52:49 +00:00
|
|
|
names would be impossible without \keyword{global}.
|
|
|
|
\indexiii{global}{name}{binding}
|
|
|
|
|
|
|
|
Names listed in a \keyword{global} statement must not be used in the same
|
1998-12-21 18:57:36 +00:00
|
|
|
code block textually preceding that \keyword{global} statement.
|
1998-05-06 19:52:49 +00:00
|
|
|
|
|
|
|
Names listed in a \keyword{global} statement must not be defined as formal
|
|
|
|
parameters or in a \keyword{for} loop control target, \keyword{class}
|
|
|
|
definition, function definition, or \keyword{import} statement.
|
|
|
|
|
|
|
|
(The current implementation does not enforce the latter two
|
|
|
|
restrictions, but programs should not abuse this freedom, as future
|
|
|
|
implementations may enforce them or silently change the meaning of the
|
|
|
|
program.)
|
|
|
|
|
1998-07-24 18:25:38 +00:00
|
|
|
\strong{Programmer's note:}
|
|
|
|
the \keyword{global} is a directive to the parser. It
|
1998-05-06 19:52:49 +00:00
|
|
|
applies only to code parsed at the same time as the \keyword{global}
|
|
|
|
statement. In particular, a \keyword{global} statement contained in an
|
1998-05-06 20:59:46 +00:00
|
|
|
\keyword{exec} statement does not affect the code block \emph{containing}
|
1998-05-06 19:52:49 +00:00
|
|
|
the \keyword{exec} statement, and code contained in an \keyword{exec}
|
|
|
|
statement is unaffected by \keyword{global} statements in the code
|
|
|
|
containing the \keyword{exec} statement. The same applies to the
|
|
|
|
\function{eval()}, \function{execfile()} and \function{compile()} functions.
|
|
|
|
\stindex{exec}
|
|
|
|
\bifuncindex{eval}
|
|
|
|
\bifuncindex{execfile}
|
|
|
|
\bifuncindex{compile}
|
1998-07-06 13:18:39 +00:00
|
|
|
|
1999-04-14 12:52:14 +00:00
|
|
|
\section{The \keyword{exec} statement \label{exec}}
|
1998-07-06 13:18:39 +00:00
|
|
|
\stindex{exec}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
exec_stmt: "exec" expression ["in" expression ["," expression]]
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
This statement supports dynamic execution of Python code. The first
|
|
|
|
expression should evaluate to either a string, an open file object, or
|
|
|
|
a code object. If it is a string, the string is parsed as a suite of
|
|
|
|
Python statements which is then executed (unless a syntax error
|
|
|
|
occurs). If it is an open file, the file is parsed until EOF and
|
|
|
|
executed. If it is a code object, it is simply executed.
|
|
|
|
|
|
|
|
In all cases, if the optional parts are omitted, the code is executed
|
|
|
|
in the current scope. If only the first expression after \keyword{in}
|
|
|
|
is specified, it should be a dictionary, which will be used for both
|
|
|
|
the global and the local variables. If two expressions are given,
|
|
|
|
both must be dictionaries and they are used for the global and local
|
|
|
|
variables, respectively.
|
|
|
|
|
|
|
|
As a side effect, an implementation may insert additional keys into
|
|
|
|
the dictionaries given besides those corresponding to variable names
|
|
|
|
set by the executed code. For example, the current implementation
|
|
|
|
may add a reference to the dictionary of the built-in module
|
|
|
|
\module{__builtin__} under the key \code{__builtins__} (!).
|
|
|
|
\ttindex{__builtins__}
|
|
|
|
\refbimodindex{__builtin__}
|
|
|
|
|
1998-07-24 18:25:38 +00:00
|
|
|
\strong{Programmer's hints:}
|
|
|
|
dynamic evaluation of expressions is supported by the built-in
|
1998-07-06 13:18:39 +00:00
|
|
|
function \function{eval()}. The built-in functions
|
|
|
|
\function{globals()} and \function{locals()} return the current global
|
|
|
|
and local dictionary, respectively, which may be useful to pass around
|
|
|
|
for use by \keyword{exec}.
|
|
|
|
\bifuncindex{eval}
|
|
|
|
\bifuncindex{globals}
|
|
|
|
\bifuncindex{locals}
|
2000-04-27 18:32:02 +00:00
|
|
|
|
|
|
|
Also, in the current implementation, multi-line compound statements must
|
|
|
|
end with a newline:
|
|
|
|
\code{exec "for v in seq:\e{}n\e{}tprint v\e{}n"} works, but
|
|
|
|
\code{exec "for v in seq:\e{}n\e{}tprint v"} fails with
|
|
|
|
\exception{SyntaxError}.
|
|
|
|
\exindex{SyntaxError}
|
|
|
|
|
|
|
|
|