1:mod:`__future__` --- Future statement definitions
2==================================================
3
4.. module:: __future__
5   :synopsis: Future statement definitions
6
7**Source code:** :source:`Lib/__future__.py`
8
9--------------
10
11:mod:`__future__` is a real module, and serves three purposes:
12
13* To avoid confusing existing tools that analyze import statements and expect to
14  find the modules they're importing.
15
16* To ensure that :ref:`future statements <future>` run under releases prior to
17  2.1 at least yield runtime exceptions (the import of :mod:`__future__` will
18  fail, because there was no module of that name prior to 2.1).
19
20* To document when incompatible changes were introduced, and when they will be
21  --- or were --- made mandatory.  This is a form of executable documentation, and
22  can be inspected programmatically via importing :mod:`__future__` and examining
23  its contents.
24
25Each statement in :file:`__future__.py` is of the form::
26
27   FeatureName = _Feature(OptionalRelease, MandatoryRelease,
28                          CompilerFlag)
29
30
31where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are
325-tuples of the same form as :data:`sys.version_info`::
33
34   (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
35    PY_MINOR_VERSION, # the 1; an int
36    PY_MICRO_VERSION, # the 0; an int
37    PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
38    PY_RELEASE_SERIAL # the 3; an int
39   )
40
41*OptionalRelease* records the first release in which the feature was accepted.
42
43In the case of a *MandatoryRelease* that has not yet occurred,
44*MandatoryRelease* predicts the release in which the feature will become part of
45the language.
46
47Else *MandatoryRelease* records when the feature became part of the language; in
48releases at or after that, modules no longer need a future statement to use the
49feature in question, but may continue to use such imports.
50
51*MandatoryRelease* may also be ``None``, meaning that a planned feature got
52dropped.
53
54Instances of class :class:`_Feature` have two corresponding methods,
55:meth:`getOptionalRelease` and :meth:`getMandatoryRelease`.
56
57*CompilerFlag* is the (bitfield) flag that should be passed in the fourth
58argument to the built-in function :func:`compile` to enable the feature in
59dynamically compiled code.  This flag is stored in the :attr:`compiler_flag`
60attribute on :class:`_Feature` instances.
61
62No feature description will ever be deleted from :mod:`__future__`. Since its
63introduction in Python 2.1 the following features have found their way into the
64language using this mechanism:
65
66+------------------+-------------+--------------+---------------------------------------------+
67| feature          | optional in | mandatory in | effect                                      |
68+==================+=============+==============+=============================================+
69| nested_scopes    | 2.1.0b1     | 2.2          | :pep:`227`:                                 |
70|                  |             |              | *Statically Nested Scopes*                  |
71+------------------+-------------+--------------+---------------------------------------------+
72| generators       | 2.2.0a1     | 2.3          | :pep:`255`:                                 |
73|                  |             |              | *Simple Generators*                         |
74+------------------+-------------+--------------+---------------------------------------------+
75| division         | 2.2.0a2     | 3.0          | :pep:`238`:                                 |
76|                  |             |              | *Changing the Division Operator*            |
77+------------------+-------------+--------------+---------------------------------------------+
78| absolute_import  | 2.5.0a1     | 3.0          | :pep:`328`:                                 |
79|                  |             |              | *Imports: Multi-Line and Absolute/Relative* |
80+------------------+-------------+--------------+---------------------------------------------+
81| with_statement   | 2.5.0a1     | 2.6          | :pep:`343`:                                 |
82|                  |             |              | *The "with" Statement*                      |
83+------------------+-------------+--------------+---------------------------------------------+
84| print_function   | 2.6.0a2     | 3.0          | :pep:`3105`:                                |
85|                  |             |              | *Make print a function*                     |
86+------------------+-------------+--------------+---------------------------------------------+
87| unicode_literals | 2.6.0a2     | 3.0          | :pep:`3112`:                                |
88|                  |             |              | *Bytes literals in Python 3000*             |
89+------------------+-------------+--------------+---------------------------------------------+
90| generator_stop   | 3.5.0b1     | 3.7          | :pep:`479`:                                 |
91|                  |             |              | *StopIteration handling inside generators*  |
92+------------------+-------------+--------------+---------------------------------------------+
93| annotations      | 3.7.0b1     | 3.10         | :pep:`563`:                                 |
94|                  |             |              | *Postponed evaluation of annotations*       |
95+------------------+-------------+--------------+---------------------------------------------+
96
97.. XXX Adding a new entry?  Remember to update simple_stmts.rst, too.
98
99
100.. seealso::
101
102   :ref:`future`
103      How the compiler treats future imports.
104