Changes copied from the FrameMaker version. Not too much.

Doc/ref/ref7.tex

@@ -11,8 +11,8 @@ traditional control flow constructs.  \keyword{try} specifies exception
 handlers and/or cleanup code for a group of statements.  Function and
 class definitions are also syntactically compound statements.
 
-Compound statements consist of one or more `clauses'.  A clause
+Compound statements consist of one or more `clauses.'  A clause
-consists of a header and a `suite'.  The clause headers of a
+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
@@ -48,15 +48,13 @@ statement:      stmt_list NEWLINE | compound_stmt
 stmt_list:      simple_stmt (";" simple_stmt)* [";"]
 \end{verbatim}
 
-Note that statements always end in a \code{NEWLINE} possibly followed
+Note that statements always end in a
-by a \code{DEDENT}.
+\code{NEWLINE}\index{NEWLINE token} possibly followed by a
-\index{NEWLINE token}
+\code{DEDENT}.\index{DEDENT token} Also note that optional
-\index{DEDENT token}
+continuation clauses always begin with a keyword that cannot start a
-
+statement, thus there are no ambiguities (the `dangling
-Also note that optional continuation clauses always begin with a
+\keyword{else}' problem is solved in Python by requiring nested
-keyword that cannot start a statement, thus there are no ambiguities
+\keyword{if} statements to be indented).
-(the `dangling \keyword{else}' problem is solved in Python by requiring
-nested \keyword{if} statements to be indented).
 \indexii{dangling}{else}
 
 The formatting of the grammar rules in the following sections places
@@ -68,16 +66,16 @@ each clause on a separate line for clarity.
 The \keyword{if} statement is used for conditional execution:
 
 \begin{verbatim}
-if_stmt:        "if" condition ":" suite
+if_stmt:        "if" expression ":" suite
-               ("elif" condition ":" suite)*
+               ("elif" expression ":" suite)*
                ["else" ":" suite]
 \end{verbatim}
 
-It selects exactly one of the suites by evaluating the conditions one
+It selects exactly one of the suites by evaluating the expressions one
 by one until one is found to be true (see section \ref{Booleans} for
 the definition of true and false); then that suite is executed (and no
 other part of the \keyword{if} statement is executed or evaluated).  If
-all conditions are false, the suite of the \keyword{else} clause, if
+all expressions are false, the suite of the \keyword{else} clause, if
 present, is executed.
 \kwindex{elif}
 \kwindex{else}
@@ -86,16 +84,16 @@ present, is executed.
 \stindex{while}
 \indexii{loop}{statement}
 
-The \keyword{while} statement is used for repeated execution as long as a
+The \keyword{while} statement is used for repeated execution as long
-condition is true:
+as an expression is true:
 
 \begin{verbatim}
-while_stmt:     "while" condition ":" suite
+while_stmt:     "while" expression ":" suite
                ["else" ":" suite]
 \end{verbatim}
 
-This repeatedly tests the condition and, if it is true, executes the
+This repeatedly tests the expression and, if it is true, executes the
-first suite; if the condition is false (which may be the first time it
+first suite; if the expression is false (which may be the first time it
 is tested) the suite of the \keyword{else} clause, if present, is
 executed and the loop terminates.
 \kwindex{else}
@@ -103,7 +101,7 @@ executed and the loop terminates.
 A \keyword{break} statement executed in the first suite terminates the
 loop without executing the \keyword{else} clause's suite.  A
 \keyword{continue} statement executed in the first suite skips the rest
-of the suite and goes back to testing the condition.
+of the suite and goes back to testing the expression.
 \stindex{break}
 \stindex{continue}
 
@@ -116,11 +114,11 @@ sequence (string, tuple or list):
 \obindex{sequence}
 
 \begin{verbatim}
-for_stmt:       "for" target_list "in" condition_list ":" suite
+for_stmt:       "for" target_list "in" expression_list ":" suite
                ["else" ":" suite]
 \end{verbatim}
 
-The condition list is evaluated once; it should yield a sequence.  The
+The expression list is evaluated once; it should yield a sequence.  The
 suite is then executed once for each item in the sequence, in the
 order of ascending indices.  Each item in turn is assigned to the
 target list using the standard rules for assignments, and then the
@@ -144,12 +142,10 @@ 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.
+loop.  Hint: the built-in function \function{range()} returns a
-
+sequence of integers suitable to emulate the effect of Pascal's
-Hint: the built-in function \function{range()} returns a sequence of
-integers suitable to emulate the effect of Pascal's
 \code{for i := a to b do};
-e.g. \code{range(3)} returns the list \code{[0, 1, 2]}.
+e.g., \code{range(3)} returns the list \code{[0, 1, 2]}.
 \bifuncindex{range}
 \indexii{Pascal}{language}
 
@@ -164,7 +160,7 @@ 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.
+copy using a slice of the whole sequence, e.g.,
 \index{loop!over mutable sequence}
 \index{mutable sequence!loop over}
 
@@ -182,7 +178,7 @@ 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" [expression ["," target]] ":" suite)+
                ["else" ":" suite]
 try_fin_stmt:   "try" ":" suite
                "finally" ":" suite
@@ -190,17 +186,18 @@ try_fin_stmt:   "try" ":" suite
 
 There are two forms of \keyword{try} statement:
 \keyword{try}...\keyword{except} and
-\keyword{try}...\keyword{finally}.  These forms cannot be mixed.
+\keyword{try}...\keyword{finally}.  These forms cannot be mixed (but
+they can be nested in each other).
 
 The \keyword{try}...\keyword{except} form specifies one or more
 exception handlers
 (the \keyword{except} clauses).  When no exception occurs in the
 \keyword{try} clause, no exception handler is executed.  When an
 exception occurs in the \keyword{try} suite, a search for an exception
-handler is started.  This inspects the except clauses in turn until
+handler is started.  This search inspects the except clauses in turn until
-one is found that matches the exception.  A condition-less except
+one is found that matches the exception.  An expression-less except
 clause, if present, must be last; it matches any exception.  For an
-except clause with a condition, that condition is evaluated, and the
+except clause with an expression, that expression is evaluated, and the
 clause matches the exception if the resulting object is ``compatible''
 with the exception.  An object is compatible with an exception if it
 is either the object that identifies the exception, or (for exceptions
@@ -213,7 +210,7 @@ object, not just an object with the same value.
 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
+If the evaluation of an expression 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 \keyword{try} statement
@@ -234,6 +231,13 @@ exception are assigned to three variables in the \module{sys} module:
 \code{sys.exc_traceback} receives a traceback object (see section
 \ref{traceback}) identifying the point in the program where the
 exception occurred.
+These details are also available through the \function{sys.exc_info()}
+function, which returns a tuple \code{(exc_type,} \code{exc_value,}
+\code{exc_traceback)}.  Use of the corresponding variables is
+deprecated in favor of this function, since their use is unsafe in a
+threaded program.  As of Python 1.5, the variables are restored to
+their previous values (before the call) when returning from a function
+that handled an exception.
 \refbimodindex{sys}
 \ttindex{exc_type}
 \ttindex{exc_value}
@@ -252,12 +256,14 @@ The \keyword{try}...\keyword{finally} form specifies a `cleanup' handler.  The
 \keyword{finally} clause is executed, and then the saved exception is
 re-raised.  If the \keyword{finally} clause raises another exception or
 executes a \keyword{return}, \keyword{break} or \keyword{continue} statement,
-the saved exception is lost.
+the saved exception is lost.  The exception information is not
+available to the program during execution of the \keyword{finally}
+clause.
 \kwindex{finally}
 
 When a \keyword{return} or \keyword{break} statement is executed in the
 \keyword{try} suite of a \keyword{try}...\keyword{finally} statement, the
-\keyword{finally} clause is also executed `on the way out'.  A
+\keyword{finally} clause is also executed `on the way out.'  A
 \keyword{continue} statement is illegal in the \keyword{try} clause.  (The
 reason is a problem with the current implementation --- this
 restriction may be lifted in the future).
@@ -269,9 +275,7 @@ restriction may be lifted in the future).
 \indexii{function}{definition}
 
 A function definition defines a user-defined function object (see
-section \ref{types}):\footnote{The new syntax to receive arbitrary
+section \ref{types}):
-keyword arguments is not yet documented in this manual.  See chapter
-12 of the Tutorial.}
 \obindex{user-defined function}
 \obindex{function}
 
@@ -280,90 +284,81 @@ funcdef:        "def" funcname "(" [parameter_list] ")" ":" suite
 parameter_list: (defparameter ",")* ("*" identifier [, "**" identifier] 
                                     | "**" identifier 
                                     | defparameter [","])
-defparameter:   parameter ["=" condition]
+defparameter:   parameter ["=" expression]
 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
+the function name in the current local namespace to a function object
 (a wrapper around the executable code for the function).  This
-function object contains a reference to the current global name space
+function object contains a reference to the current global namespace
-as the global name space to be used when the function is called.
+as the global namespace to be used when the function is called.
 \indexii{function}{name}
 \indexii{name}{binding}
 
 The function definition does not execute the function body; this gets
 executed only when the function is called.
 
-When one or more top-level parameters have the form \var{parameter \code{=}
+When one or more top-level parameters have the form \var{parameter}
-condition}, the function is said to have ``default parameter values''.
+\code{=} \var{expression}, the function is said to have ``default
-Default parameter values are evaluated when the function definition is
+parameter values.''  \strong{Default parameter values are evaluated
-executed.  For a parameter with a default value, the correponding
+when the function definition is executed.}  For a parameter with a
-argument may be omitted from a call, in which case the parameter's
+default value, the corresponding argument may be omitted from a call,
-default value is substituted.  If a parameter has a default value, all
+in which case the parameter's default value is substituted.  If a
-following parameters must also have a default value --- this is a
+parameter has a default value, all following parameters must also have
-syntactic restriction that is not expressed by the grammar.%
+a default value --- this is a syntactic restriction that is not
+expressed by the grammar.%
 \footnote{Currently this is not checked; instead,
 \code{def f(a=1, b)} is interpreted as \code{def f(a=1, b=None)}.}
 \indexiii{default}{parameter}{value}
 
-Function call semantics are described in section \ref{calls}.  When a
+Function call semantics are described in more detail in section
-user-defined function is called, first missing arguments for which a
+\ref{calls}. 
-default value exists are supplied; then the arguments (a.k.a. actual
+A function call always assigns values to all parameters mentioned in
-parameters) are bound to the (formal) parameters, as follows:
+the parameter list, either from position arguments, from keyword
-\indexii{function}{call}
+arguments, or from default values.  If the form ``\code{*identifier}''
-\indexiii{user-defined}{function}{call}
+is present, it is initialized to a tuple receiving any excess
-\index{parameter}
+positional parameters, defaulting to the empty tuple.  If the form
-\index{argument}
+``\code{**identifier}'' is present, it is initialized to a new
-\indexii{parameter}{formal}
+dictionary receiving any excess keyword arguments, defaulting to a
-\indexii{parameter}{actual}
+new empty dictionary.
 
-\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 \var{N}.  The first \var{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 \code{()}, 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}.
+described in section \ref{lambda}.  Note that the lambda form is
+merely a shorthand for a simplified function definition; a function
+defined in a ``\keyword{def}'' statement can be passed around or
+assigned to another name just like a function defined by a lambda
+form.  The ``\keyword{def}'' form is actually more powerful since it
+allows the execution of multiple statements.
 \indexii{lambda}{form}
 
+\strong{Programmer's note:} a ``\code{def}'' form executed inside a
+function definition defines a local function that can be returned or
+passed around.  Because of Python's two-scope philosophy, a local
+function defined in this way does not have access to the local
+variables of the function that contains its definition; the same rule
+applies to functions defined by a lambda form.  A standard trick to
+pass selected local variables into a locally defined function is to
+use default argument values, like this:
+
+\begin{verbatim}
+# Return a function that returns its argument incremented by 'n'
+def make_incrementer(n):
+    def increment(x, n=n):
+        return x+n
+    return increment
+
+add1 = make_incrementer(1)
+print add1(3)  # This prints '4'
+\end{verbatim}
+
 \section{Class definitions} \label{class}
 \indexii{class}{definition}
 
@@ -372,7 +367,7 @@ A class definition defines a class object (see section \ref{types}):
 
 \begin{verbatim}
 classdef:       "class" classname [inheritance] ":" suite
-inheritance:    "(" [condition_list] ")"
+inheritance:    "(" [expression_list] ")"
 classname:      identifier
 \end{verbatim}
 
@@ -380,14 +375,23 @@ 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.
+created local namespace and the original global namespace.
 (Usually, the suite contains only function definitions.)  When the
 class's suite finishes execution, its execution frame is discarded but
-its local name space is saved.  A class object is then created using
+its local namespace is saved.  A class object is then created using
-the inheritance list for the base classes and the saved local name
+the inheritance list for the base classes and the saved local
-space for the attribute dictionary.  The class name is bound to this
+namespace for the attribute dictionary.  The class name is bound to this
-class object in the original local name space.
+class object in the original local namespace.
 \index{inheritance}
 \indexii{class}{name}
 \indexii{name}{binding}
 \indexii{execution}{frame}
+
+\strong{Programmer's note:} variables defined in the class definition
+are class variables; they are shared by all instances.  To define
+instance variables, they must be given a value in the the
+\method{__init__()} method or in another method.  Both class and
+instance variables are accessible through the notation
+```code{self.name}'', and an instance variable hides a class variable
+with the same name when accessed in this way.  Class variables with
+immutable values can be used as defaults for instance variables.