Completed execution model and try statement.
diff --git a/Doc/ref.tex b/Doc/ref.tex
index a6c2876..823df62 100644
--- a/Doc/ref.tex
+++ b/Doc/ref.tex
@@ -431,9 +431,9 @@
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 @@
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 @@
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{Execution frames, name spaces, and scopes}
+\section{Code blocks, execution frames, and name spaces}
-XXX code blocks, scopes, name spaces, name binding, exceptions
+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.
+
+\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.
+
+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 @@
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 @@
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.
-XXX explain what happens on function call
+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}
+
+\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 @@
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 @@
\begin{verbatim}
try_stmt: "try" ":" suite
- ("except" condition ["," condition] ":" suite)*
+ ("except" condition ["," target] ":" suite)*
["except" ":" suite]
["finally" ":" suite]
\end{verbatim}
@@ -1859,11 +1995,36 @@
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 @@
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 @@
\begin{verbatim}
classdef: "class" identifier [inheritance] ":" suite
-inheritance: "(" expression ("," expression)* ")"
+inheritance: "(" condition_list ")"
\end{verbatim}
XXX
@@ -1903,7 +2064,7 @@
\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}
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 @@
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 @@
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 @@
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{Execution frames, name spaces, and scopes}
+\section{Code blocks, execution frames, and name spaces}
-XXX code blocks, scopes, name spaces, name binding, exceptions
+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.
+
+\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.
+
+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 @@
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 @@
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.
-XXX explain what happens on function call
+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}
+
+\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 @@
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 @@
\begin{verbatim}
try_stmt: "try" ":" suite
- ("except" condition ["," condition] ":" suite)*
+ ("except" condition ["," target] ":" suite)*
["except" ":" suite]
["finally" ":" suite]
\end{verbatim}
@@ -1859,11 +1995,36 @@
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 @@
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 @@
\begin{verbatim}
classdef: "class" identifier [inheritance] ":" suite
-inheritance: "(" expression ("," expression)* ")"
+inheritance: "(" condition_list ")"
\end{verbatim}
XXX
@@ -1903,7 +2064,7 @@
\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}