Update docs for nested scopes.

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.

2 files changed, 134 insertions, 257 deletions

diff --git a/Doc/ref/ref4.tex b/Doc/ref/ref4.tex
index 2272f3e..e2bfcca 100644
--- a/Doc/ref/ref4.tex
+++ b/Doc/ref/ref4.tex
@@ -2,166 +2,147 @@
 \index{execution model}
 
 
-\section{Code blocks, execution frames, and namespaces \label{execframes}}
-\index{code block}
+\section{Naming and binding \label{naming}}
+\indexii{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,
+\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 \dfn{scope}\index{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}\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.  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.}
+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).
-
-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
+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.
 
-\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}}
 \index{exception}
 
diff --git a/Doc/ref/refa1.tex b/Doc/ref/refa1.tex
index bf40c2d..fe1bc75 100644
--- a/Doc/ref/refa1.tex
+++ b/Doc/ref/refa1.tex
@@ -40,9 +40,10 @@ lines that can appear before a future statement are:
 
 \end{itemize}
 
-The features recognized by Python 2.2 are \samp{generators},
-\samp{division} and \samp{nested_scopes}.  \samp{nested_scopes} 
-is redundant in 2.2 as the nested scopes feature is active by default.
+The features recognized by Python 2.3 are \samp{generators},
+\samp{division} and \samp{nested_scopes}.  \samp{generators} and
+\samp{nested_scopes} are redundant in 2.3 because they are always
+enabled. 
 
 A future statement is recognized and treated specially at compile
 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__}.
 
-\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.