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>

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
+   The module's :attr:`~module.__spec__` and :attr:`~module.__loader__` will be
-   not set already, with the appropriate values.  The spec's loader will
+   set, if not set already, with the appropriate values.  The spec's loader
-   be set to the module's ``__loader__`` (if set) and to an instance of
+   will be set to the module's :attr:`!__loader__` (if set) and to an instance
-   :class:`~importlib.machinery.SourceFileLoader` otherwise.
+   of :class:`~importlib.machinery.SourceFileLoader` otherwise.
 
-   The module's :attr:`__file__` attribute will be set to the code object's
+   The module's :attr:`~module.__file__` attribute will be set to the code
-   :attr:`~codeobject.co_filename`.  If applicable, :attr:`__cached__` will also
+   object's :attr:`~codeobject.co_filename`.  If applicable,
-   be set.
+   :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
+      The setting of :attr:`~module.__cached__` and :attr:`~module.__loader__`
-      deprecated. See :class:`~importlib.machinery.ModuleSpec` for
+      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
+   Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`~module.__file__`
-   the module object is set to *pathname* if it is non-``NULL``.
+   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*.
+   Return a new module object with :attr:`module.__name__` set to *name*.
-   The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
+   The module's :attr:`!__name__`, :attr:`~module.__doc__`,
-   :attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set
+   :attr:`~module.__package__` and :attr:`~module.__loader__` attributes are
-   to ``None``); the caller is responsible for providing a :attr:`__file__`
+   filled in (all but :attr:`!__name__` are set to ``None``). The caller is
-   attribute.
+   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,
+   Return *module*'s :attr:`~module.__name__` value.  If the module does not
-   or if it is not a string, :exc:`SystemError` is raised and ``NULL`` is returned.
+   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
+   :attr:`~module.__file__` attribute.  If this is not defined, or if it is not a
-   unicode string, raise :exc:`SystemError` and return ``NULL``; otherwise return
+   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
+      :term:`finder`. See also:
-      :class:`importlib.abc.Loader` for an :term:`abstract base class`.
+
+      * :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__`
+        - :attr:`module.__name__`
-            The module's fully qualified name.
+        - :attr:`module.__file__`
-            It is ``'__main__'`` for an executed module.
+        - :attr:`module.__cached__` *(deprecated)*
-
+        - :attr:`module.__path__`
-        - :attr:`__file__`
+        - :attr:`module.__package__` *(deprecated)*
-            The location the :term:`loader` used to load the module.
+        - :attr:`module.__loader__` *(deprecated)*
-            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.
 
         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
+        An abstract method that is to return the value of
-        the specified module. If no path is available, :exc:`ImportError` is
+        :attr:`~module.__file__` for the specified module. If no path is
-        raised.
+        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
+   no synchronization between the two objects.  For example, it is possible to
-   the module's :attr:`__file__` at runtime and this will not be automatically
+   update the module's :attr:`~module.__file__` at runtime and this will not be
-   reflected in the module's :attr:`__spec__.origin`, and vice versa.
+   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
+      The module's fully qualified name (see :attr:`module.__name__`).
-      (see :attr:`__name__` attributes on modules).
       The :term:`finder` should always set this attribute to a non-empty string.
 
    .. attribute:: loader
 
-      The :term:`loader` used to load the module
+      The :term:`loader` used to load the module (see :attr:`module.__loader__`).
-      (see :attr:`__loader__` attributes on modules).
       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).
+      (see :attr:`module.__file__`).
-      For example, for modules loaded from a .py file this is the filename.
+      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
+      A (possibly empty) :term:`sequence` of strings enumerating the locations
-      (see :attr:`__path__` attributes on modules).
+      in which a package's submodules will be found
-      Most of the time this is a single directory.
+      (see :attr:`module.__path__`). Most of the time there will only be a
-      The :term:`finder` should set this attribute to a list, even an empty one, to indicate
+      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
+      ``False`` otherwise.  This value impacts how :attr:`!origin` is interpreted
-      and how the module's :attr:`__file__` is populated.
+      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__`
+      **package** is in fact not a package (i.e. lacks a
-      attribute).
+      :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.
 

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::
+   .. seealso::
-      Use :func:`importlib.util.module_from_spec` to create a new module if you
-      wish to set the various import-controlled attributes.
 
-   .. attribute:: __doc__
+      :ref:`Documentation on module objects <module-objects>`
-
+         Provides details on the special attributes that can be found on
-      The :term:`docstring` of the module. Defaults to ``None``.
+         instances of :class:`!ModuleType`.
-
-   .. 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
 
+      :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
 

Doc/reference/datamodel.rst

@@ -865,6 +865,8 @@ Instances of arbitrary classes can be made callable by defining a
 :meth:`~object.__call__` method in their class.
 
 
+.. _module-objects:
+
 Modules
 -------
 
@@ -890,52 +892,238 @@ Attribute assignment updates the module's namespace dictionary, e.g.,
 
 .. index::
    single: __name__ (module attribute)
-   single: __doc__ (module attribute)
+   single: __spec__ (module attribute)
+   single: __package__ (module attribute)
+   single: __loader__ (module attribute)
+   single: __path__ (module attribute)
    single: __file__ (module attribute)
+   single: __cached__ (module attribute)
+   single: __doc__ (module attribute)
    single: __annotations__ (module attribute)
    single: __annotate__ (module attribute)
    pair: module; namespace
 
-Predefined (writable) attributes:
+.. _import-mod-attrs:
 
-   :attr:`__name__`
+Import-related attributes on module objects
-      The module's name.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-   :attr:`__doc__`
+Module objects have the following attributes that relate to the
-      The module's documentation string, or ``None`` if
+:ref:`import system <importsystem>`. When a module is created using the machinery associated
-      unavailable.
+with the import system, these attributes are filled in based on the module's
+:term:`spec <module spec>`, before the :term:`loader` executes and loads the
+module.
 
-   :attr:`__file__`
+To create a module dynamically rather than using the import system,
-      The pathname of the file from which the
+it's recommended to use :func:`importlib.util.module_from_spec`,
-      module was loaded, if it was loaded from a file.
+which will set the various import-controlled attributes to appropriate values.
-      The :attr:`__file__`
+It's also possible to use the :class:`types.ModuleType` constructor to create
-      attribute may be missing for certain types of modules, such as C modules
+modules directly, but this technique is more error-prone, as most attributes
-      that are statically linked into the interpreter.  For extension modules
+must be manually set on the module object after it has been created when using
-      loaded dynamically from a shared library, it's the pathname of the shared
+this approach.
-      library file.
 
-   :attr:`~object.__annotations__`
+.. caution::
-      A dictionary containing
+
-      :term:`variable annotations <variable annotation>` collected during
+   With the exception of :attr:`~module.__name__`, it is **strongly**
-      module body execution.  For best practices on working
+   recommended that you rely on :attr:`~module.__spec__` and its attributes
-      with :attr:`!__annotations__`, see :mod:`annotationlib`.
+   instead of any of the other individual attributes listed in this subsection.
+   Note that updating an attribute on :attr:`!__spec__` will not update the
+   corresponding attribute on the module itself:
+
+   .. doctest::
+
+     >>> import typing
+     >>> typing.__name__, typing.__spec__.name
+     ('typing', 'typing')
+     >>> typing.__spec__.name = 'spelling'
+     >>> typing.__name__, typing.__spec__.name
+     ('typing', 'spelling')
+     >>> typing.__name__ = 'keyboard_smashing'
+     >>> typing.__name__, typing.__spec__.name
+     ('keyboard_smashing', 'spelling')
+
+.. attribute:: module.__name__
+
+   The name used to uniquely identify the module in the import system.
+   For a directly executed module, this will be set to ``"__main__"``.
+
+   This attribute must be set to the fully qualified name of the module.
+   It is expected to match the value of
+   :attr:`module.__spec__.name <importlib.machinery.ModuleSpec.name>`.
+
+.. attribute:: module.__spec__
+
+   A record of the module's import-system-related state.
+
+   Set to the :class:`module spec <importlib.machinery.ModuleSpec>` that was
+   used when importing the module. See :ref:`module-specs` for more details.
+
+   .. versionadded:: 3.4
+
+.. attribute:: module.__package__
+
+   The :term:`package` a module belongs to.
+
+   If the module is top-level (that is, not a part of any specific package)
+   then the attribute should be set to ``''`` (the empty string). Otherwise,
+   it should be set to the name of the module's package (which can be equal to
+   :attr:`module.__name__` if the module itself is a package). See :pep:`366`
+   for further details.
+
+   This attribute is used instead of :attr:`~module.__name__` to calculate
+   explicit relative imports for main modules. It defaults to ``None`` for
+   modules created dynamically using the :class:`types.ModuleType` constructor;
+   use :func:`importlib.util.module_from_spec` instead to ensure the attribute
+   is set to a :class:`str`.
+
+   It is **strongly** recommended that you use
+   :attr:`module.__spec__.parent <importlib.machinery.ModuleSpec.parent>`
+   instead of :attr:`!module.__package__`. :attr:`__package__` is now only used
+   as a fallback if :attr:`!__spec__.parent` is not set, and this fallback
+   path is deprecated.
+
+   .. versionchanged:: 3.4
+      This attribute now defaults to ``None`` for modules created dynamically
+      using the :class:`types.ModuleType` constructor.
+      Previously the attribute was optional.
+
+   .. versionchanged:: 3.6
+      The value of :attr:`!__package__` is expected to be the same as
+      :attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>`.
+      :attr:`__package__` is now only used as a fallback during import
+      resolution if :attr:`!__spec__.parent` is not defined.
+
+   .. versionchanged:: 3.10
+      :exc:`ImportWarning` is raised if an import resolution falls back to
+      :attr:`!__package__` instead of
+      :attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>`.
+
+   .. versionchanged:: 3.12
+      Raise :exc:`DeprecationWarning` instead of :exc:`ImportWarning` when
+      falling back to :attr:`!__package__` during import resolution.
+
+   .. deprecated-removed:: 3.13 3.15
+      :attr:`!__package__` will cease to be set or taken into consideration
+      by the import system or standard library.
+
+.. attribute:: module.__loader__
+
+   The :term:`loader` object that the import machinery used to load the module.
+
+   This attribute is mostly useful for introspection, but can be used for
+   additional loader-specific functionality, for example getting data
+   associated with a loader.
+
+   :attr:`!__loader__` defaults to ``None`` for modules created dynamically
+   using the :class:`types.ModuleType` constructor;
+   use :func:`importlib.util.module_from_spec` instead to ensure the attribute
+   is set to a :term:`loader` object.
+
+   It is **strongly** recommended that you use
+   :attr:`module.__spec__.loader <importlib.machinery.ModuleSpec.loader>`
+   instead of :attr:`!module.__loader__`.
+
+   .. versionchanged:: 3.4
+      This attribute now defaults to ``None`` for modules created dynamically
+      using the :class:`types.ModuleType` constructor.
+      Previously the attribute was optional.
+
+   .. deprecated-removed:: 3.12 3.14
+      Setting :attr:`!__loader__` on a module while failing to set
+      :attr:`!__spec__.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.
+
+.. attribute:: module.__path__
+
+   A (possibly empty) :term:`sequence` of strings enumerating the locations
+   where the package's submodules will be found. Non-package modules should
+   not have a :attr:`!__path__` attribute. See :ref:`package-path-rules` for
+   more details.
+
+   It is **strongly** recommended that you use
+   :attr:`module.__spec__.submodule_search_locations <importlib.machinery.ModuleSpec.submodule_search_locations>`
+   instead of :attr:`!module.__path__`.
+
+.. attribute:: module.__file__
+.. attribute:: module.__cached__
+
+   :attr:`!__file__` and :attr:`!__cached__` are both optional attributes that
+   may or may not be set. Both attributes should be a :class:`str` when they
+   are available.
+
+   :attr:`!__file__` indicates the pathname of the file from which the module
+   was loaded (if loaded from a file), or the pathname of the shared library
+   file for extension modules loaded dynamically from a shared library.
+   It might be missing for certain types of modules, such as C modules that are
+   statically linked into the interpreter, and the
+   :ref:`import system <importsystem>` may opt to leave it unset if it
+   has no semantic meaning (for example, a module loaded from a database).
+
+   If :attr:`!__file__` is set then the :attr:`!__cached__` attribute might
+   also be set,  which is the path to any compiled version of
+   the code (for example, a byte-compiled file). The file does not need to exist
+   to set this attribute; the path can simply point to where the
+   compiled file *would* exist (see :pep:`3147`).
+
+   Note that :attr:`!__cached__` may be set even if :attr:`!__file__` is not
+   set.  However, that scenario is quite atypical.  Ultimately, the
+   :term:`loader` is what makes use of the module spec provided by the
+   :term:`finder` (from which :attr:`!__file__` and :attr:`!__cached__` are
+   derived).  So if a loader can load from a cached module but otherwise does
+   not load from a file, that atypical scenario may be appropriate.
+
+   It is **strongly** recommended that you use
+   :attr:`module.__spec__.cached <importlib.machinery.ModuleSpec.cached>`
+   instead of :attr:`!module.__cached__`.
+
+   .. deprecated-removed:: 3.13 3.15
+      Setting :attr:`!__cached__` on a module while failing to set
+      :attr:`!__spec__.cached` is deprecated. In Python 3.15,
+      :attr:`!__cached__` will cease to be set or taken into consideration by
+      the import system or standard library.
+
+Other writable attributes on module objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As well as the import-related attributes listed above, module objects also have
+the following writable attributes:
+
+.. attribute:: module.__doc__
+
+   The module's documentation string, or ``None`` if unavailable.
+   See also: :attr:`__doc__ attributes <definition.__doc__>`.
+
+.. attribute:: module.__annotations__
+
+   A dictionary containing :term:`variable annotations <variable annotation>`
+   collected during module body execution.  For best practices on working with
+   :attr:`!__annotations__`, see :mod:`annotationlib`.
 
    .. versionchanged:: 3.14
       Annotations are now :ref:`lazily evaluated <lazy-evaluation>`.
       See :pep:`649`.
 
-   :attr:`~object.__annotate__`
+.. attribute:: module.__annotate__
-      The :term:`annotate function` for this module, or ``None``
+
-      if the module has no annotations. See :attr:`object.__annotate__`.
+   The :term:`annotate function` for this module, or ``None`` if the module has
+   no annotations. See also: :attr:`~object.__annotate__` attributes.
 
    .. versionadded:: 3.14
 
+Module dictionaries
+^^^^^^^^^^^^^^^^^^^
+
+Module objects also have the following special read-only attribute:
+
 .. index:: single: __dict__ (module attribute)
+.. attribute:: module.__dict__
 
-Special read-only attribute: :attr:`~object.__dict__` is the module's
+   The module's namespace as a dictionary object. Uniquely among the attributes
-namespace as a dictionary object.
+   listed here, :attr:`!__dict__` cannot be accessed as a global variable from
+   within a module; it can only be accessed as an attribute on module objects.
 
-.. impl-detail::
+   .. impl-detail::
 
       Because of the way CPython clears module dictionaries, the module
       dictionary will be cleared when the module falls out of scope even if the

Doc/reference/import.rst

@@ -513,8 +513,10 @@ holding is that if you have ``sys.modules['spam']`` and
 ``sys.modules['spam.foo']`` (as you would after the above import), the latter
 must appear as the ``foo`` attribute of the former.
 
-Module spec
+.. _module-specs:
------------
+
+Module specs
+------------
 
 The import machinery uses a variety of information about each module
 during import, especially before loading.  Most of the information is
@@ -527,163 +529,44 @@ and the loader that executes it.  Most importantly, it allows the
 import machinery to perform the boilerplate operations of loading,
 whereas without a module spec the loader had that responsibility.
 
-The module's spec is exposed as the ``__spec__`` attribute on a module object.
+The module's spec is exposed as :attr:`module.__spec__`. Setting
+:attr:`!__spec__` appropriately applies equally to
+:ref:`modules initialized during interpreter startup <programs>`.
+The one exception is ``__main__``, where :attr:`!__spec__` is
+:ref:`set to None in some cases <main_spec>`.
+
 See :class:`~importlib.machinery.ModuleSpec` for details on the contents of
 the module spec.
 
 .. versionadded:: 3.4
 
-.. _import-mod-attrs:
-
-Import-related module attributes
---------------------------------
-
-The import machinery fills in these attributes on each module object
-during loading, based on the module's spec, before the loader executes
-the module.
-
-It is **strongly** recommended that you rely on :attr:`__spec__` and
-its attributes instead of any of the other individual attributes
-listed below, except :attr:`__name__`.
-
-.. attribute:: __name__
-
-   The ``__name__`` attribute must be set to the fully qualified name of
-   the module.  This name is used to uniquely identify the module in
-   the import system.
-
-.. attribute:: __loader__
-
-   The ``__loader__`` attribute must be set to the loader object that
-   the import machinery used when loading the module.  This is mostly
-   for introspection, but can be used for additional loader-specific
-   functionality, for example getting data associated with a loader.
-
-   It is **strongly** recommended that you rely on :attr:`__spec__`
-   instead of this attribute.
-
-   .. versionchanged:: 3.12
-      The value of ``__loader__`` is expected to be the same as
-      ``__spec__.loader``.  The use of ``__loader__`` is deprecated and slated
-      for removal in Python 3.14.
-
-.. attribute:: __package__
-
-   The module's ``__package__`` attribute may be set.  Its value must
-   be a string, but it can be the same value as its ``__name__``.  When
-   the module is a package, its ``__package__`` value should be set to
-   its ``__name__``.  When the module is not a package, ``__package__``
-   should be set to the empty string for top-level modules, or for
-   submodules, to the parent package's name.  See :pep:`366` for further
-   details.
-
-   This attribute is used instead of ``__name__`` to calculate explicit
-   relative imports for main modules, as defined in :pep:`366`.
-
-   It is **strongly** recommended that you rely on :attr:`__spec__`
-   instead of this attribute.
-
-   .. versionchanged:: 3.6
-      The value of ``__package__`` is expected to be the same as
-      ``__spec__.parent``.
-
-   .. versionchanged:: 3.10
-      :exc:`ImportWarning` is raised if import falls back to
-      ``__package__`` instead of
-      :attr:`~importlib.machinery.ModuleSpec.parent`.
-
-   .. versionchanged:: 3.12
-      Raise :exc:`DeprecationWarning` instead of :exc:`ImportWarning`
-      when falling back to ``__package__``.
-
-   .. deprecated-removed:: 3.13 3.15
-      ``__package__`` will cease to be set or taken into consideration
-      by the import system or standard library.
-
-
-.. attribute:: __spec__
-
-   The ``__spec__`` attribute must be set to the module spec that was
-   used when importing the module. Setting ``__spec__``
-   appropriately applies equally to :ref:`modules initialized during
-   interpreter startup <programs>`.  The one exception is ``__main__``,
-   where ``__spec__`` is :ref:`set to None in some cases <main_spec>`.
-
-   When ``__spec__.parent`` is not set, ``__package__`` is used as
-   a fallback.
-
-   .. versionadded:: 3.4
-
-   .. versionchanged:: 3.6
-      ``__spec__.parent`` is used as a fallback when ``__package__`` is
-      not defined.
-
-.. attribute:: __path__
-
-   If the module is a package (either regular or namespace), the module
-   object's ``__path__`` attribute must be set.  The value must be
-   iterable, but may be empty if ``__path__`` has no further significance.
-   If ``__path__`` is not empty, it must produce strings when iterated
-   over. More details on the semantics of ``__path__`` are given
-   :ref:`below <package-path-rules>`.
-
-   Non-package modules should not have a ``__path__`` attribute.
-
-.. attribute:: __file__
-.. attribute:: __cached__
-
-   ``__file__`` is optional (if set, value must be a string). It indicates
-   the pathname of the file from which the module was loaded (if
-   loaded from a file), or the pathname of the shared library file
-   for extension modules loaded dynamically from a shared library.
-   It might be missing for certain types of modules, such as C
-   modules that are statically linked into the interpreter, and the
-   import system may opt to leave it unset if it has no semantic
-   meaning (e.g. a module loaded from a database).
-
-   If ``__file__`` is set then the ``__cached__`` attribute might also
-   be set,  which is the path to any compiled version of
-   the code (e.g. byte-compiled file). The file does not need to exist
-   to set this attribute; the path can simply point to where the
-   compiled file would exist (see :pep:`3147`).
-
-   Note that ``__cached__`` may be set even if ``__file__`` is not
-   set.  However, that scenario is quite atypical.  Ultimately, the
-   loader is what makes use of the module spec provided by the finder
-   (from which ``__file__`` and ``__cached__`` are derived).  So
-   if a loader can load from a cached module but otherwise does not load
-   from a file, that atypical scenario may be appropriate.
-
-   It is **strongly** recommended that you rely on :attr:`__spec__`
-   instead of ``__cached__``.
-
-   .. deprecated-removed:: 3.13 3.15
-      ``__cached__`` will cease to be set or taken into consideration
-      by the import system or standard library.
-
 .. _package-path-rules:
 
-module.__path__
+__path__ attributes on modules
----------------
+------------------------------
 
-By definition, if a module has a ``__path__`` attribute, it is a package.
+The :attr:`~module.__path__` attribute should be a (possibly empty)
+:term:`sequence` of strings enumerating the locations where the package's
+submodules will be found. By definition, if a module has a :attr:`!__path__`
+attribute, it is a :term:`package`.
 
-A package's ``__path__`` attribute is used during imports of its subpackages.
+A package's :attr:`~module.__path__` attribute is used during imports of its
+subpackages.
 Within the import machinery, it functions much the same as :data:`sys.path`,
 i.e. providing a list of locations to search for modules during import.
-However, ``__path__`` is typically much more constrained than
+However, :attr:`!__path__` is typically much more constrained than
-:data:`sys.path`.
+:data:`!sys.path`.
 
-``__path__`` must be an iterable of strings, but it may be empty.
 The same rules used for :data:`sys.path` also apply to a package's
-``__path__``, and :data:`sys.path_hooks` (described below) are
+:attr:`!__path__`. :data:`sys.path_hooks` (described below) are
-consulted when traversing a package's ``__path__``.
+consulted when traversing a package's :attr:`!__path__`.
 
-A package's ``__init__.py`` file may set or alter the package's ``__path__``
+A package's ``__init__.py`` file may set or alter the package's
+:attr:`~module.__path__`
 attribute, and this was typically the way namespace packages were implemented
 prior to :pep:`420`.  With the adoption of :pep:`420`, namespace packages no
-longer need to supply ``__init__.py`` files containing only ``__path__``
+longer need to supply ``__init__.py`` files containing only :attr:`!__path__`
-manipulation code; the import machinery automatically sets ``__path__``
+manipulation code; the import machinery automatically sets :attr:`!__path__`
 correctly for the namespace package.
 
 Module reprs

Doc/tutorial/modules.rst

@@ -585,8 +585,9 @@ as the main module of a Python application must always use absolute imports.
 Packages in Multiple Directories
 --------------------------------
 
-Packages support one more special attribute, :attr:`__path__`.  This is
+Packages support one more special attribute, :attr:`~module.__path__`.  This is
-initialized to be a list containing the name of the directory holding the
+initialized to be a :term:`sequence` of strings containing the name of the
+directory holding the
 package's :file:`__init__.py` before the code in that file is executed.  This
 variable can be modified; doing so affects future searches for modules and
 subpackages contained in the package.

Doc/whatsnew/2.6.rst

@@ -502,12 +502,12 @@ Python's :option:`-m` switch allows running a module as a script.
 When you ran a module that was located inside a package, relative
 imports didn't work correctly.
 
-The fix for Python 2.6 adds a :attr:`__package__` attribute to
+The fix for Python 2.6 adds a :attr:`module.__package__` attribute.
-modules.  When this attribute is present, relative imports will be
+When this attribute is present, relative imports will be
 relative to the value of this attribute instead of the
-:attr:`__name__` attribute.
+:attr:`~module.__name__` attribute.
 
-PEP 302-style importers can then set :attr:`__package__` as necessary.
+PEP 302-style importers can then set :attr:`~module.__package__` as necessary.
 The :mod:`runpy` module that implements the :option:`-m` switch now
 does this, so relative imports will now work correctly in scripts
 running from inside a package.

Doc/whatsnew/3.0.rst

@@ -357,8 +357,8 @@ New Syntax
   provides a standardized way of annotating a function's parameters
   and return value.  There are no semantics attached to such
   annotations except that they can be introspected at runtime using
-  the :attr:`__annotations__` attribute.  The intent is to encourage
+  the :attr:`~object.__annotations__` attribute.  The intent is to
-  experimentation through metaclasses, decorators or frameworks.
+  encourage experimentation through metaclasses, decorators or frameworks.
 
 * :pep:`3102`: Keyword-only arguments.  Named parameters occurring
   after ``*args`` in the parameter list *must* be specified using

Doc/whatsnew/3.12.rst

@@ -1309,14 +1309,15 @@ Deprecated
   may be removed in a future version of Python. Use the single-arg versions
   of these functions instead. (Contributed by Ofey Chan in :gh:`89874`.)
 
-* :exc:`DeprecationWarning` is now raised when ``__package__`` on a
+* :exc:`DeprecationWarning` is now raised when :attr:`~module.__package__` on a
-  module differs from ``__spec__.parent`` (previously it was
+  module differs from
-  :exc:`ImportWarning`).
+  :attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>` (previously
+  it was :exc:`ImportWarning`).
   (Contributed by Brett Cannon in :gh:`65961`.)
 
-* Setting ``__package__`` or ``__cached__`` on a module is deprecated,
+* Setting :attr:`~module.__package__` or :attr:`~module.__cached__` on a
-  and will cease to be set or taken into consideration by the import system in Python 3.14.
+  module is deprecated, and will cease to be set or taken into consideration by
-  (Contributed by Brett Cannon in :gh:`65961`.)
+  the import system in Python 3.14. (Contributed by Brett Cannon in :gh:`65961`.)
 
 * The bitwise inversion operator (``~``) on bool is deprecated. It will throw an
   error in Python 3.16. Use ``not`` for logical negation of bools instead.

Doc/whatsnew/3.2.rst

@@ -312,8 +312,8 @@ cluttering source directories, the *pyc* files are now collected in a
 Aside from the filenames and target directories, the new scheme has a few
 aspects that are visible to the programmer:
 
-* Imported modules now have a :attr:`__cached__` attribute which stores the name
+* Imported modules now have a :attr:`~module.__cached__` attribute which stores
-  of the actual file that was imported:
+  the name of the actual file that was imported:
 
    >>> import collections
    >>> collections.__cached__ # doctest: +SKIP

Doc/whatsnew/3.4.rst

@@ -2271,7 +2271,8 @@ Changes in the Python API
   :func:`super` and falling through all the way to the ABCs. For compatibility,
   catch both :exc:`NotImplementedError` or the appropriate exception as needed.
 
-* The module type now initializes the :attr:`__package__` and :attr:`__loader__`
+* The module type now initializes the :attr:`~module.__package__` and
+  :attr:`~module.__loader__`
   attributes to ``None`` by default. To determine if these attributes were set
   in a backwards-compatible fashion, use e.g.
   ``getattr(module, '__loader__', None) is not None``.  (:issue:`17115`.)

Doc/whatsnew/3.5.rst

@@ -423,8 +423,8 @@ are declared in the annotations::
         return 'Hello ' + name
 
 While these annotations are available at runtime through the usual
-:attr:`__annotations__` attribute, *no automatic type checking happens at
+:attr:`~object.__annotations__` attribute, *no automatic type checking happens
-runtime*.  Instead, it is assumed that a separate off-line type checker
+at runtime*.  Instead, it is assumed that a separate off-line type checker
 (e.g. `mypy <https://mypy-lang.org>`_) will be used for on-demand
 source code analysis.
 

Misc/NEWS.d/3.10.0a2.rst

@@ -226,8 +226,8 @@ thread at the time the function is called.
 .. section: Core and Builtins
 
 Enable ``from __future__ import annotations`` (:pep:`563`) by default. The
-values found in :attr:`__annotations__` dicts are now strings, e.g. ``{"x":
+values found in :attr:`~object.__annotations__` dicts are now strings, for
-"int"}`` instead of ``{"x": int}``.
+example ``{"x": "int"}`` instead of ``{"x": int}``.
 
 ..
 

Misc/NEWS.d/3.11.0a5.rst

@@ -486,8 +486,8 @@ Use ``dis.Positions`` in ``dis.Instruction`` instead of a regular ``tuple``.
 .. nonce: geS-aP
 .. section: Library
 
-:mod:`pdb` now gracefully handles ``help`` when :attr:`__doc__` is missing,
+:mod:`pdb` now gracefully handles ``help`` when :attr:`~module.__doc__` is
-for example when run with pregenerated optimized ``.pyc`` files.
+missing, for example when run with pregenerated optimized ``.pyc`` files.
 
 ..
 

Misc/NEWS.d/3.12.0a1.rst

@@ -4237,8 +4237,8 @@ by :mod:`asyncio` to AIX platform only.
 .. nonce: 4dzB80
 .. section: Library
 
-Set :attr:`doctest.DocTest.lineno` to ``None`` when object does not have
+Set :attr:`doctest.DocTest.lineno` to ``None`` when an object does not have
-:attr:`__doc__`.
+:attr:`~definition.__doc__`.
 
 ..
 

Misc/NEWS.d/next/Core and Builtins/2024-05-31-08-23-41.gh-issue-119180.KL4VxZ.rst

@@ -1,3 +1,3 @@
 :func:`classmethod` and :func:`staticmethod` now wrap the
-:attr:`__annotations__` and :attr:`!__annotate__` attributes of their
+:attr:`~object.__annotations__` and :attr:`~object.__annotate__` attributes of
-underlying callable lazily. See :pep:`649`. Patch by Jelle Zijlstra.
+their underlying callable lazily. See :pep:`649`. Patch by Jelle Zijlstra.