| \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{defintions}} |
| |
| \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 pice of Python program text that can 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. |