214 lines
10 KiB
TeX
214 lines
10 KiB
TeX
\chapter{Execution model \label{execmodel}}
|
|
\index{execution model}
|
|
|
|
|
|
\section{Naming and binding \label{naming}}
|
|
\indexii{code}{block}
|
|
\index{namespace}
|
|
\index{scope}
|
|
|
|
\dfn{Names}\index{name} refer to objects. Names are introduced by
|
|
name binding operations. Each occurrence of a name in the program
|
|
text refers to the \dfn{binding}\indexii{binding}{name} of that name
|
|
established in the innermost function block containing the use.
|
|
|
|
A \dfn{block}\index{block} is a piece of Python program text that is
|
|
executed as a unit. The following are blocks: a module, a function
|
|
body, and a class definition. Each command typed interactively is a
|
|
block. A script file (a file given as standard input to the
|
|
interpreter or specified on the interpreter command line the first
|
|
argument) is a code block. A script command (a command specified on
|
|
the interpreter command line with the `\strong{-c}' option) is a code
|
|
block. The file read by the built-in function \function{execfile()}
|
|
is a code block. The string argument passed to the built-in functions
|
|
\function{eval()} and \function{exec()} is a code block.
|
|
The expression read and evaluated by the built-in function
|
|
\function{input()} is a code block.
|
|
|
|
A code block is executed in an \dfn{execution
|
|
frame}\indexii{execution}{frame}. A frame contains some
|
|
administrative information (used for debugging) and determines where
|
|
and how execution continues after the code block's execution has
|
|
completed.
|
|
|
|
A \dfn{scope}\index{scope} defines the visibility of a name within a
|
|
block. If a local variable is defined in a block, its scope includes
|
|
that block. If the definition occurs in a function block, the scope
|
|
extends to any blocks contained within the defining one, unless a
|
|
contained block introduces a different binding for the name. The
|
|
scope of names defined in a class block is limited to the class block;
|
|
it does not extend to the code blocks of methods.
|
|
|
|
When a name is used in a code block, it is resolved using the nearest
|
|
enclosing scope. The set of all such scopes visible to a code block
|
|
is called the block's \dfn{environment}\index{environment}.
|
|
|
|
If a name is bound in a block, it is a local variable of that block.
|
|
If a name is bound at the module level, it is a global variable. (The
|
|
variables of the module code block are local and global.) If a
|
|
variable is used in a code block but not defined there, it is a
|
|
\dfn{free variable}\indexii{free}{variable}.
|
|
|
|
When a name is not found at all, a
|
|
\exception{NameError}\withsubitem{(built-in
|
|
exception)}{\ttindex{NameError}} exception is raised. If the name
|
|
refers to a local variable that has not been bound, a
|
|
\exception{UnboundLocalError}\ttindex{UnboundLocalError} exception is
|
|
raised. \exception{UnboundLocalError} is a subclass of
|
|
\exception{NameError}.
|
|
|
|
The following constructs bind names: formal parameters to functions,
|
|
\keyword{import} statements, class and function definitions (these
|
|
bind the class or function name in the defining block), and targets
|
|
that are identifiers if occurring in an assignment, \keyword{for} loop
|
|
header, or in the second position of an \keyword{except} clause
|
|
header. The \keyword{import} statement of the form ``\samp{from
|
|
\ldots import *}''\stindex{from} binds all names defined in the
|
|
imported module, except those beginning with an underscore. This form
|
|
may only be used at the module level.
|
|
|
|
A target occurring in a \keyword{del} statement is also considered bound
|
|
for this purpose (though the actual semantics are to unbind the
|
|
name). It is illegal to unbind a name that is referenced by an
|
|
enclosing scope; the compiler will report a \exception{SyntaxError}.
|
|
|
|
Each assignment or import statement occurs within a block defined by a
|
|
class or function definition or at the module level (the top-level
|
|
code block).
|
|
|
|
If a name binding operation occurs anywhere within a code block, all
|
|
uses of the name within the block are treated as references to the
|
|
current block. This can lead to errors when a name is used within a
|
|
block before it is bound.
|
|
This rule is subtle. Python lacks declarations and allows
|
|
name binding operations to occur anywhere within a code block. The
|
|
local variables of a code block can be determined by scanning the
|
|
entire text of the block for name binding operations.
|
|
|
|
If the global statement occurs within a block, all uses of the name
|
|
specified in the statement refer to the binding of that name in the
|
|
top-level namespace. Names are resolved in the top-level namespace by
|
|
searching the global namespace, i.e. the namespace of the module
|
|
containing the code block, and the builtin namespace, the namespace of
|
|
the module \module{__builtin__}. The global namespace is searched
|
|
first. If the name is not found there, the builtin namespace is
|
|
searched. The global statement must precede all uses of the name.
|
|
|
|
The built-in namespace associated with the execution of a code block
|
|
is actually found by looking up the name \code{__builtins__} in its
|
|
global namespace; this should be a dictionary or a module (in the
|
|
latter case the module's dictionary is used). By default, when in the
|
|
\module{__main__} module, \code{__builtins__} is the built-in module
|
|
\module{__builtin__} (note: no `s'); when in any other module,
|
|
\code{__builtins__} is an alias for the dictionary of the
|
|
\module{__builtin__} module itself. \code{__builtins__} can be set
|
|
to a user-created dictionary to create a weak form of restricted
|
|
execution\indexii{restricted}{execution}.
|
|
|
|
\begin{notice}
|
|
Users should not touch \code{__builtins__}; it is strictly an
|
|
implementation detail. Users wanting to override values in the
|
|
built-in namespace should \keyword{import} the \module{__builtin__}
|
|
(no `s') module and modify its attributes appropriately.
|
|
\end{notice}
|
|
|
|
The namespace for a module is automatically created the first time a
|
|
module is imported. The main module for a script is always called
|
|
\module{__main__}\refbimodindex{__main__}.
|
|
|
|
The global statement has the same scope as a name binding operation
|
|
in the same block. If the nearest enclosing scope for a free variable
|
|
contains a global statement, the free variable is treated as a global.
|
|
|
|
A class definition is an executable statement that may use and define
|
|
names. These references follow the normal rules for name resolution.
|
|
The namespace of the class definition becomes the attribute dictionary
|
|
of the class. Names defined at the class scope are not visible in
|
|
methods.
|
|
|
|
\subsection{Interaction with dynamic features \label{dynamic-features}}
|
|
|
|
There are several cases where Python statements are illegal when
|
|
used in conjunction with nested scopes that contain free
|
|
variables.
|
|
|
|
If a variable is referenced in an enclosing scope, it is illegal
|
|
to delete the name. An error will be reported at compile time.
|
|
|
|
If the wild card form of import --- \samp{import *} --- is used in a
|
|
function and the function contains or is a nested block with free
|
|
variables, the compiler will raise a \exception{SyntaxError}.
|
|
|
|
The \function{eval()}, \function{exec()}, \function{execfile()},
|
|
and \function{input()} functions do not have access to the
|
|
full environment for resolving names. Names may be resolved in the
|
|
local and global namespaces of the caller. Free variables are not
|
|
resolved in the nearest enclosing namespace, but in the global
|
|
namespace.\footnote{This limitation occurs because the code that is
|
|
executed by these operations is not available at the time the
|
|
module is compiled.}
|
|
The \function{exec()}, \function{eval()} and \function{execfile()}
|
|
functions have optional arguments to override
|
|
the global and local namespace. If only one namespace is specified,
|
|
it is used for both.
|
|
|
|
\section{Exceptions \label{exceptions}}
|
|
\index{exception}
|
|
|
|
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
|
|
\emph{raised}\index{raise an exception} at the point where the error
|
|
is detected; it may be \emph{handled}\index{handle an exception} by
|
|
the surrounding code block or by any code block that directly or
|
|
indirectly invoked the code block where the error occurred.
|
|
\index{exception handler}
|
|
\index{errors}
|
|
\index{error handling}
|
|
|
|
The Python interpreter raises an exception when it detects a 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. The \keyword{try} ... \keyword{finally} statement
|
|
specifies cleanup code which does not handle the exception, but is
|
|
executed whether an exception occurred or not in the preceding code.
|
|
|
|
Python uses the ``termination''\index{termination model} 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 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. In
|
|
either case, it prints a stack backtrace, except when the exception is
|
|
\exception{SystemExit}\withsubitem{(built-in
|
|
exception)}{\ttindex{SystemExit}}.
|
|
|
|
Exceptions are identified by class instances. The \keyword{except}
|
|
clause is selected depending on the class of the instance: it must
|
|
reference the class of the instance or a base class thereof. The
|
|
instance can be received by the handler and can carry additional
|
|
information about the exceptional condition.
|
|
|
|
Exceptions can also be identified by strings, in which case the
|
|
\keyword{except} clause is selected by object identity. An arbitrary
|
|
value can be raised along with the identifying string which can be
|
|
passed to the handler.
|
|
|
|
\deprecated{2.5}{String exceptions should not be used in new code.
|
|
They will not be supported in a future version of Python. Old code
|
|
should be rewritten to use class exceptions instead.}
|
|
|
|
\begin{notice}[warning]
|
|
Messages to exceptions are not part of the Python API. Their contents may
|
|
change from one version of Python to the next without warning and should not
|
|
be relied on by code which will run under multiple versions of the
|
|
interpreter.
|
|
\end{notice}
|
|
|
|
See also the description of the \keyword{try} statement in
|
|
section~\ref{try} and \keyword{raise} statement in
|
|
section~\ref{raise}.
|