265 lines
11 KiB
TeX
265 lines
11 KiB
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 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.
|