From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Tue, 17 Oct 2017 19:59:21 +0000 (-0700)
Subject: [3.6] bpo-31799: Make module.__spec__ more discoverable (GH-4010) (#4021)
X-Git-Tag: v3.6.4rc1~159
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=858ea4354fafa36e57859d2dfd70f8a057984075;p=python

[3.6] bpo-31799: Make module.__spec__ more discoverable (GH-4010) (#4021)

bpo-31799: Make module.__spec__ more discoverable
(cherry picked from commit 191e3138200906e43cba9347177914325b54843f)
---

diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index 6406e306c4..d194362fb0 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -1045,7 +1045,15 @@ 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.
+   A specification for a module's import-system-related state.  This is
+   typically exposed as the module's ``__spec__`` attribute.  In the
+   descriptions below, the names in parentheses give the corresponding
+   attribute available directly on the module object.
+   E.g. ``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.  Thus it is possible to update
+   the module's ``__path__`` at runtime, and this will not be automatically
+   reflected in ``__spec__.submodule_search_locations``.
 
    .. versionadded:: 3.4
 
diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
index 8cf16cad4c..7fbf8ed9d7 100644
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -519,8 +519,9 @@ 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.
 
-See :class:`~importlib.machinery.ModuleSpec` for more specifics on what
-information a module's spec may hold.
+The module's spec is exposed as the ``__spec__`` attribute on a module object.
+See :class:`~importlib.machinery.ModuleSpec` for details on the contents of
+the module spec.
 
 .. versionadded:: 3.4