[Docs] How to handle declare_namespace deprecation for existing packages?

[bluetech]

Summary

Since version v67.3.0, setuptools emits a deprecation warning for pkg_resources.declare_namespace. The deprecation warning is:

DeprecationWarning: Deprecated call to `pkg_resources.declare_namespace('zope')`.
  Implementing implicit namespace packages (as specified in PEP 420) is preferred to `pkg_resources.declare_namespace`. See https://setuptools.pypa.io/en/latest/references/keywords.html#keyword-namespace-packages
    declare_namespace(pkg)

The link https://setuptools.pypa.io/en/latest/references/keywords.html#keyword-namespace-packages points to the PyPA packaging guide https://packaging.python.org/en/latest/guides/packaging-namespace-packages/ for guidance. This guide says about pkg_resources-style namespace packages (bold added by me):

While this approach is no longer recommended, it is widely present in most existing namespace packages. If you are creating a new distribution within an existing namespace package that uses this method then it’s recommended to continue using this as the different methods are not cross-compatible and it’s not advisable to try to migrate an existing package.

So we are left with a deprecation warning, with the deprecation note guiding not to fix it.

Is there a migration path, or is the right thing to do is to ignore the deprecation?

OS / Environment

Linux, python 3.11, setuptools 67.8.0

Additional Information

I do not maintain a namespaced package myself; I use gevent, which imports zope.interface, which uses declare_namespace. I've reported the deprecation to zope.interface at zopefoundation/zope.interface#270, but @cjwatson correctly pointed out this issue.

Code of Conduct

• I agree to follow the PSF Code of Conduct

[abravalheri]

Hi @bluetech, it is possible to move package by package in existing namespaces to PEP 420 and they will interoperate (to some extent) with old implementations using pkg_resources. My suggestion would be to try this approach out and workaround the limitations¹.

Please note that the support for pkg_resources is not going to disappear out of sudden, but it is important to start taking the first steps towards the migration of packages to PEP 420.

Please find related discussions in the links below:

• Update table and add information about staggered migrations sample-namespace-packages#22
• Should we add a DeprecationWarning to pkg_resources.declare_namespace? #3434 (comment)

Footnotes

1. Existing experiments indicate that mixing pkg_resources and PEP 420 namespaces can work togheter. The limitation reported so far concerns using editable installs (which is a non-essential convenience feature, not intended for final deployments). ↩

[bluetech]

Thanks for the detailed answer @abravalheri It's good that you are already aware of this topic, and that zope are already discussing how to migrate. I'll close the issue as it isn't adding much I think.