1 :mod:`__future__` --- Future statement definitions

     2 ==================================================

     3 

     4 .. module:: __future__

     5    :synopsis: Future statement definitions

     6 

     7 

     8 :mod:`__future__` is a real module, and serves three purposes:

     9 

    10 * To avoid confusing existing tools that analyze import statements and expect to

    11   find the modules they're importing.

    12 

    13 * To ensure that future_statements run under releases prior to 2.1 at least

    14   yield runtime exceptions (the import of :mod:`__future__` will fail, because

    15   there was no module of that name prior to 2.1).

    16 

    17 * To document when incompatible changes were introduced, and when they will be

    18   --- or were --- made mandatory.  This is a form of executable documentation, and

    19   can be inspected programmatically via importing :mod:`__future__` and examining

    20   its contents.

    21 

    22 Each statement in :file:`__future__.py` is of the form::

    23 

    24    FeatureName = _Feature(OptionalRelease, MandatoryRelease,

    25                           CompilerFlag)

    26 

    27 

    28 where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are

    29 5-tuples of the same form as ``sys.version_info``::

    30 

    31    (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int

    32     PY_MINOR_VERSION, # the 1; an int

    33     PY_MICRO_VERSION, # the 0; an int

    34     PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string

    35     PY_RELEASE_SERIAL # the 3; an int

    36    )

    37 

    38 *OptionalRelease* records the first release in which the feature was accepted.

    39 

    40 In the case of a *MandatoryRelease* that has not yet occurred,

    41 *MandatoryRelease* predicts the release in which the feature will become part of

    42 the language.

    43 

    44 Else *MandatoryRelease* records when the feature became part of the language; in

    45 releases at or after that, modules no longer need a future statement to use the

    46 feature in question, but may continue to use such imports.

    47 

    48 *MandatoryRelease* may also be ``None``, meaning that a planned feature got

    49 dropped.

    50 

    51 Instances of class :class:`_Feature` have two corresponding methods,

    52 :meth:`getOptionalRelease` and :meth:`getMandatoryRelease`.

    53 

    54 *CompilerFlag* is the (bitfield) flag that should be passed in the fourth

    55 argument to the builtin function :func:`compile` to enable the feature in

    56 dynamically compiled code.  This flag is stored in the :attr:`compiler_flag`

    57 attribute on :class:`_Feature` instances.

    58 

    59 No feature description will ever be deleted from :mod:`__future__`.

    60