Add a DeprecationWarning to pkg_resources.declare_namespace (#3434)

6 files changed, 28 insertions, 6 deletions

diff --git a/changelog.d/3434.deprecation.rst b/changelog.d/3434.deprecation.rst
new file mode 100644
index 00000000..2073d2b9
--- /dev/null
+++ b/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.
diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst
index ade147ad..6173e3c2 100644
--- a/docs/references/keywords.rst
+++ b/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.
 
diff --git a/pkg_resources/__init__.py b/pkg_resources/__init__.py
index 0ae951b6..aed691ac 100644
--- a/pkg_resources/__init__.py
+++ b/pkg_resources/__init__.py
@@ -2288,6 +2288,14 @@ def _rebuild_mod_path(orig_path, package_name, module):
 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:
diff --git a/pkg_resources/tests/test_resources.py b/pkg_resources/tests/test_resources.py
index 107dda7b..2138f95e 100644
--- a/pkg_resources/tests/test_resources.py
+++ b/pkg_resources/tests/test_resources.py
@@ -830,10 +830,12 @@ class TestNamespaces:
             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 @@ class TestNamespaces:
             (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
diff --git a/pytest.ini b/pytest.ini
index 3c73f2ee..1a651f55 100644
--- a/pytest.ini
+++ b/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
diff --git a/setuptools/dist.py b/setuptools/dist.py
index 49d1ac6b..eb59f3a0 100644
--- a/setuptools/dist.py
+++ b/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)