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