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 0363a40 by Steven Hsu in branch 'main':
bpo-44693: Update __future__ entry in Doc/glossary.rst (GH-27349)
0363a40

New changeset 642d873 by Miss Islington (bot) in branch '3.10':
bpo-44693: Update __future__ entry in Doc/glossary.rst (GH-27349) (GH-27357)
642d873

New changeset 4ce6c52 by Miss Islington (bot) in branch '3.9':
bpo-44693: Update __future__ entry in Doc/glossary.rst (GH-27349) (GH-27358)
4ce6c52