Should we add a DeprecationWarning to pkg_resources.declare_namespace?

changelog.d/3434.deprecation.rst

@@ -0,0 +1,3 @@
+Added deprecation warning for ``pkg_resources.declare_namespace``.
+Users that wish to implement namespace packages, are recommended to follow the
+practice described in PEP 420 and omit the ``__init__.py`` file entirely.

docs/references/keywords.rst

@@ -390,7 +390,10 @@ extensions).
 
 ``namespace_packages``
     .. warning::
-        ``namespace_packages`` is deprecated in favor of native/implicit
+        The ``namespace_packages`` implementation relies on ``pkg_resources``.
+        However, ``pkg_resources`` has some undesirable behaviours, and
+        Setuptools intends to obviate its usage in the future. Therefore,
+        ``namespace_packages`` was deprecated in favor of native/implicit
         namespaces (:pep:`420`). Check :doc:`the Python Packaging User Guide
         <PyPUG:guides/packaging-namespace-packages>` for more information.
 

pkg_resources/__init__.py

@@ -2288,6 +2288,14 @@ def position_in_sys_path(path):
 def declare_namespace(packageName):
     """Declare that package 'packageName' is a namespace package"""
 
+    msg = (
+        "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"
+    )
+    warnings.warn(msg, DeprecationWarning, stacklevel=2)
+
     _imp.acquire_lock()
     try:
         if packageName in _namespace_packages:

pkg_resources/tests/test_resources.py

@@ -830,10 +830,12 @@ def test_two_levels_deep(self, symlinked_tmpdir):
             pkg2.ensure_dir()
             (pkg1 / '__init__.py').write_text(self.ns_str, encoding='utf-8')
             (pkg2 / '__init__.py').write_text(self.ns_str, encoding='utf-8')
-        import pkg1
+        with pytest.warns(DeprecationWarning, match="pkg_resources.declare_namespace"):
+            import pkg1
         assert "pkg1" in pkg_resources._namespace_packages
         # attempt to import pkg2 from site-pkgs2
-        import pkg1.pkg2
+        with pytest.warns(DeprecationWarning, match="pkg_resources.declare_namespace"):
+            import pkg1.pkg2
         # check the _namespace_packages dict
         assert "pkg1.pkg2" in pkg_resources._namespace_packages
         assert pkg_resources._namespace_packages["pkg1"] == ["pkg1.pkg2"]
@@ -874,8 +876,9 @@ def test_path_order(self, symlinked_tmpdir):
             (subpkg / '__init__.py').write_text(
                 vers_str % number, encoding='utf-8')
 
-        import nspkg.subpkg
-        import nspkg
+        with pytest.warns(DeprecationWarning, match="pkg_resources.declare_namespace"):
+            import nspkg.subpkg
+            import nspkg
         expected = [
             str(site.realpath() / 'nspkg')
             for site in site_dirs

pytest.ini

@@ -83,3 +83,6 @@ filterwarnings=
 	# Can't use EncodingWarning as it doesn't exist on Python 3.9
 	default:'encoding' argument not specified
 	default:UTF-8 Mode affects locale.getpreferredencoding().
+
+	# Avoid errors when testing pkg_resources.declare_namespace
+	ignore:.*pkg_resources\.declare_namespace.*:DeprecationWarning

setuptools/dist.py

@@ -280,7 +280,9 @@ def check_nsp(dist, attr, value):
             )
         msg = (
             "The namespace_packages parameter is deprecated, "
-            "consider using implicit namespaces instead (PEP 420)."
+            "consider using implicit namespaces instead (PEP 420). "
+            "See https://setuptools.pypa.io/en/latest/references/"
+            "keywords.html#keyword-namespace-packages"
         )
         warnings.warn(msg, SetuptoolsDeprecationWarning)