The Python Reference Manual.

1 files changed, 200 insertions, 0 deletions

diff --git a/Doc/ref/ref4.tex b/Doc/ref/ref4.tex
new file mode 100644
index 0000000..9ab448b
--- /dev/null
+++ b/Doc/ref/ref4.tex
@@ -0,0 +1,200 @@
+\chapter{Execution model}
+\index{execution model}
+
+\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
+body.  Some code blocks (like modules) are executed only once, others
+(like function bodies) may be executed many times.  Code blocks 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.
+\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
+command typed interactively is a separate code block; a script file is
+a code block.  The string argument passed to the built-in function
+\function{eval()} and to the \keyword{exec} statement are code blocks.
+And finally, the expression read and evaluated by the built-in
+function \function{input()} is a code block.
+
+A code block is executed in an execution frame.  An {\em 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, the local and the global name space, that affect
+execution of the code block.
+\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
+frame, and from other places as well.  Adding a name to a name space
+is called {\em binding} a name (to an object); changing the mapping of
+a name is called {\em rebinding}; removing a name is {\em unbinding}.
+Name spaces are functionally equivalent to dictionaries.
+\index{name space}
+\indexii{binding}{name}
+\indexii{rebinding}{name}
+\indexii{unbinding}{name}
+
+The {\em local name space} of an execution frame determines the default
+place where names are defined and searched.  The {\em global name
+space} determines the place where names listed in \keyword{global}
+statements are defined and searched, and where names that are not
+explicitly bound in the current code block are searched.
+\indexii{local}{name space}
+\indexii{global}{name space}
+\stindex{global}
+
+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 \keyword{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 \keyword{global} statement forces global
+interpretation of selected names throughout the code block.  The
+following constructs bind names: formal parameters, \keyword{import}
+statements, class and function definitions (these bind the class or
+function name), and targets that are identifiers if occurring in an
+assignment, \keyword{for} loop header, or except clause header.
+
+A target occurring in a \keyword{del} statement is also considered bound
+for this purpose (though the actual semantics are to ``unbind'' the
+name).
+
+When a global name is not found in the global name space, it is
+searched in the list of ``built-in'' names (which is actually the
+global name space of the module \module{__builtin__}).  When a name is not
+found at all, the \exception{NameError} exception is raised.%
+\footnote{If the code block contains \keyword{exec} statements or the
+construct \samp{from \ldots import *}, the semantics of names not
+explicitly mentioned in a {\tt global} statement change subtly: name
+lookup first searches the local name space, then the global one, then
+the built-in one.}
+\refbimodindex{__builtin__}
+\stindex{from}
+\stindex{exec}
+\stindex{global}
+\withsubitem{(built-in exception)}{\ttindex{NameError}}
+
+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.  Note that in almost all cases, the global name space is
+the name space of the containing module --- scopes in Python do not
+nest!
+
+\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 \module{__main__} & same as global & \\
+Interactive command & n.s. for \module{__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. & (2) \\
+String passed to \keyword{exec} statement
+	& global n.s. of containing block
+		& local n.s. of containing block & (1) \\
+String passed to \function{eval()}
+	& global n.s. of caller & local n.s. of caller & (1) \\
+File read by \function{execfile()}
+	& global n.s. of caller & local n.s. of caller & (1) \\
+Expression read by \function{input()}
+	& global n.s. of caller & local n.s. of caller & \\
+\hline
+\end{tabular}
+\end{center}
+\refbimodindex{__main__}
+
+Notes:
+
+\begin{description}
+
+\item[n.s.] means {\em name space}
+
+\item[(1)] The global and local name space for these can be
+overridden with optional extra arguments.
+
+\item[(2)] The body of lambda forms (see section \ref{lambda}) is
+treated exactly the same as a (nested) function definition.  Lambda
+forms have their own name space consisting of their formal arguments.
+\indexii{lambda}{form}
+
+\end{description}
+
+The built-in functions \function{globals()} and \function{locals()} returns a
+dictionary representing the current global and local name space,
+respectively.  The effect of modifications to this dictionary on the
+name space are undefined.%
+\footnote{The current implementations return the dictionary actually 
+used to implement the name space, {\em except} for functions, where
+the optimizer may cause the local name space to be implemented
+differently, and \function{locals()} returns a read-only dictionary.}
+
+\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 {\em raised} at the point where the error
+is detected; it may be {\em handled} by the surrounding code block or
+by any code block that directly or indirectly invoked the code block
+where the error occurred.
+\index{exception}
+\index{raise an exception}
+\index{handle an exception}
+\index{exception handler}
+\index{errors}
+\index{error handling}
+
+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 \keyword{raise} statement.
+Exception handlers are specified with the \keyword{try} ... \keyword{except}
+statement.
+
+Python uses the ``termination'' model of error handling: an exception
+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 or class instances.  Two
+different string objects with the same value identify different
+exceptions.  An exception can be raised with a class instance.  Such
+exceptions are caught by specifying an except clause that has the
+class name (or a base class) as the condition.
+
+When an exception is raised, an object (maybe \code{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.  For exceptions raised
+with a class instance, the instance is passed as the ``parameter''.
+
+For example:
+
+\begin{verbatim}
+>>> class Error:
+...     def __init__(self, msg): self.msg = msg
+... 
+>>> class SpecificError(Error): pass
+... 
+>>> try:
+...     raise SpecificError('broken')
+... except Error, obj:
+...     print obj.msg
+... 
+broken
+\end{verbatim}
+
+See also the description of the \keyword{try} and \keyword{raise}
+statements.