The Python Reference Manual.

1 files changed, 391 insertions, 0 deletions

diff --git a/Doc/ref/ref7.tex b/Doc/ref/ref7.tex
new file mode 100644
index 0000000..f5b8a0e
--- /dev/null
+++ b/Doc/ref/ref7.tex
@@ -0,0 +1,391 @@
+\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
+general, compound statements span multiple lines, although in simple
+incarnations a whole compound statement may be contained in one line.
+
+The \verb@if@, \verb@while@ and \verb@for@ statements implement
+traditional control flow constructs.  \verb@try@ specifies exception
+handlers and/or cleanup code for a group of statements.  Function and
+class definitions are also syntactically compound statements.
+
+Compound statements consist of one or more `clauses'.  A clause
+consists of a header and a `suite'.  The clause headers of a
+particular compound statement are all at the same indentation level.
+Each clause header begins with a uniquely identifying keyword and ends
+with a colon.  A suite is a group of statements controlled by a
+clause.  A suite can be one or more semicolon-separated simple
+statements on the same line as the header, following the header's
+colon, or it can be one or more indented statements on subsequent
+lines.  Only the latter form of suite can contain nested compound
+statements; the following is illegal, mostly because it wouldn't be
+clear to which \verb@if@ clause a following \verb@else@ clause would
+belong:
+\index{clause}
+\index{suite}
+
+\begin{verbatim}
+if test1: if test2: print x
+\end{verbatim}
+
+Also note that the semicolon binds tighter than the colon in this
+context, so that in the following example, either all or none of the
+\verb@print@ statements are executed:
+
+\begin{verbatim}
+if x < y < z: print x; print y; print z
+\end{verbatim}
+
+Summarizing:
+
+\begin{verbatim}
+compound_stmt:  if_stmt | while_stmt | for_stmt
+              | try_stmt | funcdef | classdef
+suite:          stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT
+statement:      stmt_list NEWLINE | compound_stmt
+stmt_list:      simple_stmt (";" simple_stmt)* [";"]
+\end{verbatim}
+
+Note that statements always end in a \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:
+
+\begin{verbatim}
+if_stmt:        "if" condition ":" suite
+               ("elif" condition ":" suite)*
+               ["else" ":" suite]
+\end{verbatim}
+
+It selects exactly one of the suites by evaluating the conditions one
+by one until one is found to be true (see section \ref{Booleans} for
+the definition of true and false); then that suite is executed (and no
+other part of the \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:
+
+\begin{verbatim}
+while_stmt:     "while" condition ":" suite
+               ["else" ":" suite]
+\end{verbatim}
+
+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 suite 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
+               ["else" ":" suite]
+\end{verbatim}
+
+The condition list is evaluated once; it should yield a sequence.  The
+suite is then executed once for each item in the sequence, in the
+order of ascending indices.  Each item in turn is assigned to the
+target list using the standard rules for assignments, and then the
+suite is executed.  When the items are exhausted (which is immediately
+when the sequence is empty), the suite in the \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 suite 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.
+
+The target list is not deleted when the loop is finished, but if the
+sequence is empty, it will not have been assigned to at all by the
+loop.
+
+Hint: the built-in function \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).
+An internal counter is used to keep track of which item is used next,
+and this is incremented on each iteration.  When this counter has
+reached the length of the sequence the loop terminates.  This means that
+if the suite deletes the current (or a previous) item from the
+sequence, the next item will be skipped (since it gets the index of
+the current item which has already been treated).  Likewise, if the
+suite inserts an item in the sequence before the current item, the
+current item will be treated again the next time through the loop.
+This can lead to nasty bugs that can be avoided by making a temporary
+copy using a slice of the whole sequence, e.g.
+\index{loop!over mutable sequence}
+\index{mutable sequence!loop over}
+
+\begin{verbatim}
+for x in a[:]:
+    if x < 0: a.remove(x)
+\end{verbatim}
+
+\section{The {\tt try} statement} \label{try}
+\stindex{try}
+
+The \verb@try@ statement specifies exception handlers and/or cleanup
+code for a group of statements:
+
+\begin{verbatim}
+try_stmt:       try_exc_stmt | try_fin_stmt
+try_exc_stmt:   "try" ":" suite
+               ("except" [condition ["," target]] ":" suite)+
+               ["else" ":" 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.
+
+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 (for exceptions
+that are classes) it is a base class of the exception, or it is a
+tuple containing an item that is compatible with the exception.  Note
+that the object identities must match, i.e. it must be the same
+object, not just an object with the same value.
+\kwindex{except}
+
+If no except clause matches the exception, the search for an exception
+handler continues in the surrounding code and on the invocation stack.
+
+If the evaluation of 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 (it is treated as if the entire \verb@try@ statement
+raised the exception).
+
+When a matching except clause is found, the exception's parameter is
+assigned to the target specified in that except clause, if present,
+and the except clause's suite is executed.  When the end of this suite
+is reached, execution continues normally after the entire try
+statement.  (This means that if two nested handlers exist for the same
+exception, and the exception occurs in the try clause of the inner
+handler, the outer handler will not handle the exception.)
+
+Before an except clause's suite is executed, details about the
+exception are assigned to three variables in the \verb@sys@ module:
+\verb@sys.exc_type@ receives the object identifying the exception;
+\verb@sys.exc_value@ receives the exception's parameter;
+\verb@sys.exc_traceback@ receives a traceback object (see section
+\ref{traceback}) identifying the point in the program where the
+exception occurred.
+\refbimodindex{sys}
+\ttindex{exc_type}
+\ttindex{exc_value}
+\ttindex{exc_traceback}
+\obindex{traceback}
+
+The optional \verb@else@ clause is executed when no exception occurs
+in the \verb@try@ clause.  Exceptions in the \verb@else@ clause are
+not handled by the preceding \verb@except@ clauses.
+\kwindex{else}
+
+The \verb@try...finally@ form specifies a `cleanup' handler.  The
+\verb@try@ clause is executed.  When no exception occurs, the
+\verb@finally@ clause is executed.  When an exception occurs in the
+\verb@try@ clause, the exception is temporarily saved, the
+\verb@finally@ clause is executed, and then the saved exception is
+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
+reason is a problem with the current implementation --- this
+restriction may be lifted in the future).
+\stindex{return}
+\stindex{break}
+\stindex{continue}
+
+\section{Function definitions} \label{function}
+\indexii{function}{definition}
+
+A function definition defines a user-defined function object (see
+section \ref{types}):\footnote{The new syntax to receive arbitrary
+keyword arguments is not yet documented in this manual.  See chapter
+12 of the Tutorial.}
+\obindex{user-defined function}
+\obindex{function}
+
+\begin{verbatim}
+funcdef:        "def" funcname "(" [parameter_list] ")" ":" suite
+parameter_list: (defparameter ",")* ("*" identifier [, "**" identifier] 
+                                    | "**" identifier 
+                                    | defparameter [","])
+defparameter:   parameter ["=" condition]
+sublist:        parameter ("," parameter)* [","]
+parameter:      identifier | "(" sublist ")"
+funcname:       identifier
+\end{verbatim}
+
+A function definition is an executable statement.  Its execution binds
+the function name in the current local 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.
+
+When one or more top-level parameters have the form {\em parameter =
+condition}, the function is said to have ``default parameter values''.
+Default parameter values are evaluated when the function definition is
+executed.  For a parameter with a default value, the correponding
+argument may be omitted from a call, in which case the parameter's
+default value is substituted.  If a parameter has a default value, all
+following parameters must also have a default value --- this is a
+syntactic restriction that is not expressed by the grammar.%
+\footnote{Currently this is not checked; instead,
+{\tt def f(a=1,b)} is interpreted as {\tt def f(a=1,b=None)}.}
+\indexiii{default}{parameter}{value}
+
+Function call semantics are described in section \ref{calls}.  When a
+user-defined function is called, first missing arguments for which a
+default value exists are supplied; then 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.)
+
+It is also possible to create anonymous functions (functions not bound
+to a name), for immediate use in expressions.  This uses lambda forms,
+described in section \ref{lambda}.
+\indexii{lambda}{form}
+
+\section{Class definitions} \label{class}
+\indexii{class}{definition}
+
+A class definition defines a class object (see section \ref{types}):
+\obindex{class}
+
+\begin{verbatim}
+classdef:       "class" classname [inheritance] ":" suite
+inheritance:    "(" [condition_list] ")"
+classname:      identifier
+\end{verbatim}
+
+A class definition is an executable statement.  It first evaluates the
+inheritance list, if present.  Each item in the inheritance list
+should evaluate to a class object.  The class's suite is then executed
+in a new execution frame (see section \ref{execframes}), using a newly
+created local 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}