gh-101100: Consolidate documentation on `ModuleType` attributes (#124709)

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Barry Warsaw <barry@python.org>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

5 files changed, 49 insertions, 111 deletions

diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
index a951885..3d2df03 100644
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@@ -902,7 +902,7 @@ Statements
    (indicating a "simple" target). A "simple" target consists solely of a
    :class:`Name` node that does not appear between parentheses; all other
    targets are considered complex. Only simple targets appear in
-   the :attr:`__annotations__` dictionary of modules and classes.
+   the :attr:`~object.__annotations__` dictionary of modules and classes.
 
    .. doctest::
 
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index 27d31f6..9e088a5 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -249,7 +249,7 @@ ABC hierarchy::
       An abstract method for finding a :term:`spec <module spec>` for
       the specified module.  If this is a top-level import, *path* will
       be ``None``.  Otherwise, this is a search for a subpackage or
-      module and *path* will be the value of :attr:`__path__` from the
+      module and *path* will be the value of :attr:`~module.__path__` from the
       parent package. If a spec cannot be found, ``None`` is returned.
       When passed in, ``target`` is a module object that the finder may
       use to make a more educated guess about what spec to return.
@@ -355,34 +355,12 @@ ABC hierarchy::
         (note that some of these attributes can change when a module is
         reloaded):
 
-        - :attr:`__name__`
-            The module's fully qualified name.
-            It is ``'__main__'`` for an executed module.
-
-        - :attr:`__file__`
-            The location the :term:`loader` used to load the module.
-            For example, for modules loaded from a .py file this is the filename.
-            It is not set on all modules (e.g. built-in modules).
-
-        - :attr:`__cached__`
-            The filename of a compiled version of the module's code.
-            It is not set on all modules (e.g. built-in modules).
-
-        - :attr:`__path__`
-            The list of locations where the package's submodules will be found.
-            Most of the time this is a single directory.
-            The import system passes this attribute to ``__import__()`` and to finders
-            in the same way as :data:`sys.path` but just for the package.
-            It is not set on non-package modules so it can be used
-            as an indicator that the module is a package.
-
-        - :attr:`__package__`
-            The fully qualified name of the package the module is in (or the
-            empty string for a top-level module).
-            If the module is a package then this is the same as :attr:`__name__`.
-
-        - :attr:`__loader__`
-            The :term:`loader` used to load the module.
+        - :attr:`module.__name__`
+        - :attr:`module.__file__`
+        - :attr:`module.__cached__` *(deprecated)*
+        - :attr:`module.__path__`
+        - :attr:`module.__package__` *(deprecated)*
+        - :attr:`module.__loader__` *(deprecated)*
 
         When :meth:`exec_module` is available then backwards-compatible
         functionality is provided.
@@ -418,7 +396,8 @@ ABC hierarchy::
         can implement this abstract method to give direct access
         to the data stored. :exc:`OSError` is to be raised if the *path* cannot
         be found. The *path* is expected to be constructed using a module's
-        :attr:`__file__` attribute or an item from a package's :attr:`__path__`.
+        :attr:`~module.__file__` attribute or an item from a package's
+        :attr:`~module.__path__`.
 
         .. versionchanged:: 3.4
            Raises :exc:`OSError` instead of :exc:`NotImplementedError`.
@@ -505,9 +484,9 @@ ABC hierarchy::
 
     .. abstractmethod:: get_filename(fullname)
 
-        An abstract method that is to return the value of :attr:`__file__` for
-        the specified module. If no path is available, :exc:`ImportError` is
-        raised.
+        An abstract method that is to return the value of
+        :attr:`~module.__file__` for the specified module. If no path is
+        available, :exc:`ImportError` is raised.
 
         If source code is available, then the method should return the path to
         the source file, regardless of whether a bytecode was used to load the
@@ -1166,43 +1145,45 @@ find and load modules.
 .. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)
 
    A specification for a module's import-system-related state.  This is
-   typically exposed as the module's :attr:`__spec__` attribute.  Many
+   typically exposed as the module's :attr:`~module.__spec__` attribute.  Many
    of these attributes are also available directly on a module: for example,
    ``module.__spec__.origin == module.__file__``.  Note, however, that
    while the *values* are usually equivalent, they can differ since there is
-   no synchronization between the two objects.  For example, it is possible to update
-   the module's :attr:`__file__` at runtime and this will not be automatically
-   reflected in the module's :attr:`__spec__.origin`, and vice versa.
+   no synchronization between the two objects.  For example, it is possible to
+   update the module's :attr:`~module.__file__` at runtime and this will not be
+   automatically reflected in the module's
+   :attr:`__spec__.origin <ModuleSpec.origin>`, and vice versa.
 
    .. versionadded:: 3.4
 
    .. attribute:: name
 
-      The module's fully qualified name
-      (see :attr:`__name__` attributes on modules).
+      The module's fully qualified name (see :attr:`module.__name__`).
       The :term:`finder` should always set this attribute to a non-empty string.
 
    .. attribute:: loader
 
-      The :term:`loader` used to load the module
-      (see :attr:`__loader__` attributes on modules).
+      The :term:`loader` used to load the module (see :attr:`module.__loader__`).
       The :term:`finder` should always set this attribute.
 
    .. attribute:: origin
 
       The location the :term:`loader` should use to load the module
-      (see :attr:`__file__` attributes on modules).
-      For example, for modules loaded from a .py file this is the filename.
+      (see :attr:`module.__file__`).
+      For example, for modules loaded from a ``.py`` file this is the filename.
       The :term:`finder` should always set this attribute to a meaningful value
       for the :term:`loader` to use.  In the uncommon case that there is not one
       (like for namespace packages), it should be set to ``None``.
 
    .. attribute:: submodule_search_locations
 
-      The list of locations where the package's submodules will be found
-      (see :attr:`__path__` attributes on modules).
-      Most of the time this is a single directory.
-      The :term:`finder` should set this attribute to a list, even an empty one, to indicate
+      A (possibly empty) :term:`sequence` of strings enumerating the locations
+      in which a package's submodules will be found
+      (see :attr:`module.__path__`). Most of the time there will only be a
+      single directory in this list.
+
+      The :term:`finder` should set this attribute to a sequence, even an empty
+      one, to indicate
       to the import system that the module is a package.  It should be set to ``None`` for
       non-package modules.  It is set automatically later to a special object for
       namespace packages.
@@ -1216,7 +1197,7 @@ find and load modules.
    .. attribute:: cached
 
       The filename of a compiled version of the module's code
-      (see :attr:`__cached__` attributes on modules).
+      (see :attr:`module.__cached__`).
       The :term:`finder` should always set this attribute but it may be ``None``
       for modules that do not need compiled code stored.
 
@@ -1224,14 +1205,14 @@ find and load modules.
 
       (Read-only) The fully qualified name of the package the module is in (or the
       empty string for a top-level module).
-      See :attr:`__package__` attributes on modules.
+      See :attr:`module.__package__`.
       If the module is a package then this is the same as :attr:`name`.
 
    .. attribute:: has_location
 
       ``True`` if the spec's :attr:`origin` refers to a loadable location,
-      ``False`` otherwise.  This value impacts how :attr:`origin` is interpreted
-      and how the module's :attr:`__file__` is populated.
+      ``False`` otherwise.  This value impacts how :attr:`!origin` is interpreted
+      and how the module's :attr:`~module.__file__` is populated.
 
 
 .. class:: AppleFrameworkLoader(name, path)
@@ -1416,8 +1397,8 @@ an :term:`importer`.
 
    .. versionchanged:: 3.7
       Raises :exc:`ModuleNotFoundError` instead of :exc:`AttributeError` if
-      **package** is in fact not a package (i.e. lacks a :attr:`__path__`
-      attribute).
+      **package** is in fact not a package (i.e. lacks a
+      :attr:`~module.__path__` attribute).
 
 .. function:: module_from_spec(spec)
 
diff --git a/Doc/library/pkgutil.rst b/Doc/library/pkgutil.rst
index f095cc8..4a39d53 100644
--- a/Doc/library/pkgutil.rst
+++ b/Doc/library/pkgutil.rst
@@ -26,7 +26,8 @@ support.
       __path__ = extend_path(__path__, __name__)
 
    For each directory on :data:`sys.path` that has a subdirectory that matches the
-   package name, add the subdirectory to the package's :attr:`__path__`.  This is useful
+   package name, add the subdirectory to the package's
+   :attr:`~module.__path__`. This is useful
    if one wants to distribute different parts of a single logical package as multiple
    directories.
 
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index b0e40a4..20a06a1 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -1274,7 +1274,8 @@ always available.
     that implement Python's default import semantics. The
     :meth:`~importlib.abc.MetaPathFinder.find_spec` method is called with at
     least the absolute name of the module being imported. If the module to be
-    imported is contained in a package, then the parent package's :attr:`__path__`
+    imported is contained in a package, then the parent package's
+    :attr:`~module.__path__`
     attribute is passed in as a second argument. The method returns a
     :term:`module spec`, or ``None`` if the module cannot be found.
 
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index 84b80ec..439e119 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -260,63 +260,18 @@ 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`.
+   .. seealso::
 
-      .. versionadded:: 3.4
+      :ref:`Documentation on module objects <module-objects>`
+         Provides details on the special attributes that can be found on
+         instances of :class:`!ModuleType`.
 
+      :func:`importlib.util.module_from_spec`
+         Modules created using the :class:`!ModuleType` constructor are
+         created with many of their special attributes unset or set to default
+         values. :func:`!module_from_spec` provides a more robust way of
+         creating :class:`!ModuleType` instances which ensures the various
+         attributes are set appropriately.
 
 .. data:: EllipsisType