[Python-checkins] python/dist/src/Doc/ref ref6.tex,1.63,1.64

[jhylton@users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/ref
In directory sc8-pr-cvs1:/tmp/cvs-serv1662/Doc/ref

Modified Files:
	ref6.tex 
Log Message:
Move future statement here from appendix a.


Index: ref6.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref6.tex,v
retrieving revision 1.63
retrieving revision 1.64
diff -C2 -d -r1.63 -r1.64
*** ref6.tex	31 Mar 2003 14:53:03 -0000	1.63
--- ref6.tex	21 May 2003 21:43:00 -0000	1.64
***************
*** 739,742 ****
--- 739,820 ----
  \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}}