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!

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.

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.

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

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.

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.

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.

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__

Yes, ask me to review.

 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 

 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 

 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