inspect documentation describes module type inaccurately

[ericsnowcurrently]

BPO	21760
Nosy	@ncoghlan, @ericsnowcurrently, @miss-islington, @furkanonder
PRs	bpo-21760: fix __file__ description #19097

^{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 = None
created_at = <Date 2014-06-14.19:58:13.196>
labels = ['easy', '3.11', '3.9', '3.10', 'docs']
title = 'inspect documentation describes module type inaccurately'
updated_at = <Date 2021-06-21.15:17:15.619>
user = 'https://github.com/ericsnowcurrently'

bugs.python.org fields:

activity = <Date 2021-06-21.15:17:15.619>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2014-06-14.19:58:13.196>
creator = 'eric.snow'
dependencies = []
files = []
hgrepos = []
issue_num = 21760
keywords = ['easy']
message_count = 5.0
messages = ['220576', '364831', '366210', '395472', '395475']
nosy_count = 5.0
nosy_names = ['ncoghlan', 'docs@python', 'eric.snow', 'miss-islington', 'furkanonder']
pr_nums = ['19097']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue21760'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[ericsnowcurrently]

In the documentation for the inspect module, the module type is described with just 2 of its potential 7 attributes. The language reference[2] and importlib docs[3] both provide an accurate list of module attributes.

Furthermore, the description for __file__ should be fixed. It should be clear that __file__ reflects the location from which the module was loaded, that location is not necessarily a filename, and the attribute may not exist if the module was not loaded from a specific location (e.g. builtin and frozen modules). The same goes for __cached__

[1] https://docs.python.org/dev/library/inspect.html#types-and-members
[2] https://docs.python.org/3/reference/import.html#import-related-module-attributes
[3] https://docs.python.org/3/library/importlib.html#importlib.machinery.ModuleSpec

[furkanonder]

I sent a PR to fix a __file__ description.
#19097

[furkanonder]

PR has been sent.

[miss-islington]

New changeset 878d7e4 by Furkan Onder in branch 'main':
bpo-21760: fix __file__ description (GH-19097)
878d7e4

[ericsnowcurrently]

I've merged the changes for __file__. Thanks, furkanonder!

The fixes in the types module remain to be done, though now I see 4 of the relevant attributes instead of 2. (missing: __path__, __file__, __cached__)

[tuukkamustonen]

@encukou I believe this ticket is no longer relevant.

There was a change in https://github.com/python/cpython/pull/98116/files where the module members were removed from https://docs.python.org/dev/library/inspect.html#types-and-members, that this ticket suggested to update.

There's no longer nothing to update, because we're simply referencing another docs location for the details. I assume that other location is correct and covers all the fields. That was also the assumption in the original report in this ticket:

The language reference[2] and importlib docs[3] both provide an accurate list of module attributes.

[2] https://docs.python.org/3/reference/import.html#import-related-module-attributes (it's now linked to this)
[3] https://docs.python.org/3/library/importlib.html#importlib.machinery.ModuleSpec

[encukou]

I agree. Thank you for triaging!

[ericsnowcurrently]

As #65959 (comment) notes, there are also some missing attributes in the types module docs. However, those can be addressed by gh-64019.