Move future statement here from appendix a.

jeremyhylton · jeremyhylton · commit 8bea5dc8794d · 2003-05-21T21:43:00.000Z
diff --git a/Doc/ref/ref6.tex b/Doc/ref/ref6.tex
@@ -738,6 +738,84 @@ \section{The \keyword{import} statement \label{import}}
 information.
 \bifuncindex{__import__}
 
+\subsection{Future statements \label{future}}
+
+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{productionlist}[*]
+  \production{future_statement}
+             {"from" "__future__" "import" feature ["as" name]}
+  \productioncont{("," feature ["as" name])*}
+  \production{feature}{identifier}
+  \production{name}{identifier}
+\end{productionlist}
+
+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.3 are \samp{generators},
+\samp{division} and \samp{nested_scopes}.  \samp{generators} and
+\samp{nested_scopes} are redundant in 2.3 because they are always
+enabled. 
+
+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{The \keyword{global} statement \label{global}}
 \stindex{global}
