| 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 |
Imports of the form ``from __future__ import feature`` are called |
| 12 |
:ref:`future statements <future>`. These are special-cased by the Python compiler |
| 13 |
to allow the use of new Python features in modules containing the future statement |
| 14 |
before the release in which the feature becomes standard. |
| 15 |
|
| 16 |
While these future statements are given additional special meaning by the |
| 17 |
Python compiler, they are still executed like any other import statement and |
| 18 |
the :mod:`!__future__` exists and is handled by the import system the same way |
| 19 |
any other Python module would be. This design serves three purposes: |
| 20 |
|
| 21 |
* To avoid confusing existing tools that analyze import statements and expect to |
| 22 |
find the modules they're importing. |
| 23 |
|
| 24 |
* To document when incompatible changes were introduced, and when they will be |
| 25 |
--- or were --- made mandatory. This is a form of executable documentation, and |
| 26 |
can be inspected programmatically via importing :mod:`!__future__` and examining |
| 27 |
its contents. |
| 28 |
|
| 29 |
* To ensure that :ref:`future statements <future>` run under releases prior to |
| 30 |
Python 2.1 at least yield runtime exceptions (the import of :mod:`!__future__` |
| 31 |
will fail, because there was no module of that name prior to 2.1). |
| 32 |
|
| 33 |
Module Contents |
| 34 |
--------------- |
| 35 |
|
| 36 |
No feature description will ever be deleted from :mod:`!__future__`. Since its |
| 37 |
introduction in Python 2.1 the following features have found their way into the |
| 38 |
language using this mechanism: |
| 39 |
|
| 40 |
|
| 41 |
.. list-table:: |
| 42 |
:widths: auto |
| 43 |
:header-rows: 1 |
| 44 |
|
| 45 |
* * feature |
| 46 |
* optional in |
| 47 |
* mandatory in |
| 48 |
* effect |
| 49 |
* * .. data:: nested_scopes |
| 50 |
* 2.1.0b1 |
| 51 |
* 2.2 |
| 52 |
* :pep:`227`: *Statically Nested Scopes* |
| 53 |
* * .. data:: generators |
| 54 |
* 2.2.0a1 |
| 55 |
* 2.3 |
| 56 |
* :pep:`255`: *Simple Generators* |
| 57 |
* * .. data:: division |
| 58 |
* 2.2.0a2 |
| 59 |
* 3.0 |
| 60 |
* :pep:`238`: *Changing the Division Operator* |
| 61 |
* * .. data:: absolute_import |
| 62 |
* 2.5.0a1 |
| 63 |
* 3.0 |
| 64 |
* :pep:`328`: *Imports: Multi-Line and Absolute/Relative* |
| 65 |
* * .. data:: with_statement |
| 66 |
* 2.5.0a1 |
| 67 |
* 2.6 |
| 68 |
* :pep:`343`: *The “with” Statement* |
| 69 |
* * .. data:: print_function |
| 70 |
* 2.6.0a2 |
| 71 |
* 3.0 |
| 72 |
* :pep:`3105`: *Make print a function* |
| 73 |
* * .. data:: unicode_literals |
| 74 |
* 2.6.0a2 |
| 75 |
* 3.0 |
| 76 |
* :pep:`3112`: *Bytes literals in Python 3000* |
| 77 |
* * .. data:: generator_stop |
| 78 |
* 3.5.0b1 |
| 79 |
* 3.7 |
| 80 |
* :pep:`479`: *StopIteration handling inside generators* |
| 81 |
* * .. data:: annotations |
| 82 |
* 3.7.0b1 |
| 83 |
* Never [1]_ |
| 84 |
* :pep:`563`: *Postponed evaluation of annotations*, |
| 85 |
:pep:`649`: *Deferred evaluation of annotations using descriptors* |
| 86 |
|
| 87 |
.. XXX Adding a new entry? Remember to update simple_stmts.rst, too. |
| 88 |
|
| 89 |
.. _future-classes: |
| 90 |
|
| 91 |
.. class:: _Feature |
| 92 |
|
| 93 |
Each statement in :file:`__future__.py` is of the form:: |
| 94 |
|
| 95 |
FeatureName = _Feature(OptionalRelease, MandatoryRelease, |
| 96 |
CompilerFlag) |
| 97 |
|
| 98 |
where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are |
| 99 |
5-tuples of the same form as :data:`sys.version_info`:: |
| 100 |
|
| 101 |
(PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int |
| 102 |
PY_MINOR_VERSION, # the 1; an int |
| 103 |
PY_MICRO_VERSION, # the 0; an int |
| 104 |
PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string |
| 105 |
PY_RELEASE_SERIAL # the 3; an int |
| 106 |
) |
| 107 |
|
| 108 |
.. method:: _Feature.getOptionalRelease() |
| 109 |
|
| 110 |
*OptionalRelease* records the first release in which the feature was accepted. |
| 111 |
|
| 112 |
.. method:: _Feature.getMandatoryRelease() |
| 113 |
|
| 114 |
In the case of a *MandatoryRelease* that has not yet occurred, |
| 115 |
*MandatoryRelease* predicts the release in which the feature will become part of |
| 116 |
the language. |
| 117 |
|
| 118 |
Else *MandatoryRelease* records when the feature became part of the language; in |
| 119 |
releases at or after that, modules no longer need a future statement to use the |
| 120 |
feature in question, but may continue to use such imports. |
| 121 |
|
| 122 |
*MandatoryRelease* may also be ``None``, meaning that a planned feature got |
| 123 |
dropped or that it is not yet decided. |
| 124 |
|
| 125 |
.. attribute:: _Feature.compiler_flag |
| 126 |
|
| 127 |
*CompilerFlag* is the (bitfield) flag that should be passed in the fourth |
| 128 |
argument to the built-in function :func:`compile` to enable the feature in |
| 129 |
dynamically compiled code. This flag is stored in the :attr:`_Feature.compiler_flag` |
| 130 |
attribute on :class:`_Feature` instances. |
| 131 |
|
| 132 |
.. [1] |
| 133 |
``from __future__ import annotations`` was previously scheduled to |
| 134 |
become mandatory in Python 3.10, but the change was delayed and ultimately |
| 135 |
canceled. This feature will eventually be deprecated and removed. See |
| 136 |
:pep:`649` and :pep:`749`. |
| 137 |
|
| 138 |
|
| 139 |
.. seealso:: |
| 140 |
|
| 141 |
:ref:`future` |
| 142 |
How the compiler treats future imports. |
| 143 |
|
| 144 |
:pep:`236` - Back to the __future__ |
| 145 |
The original proposal for the __future__ mechanism. |