[Python-checkins] bpo-35181: Correct importlib documentation for some module attributes (GH-15190)
miss-islington
webhook-mailer at python.org
Wed Oct 21 17:27:19 EDT 2020
https://github.com/python/cpython/commit/916ac9520108831d2099b13992a45884b112b193
commit: 916ac9520108831d2099b13992a45884b112b193
branch: 3.8
author: Miss Skeleton (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2020-10-21T14:27:10-07:00
summary:
bpo-35181: Correct importlib documentation for some module attributes (GH-15190)
@ericsnowcurrently This PR will change the following:
In the library documentation importlib.rst:
- `module.__package__` can be `module.__name__` for packages;
- `spec.parent` can be `spec.__name__` for packages;
- `spec.loader` is not `None` for namespaces packages.
In the language documentation import.rst:
- `spec.loader` is not `None` for namespace packages.
Automerge-Triggered-By: GH:warsaw
(cherry picked from commit 27f1bd8787d24ac53cc3dc6ea5eb00b8a3499839)
Co-authored-by: Géry Ogam <gery.ogam at gmail.com>
files:
M Doc/library/importlib.rst
M Doc/reference/import.rst
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index f205f5fee0544..be0dab3d057ca 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -438,8 +438,9 @@ ABC hierarchy::
package. This attribute is not set on modules.
- :attr:`__package__`
- The parent package for the module/package. If the module is
- top-level then it has a value of the empty string. The
+ The fully-qualified name of the package under which the module was
+ loaded as a submodule (or the empty string for top-level modules).
+ For packages, it is the same as :attr:`__name__`. The
:func:`importlib.util.module_for_loader` decorator can handle the
details for :attr:`__package__`.
@@ -1310,8 +1311,8 @@ find and load modules.
(``__loader__``)
- The loader to use for loading. For namespace packages this should be
- set to ``None``.
+ The :term:`Loader <loader>` that should be used when loading
+ the module. :term:`Finders <finder>` should always set this.
.. attribute:: origin
@@ -1344,8 +1345,9 @@ find and load modules.
(``__package__``)
- (Read-only) Fully-qualified name of the package to which the module
- belongs as a submodule (or ``None``).
+ (Read-only) The fully-qualified name of the package under which the module
+ should be loaded as a submodule (or the empty string for top-level modules).
+ For packages, it is the same as :attr:`__name__`.
.. attribute:: has_location
diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
index 594bb78e9ecf6..4027ffdd5e0c0 100644
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -857,9 +857,8 @@ module. ``find_spec()`` returns a fully populated spec for the module.
This spec will always have "loader" set (with one exception).
To indicate to the import machinery that the spec represents a namespace
-:term:`portion`, the path entry finder sets "loader" on the spec to
-``None`` and "submodule_search_locations" to a list containing the
-portion.
+:term:`portion`, the path entry finder sets "submodule_search_locations" to
+a list containing the portion.
.. versionchanged:: 3.4
:meth:`~importlib.abc.PathEntryFinder.find_spec` replaced
@@ -875,18 +874,7 @@ portion.
:meth:`~importlib.abc.PathEntryFinder.find_loader` takes one argument, the
fully qualified name of the module being imported. ``find_loader()``
returns a 2-tuple where the first item is the loader and the second item
- is a namespace :term:`portion`. When the first item (i.e. the loader) is
- ``None``, this means that while the path entry finder does not have a
- loader for the named module, it knows that the path entry contributes to
- a namespace portion for the named module. This will almost always be the
- case where Python is asked to import a namespace package that has no
- physical presence on the file system. When a path entry finder returns
- ``None`` for the loader, the second item of the 2-tuple return value must
- be a sequence, although it can be empty.
-
- If ``find_loader()`` returns a non-``None`` loader value, the portion is
- ignored and the loader is returned from the path based finder, terminating
- the search through the path entries.
+ is a namespace :term:`portion`.
For backwards compatibility with other implementations of the import
protocol, many path entry finders also support the same,
More information about the Python-checkins
mailing list