Skip to content

gh-77391: Say what walk_packages' prefix does to the imports #158138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
v0ropaev wants to merge 1 commit into
base: main
Choose a base branch
from
+20 −3
Open

gh-77391: Say what walk_packages' prefix does to the imports #158138

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion Doc/library/pkgutil.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,10 +112,17 @@ support.
*path* should be either ``None`` or a list of paths to look for modules in.

*prefix* is a string to output on the front of every module name on output.
It also becomes part of the name under which each package is imported
during the recursive descent.

Note that this function must import all *packages* (*not* all modules!) on
the given *path*, in order to access the ``__path__`` attribute to find
submodules.
submodules. The import is done by name, so ``prefix + name`` must resolve
to the package that was found on *path*. If it resolves to a different
package, the submodules of that one are listed instead. If it raises
:exc:`ImportError`, the submodules are left out and nothing in the results
shows that they are missing. Passing a package's ``__path__`` together
with its ``__name__`` and a trailing dot avoids both.

*onerror* is a function which gets called with one argument (the name of the
package which was being imported) if any exception occurs while trying to
Expand Down
11 changes: 9 additions & 2 deletions Lib/pkgutil.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,18 @@ def walk_packages(path=None, prefix='', onerror=None):
modules in.

'prefix' is a string to output on the front of every module name
on output.
on output. It also becomes part of the name under which each
package is imported during the recursive descent.

Note that this function must import all *packages* (NOT all
modules!) on the given path, in order to access the __path__
attribute to find submodules.
attribute to find submodules. The import is done by name, so
prefix + name must resolve to the package that was found on path.
If it resolves to a different package, the submodules of that one
are listed instead. If it raises ImportError, the submodules are
left out and nothing in the results shows that they are missing.
Passing a package's __path__ together with its __name__ and a
trailing dot avoids both.

'onerror' is a function which gets called with one argument (the
name of the package which was being imported) if any exception
Expand Down
3 changes: 3 additions & 0 deletions Misc/NEWS.d/next/Documentation/2026-09-25-00-15-48.gh-issue-77391.1utlEd.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
Document that the *prefix* argument of :func:`pkgutil.walk_packages` affects
the imports made during the recursive descent, not just the names that are
returned.
Loading