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

Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: Barry Warsaw <[email protected]>
Co-authored-by: Jelle Zijlstra <[email protected]>

Author: 4 people

Doc/c-api/import.rst

@@ -136,14 +136,14 @@ Importing Modules
    such modules have no way to know that the module object is an unknown (and
    probably damaged with respect to the module author's intents) state.
 
-   The module's :attr:`__spec__` and :attr:`__loader__` will be set, if
-   not set already, with the appropriate values.  The spec's loader will
-   be set to the module's ``__loader__`` (if set) and to an instance of
-   :class:`~importlib.machinery.SourceFileLoader` otherwise.
+   The module's :attr:`~module.__spec__` and :attr:`~module.__loader__` will be
+   set, if not set already, with the appropriate values.  The spec's loader
+   will be set to the module's :attr:`!__loader__` (if set) and to an instance
+   of :class:`~importlib.machinery.SourceFileLoader` otherwise.
 
-   The module's :attr:`__file__` attribute will be set to the code object's
-   :attr:`~codeobject.co_filename`.  If applicable, :attr:`__cached__` will also
-   be set.
+   The module's :attr:`~module.__file__` attribute will be set to the code
+   object's :attr:`~codeobject.co_filename`.  If applicable,
+   :attr:`~module.__cached__` will also be set.
 
    This function will reload the module if it was already imported.  See
    :c:func:`PyImport_ReloadModule` for the intended way to reload a module.
@@ -155,29 +155,29 @@ Importing Modules
    :c:func:`PyImport_ExecCodeModuleWithPathnames`.
 
    .. versionchanged:: 3.12
-      The setting of :attr:`__cached__` and :attr:`__loader__` is
-      deprecated. See :class:`~importlib.machinery.ModuleSpec` for
+      The setting of :attr:`~module.__cached__` and :attr:`~module.__loader__`
+      is deprecated. See :class:`~importlib.machinery.ModuleSpec` for
       alternatives.
 
 
 .. c:function:: PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
 
-   Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of
-   the module object is set to *pathname* if it is non-``NULL``.
+   Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`~module.__file__`
+   attribute of the module object is set to *pathname* if it is non-``NULL``.
 
    See also :c:func:`PyImport_ExecCodeModuleWithPathnames`.
 
 
 .. c:function:: PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
 
-   Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__`
+   Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`~module.__cached__`
    attribute of the module object is set to *cpathname* if it is
    non-``NULL``.  Of the three functions, this is the preferred one to use.
 
    .. versionadded:: 3.3
 
    .. versionchanged:: 3.12
-      Setting :attr:`__cached__` is deprecated. See
+      Setting :attr:`~module.__cached__` is deprecated. See
       :class:`~importlib.machinery.ModuleSpec` for alternatives.
 
 

Doc/c-api/module.rst

@@ -37,18 +37,19 @@ Module Objects
       single: __package__ (module attribute)
       single: __loader__ (module attribute)
 
-   Return a new module object with the :attr:`__name__` attribute set to *name*.
-   The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
-   :attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set
-   to ``None``); the caller is responsible for providing a :attr:`__file__`
-   attribute.
+   Return a new module object with :attr:`module.__name__` set to *name*.
+   The module's :attr:`!__name__`, :attr:`~module.__doc__`,
+   :attr:`~module.__package__` and :attr:`~module.__loader__` attributes are
+   filled in (all but :attr:`!__name__` are set to ``None``). The caller is
+   responsible for setting a :attr:`~module.__file__` attribute.
 
    Return ``NULL`` with an exception set on error.
 
    .. versionadded:: 3.3
 
    .. versionchanged:: 3.4
-      :attr:`__package__` and :attr:`__loader__` are set to ``None``.
+      :attr:`~module.__package__` and :attr:`~module.__loader__` are now set to
+      ``None``.
 
 
 .. c:function:: PyObject* PyModule_New(const char *name)
@@ -77,8 +78,9 @@ Module Objects
       single: __name__ (module attribute)
       single: SystemError (built-in exception)
 
-   Return *module*'s :attr:`__name__` value.  If the module does not provide one,
-   or if it is not a string, :exc:`SystemError` is raised and ``NULL`` is returned.
+   Return *module*'s :attr:`~module.__name__` value.  If the module does not
+   provide one, or if it is not a string, :exc:`SystemError` is raised and
+   ``NULL`` is returned.
 
    .. versionadded:: 3.3
 
@@ -108,8 +110,8 @@ Module Objects
       single: SystemError (built-in exception)
 
    Return the name of the file from which *module* was loaded using *module*'s
-   :attr:`__file__` attribute.  If this is not defined, or if it is not a
-   unicode string, raise :exc:`SystemError` and return ``NULL``; otherwise return
+   :attr:`~module.__file__` attribute.  If this is not defined, or if it is not a
+   string, raise :exc:`SystemError` and return ``NULL``; otherwise return
    a reference to a Unicode object.
 
    .. versionadded:: 3.2

Doc/deprecations/pending-removal-in-3.14.rst

@@ -1,6 +1,13 @@
 Pending Removal in Python 3.14
 ------------------------------
 
+* The import system:
+
+  * Setting :attr:`~module.__loader__` on a module while
+    failing to set :attr:`__spec__.loader <importlib.machinery.ModuleSpec.loader>`
+    is deprecated. In Python 3.14, :attr:`!__loader__` will cease to be set or
+    taken into consideration by the import system or the standard library.
+
 * :mod:`argparse`: The *type*, *choices*, and *metavar* parameters
   of :class:`!argparse.BooleanOptionalAction` are deprecated
   and will be removed in 3.14.

Doc/deprecations/pending-removal-in-3.15.rst

@@ -1,6 +1,18 @@
 Pending Removal in Python 3.15
 ------------------------------
 
+* The import system:
+
+  * Setting :attr:`~module.__cached__` on a module while
+    failing to set :attr:`__spec__.cached <importlib.machinery.ModuleSpec.cached>`
+    is deprecated. In Python 3.15, :attr:`!__cached__` will cease to be set or
+    take into consideration by the import system or standard library. (:gh:`97879`)
+
+  * Setting :attr:`~module.__package__` on a module while
+    failing to set :attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>`
+    is deprecated. In Python 3.15, :attr:`!__package__` will cease to be set or
+    take into consideration by the import system or standard library. (:gh:`97879`)
+
 * :mod:`ctypes`:
 
   * The undocumented :func:`!ctypes.SetPointerType` function
@@ -17,9 +29,6 @@ Pending Removal in Python 3.15
   * The :option:`!--cgi` flag to the :program:`python -m http.server`
     command-line interface has been deprecated since Python 3.13.
 
-* :mod:`importlib`: ``__package__`` and ``__cached__`` will cease to be set or
-  taken into consideration by the import system (:gh:`97879`).
-
 * :class:`locale`:
 
   * The :func:`~locale.getdefaultlocale` function

Doc/glossary.rst

@@ -461,7 +461,7 @@ Glossary
       <meta path finder>` for use with :data:`sys.meta_path`, and :term:`path
       entry finders <path entry finder>` for use with :data:`sys.path_hooks`.
 
-      See :ref:`importsystem` and :mod:`importlib` for much more detail.
+      See :ref:`finders-and-loaders` and :mod:`importlib` for much more detail.
 
    floor division
       Mathematical division that rounds down to nearest integer.  The floor
@@ -791,8 +791,11 @@ Glossary
    loader
       An object that loads a module. It must define a method named
       :meth:`load_module`. A loader is typically returned by a
-      :term:`finder`. See :pep:`302` for details and
-      :class:`importlib.abc.Loader` for an :term:`abstract base class`.
+      :term:`finder`. See also:
+
+      * :ref:`finders-and-loaders`
+      * :class:`importlib.abc.Loader`
+      * :pep:`302`
 
    locale encoding
       On Unix, it is the encoding of the LC_CTYPE locale. It can be set with
@@ -862,6 +865,8 @@ Glossary
       A namespace containing the import-related information used to load a
       module. An instance of :class:`importlib.machinery.ModuleSpec`.
 
+      See also :ref:`module-specs`.
+
    MRO
       See :term:`method resolution order`.
 

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::
 

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,22 +1197,22 @@ 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.
 
    .. attribute:: parent
 
       (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)
 

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.
 

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.