bpo-31799: Make module.__spec__ more discoverable (#4010)
bpo-31799: Make module.__spec__ more discoverable
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index 3a72648..3d350e8 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -1048,7 +1048,15 @@
.. 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 8cf16ca..7fbf8ed 100644
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -519,8 +519,9 @@
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