[issue44693] Unclear definition of the "__future__" module in Docs

[Terry J. Reedy]

Change by Terry J. Reedy :


--
nosy:  -miss-islington
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[Terry J. Reedy]

Terry J. Reedy  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[Terry J. Reedy]

Terry J. Reedy  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[Terry J. Reedy]

Terry J. Reedy  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[miss-islington]

Change by miss-islington :


--
pull_requests: +25899
pull_request: https://github.com/python/cpython/pull/27358

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[miss-islington]

Change by miss-islington :


--
nosy: +miss-islington
nosy_count: 5.0 -> 6.0
pull_requests: +25898
pull_request: https://github.com/python/cpython/pull/27357

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[Steven Hsu]

Change by Steven Hsu :


--
keywords: +patch
pull_requests: +25890
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/27349

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[Terry J. Reedy]

Terry J. Reedy  added the comment:

Yes, ask me to review.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[Steven Hsu]

Steven Hsu  added the comment:

Applying above suggestions, the first sentence of the entry "__future__" would 
be replaced by:

A :ref:`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 :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__

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[Terry J. Reedy]

Terry J. Reedy  added the comment:

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 
 and *__future__ module* to its 
doc chapter.  The first sentence above is based on the first sentence of the 
future statement doc.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[Steven D'Aprano]

Steven D'Aprano  added the comment:

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 

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[Terry J. Reedy]

Terry J. Reedy  added the comment:

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,  __future__ is a real module."  Link each 
statement to an appropriate place in the doc.

--
nosy: +terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[Éric Araujo]

Éric Araujo  added the comment:

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

--
nosy: +eric.araujo

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[Steven Hsu]

Steven Hsu  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[Steven D'Aprano]

Steven D'Aprano  added the comment:

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 

it doesn't do a normal import of the `__future__.py` module, it is actually a 
compiler directive.

--
nosy: +steven.daprano

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44693] Unclear definition of the "__future__" module in Docs

[Steven Hsu]

New submission from Steven Hsu :

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!

--
assignee: docs@python
components: Documentation
messages: 397931
nosy: StevenHsuYL, docs@python
priority: normal
severity: normal
status: open
title: Unclear definition of the "__future__" module in Docs
type: enhancement
versions: Python 3.10, Python 3.11, Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com