Doc: Namespace Packages: Inconsistent documentation of __loader__ being None

[JulienPalard]

BPO	35181
Nosy	@warsaw, @brettcannon, @ncoghlan, @ericvsmith, @ericsnowcurrently, @JulienPalard, @csabella, @maggyero, @miss-islington
PRs	bpo-35181: Correct an assumption about the namespace package loader attribute #10376 bpo-37800: Clean up importlib documentation for some module attributes #10016 bpo-35181: Correct importlib documentation for some module attributes #15190 [3.9] bpo-35181: Correct importlib documentation for some module attributes (GH-15190) #22872 [3.8] bpo-35181: Correct importlib documentation for some module attributes (GH-15190) #22873

^{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 = 'https://github.com/warsaw'
closed_at = None
created_at = <Date 2018-11-06.22:29:09.600>
labels = ['type-feature', '3.8', '3.9', '3.10', 'docs']
title = 'Doc: Namespace Packages: Inconsistent documentation of __loader__ being None'
updated_at = <Date 2020-10-24.03:04:47.832>
user = 'https://github.com/JulienPalard'

bugs.python.org fields:

activity = <Date 2020-10-24.03:04:47.832>
actor = 'maggyero'
assignee = 'barry'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2018-11-06.22:29:09.600>
creator = 'mdk'
dependencies = []
files = []
hgrepos = []
issue_num = 35181
keywords = ['patch']
message_count = 12.0
messages = ['329392', '329419', '339814', '341173', '346316', '346317', '379227', '379253', '379254', '379256', '379260', '379512']
nosy_count = 10.0
nosy_names = ['barry', 'brett.cannon', 'ncoghlan', 'eric.smith', 'docs@python', 'eric.snow', 'mdk', 'cheryl.sabella', 'maggyero', 'miss-islington']
pr_nums = ['10376', '10016', '15190', '22872', '22873']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue35181'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[JulienPalard]

The documentation states that a __loader__ of a namespace package should be None:

• 1 "For namespace packages this should be set to None."
• 2 "To indicate to the import machinery that the spec represents a namespace portion. the path entry finder sets “loader” on the spec to None".

But this looks wrong 3, looks like it has been changed in 4/5.

I think one should rely on __file__ being None on namespace packages (which make sense as they span over multiple directories) instead of __loader__ being None (a side effect of the import machinery ?).

[maggyero]

It looks like Barry Warsaw has not been fully updated the documentation after making the __spec__.loader attribute match with the __loader__ attribute, and the __spec__.file attribute match with the __file__ attribute for namespace packages.

Here is a pull request to update the library documentation of importlib (your first link [1]) with the current Barry's implementation:
#10016

Here is another pull request to update the reference documentation of the import system (your second link [2], but for a different paragraph, as I think the "To indicate to the import machinery that the spec represents a namespace portion the path entry finder sets “loader” on the spec to None" sentence is correct, since the _bootstrap.ModuleSpec.loader attribute of a namespace package remains None until the call to the importlib._bootstrap._init_module_attrs function):
#10376

[csabella]

@barry, you started a review of PR10016 and I believe all your requested changes have been made, so please review again when you get a chance. Please also take a look at PR10376. Thanks!

[warsaw]

I've approved both PRs, however I am rather uncomfortable about the code snippet in import.rst. Géry's change is a good one AFAICT, and thanks for the contribution! I would feel much better about the long term correctness of this code snippet if we had a doctest to run over it. But that's for another time.

[maggyero]

@julien, @barry

Now that the PRs are merged, I think that we can close this issue.

[maggyero]

Oops, sorry, only one of the two PRs has been merged.

[warsaw]

Apologies for the long delay in reviewing this bug. I'm looking at it now, however since Python 3.7 is in security-only mode, this will only apply to 3.10, 3.9, and 3.8.

[miss-islington]

New changeset 27f1bd8 by Géry Ogam in branch 'master':
bpo-35181: Correct importlib documentation for some module attributes (GH-15190)
27f1bd8

[miss-islington]

New changeset 916ac95 by Miss Skeleton (bot) in branch '3.8':
bpo-35181: Correct importlib documentation for some module attributes (GH-15190)
916ac95

[miss-islington]

New changeset 6e842bc by Miss Skeleton (bot) in branch '3.9':
bpo-35181: Correct importlib documentation for some module attributes (GH-15190)
6e842bc

[warsaw]

@maggyero - I haven't merged PR 10016, but I left some additional comments. Are you still interested in shepherding this PR?

[maggyero]

Thanks @barry for reviewing and merging PR 15190

I haven't merged PR 10016, but I left some additional comments. Are you still interested in shepherding this PR?

Also thanks for helping me with @ericsnowcurrently advancing this last PR. Yes I am still interested, I have reviewed all the comments and updated the whole thing, doing my best to keep the two descriptions of the module attributes and spec attributes consistent since this PEP updates both descriptions.

[warsaw]

#15190 has been merged, so I believe all issues mentioned in this issue have been resolved. The issue just never got closed, so closing it now. Please follow up here or open a new issue and @ mention me if anyone thinks otherwise. Thanks for all the contributions.