Docs for the PEP 264 changes.
diff --git a/Doc/lib/libcode.tex b/Doc/lib/libcode.tex
index 36410b2..ff6bde2 100644
--- a/Doc/lib/libcode.tex
+++ b/Doc/lib/libcode.tex
@@ -60,9 +60,8 @@
\var{filename}, \var{symbol})}) if the command is complete and
valid; \code{None} if the command is incomplete; raises
\exception{SyntaxError} if the command is complete and contains a
-syntax error, or raises \exception{OverflowError} if the command
-includes a numeric constant which exceeds the range of the
-appropriate numeric type.
+syntax error, or raises \exception{OverflowError} or
+\exception{ValueError} if the command cotains an invalid literal.
\end{funcdesc}
diff --git a/Doc/lib/libcodeop.tex b/Doc/lib/libcodeop.tex
index 6b9f3cf..4f68160 100644
--- a/Doc/lib/libcodeop.tex
+++ b/Doc/lib/libcodeop.tex
@@ -5,14 +5,29 @@
\declaremodule{standard}{codeop}
\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
+\sectionauthor{Michael Hudson}{mwh@python.net}
\modulesynopsis{Compile (possibly incomplete) Python code.}
-The \module{codeop} module provides a function to compile Python code
-with hints on whether it is certainly complete, possibly complete or
-definitely incomplete. This is used by the \refmodule{code} module
-and should not normally be used directly.
+The \module{codeop} module provides utilities upon which the Python
+read-eval-print loop can be emulated -- as in the \refmodule{code}
+module. As a result, you probably don't want to use the module
+directly -- if you want to include such a loop in your program you
+probably want to use the \refmodule{code} instead.
-The \module{codeop} module defines the following function:
+There are two parts to this job:
+
+\begin{list}
+\listitem Being able to tell if a line of input completes a Python
+ statement -- in short telling whether to print ``>>> '' or
+ ``... '' next.
+\listitem Remembering which future statements the user has entered, so
+ subsequent input can be compiled wiht these in effect.
+\end{list}
+
+The \module{codeop} module provides a way of doing each of these
+things, and a way of doing them both.
+
+To do just the former:
\begin{funcdesc}{compile_command}
{source\optional{, filename\optional{, symbol}}}
@@ -25,8 +40,8 @@
If there is a problem with \var{source}, an exception will be raised.
\exception{SyntaxError} is raised if there is invalid Python syntax,
-and \exception{OverflowError} if there is an invalid numeric
-constant.
+and \exception{OverflowError} or \exception{ValueError} if there is an
+invalid literal.
The \var{symbol} argument determines whether \var{source} is compiled
as a statement (\code{'single'}, the default) or as an expression
@@ -41,3 +56,48 @@
followed by arbitrary garbage. This will be fixed once the API
for the parser is better.
\end{funcdesc}
+
+\begin{classdesc}{Compile}{}
+Instances of this class have \method{__call__} methods indentical in
+signature to the built-in function \function{compile}, but with the
+difference that if the instance compiles program text containing a
+\module{__future__} statement, the instance 'remembers' and compiles
+all subsequent program texts with the statement in force.
+\end{classdesc}
+
+\begin{classdesc}{CommandCompiler}{}
+Instances of this class have \method{__call__} methods identical in
+signature to \function{compile_command}; the difference is that if the
+instance compiles program text containing a \method{__future__}
+statement, the instance 'remembers' and compiles all subsequent
+program texts with the statement in force.
+\end{classdesc}
+
+A note on version compatibility: the \class{Compile} and
+\class{CommandCompiler} are new in Python 2.2. If you want to enable
+the future-tracking features of 2.2 but also retain compatibility with
+2.1 and earlier versions of Python you can either write
+
+\begin{verbatim}
+try:
+ from codeop import CommandCompiler
+ compile_command = CommandCompiler()
+ del CommandCompiler
+except ImportError:
+ from codeop import compile_command
+\end{verbatim}
+
+which is a low-impact change, but introduces possibly unwanted global
+state into your program, or you can write:
+
+\begin{verbatim}
+try:
+ from codeop import CommandCompiler
+except ImportError:
+ def CommandCompiler():
+ from codeop import compile_command
+ return compile_comamnd
+\end{verbatim}
+
+and then call \code{CommandCompiler} every time you need a fresh
+compiler object.
diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex
index 12b7cf7..53970ee 100644
--- a/Doc/lib/libfuncs.tex
+++ b/Doc/lib/libfuncs.tex
@@ -118,7 +118,8 @@
operations.
\end{funcdesc}
-\begin{funcdesc}{compile}{string, filename, kind}
+\begin{funcdesc}{compile}{string, filename, kind\optional{,
+ flags\optional{, dont_inherit}}}
Compile the \var{string} into a code object. Code objects can be
executed by an \keyword{exec} statement or evaluated by a call to
\function{eval()}. The \var{filename} argument should
@@ -130,6 +131,24 @@
expression, or \code{'single'} if it consists of a single
interactive statement (in the latter case, expression statements
that evaluate to something else than \code{None} will printed).
+
+ The optional arguments \var{flags} and \optional{dont_inherit}
+ (which are new in Python 2.2) control which future statements (see
+ \pep{236}) affect the compilation of \var{string}. If neither is
+ present (or both are zero) the code is compiled with those future
+ statements that are in effect in the code that is calling compile.
+ If the \var{flags} argument is given and \var{dont_inherit} is not
+ (or is zero) then the future statements specified by the \var{flags}
+ argument are used in addition to those that would be used anyway.
+ If \var{dont_inherit} is a non-zero integer then the \var{flags}
+ argument is it -- the future statements in effect around the call to
+ compile are ignored.
+
+ Future statemants are specified by bits which can be bitwise or-ed
+ together to specify multiple statements. The bitfield required to
+ specify a given feature can be found as the \member{compiler_flag}
+ attribute on the \class{_Feature} instance in the
+ \module{__future__} module.
\end{funcdesc}
\begin{funcdesc}{complex}{real\optional{, imag}}
diff --git a/Doc/ref/refa1.tex b/Doc/ref/refa1.tex
index 9a22513..bd3a38c 100644
--- a/Doc/ref/refa1.tex
+++ b/Doc/ref/refa1.tex
@@ -40,14 +40,17 @@
\end{itemize}
-The only feature recognized by Python 2.1 is \samp{nested_scopes}.
+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.
+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
@@ -72,8 +75,11 @@
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 use the new syntax or
-semantics associated with the future statement.
+\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
@@ -110,7 +116,8 @@
Each statment in \file{__future__.py} is of the form:
\begin{verbatim}
-FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ")"
+FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ","
+ CompilerFlag ")"
\end{verbatim}
where, normally, OptionalRelease is less then MandatoryRelease, and
@@ -143,6 +150,11 @@
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}}