pkg_resources deletions and sphinxcontrib

[meejah]

Hello,

I've run into the (somewhat recent) deletions of pkg_resources from setuptools in a few different projects. Sphinx is the first one I've run across the "namespace package" issue -- the issue being that the line __import__('pkg_resources').declare_namespace(__name__) found in my case in "sphinxcontrib-seqdiag" is no longer valid and has been deleted.

According to python/importlib_metadata#378 (comment) there is no migration path -- the solution suggested there is to "just use the new way in all projects at the same time".

Is this accurate? I'm happy to prepare a pull-request for sphinxcontrib-seqdiag (which I use in a couple projects) but don't have the capacity to do the same for all sphinxcontrib packages.

For now, my only option seems to be to pin setuptools < 82.0.0 in relevant documentation builds .. but of course, that solution becomes less and less tenable over time.

Any other options? Does Sphinx have a plan for this already? (I did search some project tickets but didn't see anything)

[goutamadwant]

Pinning setuptools<82 is only a short-term bridge. The durable fix belongs in each affected sphinxcontrib-* distribution, not in Sphinx itself.

For a Python-3-only package, migrate to a PEP 420 native namespace:

• remove sphinxcontrib/__init__.py from the wheel;
• remove namespace_packages=['sphinxcontrib'] / pkg_resources.declare_namespace;
• use namespace-aware package discovery (find_namespace_packages, or the equivalent setuptools configuration).

Not every modern sphinxcontrib project needs a coordinated change: packages already using PEP 420 are fine. However, every installed distribution that still ships a regular or pkg_resources-based sphinxcontrib/__init__.py can interfere with the shared namespace and needs migration. Checking the built wheel contents is important; deleting the source file while still packaging a stale copy is not enough.

If legacy compatibility must be retained temporarily, pkgutil.extend_path is a dependency-free transition, but omitting __init__.py is the cleaner end state. A PR to sphinxcontrib-seqdiag implementing this migration would be the right scope.