From 4543b2f6d5677b8b1ccdd7827f46a25d464d648e Mon Sep 17 00:00:00 2001 From: jeej3000 <171628180+jeej3000@users.noreply.github.com> Date: Tue, 17 Nov 2026 13:10:56 +0100 Subject: [PATCH 1/2] Clarify namespace package requirements in plugin discovery guide The "Using namespace packages" section only described pkgutil-style namespace sub-packages (requiring an `__init__.py`), which contradicts PEP 420 native namespace packages. Describe both variants, mention `find_namespace_packages`, and note that `import myapp.plugins` fails when no plugin is installed. Fixes #1104 Co-authored-by: jeej1k <351634202+jeej1k@users.noreply.github.com> Co-Authored-By: Claude Sonnet 5.5 --- .../creating-and-discovering-plugins.rst | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/source/guides/creating-and-discovering-plugins.rst b/source/guides/creating-and-discovering-plugins.rst index e8eed66e14..b0f6ee5225 100644 --- a/source/guides/creating-and-discovering-plugins.rst +++ b/source/guides/creating-and-discovering-plugins.rst @@ -100,11 +100,19 @@ but it's not recommended to make your project's main top-level package bad plugin could cause the entire namespace to break which would in turn make your project unimportable. For the "namespace sub-package" approach to work, the plugin packages must omit the :file:`__init__.py` for your top-level -package directory (``myapp`` in this case) and include the namespace-package -style :file:`__init__.py` in the namespace sub-package directory -(``myapp/plugins``). This also means that plugins will need to explicitly pass -a list of packages to :func:`setup`'s ``packages`` argument instead of using -:func:`setuptools.find_packages`. +package directory (``myapp`` in this case). In the namespace sub-package +directory (``myapp/plugins``) they must either omit :file:`__init__.py`, if +you use :ref:`native namespace packages `, or +include a pkgutil-style :file:`__init__.py`, if you use the legacy approach; +all plugins have to use the same one. Plugins will also need to list their +packages explicitly or use :func:`setuptools.find_namespace_packages`, as +:func:`setuptools.find_packages` skips directories without an +:file:`__init__.py`. + +With native namespace packages, ``myapp.plugins`` only exists once at least +one plugin is installed, so ``import myapp.plugins`` raises +:exc:`ModuleNotFoundError` if there are none. Make sure your code handles that +case. .. warning:: Namespace packages are a complex feature and there are several different ways to create them. It's highly recommended to read the From 4dfa8d86db8fca2e8be1fbde4b2d4e1492c2ba2c Mon Sep 17 00:00:00 2001 From: jeej3000 <171628180+jeej3000@users.noreply.github.com> Date: Thu, 19 Nov 2026 17:39:09 +0100 Subject: [PATCH 2/2] Address review: drop same-style requirement, reword missing-directory note Co-authored-by: jeej1k <351634202+jeej1k@users.noreply.github.com> Co-Authored-By: Claude Sonnet 5.5 --- source/guides/creating-and-discovering-plugins.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/source/guides/creating-and-discovering-plugins.rst b/source/guides/creating-and-discovering-plugins.rst index b0f6ee5225..ce986c1924 100644 --- a/source/guides/creating-and-discovering-plugins.rst +++ b/source/guides/creating-and-discovering-plugins.rst @@ -103,16 +103,14 @@ the plugin packages must omit the :file:`__init__.py` for your top-level package directory (``myapp`` in this case). In the namespace sub-package directory (``myapp/plugins``) they must either omit :file:`__init__.py`, if you use :ref:`native namespace packages `, or -include a pkgutil-style :file:`__init__.py`, if you use the legacy approach; -all plugins have to use the same one. Plugins will also need to list their -packages explicitly or use :func:`setuptools.find_namespace_packages`, as +include a pkgutil-style :file:`__init__.py`, if you use the legacy approach. +Plugins will also need to list their packages explicitly or use :func:`setuptools.find_namespace_packages`, as :func:`setuptools.find_packages` skips directories without an :file:`__init__.py`. -With native namespace packages, ``myapp.plugins`` only exists once at least -one plugin is installed, so ``import myapp.plugins`` raises -:exc:`ModuleNotFoundError` if there are none. Make sure your code handles that -case. +With native namespace packages, ``import myapp.plugins`` raises +:exc:`ModuleNotFoundError` if no installed distribution provides the +``myapp/plugins`` directory. Make sure your discovery code handles that case. .. warning:: Namespace packages are a complex feature and there are several different ways to create them. It's highly recommended to read the