Doc/lib/libfuture.tex

   1 \section{\module{__future__} ---
   2          Future statement definitions}
   3
   4 \declaremodule[future]{standard}{__future__}
   5 \modulesynopsis{Future statement definitions}
   6
   7 \module{__future__} is a real module, and serves three purposes:
   8
   9 \begin{itemize}
  10
  11 \item To avoid confusing existing tools that analyze import statements
  12       and expect to find the modules they're importing.
  13
  14 \item To ensure that future_statements run under releases prior to 2.1
  15       at least yield runtime exceptions (the import of
  16       \module{__future__} will fail, because there was no module of
  17       that name prior to 2.1).
  18
  19 \item To document when incompatible changes were introduced, and when they
  20       will be --- or were --- made mandatory.  This is a form of executable
  21       documentation, and can be inspected programatically via importing
  22       \module{__future__} and examining its contents.
  23
  24 \end{itemize}
  25
  26 Each statement in \file{__future__.py} is of the form:
  27
  28 \begin{alltt}
  29 FeatureName = "_Feature(" \var{OptionalRelease} "," \var{MandatoryRelease} ","
  30                         \var{CompilerFlag} ")"
  31 \end{alltt}
  32
  33 where, normally, \var{OptionalRelease} is less than
  34 \var{MandatoryRelease}, and both are 5-tuples of the same form as
  35 \code{sys.version_info}:
  36
  37 \begin{verbatim}
  38     (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
  39      PY_MINOR_VERSION, # the 1; an int
  40      PY_MICRO_VERSION, # the 0; an int
  41      PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
  42      PY_RELEASE_SERIAL # the 3; an int
  43     )
  44 \end{verbatim}
  45
  46 \var{OptionalRelease} records the first release in which the feature
  47 was accepted.
  48
  49 In the case of a \var{MandatoryRelease} that has not yet occurred,
  50 \var{MandatoryRelease} predicts the release in which the feature will
  51 become part of the language.
  52
  53 Else \var{MandatoryRelease} records when the feature became part of
  54 the language; in releases at or after that, modules no longer need a
  55 future statement to use the feature in question, but may continue to
  56 use such imports.
  57
  58 \var{MandatoryRelease} may also be \code{None}, meaning that a planned
  59 feature got dropped.
  60
  61 Instances of class \class{_Feature} have two corresponding methods,
  62 \method{getOptionalRelease()} and \method{getMandatoryRelease()}.
  63
  64 \var{CompilerFlag} is the (bitfield) flag that should be passed in the
  65 fourth argument to the builtin function \function{compile()} to enable
  66 the feature in dynamically compiled code.  This flag is stored in the
  67 \member{compiler_flag} attribute on \class{_Feature} instances.
  68
  69 No feature description will ever be deleted from \module{__future__}.