[3.12] pythongh-101100: Consolidate documentation on ModuleType att…

…ributes (python#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>

(cherry-picked from commit 3024b16)

Doc/c-api/import.rst

@@ -120,14 +120,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.
@@ -139,29 +139,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/glossary.rst

@@ -437,7 +437,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
@@ -750,8 +750,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
@@ -821,6 +824,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

@@ -889,7 +889,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__`
+ - :attr:`module.__path__`
+ - :attr:`module.__package__`
+ - :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.
 
 
 :mod:`importlib.util` -- Utility code for importers
@@ -1353,8 +1334,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

@@ -1239,7 +1239,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.