mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-02 11:08:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 14

Update docs for nested scopes.

Browse source 
Replace section 4.1 with section A.3.

The new section 4.1 is titled "Naming and binding."  It includes the
text of section A.3 augmented with some of the detailed text from the
old section 4.1.

The \dfn, \index stuff is probably wrong, but I tried.

Also update other parts of appendix A to mention that nested scopes
and generators are standard features.
This commit is contained in:
Jeremy Hylton 2002-04-01 20:38:01 +00:00
parent f54519d9e4
commit e7d5773ed0
2 changed files with 119 additions and 242 deletions
Download patch file Download diff file Expand all files Collapse all files

249
Doc/ref/ref4.tex
View file

@ -2,166 +2,147 @@
\index{execution model} \index{execution model}
\section{Code blocks, execution frames, and namespaces \label{execframes}} \section{Naming and binding \label{naming}}
\index{code block} \indexii{code}{block}
\index{namespace} \index{namespace}
\indexii{execution}{frame} \index{scope}
A \dfn{code block}\indexii{code}{block} is a piece \dfn{Names}\index{name} refer to objects. Names are introduced by
of Python program text that can be executed as a unit, such as a name binding operations. Each occurrence of a name in the program
module, a class definition or a function body. Some code blocks (like text refers to the \dfn{binding}\indexii{binding}{name} of that name
modules) are normally executed only once, others (like function established in the innermost function block containing the use.
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 A \dfn{block}\index{block} is a piece of Python program text that is
body is a code block. A class definition is a code block. Each executed as a unit. The following are blocks: a module, a function
command typed interactively is a separate code block; a script file (a body, and a class definition. Each command typed interactively is a
file given as standard input to the interpreter or specified on the block. A script file (a file given as standard input to the
interpreter command line the first argument) is a code block; a script interpreter or specified on the interpreter command line the first
command (a command specified on the interpreter command line with the argument) is a code block. A script command (a command specified on
`\strong{-c}' option) is a code block. The file read by the built-in the interpreter command line with the `\strong{-c}' option) is a code
function \function{execfile()} is a code block. The string argument block. The file read by the built-in function \function{execfile()}
passed to the built-in function \function{eval()} and to the is a code block. The string argument passed to the built-in function
\keyword{exec} statement is a code block. And finally, the expression \function{eval()} and to the \keyword{exec} statement is a code block.
read and evaluated by the built-in function \function{input()} is a The expression read and evaluated by the built-in function
code block. \function{input()} is a code block.
A code block is executed in an execution frame. An \dfn{execution A \dfn{scope}\index{scope} defines the visibility of a name within a
frame}\indexii{execution}{frame} contains some administrative block. If a local variable is defined in a block, it's scope includes
information (used for debugging), determines where and how execution that block. If the definition occurs in a function block, the scope
continues after the code block's execution has completed, and (perhaps extends to any blocks contained within the defining one, unless a
most importantly) defines two namespaces, the local and the global contained block introduces a different binding for the name. The
namespace, that affect execution of the code block. scope of names defined in a class block is limited to the class block;
it does not extend to the code blocks of methods.
A \dfn{namespace}\index{namespace} is a mapping from names When a name is used in a code block, it is resolved using the nearest
(identifiers) to objects. A particular namespace may be referenced by enclosing scope. The set of all such scopes visible to a code block
more than one execution frame, and from other places as well. Adding is called the block's \dfn{environment}\index{environment}.
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 If a name is bound in a block, it is a local variable of that block.
frame determines the default place where names are defined and If a name is bound at the module level, it is a global variable. (The
searched. The variables of the module code block are local and global.) If a
\dfn{global namespace}\indexii{global}{namespace} determines the place variable is used in a code block but not defined there, it is a
where names listed in \keyword{global}\stindex{global} statements are \dfn{free variable}\indexii{free}{variable}.
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 When a name is not found at all, a
static inspection of the source text for the code block: in the \exception{NameError}\withsubitem{(built-in
absence of \keyword{global} statements, a name that is bound anywhere exception)}{\ttindex{NameError}} exception is raised. If the name
in the code block is local in the entire code block; all other names refers to a local variable that has not been bound, a
are considered global. The \keyword{global} statement forces global \exception{UnboundLocalError}\ttindex{UnboundLocalError} exception is
interpretation of selected names throughout the code block. The raised. \exception{UnboundLocalError} is a subclass of
following constructs bind names: formal parameters to functions, \exception{NameError}.
The following constructs bind names: formal parameters to functions,
\keyword{import} statements, class and function definitions (these \keyword{import} statements, class and function definitions (these
bind the class or function name in the defining block), and targets bind the class or function name in the defining block), and targets
that are identifiers if occurring in an assignment, \keyword{for} loop that are identifiers if occurring in an assignment, \keyword{for} loop
header, or in the second position of an \keyword{except} clause header, or in the second position of an \keyword{except} clause
header. Local names are searched only on the local namespace; global header. The \keyword{import} statement of the form ``\samp{from
names are searched only in the global and built-in \ldots import *}''\stindex{from} binds all names defined in the
namespace.\footnote{ imported module, except those beginning with an underscore. This form
If the code block contains \keyword{exec} statements or the may only be used at the module level.
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 A target occurring in a \keyword{del} statement is also considered bound
for this purpose (though the actual semantics are to ``unbind'' the for this purpose (though the actual semantics are to unbind the
name). name). It is illegal to unbind a name that is referenced by an
enclosing scope; the compiler will report a \exception{SyntaxError}.
When a global name is not found in the global namespace, it is Each assignment or import statement occurs within a block defined by a
searched in the built-in namespace (which is actually the global class or function definition or at the module level (the top-level
namespace of the module code block).
\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 If a name binding operation occurs anywhere within a code block, all
namespace for various types of code blocks. The namespace for a uses of the name within the block are treated as references to the
particular module is automatically created when the module is first current block. This can lead to errors when a name is used within a
imported (i.e., when it is loaded). Note that in almost all cases, block before it is bound.
the global namespace is the namespace of the containing module ---
scopes in Python do not nest!
\begin{tableiv}{l|l|l|l}{textrm} The previous rule is a subtle. Python lacks declarations and allows
{Code block type}{Global namespace}{Local namespace}{Notes} name binding operations to occur anywhere within a code block. The
\lineiv{Module} local variables of a code block can be determined by scanning the
{n.s. for this module} entire text of the block for name binding operations.
{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: 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.
\begin{description} 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.
\item[n.s.] means \emph{namespace} 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__}.
\item[(1)] The main module for a script is always called The global statement has the same scope as a name binding operation
\module{__main__}; ``the filename don't enter into it.'' 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.
\item[(2)] The global and local namespace for these can be A class definition is an executable statement that may use and define
overridden with optional extra arguments. 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.
\item[(3)] The \keyword{exec} statement and the \function{eval()} and \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 \function{execfile()} functions have optional arguments to override
the global and local namespace. If only one namespace is specified, the global and local namespace. If only one namespace is specified,
it is used for both. 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}} \section{Exceptions \label{exceptions}}
\index{exception} \index{exception}

112
Doc/ref/refa1.tex
View file

@ -40,9 +40,10 @@ lines that can appear before a future statement are:
\end{itemize} \end{itemize}
The features recognized by Python 2.2 are \samp{generators}, The features recognized by Python 2.3 are \samp{generators},
\samp{division} and \samp{nested_scopes}. \samp{nested_scopes} \samp{division} and \samp{nested_scopes}. \samp{generators} and
is redundant in 2.2 as the nested scopes feature is active by default. \samp{nested_scopes} are redundant in 2.3 because they are always
enabled.
A future statement is recognized and treated specially at compile A future statement is recognized and treated specially at compile
time: Changes to the semantics of core constructs are often time: Changes to the semantics of core constructs are often
@ -157,108 +158,3 @@ the feature in dynamically compiled code. This flag is stored in the
No feature description will ever be deleted from \module{__future__}. No feature description will ever be deleted from \module{__future__}.
\section{Nested scopes \label{nested-scopes}}
\indexii{nested}{scopes}
This section defines the new scoping semantics that will be introduced
in Python 2.2. They are available in Python 2.1 by using the future
statement \samp{nested_scopes}. This section begins with a bit of
terminology.
\subsection{Definitions and rules \label{definitions}}
\dfn{Names} refer to objects. Names are introduced by name binding
operations. Each occurrence of a name in the program text refers to
the binding of that name established in the innermost function block
containing the use.
A \dfn{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.
A \dfn{scope} defines the visibility of a name within a block. If a
local variable is defined in a block, it's 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}.
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}.
The name binding operations are assignment, class and function
definition, import statements, for statements, and except statements.
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 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 exec is used in a function and the function contains or is a nested
block with free variables, the compiler will raise a SyntaxError
unless the exec explicitly specifies the local namespace for the exec.
(In other words, "exec obj" would be illegal, but "exec obj in ns"
would be legal.)
The builtin functions \function{eval()} and \function{input()} can not
access free variables unless the variables are also referenced by the
program text of the block that contains the call to \function{eval()}
or \function{input()}.
\emph{Compatibility note}: The compiler for Python 2.1 will issue
warnings for uses of nested functions that will behave differently
with nested scopes. The warnings will not be issued if nested scopes
are enabled via a future statement. If a name bound in a function
scope and the function contains a nested function scope that uses the
name, the compiler will issue a warning. The name resolution rules
will result in different bindings under Python 2.1 than under Python
2.2. The warning indicates that the program may not run correctly
with all versions of Python.