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 :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.