classification
Title: Unclear definition of the "__future__" module in Docs
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: StevenHsuYL, docs@python, eric.araujo, steven.daprano, terry.reedy
Priority: normal Keywords: patch

Created on 2021-07-21 08:45 by StevenHsuYL, last changed 2021-07-26 01:41 by terry.reedy. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 27349 merged StevenHsuYL, 2021-07-25 17:06
PR 27357 merged miss-islington, 2021-07-26 01:11
PR 27358 merged miss-islington, 2021-07-26 01:11
Messages (12)
msg397931 - (view) Author: Steven Hsu (StevenHsuYL) * Date: 2021-07-21 08:45
In Doc/glossary.rst, the first sentence of the entry "__future__" is that "A pseudo-module which programmers can use to enable new language features which are not compatible with the current interpreter."

However, in Doc/library/__future__.rst, the first sentence is that ":mod:`__future__` is a real module, and serves three purposes:"

Is there any contradiction of these two descriptions, that "pseuso-module" and "real module" refer to the same module?

And if so, should we fix one of them?

Thanks for review!
msg397933 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2021-07-21 08:55
I agree that the contradiction should be resolved.

There is an actual `__future__.py` module, which on my system it is at /usr/local/lib/python3.9/__future__.py

But when we use the special syntax:

    from __future__ import <feature>

it doesn't do a normal import of the `__future__.py` module, it is actually a compiler directive.
msg397944 - (view) Author: Steven Hsu (StevenHsuYL) * Date: 2021-07-21 12:54
It sounds like that both descriptions (pseudo- and real) are true in different points of view on the __future__ module.

I have no idea how to resolve this contradiction of the original design of the module. Any suggestion?

Thanks for reply.
msg398093 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2021-07-23 20:08
> it doesn't do a normal import of the `__future__.py` module, it is actually a compiler directive.

It’s both!  The compiler has special handling for this line (pseudo-module), and the interpreter does a regular import that gets the regular python module which can be used for introspection (the third purpose noted in the module doc).
msg398096 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-07-23 21:14
I thnk the glossary should say both.  Approximately: "When the first statement of a program starts 'from __future__ import feature', a pseudo-module ... . When used later in a program, <link> __future__ is a real module."  Link each statement to an appropriate place in the doc.
msg398116 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2021-07-24 03:04
What exactly is a "pseudo-module"? I can only imagine it is something 
like sys, which exists internally in the interpreter but doesn't have an 
independent existence as a .py .dll or .so file.

That's not the case with `__future__`, which is an *actual* module. I 
think that talking about "pseudo-module" is inaccurate and confusing and 
I suggest we ought to drop it.

The real difference is (as I understand it) is that the **syntax**

    from __future__ import <feature>

is not an actual import, it doesn't go through the import system, it 
doesn't touch the `__future__` module, and it can only appear in 
restricted positions.

(It is legal in the interactive interpreter, and as the very first 
executable line of code in a .py file. So after the docstring, but 
before any code.)

So the current docs are misleading. It's not `__future__` that is 
special. That is a real module. It is the syntactic form that is 
special. It's not a pseudo-*module* but a pseudo-*import*.

With a little bit of jiggery-pokery we can even get the "from ... import 
..." version working:

    >>> from __future__ import nested_scopes as nested_scopes
    >>> nested_scopes
    _Feature((2, 1, 0, 'beta', 1), (2, 2, 0, 'alpha', 0), 16)

(Only tested in the interactive interpreter, but I presume it will also 
work in a .py file.)

So:

1. `__future__` is a real, not "pseudo", module.

2. We can import from the module like any other module.

3. It is the *syntax* `from __future__ import <feature>` that is 
   special, not the module.

4. It behaves as a compiler directive, not an import.

Let's fix the docs to describe what actually happens and drop any 
reference to "pseudo-module". It is needlessly confusing and inaccurate.
msg398117 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-07-24 05:47
I agree with Steven's more careful analysis and with canning 'pseudo'.  Current suggestion.

A *future statement*, "from __future__ import *feature* ...",  directs the compiler to compile the current module using syntax or semantics that will become standard in a future release of Python.  The *__future__ module* documents the possible values of *feature*.

Cross reference *future statement to <reference/simple_stmts.html#future-statements> and *__future__ module* to its doc chapter.  The first sentence above is based on the first sentence of the future statement doc.
msg398122 - (view) Author: Steven Hsu (StevenHsuYL) * Date: 2021-07-24 08:36
Applying above suggestions, the first sentence of the entry "__future__" would be replaced by:

A :ref:`future statement <future>`, "from __future__ import *feature* ...", directs the compiler to compile the current module using syntax or semantics that will become standard in a future release of Python. The :mod:`__future__` module documents the possible values of *feature*.

And the confusing sentence, "A pseudo-module which programmers can use to enable new language features which are not compatible with the current interpreter." would be removed.

Can I fix this issue this way? 
If confirmed, I would make a PR for this issue.

--
:ref:`future` -> https://docs.python.org/3.9/reference/simple_stmts.html#future-statements
:mod:`__future__` -> https://docs.python.org/3.9/library/__future__.html#module-__future__
msg398168 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-07-24 17:04
Yes, ask me to review.
msg398204 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-07-26 01:11
New changeset 0363a4014d90df17a29042de008ef0b659f92505 by Steven Hsu in branch 'main':
bpo-44693: Update __future__ entry in Doc/glossary.rst (GH-27349)
https://github.com/python/cpython/commit/0363a4014d90df17a29042de008ef0b659f92505
msg398205 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-07-26 01:40
New changeset 642d873d672eb1b4ddffd99e665c54ed358a4562 by Miss Islington (bot) in branch '3.10':
bpo-44693: Update __future__ entry in Doc/glossary.rst (GH-27349) (GH-27357)
https://github.com/python/cpython/commit/642d873d672eb1b4ddffd99e665c54ed358a4562
msg398206 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-07-26 01:40
New changeset 4ce6c5285abd78dc936ec6036e7bb964fd55d955 by Miss Islington (bot) in branch '3.9':
bpo-44693: Update __future__ entry in Doc/glossary.rst (GH-27349) (GH-27358)
https://github.com/python/cpython/commit/4ce6c5285abd78dc936ec6036e7bb964fd55d955
History
Date User Action Args
2021-07-26 01:41:07terry.reedysetstatus: open -> closed
nosy: - miss-islington

resolution: fixed
stage: patch review -> resolved
2021-07-26 01:40:39terry.reedysetmessages: + msg398206
2021-07-26 01:40:16terry.reedysetmessages: + msg398205
2021-07-26 01:11:35terry.reedysetmessages: + msg398204
2021-07-26 01:11:27miss-islingtonsetpull_requests: + pull_request25899
2021-07-26 01:11:22miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request25898
2021-07-25 17:06:12StevenHsuYLsetkeywords: + patch
stage: patch review
pull_requests: + pull_request25890
2021-07-24 17:04:36terry.reedysetmessages: + msg398168
2021-07-24 08:36:54StevenHsuYLsetmessages: + msg398122
2021-07-24 05:47:56terry.reedysetmessages: + msg398117
2021-07-24 03:04:59steven.dapranosetmessages: + msg398116
2021-07-23 21:14:10terry.reedysetnosy: + terry.reedy
messages: + msg398096
2021-07-23 20:08:21eric.araujosetnosy: + eric.araujo
messages: + msg398093
2021-07-21 12:54:44StevenHsuYLsetmessages: + msg397944
2021-07-21 08:55:50steven.dapranosetnosy: + steven.daprano
messages: + msg397933
2021-07-21 08:45:17StevenHsuYLcreate