Skip to content

Commit 27f1bd8

Browse files
authored
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
1 parent f8b1ccd commit 27f1bd8

File tree

2 files changed

+11
-21
lines changed

2 files changed

+11
-21
lines changed

Doc/library/importlib.rst

+8-6
Original file line numberDiff line numberDiff line change
@@ -438,8 +438,9 @@ ABC hierarchy::
438438
package. This attribute is not set on modules.
439439

440440
- :attr:`__package__`
441-
The parent package for the module/package. If the module is
442-
top-level then it has a value of the empty string. The
441+
The fully-qualified name of the package under which the module was
442+
loaded as a submodule (or the empty string for top-level modules).
443+
For packages, it is the same as :attr:`__name__`. The
443444
:func:`importlib.util.module_for_loader` decorator can handle the
444445
details for :attr:`__package__`.
445446

@@ -1347,8 +1348,8 @@ find and load modules.
13471348

13481349
(``__loader__``)
13491350

1350-
The loader to use for loading. For namespace packages this should be
1351-
set to ``None``.
1351+
The :term:`Loader <loader>` that should be used when loading
1352+
the module. :term:`Finders <finder>` should always set this.
13521353

13531354
.. attribute:: origin
13541355

@@ -1381,8 +1382,9 @@ find and load modules.
13811382

13821383
(``__package__``)
13831384

1384-
(Read-only) Fully-qualified name of the package to which the module
1385-
belongs as a submodule (or ``None``).
1385+
(Read-only) The fully-qualified name of the package under which the module
1386+
should be loaded as a submodule (or the empty string for top-level modules).
1387+
For packages, it is the same as :attr:`__name__`.
13861388

13871389
.. attribute:: has_location
13881390

Doc/reference/import.rst

+3-15
Original file line numberDiff line numberDiff line change
@@ -857,9 +857,8 @@ module. ``find_spec()`` returns a fully populated spec for the module.
857857
This spec will always have "loader" set (with one exception).
858858

859859
To indicate to the import machinery that the spec represents a namespace
860-
:term:`portion`, the path entry finder sets "loader" on the spec to
861-
``None`` and "submodule_search_locations" to a list containing the
862-
portion.
860+
:term:`portion`, the path entry finder sets "submodule_search_locations" to
861+
a list containing the portion.
863862

864863
.. versionchanged:: 3.4
865864
:meth:`~importlib.abc.PathEntryFinder.find_spec` replaced
@@ -875,18 +874,7 @@ portion.
875874
:meth:`~importlib.abc.PathEntryFinder.find_loader` takes one argument, the
876875
fully qualified name of the module being imported. ``find_loader()``
877876
returns a 2-tuple where the first item is the loader and the second item
878-
is a namespace :term:`portion`. When the first item (i.e. the loader) is
879-
``None``, this means that while the path entry finder does not have a
880-
loader for the named module, it knows that the path entry contributes to
881-
a namespace portion for the named module. This will almost always be the
882-
case where Python is asked to import a namespace package that has no
883-
physical presence on the file system. When a path entry finder returns
884-
``None`` for the loader, the second item of the 2-tuple return value must
885-
be a sequence, although it can be empty.
886-
887-
If ``find_loader()`` returns a non-``None`` loader value, the portion is
888-
ignored and the loader is returned from the path based finder, terminating
889-
the search through the path entries.
877+
is a namespace :term:`portion`.
890878

891879
For backwards compatibility with other implementations of the import
892880
protocol, many path entry finders also support the same,

0 commit comments

Comments
 (0)