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.3 are \samp{generators},
  44 \samp{division} and \samp{nested_scopes}.  \samp{generators} and
  45 \samp{nested_scopes} are redundant in 2.3 because they are always
  46 enabled.
  47
  48 A future statement is recognized and treated specially at compile
  49 time: Changes to the semantics of core constructs are often
  50 implemented by generating different code.  It may even be the case
  51 that a new feature introduces new incompatible syntax (such as a new
  52 reserved word), in which case the compiler may need to parse the
  53 module differently.  Such decisions cannot be pushed off until
  54 runtime.
  55
  56 For any given release, the compiler knows which feature names have been
  57 defined, and raises a compile-time error if a future statement contains
  58 a feature not known to it.
  59
  60 The direct runtime semantics are the same as for any import statement:
  61 there is a standard module \module{__future__}, described later, and
  62 it will be imported in the usual way at the time the future statement
  63 is executed.
  64
  65 The interesting runtime semantics depend on the specific feature
  66 enabled by the future statement.
  67
  68 Note that there is nothing special about the statement:
  69
  70 \begin{verbatim}
  71 import __future__ [as name]
  72 \end{verbatim}
  73
  74 That is not a future statement; it's an ordinary import statement with
  75 no special semantics or syntax restrictions.
  76
  77 Code compiled by an exec statement or calls to the builtin functions
  78 \function{compile()} and \function{execfile()} that occur in a module
  79 \module{M} containing a future statement will, by default, use the new
  80 syntax or semantics associated with the future statement.  This can,
  81 starting with Python 2.2 be controlled by optional arguments to
  82 \function{compile()} --- see the documentation of that function in the
  83 library reference for details.
  84
  85 A future statement typed at an interactive interpreter prompt will
  86 take effect for the rest of the interpreter session.  If an
  87 interpreter is started with the \programopt{-i} option, is passed a
  88 script name to execute, and the script includes a future statement, it
  89 will be in effect in the interactive session started after the script
  90 is executed.
  91
  92 \section{\module{__future__} ---
  93          Future statement definitions}
  94
  95 \declaremodule[future]{standard}{__future__}
  96 \modulesynopsis{Future statement definitions}
  97
  98 \module{__future__} is a real module, and serves three purposes:
  99
 100 \begin{itemize}
 101
 102 \item To avoid confusing existing tools that analyze import statements
 103       and expect to find the modules they're importing.
 104
 105 \item To ensure that future_statements run under releases prior to 2.1
 106       at least yield runtime exceptions (the import of
 107       \module{__future__} will fail, because there was no module of
 108       that name prior to 2.1).
 109
 110 \item To document when incompatible changes were introduced, and when they
 111       will be --- or were --- made mandatory.  This is a form of executable
 112       documentation, and can be inspected programatically via importing
 113       \module{__future__} and examining its contents.
 114
 115 \end{itemize}
 116
 117 Each statment in \file{__future__.py} is of the form:
 118
 119 \begin{verbatim}
 120 FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ","
 121                         CompilerFlag ")"
 122 \end{verbatim}
 123
 124 where, normally, OptionalRelease is less then MandatoryRelease, and
 125 both are 5-tuples of the same form as \code{sys.version_info}:
 126
 127 \begin{verbatim}
 128     (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
 129      PY_MINOR_VERSION, # the 1; an int
 130      PY_MICRO_VERSION, # the 0; an int
 131      PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
 132      PY_RELEASE_SERIAL # the 3; an int
 133     )
 134 \end{verbatim}
 135
 136 OptionalRelease records the first release in which the feature was
 137 accepted.
 138
 139 In the case of MandatoryReleases that have not yet occurred,
 140 MandatoryRelease predicts the release in which the feature will become
 141 part of the language.
 142
 143 Else MandatoryRelease records when the feature became part of the
 144 language; in releases at or after that, modules no longer need a
 145 future statement to use the feature in question, but may continue to
 146 use such imports.
 147
 148 MandatoryRelease may also be \code{None}, meaning that a planned
 149 feature got dropped.
 150
 151 Instances of class \class{_Feature} have two corresponding methods,
 152 \method{getOptionalRelease()} and \method{getMandatoryRelease()}.
 153
 154 CompilerFlag is the (bitfield) flag that should be passed in the
 155 fourth argument to the builtin function \function{compile()} to enable
 156 the feature in dynamically compiled code.  This flag is stored in the
 157 \member{compiler_flag} attribute on \class{_Future} instances.
 158
 159 No feature description will ever be deleted from \module{__future__}.
 160