ref: 2fe3b28f86ed4aa291fb8a620b948abe9c6a1f84
dir: /sys/src/cmd/python/Doc/lib/libfuture.tex/
\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 statement in \file{__future__.py} is of the form:
\begin{alltt}
FeatureName = "_Feature(" \var{OptionalRelease} "," \var{MandatoryRelease} ","
\var{CompilerFlag} ")"
\end{alltt}
where, normally, \var{OptionalRelease} is less than
\var{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}
\var{OptionalRelease} records the first release in which the feature
was accepted.
In the case of a \var{MandatoryRelease} that has not yet occurred,
\var{MandatoryRelease} predicts the release in which the feature will
become part of the language.
Else \var{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.
\var{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()}.
\var{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{_Feature} instances.
No feature description will ever be deleted from \module{__future__}.