[Python-checkins] python/dist/src/Doc/ref ref4.tex,1.28.18.2,1.28.18.3
rhettinger@users.sourceforge.net
rhettinger@users.sourceforge.net
Sat, 05 Oct 2002 09:55:13 -0700
Update of /cvsroot/python/python/dist/src/Doc/ref
In directory usw-pr-cvs1:/tmp/cvs-serv11498
Modified Files:
Tag: release22-maint
ref4.tex
Log Message:
Backported Jeremy's documentation of nested scopes, execution frames
and such.
Index: ref4.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref4.tex,v
retrieving revision 1.28.18.2
retrieving revision 1.28.18.3
diff -C2 -d -r1.28.18.2 -r1.28.18.3
*** ref4.tex 28 Aug 2002 02:10:04 -0000 1.28.18.2
--- ref4.tex 5 Oct 2002 16:55:11 -0000 1.28.18.3
***************
*** 3,165 ****
! \section{Code blocks, execution frames, and namespaces \label{execframes}}
! \index{code block}
\index{namespace}
! \indexii{execution}{frame}
! A \dfn{code block}\indexii{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 normally 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.
! 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 (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 function \function{eval()} and to the
! \keyword{exec} statement is a code block. 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 \dfn{execution
! frame}\indexii{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 namespaces, the local and the global
! namespace, that affect execution of the code block.
! A \dfn{namespace}\index{namespace} is a mapping from names
! (identifiers) to objects. A particular namespace may be referenced by
! more than one execution frame, and from other places as well. Adding
! a name to a namespace is called \dfn{binding}\indexii{binding}{name} a
! name (to an object); changing the mapping of a name is called
! \dfn{rebinding}\indexii{rebinding}{name}; removing a name is
! \dfn{unbinding}\indexii{unbinding}{name}. Namespaces are functionally
! equivalent to dictionaries (and often implemented as dictionaries).
! The \dfn{local namespace}\indexii{local}{namespace} of an execution
! frame determines the default place where names are defined and
! searched. The
! \dfn{global namespace}\indexii{global}{namespace} determines the place
! where names listed in \keyword{global}\stindex{global} statements are
! defined and searched, and where names that are not bound anywhere 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 \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 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. Local names are searched only on the local namespace; global
! names are searched only in the global and built-in
! namespace.\footnote{
! If the code block contains \keyword{exec} statements or the
! construct ``\samp{from \ldots import *}'', the semantics of local
! names change: local name lookup first searches the local namespace,
! then the global namespace and the built-in namespace.}
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 namespace, it is
! searched in the built-in namespace (which is actually the global
! namespace of the module
! \module{__builtin__}\refbimodindex{__builtin__}). 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
! its dictionary is used). Normally, the \code{__builtins__} namespace
! is the dictionary of the built-in module \module{__builtin__} (note:
! no `s'); if it isn't, restricted
! execution\indexii{restricted}{execution} mode is in effect. When a
! name is not found at all, a
! \exception{NameError}\withsubitem{(built-in
! exception)}{\ttindex{NameError}} exception is raised.
! \stindex{from}
! \stindex{exec}
! \stindex{global}
! The following table lists the meaning of the local and global
! namespace for various types of code blocks. The namespace for a
! particular module is automatically created when the module is first
! imported (i.e., when it is loaded). Note that in almost all cases,
! the global namespace is the namespace of the containing module ---
! scopes in Python do not nest!
! \begin{tableiv}{l|l|l|l}{textrm}
! {Code block type}{Global namespace}{Local namespace}{Notes}
! \lineiv{Module}
! {n.s. for this module}
! {same as global}{}
! \lineiv{Script (file or command)}
! {n.s. for \module{__main__}\refbimodindex{__main__}}
! {same as global}{(1)}
! \lineiv{Interactive command}
! {n.s. for \module{__main__}\refbimodindex{__main__}}
! {same as global}{}
! \lineiv{Class definition}
! {global n.s. of containing block}
! {new n.s.}{}
! \lineiv{Function body}
! {global n.s. of containing block}
! {new n.s.}{(2)}
! \lineiv{String passed to \keyword{exec} statement}
! {global n.s. of containing block}
! {local n.s. of containing block}{(2), (3)}
! \lineiv{String passed to \function{eval()}}
! {global n.s. of caller}
! {local n.s. of caller}{(2), (3)}
! \lineiv{File read by \function{execfile()}}
! {global n.s. of caller}
! {local n.s. of caller}{(2), (3)}
! \lineiv{Expression read by \function{input()}}
! {global n.s. of caller}
! {local n.s. of caller}{}
! \end{tableiv}
! Notes:
! \begin{description}
! \item[n.s.] means \emph{namespace}
! \item[(1)] The main module for a script is always called
! \module{__main__}; ``the filename don't enter into it.''
! \item[(2)] The global and local namespace for these can be
! overridden with optional extra arguments.
! \item[(3)] The \keyword{exec} statement and the \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.
! \end{description}
! The built-in functions \function{globals()} and \function{locals()} returns a
! dictionary representing the current global and local namespace,
! respectively. The effect of modifications to this dictionary on the
! namespace are undefined.\footnote{
! The current implementations return the dictionary actually used to
! implement the namespace, \emph{except} for functions, where the
! optimizer may cause the local namespace to be implemented
! differently, and \function{locals()} returns a read-only
! dictionary.}
\section{Exceptions \label{exceptions}}
--- 3,152 ----
! \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 function
! \function{eval()} and to the \keyword{exec} statement 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.
! The previous rule is a 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). Normally, the
! \code{__builtins__} namespace is the dictionary of the built-in module
! \module{__builtin__} (note: no `s'). If it isn't, restricted
! execution\indexii{restricted}{execution} mode is in effect.
! 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 SyntaxError.
+
+ If \keyword{exec} is used in a function and the function contains or
+ is a nested block with free variables, the compiler will raise a
+ \exception{SyntaxError} unless the exec explicitly specifies the local
+ namespace for the \keyword{exec}. (In other words, \samp{exec obj}
+ would be illegal, but \samp{exec obj in ns} would be legal.)
+
+ The \function{eval()}, \function{execfile()}, and \function{input()}
+ functions and the \keyword{exec} statement 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 \keyword{exec} statement and the \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}}
***************
*** 206,214 ****
When an exception is raised, an object (maybe \code{None}) is passed
! as the exception's ``parameter'' or ``value''; this object does not
! affect the selection of an exception handler, but is passed to the
! selected exception handler as additional information. For class
! exceptions, this object must be an instance of the exception class
! being raised.
\begin{notice}[warning]
--- 193,200 ----
When an exception is raised, an object (maybe \code{None}) is passed
! as the exception's \emph{value}; this object does not affect the
! selection of an exception handler, but is passed to the selected
! exception handler as additional information. For class exceptions,
! this object must be an instance of the exception class being raised.
\begin{notice}[warning]