/Doc/library/__future__.rst

 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
22Each statement in :file:`__future__.py` is of the form::
23
24   FeatureName = _Feature(OptionalRelease, MandatoryRelease,
25                          CompilerFlag)
26
27
28where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are
295-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
40In the case of a *MandatoryRelease* that has not yet occurred,
41*MandatoryRelease* predicts the release in which the feature will become part of
42the language.
43
44Else *MandatoryRelease* records when the feature became part of the language; in
45releases at or after that, modules no longer need a future statement to use the
46feature in question, but may continue to use such imports.
47
48*MandatoryRelease* may also be ``None``, meaning that a planned feature got
49dropped.
50
51Instances 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
55argument to the builtin function :func:`compile` to enable the feature in
56dynamically compiled code.  This flag is stored in the :attr:`compiler_flag`
57attribute on :class:`_Feature` instances.
58
59No feature description will ever be deleted from :mod:`__future__`.
60
61.. seealso::
62
63   :ref:`future`
64      How the compiler treats future imports.