docs are missing info about module attributes #64019

ericsnowcurrently · 2013-11-28T06:42:21Z

BPO	19820
Nosy	@ericsnowcurrently, @eamanu, @MichaelAnckaert, @anilbey
PRs	bpo-19820: Updated documentation for inspect module: some module attributes were… #15359

^{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 2013-11-28.06:42:20.974>
labels = ['easy', '3.7', '3.8', '3.9', 'type-feature', 'docs']
title = 'docs are missing info about module attributes'
updated_at = <Date 2019-08-21.12:23:23.366>
user = 'https://github.com/ericsnowcurrently'

bugs.python.org fields:

activity = <Date 2019-08-21.12:23:23.366>
actor = 'michaelanckaert'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2013-11-28.06:42:20.974>
creator = 'eric.snow'
dependencies = []
files = []
hgrepos = []
issue_num = 19820
keywords = ['patch', 'easy']
message_count = 6.0
messages = ['204642', '347930', '349712', '349718', '349727', '349735']
nosy_count = 6.0
nosy_names = ['Arfrever', 'docs@python', 'eric.snow', 'eamanu', 'michaelanckaert', 'anilbey']
pr_nums = ['15359']
priority = 'low'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue19820'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

Linked PRs

The text was updated successfully, but these errors were encountered:

ericsnowcurrently · 2013-11-28T06:42:20Z

The docs for the inspect module and the types module do not list all the import-related module attributes. I'm guessing they've been out of sync a while.

The docstring for for inspect.ismodule() is likewise missing information.

anilbey · 2019-07-14T17:39:25Z

Are they still missing? inspect.ismodule() seems to be there at least.
https://docs.python.org/3/library/inspect.html

MichaelAnckaert · 2019-08-14T15:40:51Z

As far as I can tell there is at least some information missing from the 'Types and members' section. Not all attributes are listed in the table.

For example the attribute __cached__ is missing from the module type but it is documented in the inspect module.

I can update the docs but I would rely on the comments in Lib/inspect.py on what to include. Executing inspect.getmembers on a module returns a lot more attributes than documented in ismodule.

ericsnowcurrently · 2019-08-14T17:10:15Z

The relevant module attributes are described in the importlib docs: https://docs.python.org/3/library/importlib.html#importlib.abc.Loader.load_module

eamanu · 2019-08-14T17:55:12Z

I can update the docs but I would rely on the comments in Lib/inspect.py on what to include. Executing inspect.getmembers on a module returns a lot more attributes than documented in ismodule.

I can help too.

MichaelAnckaert · 2019-08-14T19:00:04Z

@emmanuel: thanks for offering your help.

I made a first attempt at improving the docs in this branch: https://github.com/MichaelAnckaert/cpython/tree/bpo-19820

…butes instead of listing them (GH-98116) Co-authored-by: Michael Anckaert <michael.anckaert@sinax.be>

… attributes instead of listing them (pythonGH-98116) (cherry picked from commit 7d2dcc5) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> Co-authored-by: Michael Anckaert <michael.anckaert@sinax.be>

brettcannon · 2022-11-25T19:13:22Z

This is fixed in main, but the 3.11 backport failed.

… attributes instead of listing them (pythonGH-98116) (cherry picked from commit 7d2dcc5) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> Co-authored-by: Michael Anckaert <michael.anckaert@sinax.be>

…butes instead of listing them (GH-98116) (cherry picked from commit 7d2dcc5) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> Co-authored-by: Michael Anckaert <michael.anckaert@sinax.be>

ericsnowcurrently · 2024-07-18T17:14:38Z

The types module doc still needs fixing. ¹ The following attributes are not listed in the entry there for ModuleType:

__path__
__file__
__cached__

Honestly, we'd probably be best served by replacing the attributes in the types docs entry with a reference to the import docs, like we did in gh-98116. That's assuming we would also be careful to transfer the information that is exclusive to the types module docs, if any.

(expand for a basic diff)

diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index 116868c24be..88bca9dba44 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -259,64 +259,7 @@ Standard names are defined for the following types:

    The type of :term:`modules <module>`. The constructor takes the name of the
    module to be created and optionally its :term:`docstring`.
-
-   .. note::
-      Use :func:`importlib.util.module_from_spec` to create a new module if you
-      wish to set the various import-controlled attributes.
-
-   .. attribute:: __doc__
-
-      The :term:`docstring` of the module. Defaults to ``None``.
-
-   .. attribute:: __loader__
-
-      The :term:`loader` which loaded the module. Defaults to ``None``.
-
-      This attribute is to match :attr:`importlib.machinery.ModuleSpec.loader`
-      as stored in the :attr:`__spec__` object.
-
-      .. note::
-         A future version of Python may stop setting this attribute by default.
-         To guard against this potential change, preferably read from the
-         :attr:`__spec__` attribute instead or use
-         ``getattr(module, "__loader__", None)`` if you explicitly need to use
-         this attribute.
-
-      .. versionchanged:: 3.4
-         Defaults to ``None``. Previously the attribute was optional.
-
-   .. attribute:: __name__
-
-      The name of the module. Expected to match
-      :attr:`importlib.machinery.ModuleSpec.name`.
-
-   .. attribute:: __package__
-
-      Which :term:`package` a module belongs to. If the module is top-level
-      (i.e. not a part of any specific package) then the attribute should be set
-      to ``''``, else it should be set to the name of the package (which can be
-      :attr:`__name__` if the module is a package itself). Defaults to ``None``.
-
-      This attribute is to match :attr:`importlib.machinery.ModuleSpec.parent`
-      as stored in the :attr:`__spec__` object.
-
-      .. note::
-         A future version of Python may stop setting this attribute by default.
-         To guard against this potential change, preferably read from the
-         :attr:`__spec__` attribute instead or use
-         ``getattr(module, "__package__", None)`` if you explicitly need to use
-         this attribute.
-
-      .. versionchanged:: 3.4
-         Defaults to ``None``. Previously the attribute was optional.
-
-   .. attribute:: __spec__
-
-      A record of the module's import-system-related state. Expected to be an
-      instance of :class:`importlib.machinery.ModuleSpec`.
-
-      .. versionadded:: 3.4
-
+   See :ref:`import-mod-attrs` for module attributes.

 .. data:: EllipsisType

See https://github.com/python/cpython/issues/65959#issuecomment-1093657481. ↩

picnixz · 2024-07-21T15:14:51Z

The change might not be that trivial:

>>> import types
>>> dir(types.ModuleType('a'))
['__doc__', '__loader__', '__name__', '__package__', '__spec__']

So we really have those attributes, and not more I'd say by default. There is also a note saying:

Use importlib.util.module_from_spec to create a new module if you wish to set the various import-controlled attributes.

I think the __file__, __path__ and __cached__ attributes fall under this category. An alternative is to add additional keyword arguments to the ModuleType constructor to manually initialize other attributes instead of calling module_from_spec and then refer to the other section as Eric's did.

terryjreedy · 2025-02-24T03:21:35Z

The issue has been fixed. Possible additional changes elsewhere should be new issues.

ericsnowcurrently assigned docspython Nov 28, 2013

ericsnowcurrently added docs Documentation in the Doc dir type-feature A feature request or enhancement easy labels Nov 28, 2013

ericsnowcurrently added 3.7 (EOL) end of life 3.8 (EOL) end of life 3.9 only security fixes labels Aug 14, 2019

ezio-melotti transferred this issue from another repository Apr 10, 2022

JelleZijlstra mentioned this issue May 8, 2022

bpo-19820: Updated documentation for inspect module: some module attributes were… #15359

Closed

AlexWaygood removed 3.8 (EOL) end of life 3.7 (EOL) end of life labels May 11, 2022

bedevere-bot mentioned this issue Oct 9, 2022

gh-64019: Have attribute table in inspect docs link to module attributes instead of listing them #98116

Merged

AA-Turner added 3.11 only security fixes 3.10 only security fixes 3.12 only security fixes and removed 3.9 only security fixes labels Oct 11, 2022

brettcannon pushed a commit that referenced this issue Nov 25, 2022

gh-64019: Have attribute table in inspect docs link to module attri…

7d2dcc5

…butes instead of listing them (GH-98116) Co-authored-by: Michael Anckaert <michael.anckaert@sinax.be>

bedevere-bot mentioned this issue Nov 25, 2022

[3.10] gh-64019: Have attribute table in inspect docs link to module attributes instead of listing them (GH-98116) #99782

Closed

brettcannon closed this as completed Nov 25, 2022

bedevere-bot mentioned this issue Nov 25, 2022

[3.11] gh-64019: Have attribute table in inspect docs link to module attributes instead of listing them (GH-98116) #99783

Merged

ericsnowcurrently reopened this Jul 18, 2024

ericsnowcurrently mentioned this issue Jul 18, 2024

inspect documentation describes module type inaccurately #65959

Closed

picnixz mentioned this issue Sep 7, 2024

Three inconsistent module attributes #81700

Open

terryjreedy closed this as completed Feb 24, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs are missing info about module attributes #64019

docs are missing info about module attributes #64019

ericsnowcurrently commented Nov 28, 2013 •

edited by bedevere-app bot

Loading

ericsnowcurrently commented Nov 28, 2013

anilbey mannequin commented Jul 14, 2019

MichaelAnckaert mannequin commented Aug 14, 2019

ericsnowcurrently commented Aug 14, 2019

eamanu mannequin commented Aug 14, 2019

MichaelAnckaert mannequin commented Aug 14, 2019

brettcannon commented Nov 25, 2022

ericsnowcurrently commented Jul 18, 2024

picnixz commented Jul 21, 2024 •

edited

Loading

terryjreedy commented Feb 24, 2025

docs are missing info about module attributes #64019

docs are missing info about module attributes #64019

Comments

ericsnowcurrently commented Nov 28, 2013 • edited by bedevere-app bot Loading

Linked PRs

ericsnowcurrently commented Nov 28, 2013

anilbey mannequin commented Jul 14, 2019

MichaelAnckaert mannequin commented Aug 14, 2019

ericsnowcurrently commented Aug 14, 2019

eamanu mannequin commented Aug 14, 2019

MichaelAnckaert mannequin commented Aug 14, 2019

brettcannon commented Nov 25, 2022

ericsnowcurrently commented Jul 18, 2024

Footnotes

picnixz commented Jul 21, 2024 • edited Loading

terryjreedy commented Feb 24, 2025

ericsnowcurrently commented Nov 28, 2013 •

edited by bedevere-app bot

Loading

picnixz commented Jul 21, 2024 •

edited

Loading