Add documentation for __future__

1 files changed, 69 insertions, 0 deletions

diff --git a/Doc/lib/lib__future__.tex b/Doc/lib/lib__future__.tex
new file mode 100644
index 0000000..bd66368
--- /dev/null
+++ b/Doc/lib/lib__future__.tex
@@ -0,0 +1,69 @@
+\section{\module{__future__} ---
+         Future statement definitions}
+
+\declaremodule[future]{standard}{__future__}
+\modulesynopsis{Future statement definitions}
+
+\module{__future__} is a real module, and serves three purposes:
+
+\begin{itemize}
+
+\item To avoid confusing existing tools that analyze import statements
+      and expect to find the modules they're importing.
+
+\item To ensure that future_statements run under releases prior to 2.1
+      at least yield runtime exceptions (the import of
+      \module{__future__} will fail, because there was no module of
+      that name prior to 2.1). 
+
+\item To document when incompatible changes were introduced, and when they
+      will be --- or were --- made mandatory.  This is a form of executable
+      documentation, and can be inspected programatically via importing
+      \module{__future__} and examining its contents.
+
+\end{itemize}
+
+Each statment in \file{__future__.py} is of the form:
+
+\begin{verbatim}
+FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ","
+                        CompilerFlag ")"
+\end{verbatim}
+
+where, normally, OptionalRelease is less then MandatoryRelease, and
+both are 5-tuples of the same form as \code{sys.version_info}:
+
+\begin{verbatim}
+    (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
+     PY_MINOR_VERSION, # the 1; an int
+     PY_MICRO_VERSION, # the 0; an int
+     PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
+     PY_RELEASE_SERIAL # the 3; an int
+    )
+\end{verbatim}
+
+OptionalRelease records the first release in which the feature was
+accepted. 
+
+In the case of MandatoryReleases that have not yet occurred,
+MandatoryRelease predicts the release in which the feature will become
+part of the language.
+
+Else MandatoryRelease records when the feature became part of the
+language; in releases at or after that, modules no longer need a
+future statement to use the feature in question, but may continue to
+use such imports. 
+
+MandatoryRelease may also be \code{None}, meaning that a planned
+feature got dropped.
+
+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__}.
+