Debian Codegraph @

Doc/library/__future__.rst

raw
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
86 .. XXX Adding a new entry? Remember to update simple_stmts.rst, too.
87
88 .. _future-classes:
89
90 .. class:: _Feature
91
92 Each statement in :file:`__future__.py` is of the form::
93
94 FeatureName = _Feature(OptionalRelease, MandatoryRelease,
95 CompilerFlag)
96
97 where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are
98 5-tuples of the same form as :data:`sys.version_info`::
99
100 (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
101 PY_MINOR_VERSION, # the 1; an int
102 PY_MICRO_VERSION, # the 0; an int
103 PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
104 PY_RELEASE_SERIAL # the 3; an int
105 )
106
107 .. method:: _Feature.getOptionalRelease()
108
109 *OptionalRelease* records the first release in which the feature was accepted.
110
111 .. method:: _Feature.getMandatoryRelease()
112
113 In the case of a *MandatoryRelease* that has not yet occurred,
114 *MandatoryRelease* predicts the release in which the feature will become part of
115 the language.
116
117 Else *MandatoryRelease* records when the feature became part of the language; in
118 releases at or after that, modules no longer need a future statement to use the
119 feature in question, but may continue to use such imports.
120
121 *MandatoryRelease* may also be ``None``, meaning that a planned feature got
122 dropped or that it is not yet decided.
123
124 .. attribute:: _Feature.compiler_flag
125
126 *CompilerFlag* is the (bitfield) flag that should be passed in the fourth
127 argument to the built-in function :func:`compile` to enable the feature in
128 dynamically compiled code. This flag is stored in the :attr:`_Feature.compiler_flag`
129 attribute on :class:`_Feature` instances.
130
131 .. [1]
132 ``from __future__ import annotations`` was previously scheduled to
133 become mandatory in Python 3.10, but the Python Steering Council
134 twice decided to delay the change
135 (`announcement for Python 3.10 <https://mail.python.org/archives/list/[email protected]/message/CLVXXPQ2T2LQ5MP2Y53VVQFCXYWQJHKZ/>`__;
136 `announcement for Python 3.11 <https://mail.python.org/archives/list/[email protected]/message/VIZEBX5EYMSYIJNDBF6DMUMZOCWHARSO/>`__).
137 No final decision has been made yet. See also :pep:`563` and :pep:`649`.
138
139
140 .. seealso::
141
142 :ref:`future`
143 How the compiler treats future imports.
144
145 :pep:`236` - Back to the __future__
146 The original proposal for the __future__ mechanism.