Completed execution model and try statement.

1 files changed, 191 insertions, 30 deletions

diff --git a/Doc/ref/ref.tex b/Doc/ref/ref.tex
index a6c2876..823df62 100644
--- a/Doc/ref/ref.tex
+++ b/Doc/ref/ref.tex
@@ -431,9 +431,9 @@ some properties of objects that are important to know about.
 
 Every object has an identity, a type and a value.  An object's {\em
 identity} never changes once it has been created; think of it as the
-object's (permanent) address.  An object's {\em type} determines the
-operations that an object supports (e.g., does it have a length?)  and
-also defines the ``meaning'' of the object's value.  The type also
+object's address in memory.  An object's {\em type} determines the
+operations that an object supports (e.g., ``does it have a length?'')
+and also defines the ``meaning'' of the object's value.  The type also
 never changes.  The {\em value} of some objects can change; whether
 this is possible is a property of its type.
 
@@ -450,12 +450,13 @@ references.)
 Note that the use of the implementation's tracing or debugging
 facilities may keep objects alive that would normally be collectable.
 
-(Some objects contain references to ``external'' resources such as
-open files.  It is understood that these resources are freed when the
-object is garbage-collected, but since garbage collection is not
-guaranteed, such objects also provide an explicit way to release the
-external resource (e.g., a \verb\close\ method).  Programs are strongly
-recommended to use this.)
+Some objects contain references to ``external'' resources such as open
+files or windows.  It is understood that these resources are freed
+when the object is garbage-collected, but since garbage collection is
+not guaranteed to happen, such objects also provide an explicit way to
+release the external resource, usually a \verb\close\ method.
+Programs are strongly recommended to always explicitly close such
+objects.
 
 Some objects contain references to other objects.  These references
 are part of the object's value; in most cases, when such a
@@ -463,23 +464,135 @@ are part of the object's value; in most cases, when such a
 comparison applies to the {\em values} of the referenced objects (not
 their identities).
 
-Types affect almost all aspects of objects.
-Even 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
+Types affect almost all aspects of an object's life.  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
 
 \begin{verbatim}
 a = 1; b = 1; c = []; d = []
 \end{verbatim}
 
-\verb\a\ and \verb\b\ may or may not refer to the same object, but
-\verb\c\ and \verb\d\ are guaranteed to refer to two different, unique,
-newly created lists.
+\verb\a\ and \verb\b\ may or may not refer to the same object with the
+value one, depending on the implementation, but \verb\c\ and \verb\d\
+are guaranteed to refer to two different, unique, newly created empty
+lists.
+
+\section{Code blocks, execution frames, and name spaces}
+
+A ``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
+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 aren't textually contained) as part of their
+execution.
+
+Each command typed interactively is a separate code block; a script
+file is a code block; the string argument passed to the built-in
+functions \verb\eval\ and \verb\exec\ are code blocks; the expression
+read and evaluated by the built-in function \verb\input\ is a code
+block.
+
+A code block is executed in an ``execution frame''.  An execution
+frame contains some administrative information (used for debugging),
+determines where and how execution continues after the code block's
+execution has completed, and (perhaps most importantly) defines two
+``name spaces'' that affect execution of the code block.
+
+A name space is a mapping from names (identifiers) to objects.  A
+particular name space may be referenced by more than one execution
+frame, and from other places as well.  Adding a name to a name space
+is called ``binding'' a name (to an object); changing the mapping of a
+name is called ``rebinding''; removing a name from the name space is
+called ``unbinding''.  Name spaces are functionally equivalent to
+dictionaries (described below).
+
+The ``local name space'' of an execution frame determines the default
+place where names are defined and searched.  The ``global name
+space'' determines the place where names listed in \verb\global\
+statements are defined and searched, and where names that are not
+explicitly bound in the current code block are searched.
+
+Whether a name is local or global in a code block is determined by
+static inspection of the source text for the code block: in the
+absence of \verb\global\ statements, a name that is bound anywhere in
+the code block is local in the entire code block; all other names are
+considered global.  The \verb\global\ statement forces global
+interpretation of selected names throughout the code block.  The
+following constructs bind names: formal parameters, \verb\import\
+statements, class and function definitions (these bind the class or
+function name), and targets that are identifiers if occurring in an
+assignment, \verb\for\ loop header, or \verb\except\ clause header.
+(A target occurring in a \verb\del\ statement does not bind a name.)
+
+When a global name is not found in the global name space, it is
+searched in the list of ``built-in'' names (this is actually the
+global name space of the module \verb\builtin\).  When a name is not
+found at all, the \verb\NameError\ exception is raised.
+
+The following table lists the meaning of the local and global name
+space for various types of code blocks.  The name space for a
+particular module is automatically created when the module is first
+referenced.
 
-\section{Execution frames, name spaces, and scopes}
+\begin{center}
+\begin{tabular}{|l|l|l|l|}
+\hline
+Code block type & Global name space & Local name space & Notes \\
+\hline
+Module & n.s. for this module & same as global & \\
+Script & n.s. for \verb\__main__\ & same as global & \\
+Interactive command & n.s. for \verb\__main__\ & same as global & \\
+Class definition & global n.s. of containing block & new n.s. & \\
+Function body & global n.s. of containing block & new n.s. & \\
+String passed to \verb\exec\ or \verb\eval\
+	& global n.s. of caller & local n.s. of caller & (1) \\
+File read by \verb\execfile\
+	& global n.s. of caller & local n.s. of caller & (1) \\
+Expression read by \verb\input\
+	& global n.s. of caller & local n.s. of caller & \\
+\hline
+\end{tabular}
+\end{center}
+
+Notes:
+\begin{description}
+\item[(1)] The global and local name space for these functions can be
+overridden with optional extra arguments.
+\end{description}
+
+\section{Exceptions}
+
+Exceptions are a means of breaking out of the normal flow of control
+of a code block in order to handle errors (or other exceptional
+conditions).  An exception is ``raised'' at the point where the error
+is detected; it may be ``handled'' by the surrounding code block or by any
+code block that directly or indirectly invoked the code block where
+the error occurred.
+
+The Python interpreter raises an exception when it detects an run-time
+error (such as division by zero).  A Python program can also
+explicitly raise an exception with the \verb\raise\ statement.
+Exception handlers are specified with the \verb\try...except\ statement.
 
-XXX code blocks, scopes, name spaces, name binding, exceptions
+Python uses the ``termination'' model of error handling: a handler can
+find out what happened and continue execution at an outer level, but
+it cannot repair the cause of the error and retry the failing
+operation (except by re-entering the the offending piece of code from
+the top).
+
+When an exception is not handled at all, the interpreter terminates
+execution of the program, or returns to its interactive main loop.
+
+Exceptions are identified by string objects.  Two different string
+objects with the same value identify different exceptions.
+
+When an exception is raised, an object (maybe \verb\None\) is passed
+as the exception's ``parameter''; this object does not affect the
+selection of an exception handler, but is passed to the selected
+exception handler as additional information.
 
 \chapter{The standard type hierarchy}
 
@@ -700,7 +813,7 @@ call a class object with one or more arguments.
 Modules are imported by the \verb\import\ statement (see section
 \ref{import}).  A module object is a container for a module's name
 space, which is a dictionary (the same dictionary as referenced by the
-\ver\func_globals\ attribute of functions defined in the module).
+\verb\func_globals\ attribute of functions defined in the module).
 Module attribute references are translated to lookups in this
 dictionary.  A module object does not contain the code object used to
 initialize the module (since it isn't needed once the initialization
@@ -1069,9 +1182,32 @@ call:           primary "(" [condition_list] ")"
 The primary must evaluate to a callable object (user-defined
 functions, built-in functions, methods of built-in objects, class
 objects, and methods of class instances are callable).  If it is a
-class, the argument list must be empty.
+class, the argument list must be empty; otherwise, the arguments are
+evaluated.
+
+A call always returns some value, possibly \verb\None\, unless it
+raises an exception.  How this value is computed depends on the type
+of the callable object.  If it is:
+
+\begin{description}
 
-XXX explain what happens on function call
+\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.
+
+\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.
+
+\item[a class object:] a new instance of that class is returned.
+
+\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.
+
+\end{description}
 
 \section{Factors}
 
@@ -1501,9 +1637,9 @@ happens.  It is useful as a placeholder when a statement is
 required syntactically, but no code needs to be executed, for example:
 
 \begin{verbatim}
-def f(arg): pass    # a no-op function
+def f(arg): pass    # a function that does nothing (yet)
 
-class C: pass       # an empty class
+class C: pass       # an class with no methods (yet)
 \end{verbatim}
 
 \section{The {\tt del} statement}
@@ -1844,7 +1980,7 @@ code for a group of statements:
 
 \begin{verbatim}
 try_stmt:       "try" ":" suite
-               ("except" condition ["," condition] ":" suite)*
+               ("except" condition ["," target] ":" suite)*
                ["except" ":" suite]
                ["finally" ":" suite]
 \end{verbatim}
@@ -1859,11 +1995,36 @@ clause just executes the suite of statements in its \verb\try\ clause.
 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 HIRO
+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.
+
+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.
+
+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.)
 
 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 on 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
@@ -1871,7 +2032,7 @@ executes a \verb\return\, \verb\break\ or \verb\continue\ statement,
 the saved exception is lost.
 
 When a \verb\return\ or \verb\break\ statement is executed in the
-\verb\try suite of a \verb\try...finally\ statement, 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
@@ -1895,7 +2056,7 @@ XXX
 
 \begin{verbatim}
 classdef:       "class" identifier [inheritance] ":" suite
-inheritance:    "(" expression ("," expression)* ")"
+inheritance:    "(" condition_list ")"
 \end{verbatim}
 
 XXX
@@ -1903,7 +2064,7 @@ XXX
 \section{P.M.}
 
 XXX Syntax for scripts, modules
-XXX Syntax for interactive input, eval, exec, input
+XXX Syntax for interactive input, eval, exec, execfile, input
 XXX New definition of expressions (as conditions)
 
 \end{document}