Skip to content

Commit 3b86891

Browse files
hauntsaninjahauntsaninja
authored
gh-110893: Improve the documentation for __future__ module (#114642)
nedbat took issue with the phrasing "real module". I'm actually fine with that phrasing, but I do think the `__future__` page should be clear about the way in which the `__future__` module is special. (Yes, there was a footnote linking to the future statements part of the reference, but there should be upfront discussion). I'm sympathetic to nedbat's claim that no one really cares about `__future__._Feature`, so I've moved the interesting table up to the top.
1 parent 1ac1b2f commit 3b86891

File tree

1 file changed

+56
-42
lines changed

1 file changed

+56
-42
lines changed

‎Doc/library/__future__.rst

Lines changed: 56 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -8,20 +8,68 @@
88

99
--------------
1010

11-
:mod:`__future__` is a real module, and serves three purposes:
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:
1220

1321
* To avoid confusing existing tools that analyze import statements and expect to
1422
find the modules they're importing.
1523

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-
2024
* To document when incompatible changes were introduced, and when they will be
2125
--- or were --- made mandatory. This is a form of executable documentation, and
2226
can be inspected programmatically via importing :mod:`__future__` and examining
2327
its contents.
2428

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+
| feature | optional in | mandatory in | effect |
42+
+==================+=============+==============+=============================================+
43+
| nested_scopes | 2.1.0b1 | 2.2 | :pep:`227`: |
44+
| | | | *Statically Nested Scopes* |
45+
+------------------+-------------+--------------+---------------------------------------------+
46+
| generators | 2.2.0a1 | 2.3 | :pep:`255`: |
47+
| | | | *Simple Generators* |
48+
+------------------+-------------+--------------+---------------------------------------------+
49+
| division | 2.2.0a2 | 3.0 | :pep:`238`: |
50+
| | | | *Changing the Division Operator* |
51+
+------------------+-------------+--------------+---------------------------------------------+
52+
| absolute_import | 2.5.0a1 | 3.0 | :pep:`328`: |
53+
| | | | *Imports: Multi-Line and Absolute/Relative* |
54+
+------------------+-------------+--------------+---------------------------------------------+
55+
| with_statement | 2.5.0a1 | 2.6 | :pep:`343`: |
56+
| | | | *The "with" Statement* |
57+
+------------------+-------------+--------------+---------------------------------------------+
58+
| print_function | 2.6.0a2 | 3.0 | :pep:`3105`: |
59+
| | | | *Make print a function* |
60+
+------------------+-------------+--------------+---------------------------------------------+
61+
| unicode_literals | 2.6.0a2 | 3.0 | :pep:`3112`: |
62+
| | | | *Bytes literals in Python 3000* |
63+
+------------------+-------------+--------------+---------------------------------------------+
64+
| generator_stop | 3.5.0b1 | 3.7 | :pep:`479`: |
65+
| | | | *StopIteration handling inside generators* |
66+
+------------------+-------------+--------------+---------------------------------------------+
67+
| annotations | 3.7.0b1 | TBD [1]_ | :pep:`563`: |
68+
| | | | *Postponed evaluation of annotations* |
69+
+------------------+-------------+--------------+---------------------------------------------+
70+
71+
.. XXX Adding a new entry? Remember to update simple_stmts.rst, too.
72+
2573
.. _future-classes:
2674

2775
.. class:: _Feature
@@ -65,43 +113,6 @@
65113
dynamically compiled code. This flag is stored in the :attr:`_Feature.compiler_flag`
66114
attribute on :class:`_Feature` instances.
67115

68-
No feature description will ever be deleted from :mod:`__future__`. Since its
69-
introduction in Python 2.1 the following features have found their way into the
70-
language using this mechanism:
71-
72-
+------------------+-------------+--------------+---------------------------------------------+
73-
| feature | optional in | mandatory in | effect |
74-
+==================+=============+==============+=============================================+
75-
| nested_scopes | 2.1.0b1 | 2.2 | :pep:`227`: |
76-
| | | | *Statically Nested Scopes* |
77-
+------------------+-------------+--------------+---------------------------------------------+
78-
| generators | 2.2.0a1 | 2.3 | :pep:`255`: |
79-
| | | | *Simple Generators* |
80-
+------------------+-------------+--------------+---------------------------------------------+
81-
| division | 2.2.0a2 | 3.0 | :pep:`238`: |
82-
| | | | *Changing the Division Operator* |
83-
+------------------+-------------+--------------+---------------------------------------------+
84-
| absolute_import | 2.5.0a1 | 3.0 | :pep:`328`: |
85-
| | | | *Imports: Multi-Line and Absolute/Relative* |
86-
+------------------+-------------+--------------+---------------------------------------------+
87-
| with_statement | 2.5.0a1 | 2.6 | :pep:`343`: |
88-
| | | | *The "with" Statement* |
89-
+------------------+-------------+--------------+---------------------------------------------+
90-
| print_function | 2.6.0a2 | 3.0 | :pep:`3105`: |
91-
| | | | *Make print a function* |
92-
+------------------+-------------+--------------+---------------------------------------------+
93-
| unicode_literals | 2.6.0a2 | 3.0 | :pep:`3112`: |
94-
| | | | *Bytes literals in Python 3000* |
95-
+------------------+-------------+--------------+---------------------------------------------+
96-
| generator_stop | 3.5.0b1 | 3.7 | :pep:`479`: |
97-
| | | | *StopIteration handling inside generators* |
98-
+------------------+-------------+--------------+---------------------------------------------+
99-
| annotations | 3.7.0b1 | TBD [1]_ | :pep:`563`: |
100-
| | | | *Postponed evaluation of annotations* |
101-
+------------------+-------------+--------------+---------------------------------------------+
102-
103-
.. XXX Adding a new entry? Remember to update simple_stmts.rst, too.
104-
105116
.. [1]
106117
``from __future__ import annotations`` was previously scheduled to
107118
become mandatory in Python 3.10, but the Python Steering Council
@@ -115,3 +126,6 @@ language using this mechanism:
115126

116127
:ref:`future`
117128
How the compiler treats future imports.
129+
130+
:pep:`236` - Back to the __future__
131+
The original proposal for the __future__ mechanism.

0 commit comments

Comments
 (0)