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
This commit is contained in:
Géry Ogam 2020-10-21 23:17:35 +02:00 committed by GitHub
parent f8b1ccd63c
commit 27f1bd8787
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 11 additions and 21 deletions

View File

@ -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__`.
@ -1347,8 +1348,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
@ -1381,8 +1382,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

View File

@ -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,