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 27f1bd8787
)
Co-authored-by: Géry Ogam <gery.ogam@gmail.com>
This commit is contained in:
parent
ba666747af
commit
916ac95201
|
@ -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
|
||||
|
||||
|
|
|
@ -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,
|
||||
|
|
Loading…
Reference in New Issue