Doc/library/__future__.rst

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