From 2177e1f813a6aa05c29a8f36d787171d954465c7 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Wed, 6 Jul 2022 23:35:53 +0100 Subject: [PATCH 1/4] Add DeprecationWarning to `pkg_resources.declare_namespace` --- pkg_resources/__init__.py | 6 ++++++ pkg_resources/tests/test_resources.py | 11 +++++++---- pytest.ini | 3 +++ 3 files changed, 16 insertions(+), 4 deletions(-) diff --git a/pkg_resources/__init__.py b/pkg_resources/__init__.py index 0ae951b628..cc1c6d9c72 100644 --- a/pkg_resources/__init__.py +++ b/pkg_resources/__init__.py @@ -2288,6 +2288,12 @@ 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`." + ) + 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 107dda7bab..2138f95e7b 100644 --- a/pkg_resources/tests/test_resources.py +++ b/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 diff --git a/pytest.ini b/pytest.ini index 4f4f9cde59..fd7ec6ded8 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 From 7066963dc4d786f7ee8bfb09a20f78a143d1ad81 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 7 Jul 2022 10:57:02 +0100 Subject: [PATCH 2/4] Add news fragment --- changelog.d/3434.deprecation.rst | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 changelog.d/3434.deprecation.rst diff --git a/changelog.d/3434.deprecation.rst b/changelog.d/3434.deprecation.rst new file mode 100644 index 0000000000..2073d2b91a --- /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. From 81e1137a7d158df0b81d1ae53f6e0b56118acfba Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Mon, 13 Feb 2023 19:18:22 +0000 Subject: [PATCH 3/4] Add information on why namespace_packages are deprecated --- docs/references/keywords.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index ade147ad75..6173e3c228 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 ` for more information. From de2361c389304603f0daf70b0ee0647af0b9e981 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Mon, 13 Feb 2023 19:23:36 +0000 Subject: [PATCH 4/4] Add links explaining deprecations --- pkg_resources/__init__.py | 4 +++- setuptools/dist.py | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/pkg_resources/__init__.py b/pkg_resources/__init__.py index cc1c6d9c72..aed691ac4c 100644 --- a/pkg_resources/__init__.py +++ b/pkg_resources/__init__.py @@ -2290,7 +2290,9 @@ def declare_namespace(packageName): msg = ( "Implementing implicit namespace packages (as specified in PEP 420) " - "is preferred to `pkg_resources.declare_namespace`." + "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) diff --git a/setuptools/dist.py b/setuptools/dist.py index cd34d74a9c..f1de97de9d 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)