[Python-checkins] Clarify attribute docs on types.ModuleType (GH-24974)

miss-islington webhook-mailer at python.org
Tue Mar 23 12:01:31 EDT 2021


https://github.com/python/cpython/commit/10e17bc69332f5dd99a4dfd4cfdf2290022ebc51
commit: 10e17bc69332f5dd99a4dfd4cfdf2290022ebc51
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2021-03-23T09:01:10-07:00
summary:

Clarify attribute docs on types.ModuleType (GH-24974)

(cherry picked from commit 76b5d714e4e2b9f3b63847325cba51d4c4dc36bc)

Co-authored-by: Brett Cannon <brett at python.org>

files:
M Doc/library/types.rst

diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index d83d9667ba3a7..d1099cf2af085 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -209,7 +209,7 @@ Standard names are defined for the following types:
 
 .. class:: ModuleType(name, doc=None)
 
-   The type of :term:`modules <module>`. Constructor takes the name of the
+   The type of :term:`modules <module>`. The constructor takes the name of the
    module to be created and optionally its :term:`docstring`.
 
    .. note::
@@ -224,12 +224,23 @@ Standard names are defined for the following types:
 
       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, preferrably 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.
+      The name of the module. Expected to match
+      :attr:`importlib.machinery.ModuleSpec.name`.
 
    .. attribute:: __package__
 
@@ -238,9 +249,26 @@ Standard names are defined for the following types:
       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, preferrably 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 the module's import-system-related state. Expected to be
+      an instance of :class:`importlib.machinery.ModuleSpec`.
+
+      .. versionadded:: 3.4
+
 
 .. class:: GenericAlias(t_origin, t_args)
 



More information about the Python-checkins mailing list