pydoc: move __future__ imports out of the DATA block

[anntzer]

BPO	26120
Nosy	@serhiy-storchaka, @vedgar, @iritkatriel
PRs	bpo-26120: make pydoc exclude __future__ imports from the data block of the module #30888 bpo-26120: do not exclude __future__ Features in pydoc of the __future__ module itself #32180

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2022-03-29.22:07:47.957>
created_at = <Date 2016-01-15.06:31:39.957>
labels = ['3.11', 'type-feature', 'library', 'docs']
title = 'pydoc: move __future__ imports out of the DATA block'
updated_at = <Date 2022-03-29.22:07:47.956>
user = 'https://github.com/anntzer'

bugs.python.org fields:

activity = <Date 2022-03-29.22:07:47.956>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = True
closed_date = <Date 2022-03-29.22:07:47.957>
closer = 'iritkatriel'
components = ['Documentation', 'Library (Lib)']
creation = <Date 2016-01-15.06:31:39.957>
creator = 'Antony.Lee'
dependencies = []
files = []
hgrepos = []
issue_num = 26120
keywords = ['patch']
message_count = 15.0
messages = ['258272', '407922', '407939', '411604', '416086', '416155', '416160', '416192', '416212', '416213', '416263', '416264', '416276', '416284', '416301']
nosy_count = 4.0
nosy_names = ['docs@python', 'serhiy.storchaka', 'veky', 'iritkatriel']
pr_nums = ['30888', '32180']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue26120'
versions = ['Python 3.11']

[anntzer]

Currently, for a module that uses future imports, the DATA section of pydoc foo contains these imports interspersed with the "real" data from the module.

Even though it is fully-featured _Feature objects that are imported, it probably makes sense to move them out of this section.

[iritkatriel]

Reproduced on 3.11.

[vedgar]

I thought that _Feature starts with an underscore precisely to evade such listings. Do other "private" module data also get listed?

[iritkatriel]

It's like this:

>>> import foo
>>> dir(foo)
['__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', 'annotations', 'x']
>>> foo.annotations
_Feature((3, 7, 0, 'beta', 1), (3, 11, 0, 'alpha', 0), 16777216)

So the attribute in foo is called annotations, i.e. it's not private.

[serhiy-storchaka]

I am positive about this idea, but we must also think about the possible negative consequences. For example, the future annotations will be included in the star-import by default and can override some global names. The fact that some names not visible in the module help can override global names can be confusing.

I think it should be discussed with a wider auditory.

[iritkatriel]

That's a good point. I see that the __future__ imports appear in the dir() of the module, and indeed they are imported with 'from m import *'.

But I wonder if that is actually a bug. If you try this:

% cat x.py

from __future__ import annotations

% cat y.py
from x import *

print(dir())

class D:
    def f(self, a: D):
        return 42

% ./python.exe y.py    
['__annotations__', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', 'annotations']
Traceback (most recent call last):
  File "/Users/iritkatriel/src/cpython-654/y.py", line 5, in <module>
    class D:
    ^^^^^^^^
  File "/Users/iritkatriel/src/cpython-654/y.py", line 6, in D
    def f(self, a: D):
                   ^
NameError: name 'D' is not defined

---

but if you add "from __future__ import annotations" at the top of y.py, then it does run.

So perhaps the future imports should be excluded by "from m import *"?

[serhiy-storchaka]

I once proposed to exclude modules from the star import by default, but this proposition was rejected. You can try, maybe your proposition will be more acceptable.

[serhiy-storchaka]

Module objects are not shown in the help unless they are submodules of the specified module, even if they are imported with the star import. With this precedence I think it is okay to exclude the __future__ annotations as well.

[iritkatriel]

New changeset 15ba816 by Irit Katriel in branch 'main':
bpo-26120: make pydoc exclude __future__ imports from the data block of the module (GH-30888)
15ba816

[iritkatriel]

Thank you, Serhiy!