summaryrefslogtreecommitdiffstats
path: root/Doc/ref/ref.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/ref/ref.tex')
-rw-r--r--Doc/ref/ref.tex707
1 files changed, 534 insertions, 173 deletions
diff --git a/Doc/ref/ref.tex b/Doc/ref/ref.tex
index 69b6e96..4c9fcaa 100644
--- a/Doc/ref/ref.tex
+++ b/Doc/ref/ref.tex
@@ -131,7 +131,7 @@ In lexical definitions (as the example above), two more conventions
are used: Two literal characters separated by three dots mean a choice
of any single character in the given (inclusive) range of ASCII
characters. A phrase between angular brackets (\verb\<...>\) gives an
-informal description of the symbol defined; e.g., this could be used
+informal description of the symbol defined; e.g. this could be used
to describe the notion of `control character' if needed.
\index{lexical definitions}
\index{ASCII}
@@ -158,7 +158,7 @@ chapter describes how the lexical analyzer breaks a file into tokens.
A Python program is divided in a number of logical lines. The end of
a logical line is represented by the token NEWLINE. Statements cannot
cross logical line boundaries except where NEWLINE is allowed by the
-syntax (e.g., between statements in compound statements).
+syntax (e.g. between statements in compound statements).
\index{line structure}
\index{logical line}
\index{NEWLINE token}
@@ -326,7 +326,7 @@ def finally import pass while
% print string.ljust(l[j], 10),
% print
-\section{Literals}
+\section{Literals} \label{literals}
Literals are notations for constant values of some built-in types.
\index{literal}
@@ -509,7 +509,7 @@ Every object has an identity, a type and a value. An object's {\em
identity} never changes once it has been created; you may think of it
as the object's address in memory. An object's {\em type} is also
unchangeable. It determines the operations that an object supports
-(e.g., ``does it have a length?'') and also defines the possible
+(e.g. ``does it have a length?'') and also defines the possible
values for objects of that type. The {\em value} of some objects can
change. Objects whose value can change are said to be {\em mutable};
objects whose value is unchangeable once they are created are called
@@ -559,7 +559,7 @@ Types affect almost all aspects of objects' lives. Even the meaning
of object identity is affected in some sense: for immutable types,
operations that compute new values may actually return a reference to
any existing object with the same type and value, while for mutable
-objects this is not allowed. E.g., after
+objects this is not allowed. E.g. after
\begin{verbatim}
a = 1; b = 1; c = []; d = []
@@ -574,11 +574,12 @@ lists.
Below is a list of the types that are built into Python. Extension
modules written in C can define additional types. Future versions of
-Python may add types to the type hierarchy (e.g., rational or complex
+Python may add types to the type hierarchy (e.g. rational or complex
numbers, efficiently stored arrays of integers, etc.).
\index{type}
-\index{type hierarchy}
-\index{extension module}
+\indexii{data}{type}
+\indexii{type}{hierarchy}
+\indexii{extension}{module}
\index{C}
Some of the type descriptions below contain a paragraph listing
@@ -590,8 +591,8 @@ is a list of the method names of a built-in object, if it has any;
\verb\__members__\ is a list of the data attribute names of a built-in
object, if it has any.
\index{attribute}
-\index{special attribute}
-\index{generic special attribute}
+\indexii{special}{attribute}
+\indexiii{generic}{special}{attribute}
\ttindex{__methods__}
\ttindex{__members__}
@@ -602,21 +603,23 @@ This type has a single value. There is a single object with this value.
This object is accessed through the built-in name \verb\None\.
It is returned from functions that don't explicitly return an object.
\ttindex{None}
+\obindex{None@{\tt None}}
\item[Numbers]
-These are created by numeric literals and returned as results
-by arithmetic operators and arithmetic built-in functions.
-Numeric objects are immutable; once created their value never changes.
-Python numbers are of course strongly related to mathematical numbers,
-but subject to the limitations of numerical representation in computers.
-\index{number}
+These are created by numeric literals and returned as results by
+arithmetic operators and arithmetic built-in functions. Numeric
+objects are immutable; once created their value never changes. Python
+numbers are of course strongly related to mathematical numbers, but
+subject to the limitations of numerical representation in computers.
+\obindex{number}
+\obindex{numeric}
Python distinguishes between integers and floating point numbers:
\begin{description}
\item[Integers]
These represent elements from the mathematical set of whole numbers.
-\index{integer}
+\obindex{integer}
There are two types of integers:
@@ -632,7 +635,7 @@ For the purpose of shift and mask operations, integers are assumed to
have a binary, 2's complement notation using 32 or more bits, and
hiding no bits from the user (i.e., all $2^{32}$ different bit
patterns correspond to different values).
-\index{plain integer}
+\obindex{plain integer}
\item[Long integers]
These represent numbers in an unlimited range, subject to avaiable
@@ -640,7 +643,7 @@ These represent numbers in an unlimited range, subject to avaiable
a binary representation is assumed, and negative numbers are
represented in a variant of 2's complement which gives the illusion of
an infinite string of sign bits extending to the left.
-\index{long integer}
+\obindex{long integer}
\end{description} % Integers
@@ -651,13 +654,14 @@ plain and long integer domains. For any operation except left shift,
if it yields a result in the plain integer domain without causing
overflow, it will yield the same result in the long integer domain or
when using mixed operands.
-\index{integer representation}
+\indexii{integer}{representation}
\item[Floating point numbers]
These represent machine-level double precision floating point numbers.
You are at the mercy of the underlying machine architecture and
C implementation for the accepted range and handling of overflow.
-\index{floating point number}
+\obindex{floating point}
+\indexii{floating point}{number}
\index{C}
\end{description} % Numbers
@@ -668,7 +672,7 @@ The built-in function \verb\len()\ returns the number of elements
of a sequence. When this number is $n$, the index set contains
the numbers $0, 1, \ldots, n-1$. Element \verb\i\ of sequence
\verb\a\ is selected by \verb\a[i]\.
-\index{seqence}
+\obindex{seqence}
\bifuncindex{len}
\index{index operation}
\index{item selection}
@@ -690,7 +694,8 @@ created. (If the object contains references to other objects,
these other objects may be mutable and may be changed; however
the collection of objects directly referenced by an immutable object
cannot change.)
-\index{immutable sequence}
+\obindex{immutable sequence}
+\obindex{immutable}
The following types are immutable sequences:
@@ -703,9 +708,9 @@ Characters represent (at least) 8-bit bytes. The built-in
functions \verb\chr()\ and \verb\ord()\ convert between characters
and nonnegative integers representing the byte values.
Bytes with the values 0-127 represent the corresponding ASCII values.
-The string data type is also used to represent arrays of bytes, e.g.,
+The string data type is also used to represent arrays of bytes, e.g.
to hold data read from a file.
-\index{string}
+\obindex{string}
\index{character}
\index{byte}
\index{ASCII}
@@ -720,7 +725,7 @@ Or perhaps someone can propose a better rule?)
\index{ASCII}
\index{EBCDIC}
\index{character set}
-\index{string comparison}
+\indexii{string}{comparison}
\bifuncindex{chr}
\bifuncindex{ord}
@@ -732,9 +737,9 @@ by affixing a comma to an expression (an expression by itself does
not create a tuple, since parentheses must be usable for grouping of
expressions). An empty tuple can be formed by enclosing `nothing' in
parentheses.
-\index{tuple}
-\index{singleton tuple}
-\index{empty tuple}
+\obindex{tuple}
+\indexii{singleton}{tuple}
+\indexii{empty}{tuple}
\end{description} % Immutable sequences
@@ -742,9 +747,11 @@ parentheses.
Mutable sequences can be changed after they are created. The
subscription and slicing notations can be used as the target of
assignment and \verb\del\ (delete) statements.
-\index{mutable sequece}
-\index{assignment statement}
-\kwindex{del}
+\obindex{mutable sequece}
+\obindex{mutable}
+\indexii{assignment}{statement}
+\index{delete}
+\stindex{del}
\index{subscription}
\index{slicing}
@@ -757,7 +764,7 @@ The elements of a list are arbitrary Python objects. Lists are formed
by placing a comma-separated list of expressions in square brackets.
(Note that there are no special cases needed to form lists of length 0
or 1.)
-\index{list}
+\obindex{list}
\end{description} % Mutable sequences
@@ -772,7 +779,7 @@ The built-in function \verb\len()\ returns the number of elements
in a mapping.
\bifuncindex{len}
\index{subscription}
-\index{mapping}
+\obindex{mapping}
There is currently a single mapping type:
@@ -780,19 +787,21 @@ There is currently a single mapping type:
\item[Dictionaries]
These represent finite sets of objects indexed by strings.
-Dictionaries are created by the \verb\{...}\ notation (see section
-\ref{dict}). (Implementation note: the strings used for indexing must
-not contain null bytes.)
-\index{dictionary}
+Dictionaries are mutable; they are created by the \verb\{...}\
+notation (see section \ref{dict}). (Implementation note: the strings
+used for indexing must not contain null bytes.)
+\obindex{dictionary}
+\obindex{mutable}
\end{description} % Mapping types
\item[Callable types]
These are the types to which the function call (invocation) operation,
written as \verb\function(argument, argument, ...)\, can be applied:
-\index{callable type}
\indexii{function}{call}
\index{invocation}
+\indexii{function}{argument}
+\obindex{callable}
\begin{description}
@@ -802,7 +811,8 @@ A user-defined function object is created by a function definition
list containing the same number of items as the function's formal
parameter list.
\indexii{user-defined}{function}
-\index{function object}
+\obindex{function}
+\obindex{user-defined function}
Special read-only attributes: \verb\func_code\ is the code object
representing the compiled function body, and \verb\func_globals\ is (a
@@ -820,8 +830,10 @@ called with an argument list containing one item less than the number
of items in the function's formal parameter list. When called, the
class instance becomes the first argument, and the call arguments are
shifted one to the right.
-\indexii{object}{closure}
+\obindex{method}
+\obindex{user-defined method}
indexii{user-defined}{method}
+\index{object closure}
Special read-only attributes: \verb\im_self\ is the class instance
object, \verb\im_func\ is the function object.
@@ -833,6 +845,8 @@ A built-in function object is a wrapper around a C function. Examples
of built-in functions are \verb\len\ and \verb\math.sin\. There
are no special attributes. The number and type of the arguments are
determined by the C function.
+\obindex{built-in function}
+\obindex{function}
\index{C}
\item[Built-in methods]
@@ -840,6 +854,8 @@ This is really a different disguise of a built-in function, this time
containing an object passed to the C function as an implicit extra
argument. An example of a built-in method is \verb\list.append\ if
\verb\list\ is a list object.
+\obindex{built-in method}
+\obindex{method}
\indexii{built-in}{method}
\item[Classes]
@@ -848,7 +864,10 @@ parameterless function, a new class instance (also described below) is
created and returned. The class's initialization function is not
called --- this is the responsibility of the caller. It is illegal to
call a class object with one or more arguments.
-\index{class}
+\obindex{class}
+\obindex{class instance}
+\obindex{instance}
+\indexii{class object}{call}
\end{description}
@@ -862,7 +881,7 @@ dictionary. A module object does not contain the code object used to
initialize the module (since it isn't needed once the initialization
is done).
\stindex{import}
-\index{module}
+\obindex{module}
Attribute assignment update the module's name space dictionary.
@@ -871,6 +890,7 @@ space as a dictionary object; \verb\__name__\ yields the module's name
as a string object.
\ttindex{__dict__}
\ttindex{__name__}
+\indexii{module}{name space}
\item[Classes]
Class objects are created by class definitions (see section
@@ -880,7 +900,10 @@ lookups in this dictionary. When an attribute name is not found
there, the attribute search continues in the base classes. The search
is depth-first, left-to-right in the order of their occurrence in the
base class list.
-\index{class}
+\obindex{class}
+\obindex{class instance}
+\obindex{instance}
+\indexii{class object}{call}
\index{container}
\index{dictionary}
\indexii{class}{attribute}
@@ -891,6 +914,7 @@ dictionary of a base class.
A class can be called as a parameterless function to yield a class
instance (see above).
+\indexii{class object}{call}
Special read-only attributes: \verb\__dict__\ yields te dictionary
containing the class's name space; \verb\__bases__\ yields a tuple
@@ -907,6 +931,8 @@ there, and the instance's class has an attribute by that name, and
that class attribute is a user-defined function (and in no other
cases), the instance attribute reference yields a user-defined method
object (see above) constructed from the instance and the function.
+\obindex{class instance}
+\obindex{instance}
\indexii{class}{instance}
\indexii{class instance}{attribute}
@@ -927,7 +953,7 @@ the \verb\makefile\ method of socket objects. \verb\sys.stdin\,
the the interpreter's standard input, output and error streams.
See the Python Library Reference for methods of file objects and other
details.
-\index{file}
+\obindex{file}
\index{C}
\index{stdio}
\bifuncindex{open}
@@ -936,6 +962,9 @@ details.
\ttindex{stdin}
\ttindex{stdout}
\ttindex{stderr}
+\ttindex{sys.stdin}
+\ttindex{sys.stdout}
+\ttindex{sys.stderr}
\item[Internal types]
A few types used internally by the interpreter are exposed to the user.
@@ -951,7 +980,7 @@ object and a function object is that the function object contains an
explicit reference to the function's context (the module in which it
was defined) which a code object contains no context. There is no way
to execute a bare code object.
-\index{code object}
+\obindex{code}
Special read-only attributes: \verb\co_code\ is a string representing
the sequence of instructions; \verb\co_consts\ is a list of literals
@@ -968,7 +997,7 @@ example of how to do this.)
\item[Frame objects]
Frame objects represent execution frames. They may occur in traceback
objects (see below).
-\index{frame object}
+\obindex{frame}
Special read-only attributes: \verb\f_back\ is to the previous
stack frame (towards the caller), or \verb\None\ if this is the bottom
@@ -996,12 +1025,14 @@ program contains no suitable handler, the stack trace is written
(nicely formatted) to the standard error stream; if the interpreter is
interactive, it is also made available to the user as
\verb\sys.last_traceback\.
-\index{traceback object}
+\obindex{traceback}
\indexii{stack}{trace}
-\index{exception handler}
-\index{execution stack}
+\indexii{exception}{handler}
+\indexii{execution}{stack}
\ttindex{exc_traceback}
\ttindex{last_traceback}
+\ttindex{sys.exc_traceback}
+\ttindex{sys.last_traceback}
Special read-only attributes: \verb\tb_next\ is the next level in the
stack trace (towards the frame where the exception occurred), or
@@ -1023,8 +1054,12 @@ exception occurred in a \verb\try\ statement with no matching
\end{description} % Types
\chapter{Execution model}
+\index{execution model}
-\section{Code blocks, execution frames, and name spaces}
+\section{Code blocks, execution frames, and name spaces} \label{execframes}
+\index{code block}
+\indexii{execution}{frame}
+\index{name space}
A {\em code block} is a piece of Python program text that can be
executed as a unit, such as a module, a class definition or a function
@@ -1032,8 +1067,9 @@ body. Some code blocks (like modules) are executed only once, others
(like function bodies) may be executed many times. Code block may
textually contain other code blocks. Code blocks may invoke other
code blocks (that may or may not be textually contained in them) as
-part of their execution, e.g., by invoking (calling) a function.
+part of their execution, e.g. by invoking (calling) a function.
\index{code block}
+\indexii{code}{block}
The following are code blocks: A module is a code block. A function
body is a code block. A class definition is a code block. Each
@@ -1049,7 +1085,7 @@ determines where and how execution continues after the code block's
execution has completed, and (perhaps most importantly) defines two
name spaces, the local and the global name space, that affect
execution of the code block.
-\index{execution frame}
+\indexii{execution}{frame}
A {\em name space} is a mapping from names (identifiers) to objects.
A particular name space may be referenced by more than one execution
@@ -1166,9 +1202,11 @@ See also the description of the \verb\try\ and \verb\raise\
statements.
\chapter{Expressions and conditions}
+\index{expression}
+\index{condition}
-In this and the following chapters, extended BNF notation will be used
-to describe syntax, not lexical analysis.
+{\bf Note:} In this and the following chapters, extended BNF notation
+will be used to describe syntax, not lexical analysis.
\index{BNF}
This chapter explains the meaning of the elements of expressions and
@@ -1176,14 +1214,16 @@ conditions. Conditions are a superset of expressions, and a condition
may be used wherever an expression is required by enclosing it in
parentheses. The only places where expressions are used in the syntax
instead of conditions is in expression statements and on the
-right-hand side of assignments; this catches some nasty bugs like
-accedentally writing \verb\x == 1\ instead of \verb\x = 1\.
+right-hand side of assignment statements; this catches some nasty bugs
+like accedentally writing \verb\x == 1\ instead of \verb\x = 1\.
+\indexii{assignment}{statement}
The comma plays several roles in Python's syntax. It is usually an
operator with a lower precedence than all others, but occasionally
-serves other purposes as well; e.g., it separates function arguments,
+serves other purposes as well; e.g. it separates function arguments,
is used in list and dictionary constructors, and has special semantics
in \verb\print\ statements.
+\index{comma}
When (one alternative of) a syntax rule has the form
@@ -1193,14 +1233,20 @@ name: othername
and no semantics are given, the semantics of this form of \verb\name\
are the same as for \verb\othername\.
+\index{syntax}
\section{Arithmetic conversions}
+\indexii{arithmetic}{conversion}
When a description of an arithmetic operator below uses the phrase
``the numeric arguments are converted to a common type'',
this both means that if either argument is not a number, a
\verb\TypeError\ exception is raised, and that otherwise
the following conversions are applied:
+\exindex{TypeError}
+\indexii{floating point}{number}
+\indexii{long}{integer}
+\indexii{plain}{integer}
\begin{itemize}
\item first, if either argument is a floating point number,
@@ -1212,6 +1258,7 @@ the following conversions are applied:
\end{itemize}
\section{Atoms}
+\index{atom}
Atoms are the most basic elements of expressions. Forms enclosed in
reverse quotes or in parentheses, brackets or braces are also
@@ -1223,6 +1270,8 @@ enclosure: parenth_form | list_display | dict_display | string_conversion
\end{verbatim}
\subsection{Identifiers (Names)}
+\index{name}
+\index{identifier}
An identifier occurring as an atom is a reference to a local, global
or built-in name binding. If a name can be assigned to anywhere in a
@@ -1230,12 +1279,19 @@ code block, and is not mentioned in a \verb\global\ statement in that
code block, it refers to a local name throughout that code block.
Otherwise, it refers to a global name if one exists, else to a
built-in name.
+\indexii{name}{binding}
+\index{code block}
+\stindex{global}
+\indexii{built-in}{name}
+\indexii{global}{name}
When the name is bound to an object, evaluation of the atom yields
that object. When a name is not bound, an attempt to evaluate it
raises a \verb\NameError\ exception.
+\exindex{NameError}
\subsection{Literals}
+\index{literal}
Python knows string and numeric literals:
@@ -1243,21 +1299,23 @@ Python knows string and numeric literals:
literal: stringliteral | integer | longinteger | floatnumber
\end{verbatim}
-Evaluation of a literal yields an object of the given type
-(string, integer, long integer, floating point number)
-with the given value.
+Evaluation of a literal yields an object of the given type (string,
+integer, long integer, floating point number) with the given value.
The value may be approximated in the case of floating point literals.
+See section \ref{literals} for details.
All literals correspond to immutable data types, and hence the
object's identity is less important than its value. Multiple
evaluations of literals with the same value (either the same
occurrence in the program text or a different occurrence) may obtain
the same object or a different object with the same value.
+\indexiii{immutable}{data}{type}
(In the original implementation, all literals in the same code block
with the same type and value yield the same object.)
\subsection{Parenthesized forms}
+\index{parenthesized form}
A parenthesized form is an optional condition list enclosed in
parentheses:
@@ -1271,14 +1329,18 @@ yields.
An empty pair of parentheses yields an empty tuple object. Since
tuples are immutable, the rules for literals apply here.
+\indexii{empty}{tuple}
(Note that tuples are not formed by the parentheses, but rather by use
of the comma operator. The exception is the empty tuple, for which
parentheses {\em are} required --- allowing unparenthesized ``nothing''
in expressions would causes ambiguities and allow common typos to
pass uncaught.)
+\index{comma}
+\index{tuple}{display}
\subsection{List displays}
+\indexii{list}{display}
A list display is a possibly empty series of conditions enclosed in
square brackets:
@@ -1288,15 +1350,21 @@ list_display: "[" [condition_list] "]"
\end{verbatim}
A list display yields a new list object.
+\obindex{list}
-If it has no condition list, the list object has no items.
-Otherwise, the elements of the condition list are evaluated
-from left to right and inserted in the list object in that order.
+If it has no condition list, the list object has no items. Otherwise,
+the elements of the condition list are evaluated from left to right
+and inserted in the list object in that order.
+\indexii{empty}{list}
\subsection{Dictionary displays} \label{dict}
+\indexii{dictionary}{display}
A dictionary display is a possibly empty series of key/datum pairs
enclosed in curly braces:
+\index{key}
+\index{datum}
+\index{key/datum pair}
\begin{verbatim}
dict_display: "{" [key_datum_list] "}"
@@ -1305,17 +1373,20 @@ key_datum: condition ":" condition
\end{verbatim}
A dictionary display yields a new dictionary object.
+\obindex{dictionary}
The key/datum pairs are evaluated from left to right to define the
entries of the dictionary: each key object is used as a key into the
dictionary to store the corresponding datum.
-Keys must be strings, otherwise a \verb\TypeError\ exception is raised.
-Clashes between duplicate keys are not detected; the last datum
-(textually rightmost in the display) stored for a given key value
-prevails.
+Keys must be strings, otherwise a \verb\TypeError\ exception is
+raised. Clashes between duplicate keys are not detected; the last
+datum (textually rightmost in the display) stored for a given key
+value prevails.
+\exindex{TypeError}
\subsection{String conversions}
+\indexii{string}{conversion}
A string conversion is a condition list enclosed in reverse (or
backward) quotes:
@@ -1324,8 +1395,9 @@ backward) quotes:
string_conversion: "`" condition_list "`"
\end{verbatim}
-A string conversion evaluates the contained condition list and converts the
-resulting object into a string according to rules specific to its type.
+A string conversion evaluates the contained condition list and
+converts the resulting object into a string according to rules
+specific to its type.
If the object is a string, a number, \verb\None\, or a tuple, list or
dictionary containing only objects whose type is one of these, the
@@ -1337,11 +1409,13 @@ involved).
(In particular, converting a string adds quotes around it and converts
``funny'' characters to escape sequences that are safe to print.)
-It is illegal to attempt to convert recursive objects (e.g., lists or
+It is illegal to attempt to convert recursive objects (e.g. lists or
dictionaries that contain a reference to themselves, directly or
indirectly.)
+\obindex{recursive}
\section{Primaries} \label{primaries}
+\index{primary}
Primaries represent the most tightly bound operations of the language.
Their syntax is:
@@ -1351,6 +1425,7 @@ primary: atom | attributeref | subscription | slicing | call
\end{verbatim}
\subsection{Attribute references}
+\indexii{attribute}{reference}
An attribute reference is a primary followed by a period and a name:
@@ -1359,16 +1434,27 @@ attributeref: primary "." identifier
\end{verbatim}
The primary must evaluate to an object of a type that supports
-attribute references, e.g., a module or a list. This object is then
+attribute references, e.g. a module or a list. This object is then
asked to produce the attribute whose name is the identifier. If this
attribute is not available, the exception \verb\AttributeError\ is
raised. Otherwise, the type and value of the object produced is
determined by the object. Multiple evaluations of the same attribute
reference may yield different objects.
+\obindex{module}
+\obindex{list}
\subsection{Subscriptions}
+\index{subscription}
-A subscription selects an item of a sequence or mapping object:
+A subscription selects an item of a sequence (string, tuple or list)
+or mapping (dictionary) object:
+\obindex{sequence}
+\obindex{mapping}
+\obindex{string}
+\obindex{tuple}
+\obindex{list}
+\obindex{dictionary}
+\indexii{sequence}{item}
\begin{verbatim}
subscription: primary "[" condition "]"
@@ -1382,17 +1468,26 @@ the value in the mapping that corresponds to that key.
If it is a sequence, the condition must evaluate to a plain integer.
If this value is negative, the length of the sequence is added to it
-(so that, e.g., \verb\x[-1]\ selects the last item of \verb\x\.)
+(so that, e.g. \verb\x[-1]\ selects the last item of \verb\x\.)
The resulting value must be a nonnegative integer smaller than the
number of items in the sequence, and the subscription selects the item
whose index is that value (counting from zero).
A string's items are characters. A character is not a separate data
type but a string of exactly one character.
+\index{character}
+\indexii{string}{item}
\subsection{Slicings}
+\index{slicing}
+\index{slice}
-A slicing selects a range of items in a sequence object:
+A slicing (or slice) selects a range of items in a sequence (string,
+tuple or list) object:
+\obindex{sequence}
+\obindex{string}
+\obindex{tuple}
+\obindex{list}
\begin{verbatim}
slicing: primary "[" [condition] ":" [condition] "]"
@@ -1408,9 +1503,12 @@ empty sequence. It is not an error if $i$ or $j$ lie outside the
range of valid indexes (such items don't exist so they aren't
selected).
-\subsection{Calls}
+\subsection{Calls} \label{calls}
+\index{call}
-A call calls a function with a possibly empty series of arguments:
+A call calls a callable object (e.g. a function) with a possibly empty
+series of arguments:
+\obindex{callable}
\begin{verbatim}
call: primary "(" [condition_list] ")"
@@ -1430,23 +1528,44 @@ of the callable object. If it is:
\item[a user-defined function:] the code block for the function is
executed, passing it the argument list. The first thing the code
-block will do is bind the formal parameters to the arguments. When
-the code block executes a \verb\return\ statement, this specifies the
-return value of the function call.
+block will do is bind the formal parameters to the arguments; this is
+described in section \ref{function}. When the code block executes a
+\verb\return\ statement, this specifies the return value of the
+function call.
+\indexii{function}{call}
+\indexiii{user-defined}{function}{call}
+\obindex{user-defined function}
+\obindex{function}
\item[a built-in function or method:] the result is up to the
interpreter; see the library reference manual for the descriptions of
built-in functions and methods.
+\indexii{function}{call}
+\indexii{built-in function}{call}
+\indexii{method}{call}
+\indexii{built-in method}{call}
+\obindex{built-in method}
+\obindex{built-in function}
+\obindex{method}
+\obindex{function}
\item[a class object:] a new instance of that class is returned.
+\obindex{class}
+\indexii{class object}{call}
\item[a class instance method:] the corresponding user-defined
function is called, with an argument list that is one longer than the
argument list of the call: the instance becomes the first argument.
+\obindex{class instance}
+\obindex{instance}
+\indexii{instance}{call}
+\indexii{class instance}{call}
\end{description}
\section{Unary arithmetic operations}
+\indexiii{unary}{arithmetic}{operation}
+\indexiii{unary}{bit-wise}{operation}
All unary arithmetic (and bit-wise) operations have the same priority:
@@ -1454,19 +1573,26 @@ All unary arithmetic (and bit-wise) operations have the same priority:
u_expr: primary | "-" u_expr | "+" u_expr | "~" u_expr
\end{verbatim}
-The unary \verb\"-"\ operator yields the negative of its
+The unary \verb\"-"\ (minus) operator yields the negation of its
numeric argument.
+\index{negation}
+\index{minus}
-The unary \verb\"+"\ operator yields its numeric argument unchanged.
+The unary \verb\"+"\ (plus) operator yields its numeric argument
+unchanged.
+\index{plus}
-The unary \verb\"~"\ operator yields the bit-wise negation of its
-plain or long integer argument. The bit-wise negation negation of
+The unary \verb\"~"\ (invert) operator yields the bit-wise inversion
+of its plain or long integer argument. The bit-wise inversion of
\verb\x\ is defined as \verb\-(x+1)\.
+\index{inversion}
In all three cases, if the argument does not have the proper type,
a \verb\TypeError\ exception is raised.
+\exindex{TypeError}
\section{Binary arithmetic operations}
+\indexiii{binary}{arithmetic}{operation}
The binary arithmetic operations have the conventional priority
levels. Note that some of these operations also apply to certain
@@ -1485,6 +1611,7 @@ must be a plain integer and the other must be a sequence. In the
former case, the numbers are converted to a common type and then
multiplied together. In the latter case, sequence repetition is
performed; a negative repetition factor yields an empty sequence.
+\index{multiplication}
The \verb\"/"\ (division) operator yields the quotient of its
arguments. The numeric arguments are first converted to a common
@@ -1492,15 +1619,18 @@ type. Plain or long integer division yields an integer of the same
type; the result is that of mathematical division with the `floor'
function applied to the result. Division by zero raises the
\verb\ZeroDivisionError\ exception.
+\exindex{ZeroDivisionError}
+\index{division}
The \verb\"%"\ (modulo) operator yields the remainder from the
division of the first argument by the second. The numeric arguments
are first converted to a common type. A zero right argument raises
the \verb\ZeroDivisionError\ exception. The arguments may be floating
-point numbers, e.g., \verb\3.14 % 0.7\ equals \verb\0.34\. The modulo
+point numbers, e.g. \verb\3.14 % 0.7\ equals \verb\0.34\. The modulo
operator always yields a result with the same sign as its second
operand (or zero); the absolute value of the result is strictly
smaller than the second operand.
+\index{modulo}
The integer division and modulo operators are connected by the
following identity: \verb\x == (x/y)*y + (x%y)\. Integer division and
@@ -1514,12 +1644,15 @@ The arguments must either both be numbers, or both sequences of the
same type. In the former case, the numbers are converted to a common
type and then added together. In the latter case, the sequences are
concatenated.
+\index{addition}
The \verb\"-"\ (subtraction) operator yields the difference of its
arguments. The numeric arguments are first converted to a common
type.
+\index{subtraction}
\section{Shifting operations}
+\indexii{shifting}{operation}
The shifting operations have lower priority than the arithmetic
operations:
@@ -1539,8 +1672,10 @@ integers there is no overflow check so this drops bits and flip the
sign if the result is not less than $2^{31}$ in absolute value.
Negative shift counts raise a \verb\ValueError\ exception.
+\exindex{ValueError}
-\section{Bitwise operations}
+\section{Binary bit-wise operations}
+\indexiii{binary}{bit-wise}{operation}
Each of the three bitwise operations has a different priority level:
@@ -1553,42 +1688,49 @@ or_expr: xor_expr | or_expr "|" xor_expr
The \verb\"&"\ operator yields the bitwise AND of its arguments, which
must be plain or long integers. The arguments are converted to a
common type.
+\indexii{bit-wise}{and}
-The \verb\"~"\ operator yields the bitwise XOR (exclusive OR) of its
+The \verb\"^"\ operator yields the bitwise XOR (exclusive OR) of its
arguments, which must be plain or long integers. The arguments are
converted to a common type.
+\indexii{bit-wise}{xor}
+\indexii{exclusive}{or}
The \verb\"|"\ operator yields the bitwise (inclusive) OR of its
arguments, which must be plain or long integers. The arguments are
converted to a common type.
+\indexii{bit-wise}{or}
+\indexii{inclusive}{or}
\section{Comparisons}
+\index{comparison}
Contrary to C, all comparison operations in Python have the same
priority, which is lower than that of any arithmetic, shifting or
bitwise operation. Also contrary to C, expressions like
\verb\a < b < c\ have the interpretation that is conventional in
mathematics:
+\index{C}
\begin{verbatim}
comparison: or_expr (comp_operator or_expr)*
comp_operator: "<"|">"|"=="|">="|"<="|"<>"|"!="|"is" ["not"]|["not"] "in"
\end{verbatim}
-Comparisons yield integer value: 1 for true, 0 for false.
+Comparisons yield integer values: 1 for true, 0 for false.
-Comparisons can be chained arbitrarily,
-e.g., $x < y <= z$ is equivalent to
-$x < y$ \verb\and\ $y <= z$, except that $y$ is evaluated only once
-(but in both cases $z$ is not evaluated at all when $x < y$ is
-found to be false).
+Comparisons can be chained arbitrarily, e.g. $x < y <= z$ is
+equivalent to $x < y$ \verb\and\ $y <= z$, except that $y$ is
+evaluated only once (but in both cases $z$ is not evaluated at all
+when $x < y$ is found to be false).
+\indexii{chaining}{comparisons}
Formally, $e_0 op_1 e_1 op_2 e_2 ...e_{n-1} op_n e_n$ is equivalent to
$e_0 op_1 e_1$ \verb\and\ $e_1 op_2 e_2$ \verb\and\ ... \verb\and\
$e_{n-1} op_n e_n$, except that each expression is evaluated at most once.
Note that $e_0 op_1 e_1 op_2 e_2$ does not imply any kind of comparison
-between $e_0$ and $e_2$, e.g., $x < y > z$ is perfectly legal.
+between $e_0$ and $e_2$, e.g. $x < y > z$ is perfectly legal.
The forms \verb\<>\ and \verb\!=\ are equivalent; for consistency with
C, \verb\!=\ is preferred; where \verb\!=\ is mentioned below
@@ -1600,9 +1742,9 @@ If both are numbers, they are coverted to a common type. Otherwise,
objects of different types {\em always} compare unequal, and are
ordered consistently but arbitrarily.
-(This unusual
-definition of comparison is done to simplify the definition of
-operations like sorting and the \verb\in\ and \verb\not in\ operators.)
+(This unusual definition of comparison is done to simplify the
+definition of operations like sorting and the \verb\in\ and \verb\not
+in\ operators.)
Comparison of objects of the same type depends on the type:
@@ -1643,12 +1785,20 @@ $x ~\verb\not in\~ y$ yields the inverse truth value. The exception
\verb\TypeError\ is raised when $y$ is not a sequence, or when $y$ is
a string and $x$ is not a string of length one.%
\footnote{The latter restriction is sometimes a nuisance.}
+\opindex{in}
+\opindex{not in}
+\indexii{membership}{test}
+\obindex{sequence}
-The operators \verb\is\ and \verb\is not\ compare object identity:
+The operators \verb\is\ and \verb\is not\ test for object identity:
$x ~\verb\is\~ y$ is true if and only if $x$ and $y$ are the same
object. $x ~\verb\is not\~ y$ yields the inverse truth value.
+\opindex{is}
+\opindex{is not}
+\indexii{identity}{test}
\section{Boolean operations} \label{Booleans}
+\indexii{Boolean}{operation}
Boolean operations have the lowest priority of all Python operations:
@@ -1666,14 +1816,17 @@ as false: \verb\None\, numeric zero of all types, empty sequences
other values are interpreted as true.
The operator \verb\not\ yields 1 if its argument is false, 0 otherwise.
+\opindex{not}
The condition $x ~\verb\and\~ y$ first evaluates $x$; if $x$ is false,
its value is returned; otherwise, $y$ is evaluated and the resulting
value is returned.
+\opindex{and}
The condition $x ~\verb\or\~ y$ first evaluates $x$; if $x$ is true,
its value is returned; otherwise, $y$ is evaluated and the resulting
value is returned.
+\opindex{or}
(Note that \verb\and\ and \verb\or\ do not restrict the value and type
they return to 0 and 1, but rather return the last evaluated argument.
@@ -1685,6 +1838,8 @@ same type as its argument, so e.g. \verb\not 'foo'\ yields \verb\0\,
not \verb\''\.)
\section{Expression lists and condition lists}
+\indexii{expression}{list}
+\indexii{condition}{list}
\begin{verbatim}
expr_list: or_expr ("," or_expr)* [","]
@@ -1707,16 +1862,19 @@ tuple. The length of the tuple is the number of expressions
from left to right. (Conditions lists are used syntactically is a few
places where no tuple is constructed but a list of values is needed
nevertheless.)
+\obindex{tuple}
The trailing comma is required only to create a single tuple (a.k.a. a
{\em singleton}); it is optional in all other cases. A single
expression (condition) without a trailing comma doesn't create a
tuple, but rather yields the value of that expression (condition).
+\indexii{trailing}{comma}
(To create an empty tuple, use an empty pair of parentheses:
\verb\()\.)
\chapter{Simple statements}
+\indexii{simple}{statement}
Simple statements are comprised within a single logical line.
Several simple statements may occur on a single line separated
@@ -1737,6 +1895,7 @@ simple_stmt: expression_stmt
\end{verbatim}
\section{Expression statements}
+\indexii{expression}{statement}
Expression statements are used (mostly interactively) to compute and
write a value, or (usually) to call a procedure (a function that
@@ -1751,16 +1910,28 @@ An expression statement evaluates the expression list (which may be a
single expression). If the value is not \verb\None\, it is converted
to a string using the rules for string conversions (expressions in
reverse quotes), and the resulting string is written to standard
-output on a line by itself.
+output (see section \ref{print}) on a line by itself.
+\indexii{expression}{list}
+\ttindex{None}
+\indexii{string}{conversion}
+\index{output}
+\indexii{standard}{output}
+\indexii{writing}{values}
(The exception for \verb\None\ is made so that procedure calls, which
are syntactically equivalent to expressions, do not cause any output.
A tuple with only \verb\None\ items is written normally.)
+\indexii{procedure}{call}
\section{Assignment statements}
+\indexii{assignment}{statement}
Assignment statements are used to (re)bind names to values and to
modify attributes or items of mutable objects:
+\indexii{binding}{name}
+\indexii{rebinding}{name}
+\obindex{mutable}
+\indexii{attribute}{assignment}
\begin{verbatim}
assignment_stmt: (target_list "=")+ expression_list
@@ -1776,6 +1947,7 @@ 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
@@ -1784,9 +1956,12 @@ 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
@@ -1801,22 +1976,28 @@ corresponding targets.
\end{itemize}
-Assignment of an object to a (simple) target is recursively defined as
+Assignment of an object to a single target is recursively defined as
follows.
-\begin{itemize}
+\begin{itemize} % nested
\item
If the target is an identifier (name):
+
\begin{itemize}
+
\item
If the name does not occur in a \verb\global\ statement in the current
code block: the name is bound to the object in the current local name
space.
+\stindex{global}
+
\item
Otherwise: the name is bound to the object in the current global name
space.
-\end{itemize}
+
+\end{itemize} % nested
+
The name is rebound if it was already bound.
\item
@@ -1836,27 +2017,34 @@ attributes; if this is not the case, \verb\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 \verb\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
(list) object or a mapping (dictionary) object. Next, the subscript
expression is evaluated.
-
-If the primary is a sequence object, the subscript 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,
-\verb\IndexError\ is raised (assignment to a subscripted sequence
-cannot add new items to a list).
-
-If the primary is a mapping object, the subscript must have a type
-compatible with the mapping's key type, and the mapping is then asked
-to 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).
+\indexii{subscription}{assignment}
+\obindex{mutable}
+
+If the primary is a mutable sequence object (a list), the subscript
+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, \verb\IndexError\ is raised (assignment to a subscripted
+sequence cannot add new items to a list).
+\obindex{sequence}
+\obindex{list}
+
+If the primary is a mapping (dictionary) object, the subscript must
+have a type compatible with the mapping's key type, and the mapping is
+then asked to 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
@@ -1870,6 +2058,7 @@ lie between zero and the sequence's length, inclusive. Finally, the
sequence object is asked to replace the items indicated by the slice
with the items of the assigned sequence. This may change the
sequence's length, if it allows it.
+\indexii{slicing}{assignment}
\end{itemize}
@@ -1879,6 +2068,7 @@ during the code generation phase, causing less detailed error
messages.)
\section{The {\tt pass} statement}
+\stindex{pass}
\begin{verbatim}
pass_stmt: "pass"
@@ -1887,6 +2077,7 @@ pass_stmt: "pass"
\verb\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)
@@ -1895,6 +2086,7 @@ class C: pass # an class with no methods (yet)
\end{verbatim}
\section{The {\tt del} statement}
+\stindex{del}
\begin{verbatim}
del_stmt: "del" target_list
@@ -1903,20 +2095,26 @@ del_stmt: "del" target_list
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 target list recursively deletes each target, from left
+to right.
Deletion of a name removes the binding of that name (which must exist)
from the local or global name space, depending on whether the name
occurs in a \verb\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}
-\section{The {\tt print} statement}
+\section{The {\tt print} statement} \label{print}
+\stindex{print}
\begin{verbatim}
print_stmt: "print" [ condition ("," condition)* [","] ]
@@ -1934,18 +2132,27 @@ output is \verb/\n/; or (3) when the last write operation on standard
output was not a \verb\print\ statement. (In some cases it may be
functional to write an empty string to standard output for this
reason.)
+\index{output}
+\indexii{writing}{values}
A \verb/"\n"/ character is written at the end, unless the \verb\print\
statement ends with a comma. This is the only action if the statement
contains just the keyword \verb\print\.
+\indexii{trailing}{comma}
+\indexii{newline}{suppression}
Standard output is defined as the file object named \verb\stdout\
in the built-in module \verb\sys\. If no such object exists,
or if it is not a writable file, a \verb\RuntimeError\ exception is raised.
(The original implementation attempts to write to the system's original
standard output instead, but this is not safe, and should be fixed.)
+\indexii{standard}{output}
+\bimodindex{sys}
+\ttindex{stdout}
+\exindex{RuntimeError}
\section{The {\tt return} statement}
+\stindex{return}
\begin{verbatim}
return_stmt: "return" [condition_list]
@@ -1953,6 +2160,8 @@ return_stmt: "return" [condition_list]
\verb\return\ may only occur syntactically nested in a function
definition, not within a nested class definition.
+\indexii{function}{definition}
+\indexii{class}{definition}
If a condition list is present, it is evaluated, else \verb\None\
is substituted.
@@ -1963,8 +2172,10 @@ list (or \verb\None\) as return value.
When \verb\return\ passes control out of a \verb\try\ statement
with a \verb\finally\ clause, that finally clause is executed
before really leaving the function.
+\kwindex{finally}
\section{The {\tt raise} statement}
+\stindex{raise}
\begin{verbatim}
raise_stmt: "raise" condition ["," condition]
@@ -1973,11 +2184,14 @@ raise_stmt: "raise" condition ["," condition]
\verb\raise\ evaluates its first condition, which must yield
a string object. If there is a second condition, this is evaluated,
else \verb\None\ is substituted.
+\index{exception}
+\indexii{raising}{exception}
It then raises the exception identified by the first object,
with the second one (or \verb\None\) as its parameter.
\section{The {\tt break} statement}
+\stindex{break}
\begin{verbatim}
break_stmt: "break"
@@ -1985,18 +2199,25 @@ break_stmt: "break"
\verb\break\ may only occur syntactically nested in a \verb\for\
or \verb\while\ loop, not nested in a function or class definition.
+\stindex{for}
+\stindex{while}
+\indexii{loop}{statement}
It terminates the neares enclosing loop, skipping the optional
\verb\else\ clause if the loop has one.
+\kwindex{else}
If a \verb\for\ loop is terminated by \verb\break\, the loop control
target keeps its current value.
+\indexii{loop control}{target}
When \verb\break\ passes control out of a \verb\try\ statement
with a \verb\finally\ clause, that finally clause is executed
before really leaving the loop.
+\kwindex{finally}
\section{The {\tt continue} statement}
+\stindex{continue}
\begin{verbatim}
continue_stmt: "continue"
@@ -2007,10 +2228,15 @@ continue_stmt: "continue"
not nested in the \verb\try\ clause of a \verb\try\ statement with a
\verb\finally\ clause (it may occur nested in a \verb\except\ or
\verb\finally\ clause of a \verb\try\ statement though).
+\stindex{for}
+\stindex{while}
+\indexii{loop}{statement}
+\kwindex{finally}
It continues with the next cycle of the nearest enclosing loop.
\section{The {\tt import} statement} \label{import}
+\stindex{import}
\begin{verbatim}
import_stmt: "import" identifier ("," identifier)*
@@ -2024,6 +2250,9 @@ name space (of the scope where the \verb\import\ statement occurs).
The first form (without \verb\from\) repeats these steps for each
identifier in the list, the \verb\from\ form performs them once, with
the first identifier specifying the module name.
+\indexii{importing}{module}
+\indexii{name}{binding}
+\kwindex{from}
The system maintains a table of modules that have been initialized,
indexed by module name. (The current implementation makes this table
@@ -2036,6 +2265,15 @@ the module name with extension \verb\".py"\. (The current
implementation uses the list of strings \verb\sys.path\ as the search
path; it is initialized from the shell environment variable
\verb\$PYTHONPATH\, with an installation-dependent default.)
+\ttindex{modules}
+\ttindex{sys.modules}
+\indexii{module}{name}
+\indexii{built-in}{module}
+\indexii{user-defined}{module}
+\bimodindex{sys}
+\ttindex{path}
+\ttindex{sys.path}
+\indexii{filename}{extension}
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,
@@ -2045,6 +2283,10 @@ yielding an executable code block. If a syntax error occurs,
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.
@@ -2058,11 +2300,16 @@ local name space to the object thus found. If a name is not found,
\verb\ImportError\ is raised. If the list of identifiers is replaced
by a star (\verb\*\), all names defined in the module are bound,
except those beginning with an underscore(\verb\_\).
+\indexii{name}{binding}
+\exindex{ImportError}
Names bound by import statements may not occur in \verb\global\
statements in the same scope.
+\stindex{global}
The \verb\from\ form with \verb\*\ may only occur in a module scope.
+\kwindex{from}
+\ttindex{from ... import *}
(The current implementation does not enforce the latter two
restrictions, but programs should not abuse this freedom, as future
@@ -2070,6 +2317,7 @@ implementations may enforce them or silently change the meaning of the
program.)
\section{The {\tt global} statement} \label{global}
+\stindex{global}
\begin{verbatim}
global_stmt: "global" identifier ("," identifier)*
@@ -2080,6 +2328,7 @@ entire current scope. It means that the listed identifiers are to be
interpreted as globals. While {\em using} global names is automatic
if they are not defined in the local scope, {\em assigning} to global
names would be impossible without \verb\global\.
+\indexiii{global}{name}{binding}
Names listed in a \verb\global\ statement must not be used in the same
scope before that \verb\global\ statement is executed.
@@ -2094,6 +2343,7 @@ implementations may enforce them or silently change the meaning of the
program.)
\chapter{Compound statements}
+\indexii{compound}{statement}
Compound statements contain (groups of) other statements; they affect
or control the execution of those other statements in some way. In
@@ -2117,6 +2367,8 @@ 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 \verb\if\ clause a following \verb\else\ clause would
belong:
+\index{clause}
+\index{suite}
\begin{verbatim}
if test1: if test2: print x
@@ -2141,16 +2393,20 @@ stmt_list: simple_stmt (";" simple_stmt)* [";"]
Note that statements always ends in a \verb\NEWLINE\ possibly followed
by a \verb\DEDENT\.
+\index{NEWLINE token}
+\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 \verb\else\' problem is solved in Python by requiring
nested \verb\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 {\tt if} statement}
+\stindex{if}
The \verb\if\ statement is used for conditional execution:
@@ -2166,8 +2422,12 @@ the definition of true and false); then that suite is executed (and no
other part of the \verb\if\ statement is executed or evaluated). If
all conditions are false, the suite of the \verb\else\ clause, if
present, is executed.
+\kwindex{elif}
+\kwindex{else}
\section{The {\tt while} statement}
+\stindex{while}
+\indexii{loop}{statement}
The \verb\while\ statement is used for repeated execution as long as a
condition is true:
@@ -2181,16 +2441,22 @@ This repeatedly tests the condition and, if it is true, executes the
first suite; if the condition is false (which may be the first time it
is tested) the suite of the \verb\else\ clause, if present, is
executed and the loop terminates.
+\kwindex{else}
A \verb\break\ statement executed in the first suite terminates the
loop without executing the \verb\else\ clause's suite. A
\verb\continue\ statement executed in the first suited skips the rest
of the suite and goes back to testing the condition.
+\stindex{break}
+\stindex{continue}
\section{The {\tt for} statement}
+\stindex{for}
+\indexii{loop}{statement}
The \verb\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" condition_list ":" suite
@@ -2204,12 +2470,17 @@ 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 \verb\else\ clause, if
present, is executed, and the loop terminates.
+\kwindex{in}
+\kwindex{else}
+\indexii{target}{list}
A \verb\break\ statement executed in the first suite terminates the
loop without executing the \verb\else\ clause's suite. A
\verb\continue\ statement executed in the first suited skips the rest
of the suite and continues with the next item, or with the \verb\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.
@@ -2221,6 +2492,8 @@ loop.
Hint: the built-in function \verb\range()\ returns a sequence of
integers suitable to emulate the effect of Pascal's \verb\for i := a
to b do\; e.g. \verb\range(3)\ returns the list \verb\[0, 1, 2]\.
+\bifuncindex{range}
+\index{Pascal}
{\bf Warning:} There is a subtlety when the sequence is being modified
by the loop (this can only occur for mutable sequences, i.e. lists).
@@ -2234,6 +2507,8 @@ 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[:]:
@@ -2241,6 +2516,7 @@ for x in a[:]:
\end{verbatim}
\section{The {\tt try} statement}
+\stindex{try}
The \verb\try\ statement specifies exception handlers and/or cleanup
code for a group of statements:
@@ -2248,31 +2524,29 @@ code for a group of statements:
\begin{verbatim}
try_stmt: try_exc_stmt | try_fin_stmt
try_exc_stmt: "try" ":" suite
- ("except" condition ["," target] ":" suite)*
- ["except" ":" suite]
+ ("except" [condition ["," target]] ":" suite)+
try_fin_stmt: "try" ":" suite
"finally" ":" suite
\end{verbatim}
There are two forms of \verb\try\ statement: \verb\try...except\ and
-\verb\try...finally\. These forms cannot be mixed. A \verb\try\
-clause with neither a \verb\except\ clause nor a \verb\finally\ clause
-just executes the suite of statements in its \verb\try\ clause (it
-could be forbidden syntactically but there seems little reason to do
-so).
-
-The \verb\try...except\ form specifies one or more exception handlers.
-When no exception occurs in the \verb\try\ clause, no exception
-handler is executed. When an exception occurs in the \verb\try\
-suite, a search for an exception handler is started. This inspects
-the except clauses (exception handlers) in turn until one is found
-that matches the exception. A condition-less except clause (which
-must be last) matches any exception. For except clause with a
-condition, that condition 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 it is a tuple containing
-an item that is compatible with the exception.
+\verb\try...finally\. These forms cannot be mixed.
+
+The \verb\try...except\ form specifies one or more exception handlers
+(the \verb\except\ clauses). When no exception occurs in the
+\verb\try\ clause, no exception handler is executed. When an
+exception occurs in the \verb\try\ suite, a search for an exception
+handler is started. This inspects the except clauses in turn until
+one is found that matches the exception. A condition-less except
+clause, if present, must be last; it matches any exception. For an
+except clause with a condition, that condition 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 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 onject 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.
@@ -2280,16 +2554,16 @@ handler continues in the surrounding code and on the invocation stack.
If the evaluation of a condition 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.
+on the call stack (it is treated as if the entire \verb\try\ statement
+raised the exception).
-When a matching except clause is found in a try statement, the
-exception's parameter is assigned to the target specified in the
-except clause (if present), and the except clause's suite is executed.
-When the end of this suite is reached, execution continues normally
-at the point following 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 notice 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.)
The \verb\try...finally\ form specifies a `cleanup' handler. The
\verb\try\ clause is executed. When no exception occurs, the
@@ -2299,22 +2573,32 @@ The \verb\try...finally\ form specifies a `cleanup' handler. The
re-raised. If the \verb\finally\ clause raises another exception or
executes a \verb\return\, \verb\break\ or \verb\continue\ statement,
the saved exception is lost.
+\kwindex{finally}
When a \verb\return\ or \verb\break\ statement is executed in the
\verb\try\ suite of a \verb\try...finally\ statement, the
\verb\finally\ clause is also executed `on the way out'. A
-\verb\continue\ statement is illegal in the \verb\try\ clause (the
+\verb\continue\ statement is illegal in the \verb\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 function:
+A function definition defines a user-defined function object (see
+section \ref{types}):
+\obindex{user-defined function}
+\obindex{function}
\begin{verbatim}
-funcdef: "def" identifier "(" [parameter_list] ")" ":" suite
-parameter_list: parameter ("," parameter)*
-parameter: identifier | "(" parameter_list ")"
+funcdef: "def" funcname "(" [parameter_list] ")" ":" suite
+parameter_list: (parameter ",")* ("*" identifier | parameter [","])
+sublist: parameter ("," parameter)* [","]
+parameter: identifier | "(" sublist ")"
+funcname: identifier
\end{verbatim}
A function definition is an executable statement. Its execution binds
@@ -2322,34 +2606,88 @@ the function name in the current local name space to a function object
(a wrapper around the executable code for the function). This
function object contains a reference to the current global name space
as the global name space 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. Function call semantics
-are described elsewhere (see XXX).
+executed only when the function is called.
+
+Function call semantics are described in section \ref{calls}. When a
+user-defined function is called, the arguments (a.k.a. actual
+parameters) are bound to the (formal) parameters, as follows:
+\indexii{function}{call}
+\indexiii{user-defined}{function}{call}
+\index{parameter}
+\index{argument}
+\indexii{parameter}{formal}
+\indexii{parameter}{actual}
+
+\begin{itemize}
+
+\item
+If there are no formal parameters, there must be no arguments.
+
+\item
+If the formal parameter list does not end in a star followed by an
+identifier, there must be exactly as many arguments as there are
+parameters in the formal parameter list (at the top level); the
+arguments are assigned to the formal parameters one by one. Note that
+the presence or absence of a trailing comma at the top level in either
+the formal or the actual parameter list makes no difference. The
+assignment to a formal parameter is performed as if the parameter
+occurs on the left hand side of an assignment statement whose right
+hand side's value is that of the argument.
+
+\item
+If the formal parameter list ends in a star followed by an identifier,
+preceded by zero or more comma-followed parameters, there must be at
+least as many arguments as there are parameters preceding the star.
+Call this number {\em N}. The first {\em N} arguments are assigned to
+the corresponding formal parameters in the way descibed above. A
+tuple containing the remaining arguments, if any, is then assigned to
+the identifier following the star. This variable will always be a
+tuple: if there are no extra arguments, its value is \verb\()\, if
+there is just one extra argument, it is a singleton tuple.
+\indexii{variable length}{parameter list}
+
+\end{itemize}
+
+Note that the `variable length parameter list' feature only works at
+the top level of the parameter list; individual parameters use a model
+corresponding more closely to that of ordinary assignment. While the
+latter model is generally preferable, because of the greater type
+safety it offers (wrong-sized tuples aren't silently mistreated),
+variable length parameter lists are a sufficiently accepted practice
+in most programming languages that a compromise has been worked out.
+(And anyway, assignment has no equivalent for empty argument lists.)
\section{Class definitions} \label{class}
+\indexii{class}{definition}
-A class definition defines a class:
+A class definition defines a class object (see section \ref{types}):
+\obindex{class}
\begin{verbatim}
-classdef: "class" identifier [inheritance] ":" suite
-inheritance: "(" condition_list ")"
+classdef: "class" classname [inheritance] ":" suite
+inheritance: "(" [condition_list] ")"
+classname: identifier
\end{verbatim}
-A class definition is an executable statement. It first executes the
-inheritance list, if present. The class's suite is executed in a new
-execution frame, using a newly created local name space and the
-original global name space. (Usually, the suite contains only
-function definitions.) When the class's suite finishes execution, its
-execution frame is discarded but its local name space is saved. A
-class object (see XXX) is created using the inheritance list for the
-base classes and the saved local name space for the attribute
-dictionary. The class name is then bound to this class object in the
-original local name space.
-
-\section{P.M.}
-
-XXX New definition of expressions (as conditions)
+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 name space and the original global name space.
+(Usually, the suite contains only function definitions.) When the
+class's suite finishes execution, its execution frame is discarded but
+its local name space is saved. A class object is then created using
+the inheritance list for the base classes and the saved local name
+space for the attribute dictionary. The class name is bound to this
+class object in the original local name space.
+\index{inheritance}
+\indexii{class}{name}
+\indexii{name}{binding}
+\indexii{execution}{frame}
\chapter{Top-level components}
@@ -2357,8 +2695,10 @@ The Python interpreter can get its input from a number of sources:
from a script passed to it as standard input or as program argument,
typed in interactively, from a module source file, etc. This chapter
gives the syntax used in these cases.
+\index{interpreter}
\section{Complete Python programs}
+\index{program}
While a language specification need not prescribe how the language
interpreter is invoked, it is useful to have a notion of a complete
@@ -2369,6 +2709,9 @@ available, but none have been initialized, except for \verb\sys\
exceptions and \verb\None\) and \verb\__main__\. The latter is used
to provide the local and global name space for execution of the
complete program.
+\bimodindex{sys}
+\bimodindex{__main__}
+\bimodindex{builtin}
The syntax for a complete Python program is that for file input,
described in the next section.
@@ -2378,6 +2721,7 @@ it does not read and execute a complete program but reads and executes
one statement (possibly compound) at a time. The initial environment
is identical to that of a complete program; each statement is executed
in the name space of \verb\__main__\.
+\index{interactive mode}
Under {\UNIX}, a complete program can be passed to the interpreter in
three forms: with the {\bf -c} {\it string} command line option, as a
@@ -2385,6 +2729,9 @@ file passed as the first command line argument, or as standard input.
If the file or standard input is a tty device, the interpreter enters
interactive mode; otherwise, it executes the file as a complete
program.
+\index{UNIX}
+\index{command line}
+\index{standard input}
\section{File input}
@@ -2403,8 +2750,10 @@ This syntax is used in the following situations:
\item when parsing a module;
\item when parsing a string passed to \verb\exec()\;
+\bifuncindex{exec}
\item when parsing a file passed to \verb\execfile()\;
+\bifuncindex{execfile}
\end{itemize}
@@ -2421,22 +2770,34 @@ line in interactive mode; this is needed to help the parser detect the
end of the input.
\section{Expression input}
+\index{input}
There are two forms of expression input. Both ignore leading
whitespace.
The string argument to \verb\eval()\ must have the following form:
+\bifuncindex{eval}
\begin{verbatim}
eval_input: condition_list NEWLINE*
\end{verbatim}
The input line read by \verb\input()\ must have the following form:
+\bifuncindex{input}
\begin{verbatim}
input_input: condition_list NEWLINE
\end{verbatim}
+Note: to read `raw' input line without interpretation, you can use the
+built-in function \verb\raw_input()\ or the \verb\readline()\ method
+of file objects.
+\obindex{file}
+\index{input!raw}
+\index{raw input}
+\bifuncindex{raw_index}
+\ttindex{readline}
+
\input{ref.ind} % The index
\end{document}