cpython/Doc/ref/refa1.tex

\chapter{Future statements and nested scopes \label{futures}}
\sectionauthor{Jeremy Hylton}{jeremy@alum.mit.edu}


The semantics of Python's static scoping will change in version 2.2 to
support resolution of unbound local names in enclosing functions'
namespaces.  The new semantics will be available in Python 2.1 through
the use of a future statement.  This appendix documents these two
features for Python 2.1; it will be removed in Python 2.2 and the
features will be documented in the main sections of this manual.


\section{Future statements \label{future-statements}}

A \dfn{future statement}\indexii{future}{statement} is a directive to
the compiler that a particular module should be compiled using syntax
or semantics that will be available in a specified future release of
Python.  The future statement is intended to ease migration to future
versions of Python that introduce incompatible changes to the
language.  It allows use of the new features on a per-module basis
before the release in which the feature becomes standard.

\begin{verbatim}
future_statement: "from" "__future__" "import" feature ["as" name]
                 ("," feature ["as" name])*

feature: identifier
name: identifier
\end{verbatim}

A future statement must appear near the top of the module.  The only
lines that can appear before a future statement are:

\begin{itemize}

\item the module docstring (if any),
\item comments,
\item blank lines, and
\item other future statements.

\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.

A future statement is recognized and treated specially at compile
time: Changes to the semantics of core constructs are often
implemented by generating different code.  It may even be the case
that a new feature introduces new incompatible syntax (such as a new
reserved word), in which case the compiler may need to parse the
module differently.  Such decisions cannot be pushed off until
runtime.

For any given release, the compiler knows which feature names have been
defined, and raises a compile-time error if a future statement contains
a feature not known to it.

The direct runtime semantics are the same as for any import statement:
there is a standard module \module{__future__}, described later, and
it will be imported in the usual way at the time the future statement
is executed.

The interesting runtime semantics depend on the specific feature
enabled by the future statement.

Note that there is nothing special about the statement:

\begin{verbatim}
import __future__ [as name]
\end{verbatim}

That is not a future statement; it's an ordinary import statement with
no special semantics or syntax restrictions.

Code compiled by an exec statement or calls to the builtin functions
\function{compile()} and \function{execfile()} that occur in a module
\module{M} containing a future statement will, by default, use the new 
syntax or semantics associated with the future statement.  This can,
starting with Python 2.2 be controlled by optional arguments to
\function{compile()} --- see the documentation of that function in the 
library reference for details.

A future statement typed at an interactive interpreter prompt will
take effect for the rest of the interpreter session.  If an
interpreter is started with the \programopt{-i} option, is passed a
script name to execute, and the script includes a future statement, it
will be in effect in the interactive session started after the script
is executed.

\section{\module{__future__} ---
         Future statement definitions}

\declaremodule[future]{standard}{__future__}
\modulesynopsis{Future statement definitions}

\module{__future__} is a real module, and serves three purposes:

\begin{itemize}

\item To avoid confusing existing tools that analyze import statements
      and expect to find the modules they're importing.

\item To ensure that future_statements run under releases prior to 2.1
      at least yield runtime exceptions (the import of
      \module{__future__} will fail, because there was no module of
      that name prior to 2.1). 

\item To document when incompatible changes were introduced, and when they
      will be --- or were --- made mandatory.  This is a form of executable
      documentation, and can be inspected programatically via importing
      \module{__future__} and examining its contents.

\end{itemize}

Each statment in \file{__future__.py} is of the form:

\begin{verbatim}
FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ","
                        CompilerFlag ")"
\end{verbatim}

where, normally, OptionalRelease is less then MandatoryRelease, and
both are 5-tuples of the same form as \code{sys.version_info}:

\begin{verbatim}
    (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
     PY_MINOR_VERSION, # the 1; an int
     PY_MICRO_VERSION, # the 0; an int
     PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
     PY_RELEASE_SERIAL # the 3; an int
    )
\end{verbatim}

OptionalRelease records the first release in which the feature was
accepted. 

In the case of MandatoryReleases that have not yet occurred,
MandatoryRelease predicts the release in which the feature will become
part of the language.

Else MandatoryRelease records when the feature became part of the
language; in releases at or after that, modules no longer need a
future statement to use the feature in question, but may continue to
use such imports. 

MandatoryRelease may also be \code{None}, meaning that a planned
feature got dropped.

Instances of class \class{_Feature} have two corresponding methods,
\method{getOptionalRelease()} and \method{getMandatoryRelease()}.

CompilerFlag is the (bitfield) flag that should be passed in the
fourth argument to the builtin function \function{compile()} to enable
the feature in dynamically compiled code.  This flag is stored in the
\member{compiler_flag} attribute on \class{_Future} instances.

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 defintion.

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.