pypa / pypa/packaging.python.org

Cover PEP 420 namespace packages in "Creating and discovering plugins" guide

Open
#1,104 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

component: guides type: enhancement
Dominant language
Python
Stars
1.7k
Forks
1.7k
Avg merge
3d 12h
Merged PRs (30d)
4

Description

Using namespace packages is not explicit whether it talks about native PEP 420 namespace packages, or pkg-style namespace packages.

I tried to apply it for PEP 420 namespace packages and stumbled over two issues:

First, the given example doesn't wrap import myapp.plugin in try/except, but actually ModuleNotFoundError should be handled because, as a core package maintainer, you can't know how many plugins will be installed at runtime. In case of zero plugins installed, how would you guarantee a myapp.plugins namespace will exists anyways? At least setuptools won't let you install empty directories.

Second, the guide says

include the namespace-package style init.py in the namespace sub-package directory

But PEP 420 explicitly requires the absence of __init__.py files. Then, what is a namespace-package style __init__.py in the context of PEP 420? I believe @theacodes had pkg-style namespace packages in mind when adding that sentence with #296.

Could we make it either more clear the guide is not 1:1 applicable for native namespace packages, or even better, find a suggested minimal working PEP 420 example and adapt the guide accordingly?

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the “Using namespace packages” section in the Creating and discovering plugins guide, then compare its example with PEP 420 and the packaging namespace-packages guide. Clarify whether the existing instructions describe native or pkg-style namespaces, and document a correct minimal native-namespace example if appropriate. Done means the guide no longer conflicts with PEP 420 and explains the no-plugin case.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.