[Docs] Clarity on transition for `pkg_resources.declare_namespace`

[tonybaloney]

Summary

I'm trying to work out how to remove uses of:

import pkg_resources
pkg_resources.declare_namespace(__name__)

Now that pkg_resources is deprecated.

There is a docs section on this:

https://setuptools.pypa.io/en/latest/userguide/package_discovery.html#pkg-resource-style-namespace-package

Which suggests the following snippet:

__import__("pkg_resources").declare_namespace(__name__)

Won't this also not work because pkg_resources is deprecated?

OS / Environment

No response

Additional Information

na

Code of Conduct

• I agree to follow the PSF Code of Conduct

[abravalheri]

Hi @tonybaloney, thank you very much for opening this issue.

Please note that the docs don't actually suggest replacing it with __import__("pkg_resources").declare_namespace(__name__).

In the documentation's page that you mentioned, there is a clear reference that pkg_resources is deprecated:

Historically, there were two methods to create namespace packages. One is the pkg_resources style supported by setuptools and the other one being pkgutils style offered by pkgutils module in Python. Both are now considered deprecated despite the fact they still linger in many existing packages. These two differ in many subtle yet significant aspects and you can find out more on Python packaging user guide.

Instead the docs contain a detailed example of namespace package implemented using the technique described in PEP 420¹.

The link in the Python Packaging User Guide also contains a warning about legacy namespaces and recommends PEP 420 approach (a.k.a. "native namespace packages").

I am not sure which kind of clarity you would be interested... Could you please provide a PR with your suggestion on how to improve it²?

Footnotes

1. By default, if your project structure is reasonably standard, you don't even need to provide any config, just having the namespaces organised into directories will suffice, and setuptools will automatically find the correct packages. ↩

2. Please just have in mind that it is important to keep some form of the documentation of the legacy/deprecated approach, so people supporting old packages can still find helpful documentation. That is why we cannot simply exclude all the references completely. ↩