Doc/ref/refa1.tex

   1 \chapter{Future statements and nested scopes \label{futures}}
   2 \sectionauthor{Jeremy Hylton}{jeremy@alum.mit.edu}
   3
   4
   5 The semantics of Python's static scoping will change in version 2.2 to
   6 support resolution of unbound local names in enclosing functions'
   7 namespaces.  The new semantics will be available in Python 2.1 through
   8 the use of a future statement.  This appendix documents these two
   9 features for Python 2.1; it will be removed in Python 2.2 and the
  10 features will be documented in the main sections of this manual.
  11
  12
  13 \section{Future statements \label{future-statements}}
  14
  15 A \dfn{future statement}\indexii{future}{statement} is a directive to
  16 the compiler that a particular module should be compiled using syntax
  17 or semantics that will be available in a specified future release of
  18 Python.  The future statement is intended to ease migration to future
  19 versions of Python that introduce incompatible changes to the
  20 language.  It allows use of the new features on a per-module basis
  21 before the release in which the feature becomes standard.
  22
  23 \begin{productionlist}[*]
  24   \production{future_statement}
  25              {"from" "__future__" "import" feature ["as" name]}
  26   \productioncont{("," feature ["as" name])*}
  27   \production{feature}{identifier}
  28   \production{name}{identifier}
  29 \end{productionlist}
  30
  31 A future statement must appear near the top of the module.  The only
  32 lines that can appear before a future statement are:
  33
  34 \begin{itemize}
  35
  36 \item the module docstring (if any),
  37 \item comments,
  38 \item blank lines, and
  39 \item other future statements.
  40
  41 \end{itemize}
  42
  43 The features recognized by Python 2.2 are \samp{generators},
  44 \samp{division} and \samp{nested_scopes}.  \samp{nested_scopes}
  45 is redundant in 2.2 as the nested scopes feature is active by default.
  46
  47 A future statement is recognized and treated specially at compile
  48 time: Changes to the semantics of core constructs are often
  49 implemented by generating different code.  It may even be the case
  50 that a new feature introduces new incompatible syntax (such as a new
  51 reserved word), in which case the compiler may need to parse the
  52 module differently.  Such decisions cannot be pushed off until
  53 runtime.
  54
  55 For any given release, the compiler knows which feature names have been
  56 defined, and raises a compile-time error if a future statement contains
  57 a feature not known to it.
  58
  59 The direct runtime semantics are the same as for any import statement:
  60 there is a standard module \module{__future__}, described later, and
  61 it will be imported in the usual way at the time the future statement
  62 is executed.
  63
  64 The interesting runtime semantics depend on the specific feature
  65 enabled by the future statement.
  66
  67 Note that there is nothing special about the statement:
  68
  69 \begin{verbatim}
  70 import __future__ [as name]
  71 \end{verbatim}
  72
  73 That is not a future statement; it's an ordinary import statement with
  74 no special semantics or syntax restrictions.
  75
  76 Code compiled by an exec statement or calls to the builtin functions
  77 \function{compile()} and \function{execfile()} that occur in a module
  78 \module{M} containing a future statement will, by default, use the new
  79 syntax or semantics associated with the future statement.  This can,
  80 starting with Python 2.2 be controlled by optional arguments to
  81 \function{compile()} --- see the documentation of that function in the
  82 library reference for details.
  83
  84 A future statement typed at an interactive interpreter prompt will
  85 take effect for the rest of the interpreter session.  If an
  86 interpreter is started with the \programopt{-i} option, is passed a
  87 script name to execute, and the script includes a future statement, it
  88 will be in effect in the interactive session started after the script
  89 is executed.
  90
  91 \section{\module{__future__} ---
  92          Future statement definitions}
  93
  94 \declaremodule[future]{standard}{__future__}
  95 \modulesynopsis{Future statement definitions}
  96
  97 \module{__future__} is a real module, and serves three purposes:
  98
  99 \begin{itemize}
 100
 101 \item To avoid confusing existing tools that analyze import statements
 102       and expect to find the modules they're importing.
 103
 104 \item To ensure that future_statements run under releases prior to 2.1
 105       at least yield runtime exceptions (the import of
 106       \module{__future__} will fail, because there was no module of
 107       that name prior to 2.1).
 108
 109 \item To document when incompatible changes were introduced, and when they
 110       will be --- or were --- made mandatory.  This is a form of executable
 111       documentation, and can be inspected programatically via importing
 112       \module{__future__} and examining its contents.
 113
 114 \end{itemize}
 115
 116 Each statment in \file{__future__.py} is of the form:
 117
 118 \begin{verbatim}
 119 FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ","
 120                         CompilerFlag ")"
 121 \end{verbatim}
 122
 123 where, normally, OptionalRelease is less then MandatoryRelease, and
 124 both are 5-tuples of the same form as \code{sys.version_info}:
 125
 126 \begin{verbatim}
 127     (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
 128      PY_MINOR_VERSION, # the 1; an int
 129      PY_MICRO_VERSION, # the 0; an int
 130      PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
 131      PY_RELEASE_SERIAL # the 3; an int
 132     )
 133 \end{verbatim}
 134
 135 OptionalRelease records the first release in which the feature was
 136 accepted.
 137
 138 In the case of MandatoryReleases that have not yet occurred,
 139 MandatoryRelease predicts the release in which the feature will become
 140 part of the language.
 141
 142 Else MandatoryRelease records when the feature became part of the
 143 language; in releases at or after that, modules no longer need a
 144 future statement to use the feature in question, but may continue to
 145 use such imports.
 146
 147 MandatoryRelease may also be \code{None}, meaning that a planned
 148 feature got dropped.
 149
 150 Instances of class \class{_Feature} have two corresponding methods,
 151 \method{getOptionalRelease()} and \method{getMandatoryRelease()}.
 152
 153 CompilerFlag is the (bitfield) flag that should be passed in the
 154 fourth argument to the builtin function \function{compile()} to enable
 155 the feature in dynamically compiled code.  This flag is stored in the
 156 \member{compiler_flag} attribute on \class{_Future} instances.
 157
 158 No feature description will ever be deleted from \module{__future__}.
 159
 160 \section{Nested scopes \label{nested-scopes}}
 161 \indexii{nested}{scopes}
 162
 163 This section defines the new scoping semantics that will be introduced
 164 in Python 2.2.  They are available in Python 2.1 by using the future
 165 statement \samp{nested_scopes}.  This section begins with a bit of
 166 terminology.
 167
 168 \subsection{Definitions and rules \label{definitions}}
 169
 170 \dfn{Names} refer to objects.  Names are introduced by name binding
 171 operations.  Each occurrence of a name in the program text refers to
 172 the binding of that name established in the innermost function block
 173 containing the use.
 174
 175 A \dfn{block} is a piece of Python program text that is executed as
 176 a unit.  The following are blocks: a module, a function body, and a
 177 class definition.
 178
 179 A \dfn{scope} defines the visibility of a name within a block.  If a
 180 local variable is defined in a block, it's scope includes that block.
 181 If the definition occurs in a function block, the scope extends to any
 182 blocks contained within the defining one, unless a contained block
 183 introduces a different binding for the name.  The scope of names
 184 defined in a class block is limited to the class block; it does not
 185 extend to the code blocks of methods.
 186
 187 When a name is used in a code block, it is resolved using the nearest
 188 enclosing scope.  The set of all such scopes visible to a code block
 189 is called the block's \dfn{environment}.
 190
 191 If a name is bound in a block, it is a local variable of that block.
 192 If a name is bound at the module level, it is a global variable.  (The
 193 variables of the module code block are local and global.)  If a
 194 variable is used in a code block but not defined there, it is a
 195 \dfn{free variable}.
 196
 197 The name binding operations are assignment, class and function
 198 definition, import statements, for statements, and except statements.
 199 Each assignment or import statement occurs within a block defined by a
 200 class or function definition or at the module level (the top-level
 201 code block).
 202
 203 If a name binding operation occurs anywhere within a code block, all
 204 uses of the name within the block are treated as references to the
 205 current block.  This can lead to errors when a name is used within a
 206 block before it is bound.
 207
 208 The previous rule is a subtle.  Python lacks declarations and allows
 209 name binding operations to occur anywhere within a code block.  The
 210 local variables of a code block can be determined by scanning the
 211 entire text of the block for name binding operations.
 212
 213 If the global statement occurs within a block, all uses of the name
 214 specified in the statement refer to the binding of that name in the
 215 top-level namespace.  Names are resolved in the top-level namespace by
 216 searching the global namespace, i.e. the namespace of the module
 217 containing the code block, and the builtin namespace, the namespace of
 218 the module \module{__builtin__}.  The global namespace is searched
 219 first.  If the name is not found there, the builtin namespace is
 220 searched.  The global statement must precede all uses of the name.
 221
 222 The global statement has the same scope as a name binding operation
 223 in the same block.  If the nearest enclosing scope for a free variable
 224 contains a global statement, the free variable is treated as a global.
 225
 226 A class definition is an executable statement that may use and define
 227 names.  These references follow the normal rules for name resolution.
 228 The namespace of the class definition becomes the attribute dictionary
 229 of the class.  Names defined at the class scope are not visible in
 230 methods.
 231
 232 \subsection{Interaction with dynamic features \label{dynamic-features}}
 233
 234 There are several cases where Python statements are illegal when
 235 used in conjunction with nested scopes that contain free
 236 variables.
 237
 238 If a variable is referenced in an enclosing scope, it is illegal
 239 to delete the name.  An error will be reported at compile time.
 240
 241 If the wild card form of import --- \samp{import *} --- is used in a
 242 function and the function contains or is a nested block with free
 243 variables, the compiler will raise a SyntaxError.
 244
 245 If exec is used in a function and the function contains or is a nested
 246 block with free variables, the compiler will raise a SyntaxError
 247 unless the exec explicitly specifies the local namespace for the exec.
 248 (In other words, "exec obj" would be illegal, but "exec obj in ns"
 249 would be legal.)
 250
 251 The builtin functions \function{eval()} and \function{input()} can not
 252 access free variables unless the variables are also referenced by the
 253 program text of the block that contains the call to \function{eval()}
 254 or \function{input()}.
 255
 256 \emph{Compatibility note}: The compiler for Python 2.1 will issue
 257 warnings for uses of nested functions that will behave differently
 258 with nested scopes.  The warnings will not be issued if nested scopes
 259 are enabled via a future statement.  If a name bound in a function
 260 scope and the function contains a nested function scope that uses the
 261 name, the compiler will issue a warning.  The name resolution rules
 262 will result in different bindings under Python 2.1 than under Python
 263 2.2.  The warning indicates that the program may not run correctly
 264 with all versions of Python.