Merge pull request #3843 from pypa/debt/deprecate-pkg_resources

Officially deprecate pkg_resources

changelog.d/3843.change.rst

@@ -0,0 +1 @@
+Although pkg_resources has been discouraged for use, some projects still consider pkg_resources viable for usage. This change makes it clear that pkg_resources should not be used, emitting a DeprecationWarning when imported.

docs/pkg_resources.rst

@@ -11,12 +11,13 @@ subpackages, and APIs for managing Python's current "working set" of active
 packages.
 
 .. attention::
-   Use of ``pkg_resources`` is discouraged in favor of
+   Use of ``pkg_resources`` is deprecated in favor of
    `importlib.resources <https://docs.python.org/3/library/importlib.html#module-importlib.resources>`_,
    `importlib.metadata <https://docs.python.org/3/library/importlib.metadata.html>`_,
    and their backports (:pypi:`importlib_resources`,
    :pypi:`importlib_metadata`).
-   Please consider using those libraries instead of pkg_resources.
+   Users should refrain from new usage of ``pkg_resources`` and
+   should work to port to importlib-based solutions.
 
 
 --------

pkg_resources/__init__.py

@@ -12,6 +12,12 @@
 .egg files, and unpacked .egg files.  It can also work in a limited way with
 .zip files and with custom PEP 302 loaders that support the ``get_data()``
 method.
+
+This module is deprecated. Users are directed to
+`importlib.resources <https://docs.python.org/3/library/importlib.resources.html>`_
+and
+`importlib.metadata <https://docs.python.org/3/library/importlib.metadata.html>`_
+instead.
 """
 
 import sys
@@ -112,6 +118,9 @@
 _namespace_packages = None
 
 
+warnings.warn("pkg_resources is deprecated as an API", DeprecationWarning)
+
+
 class PEP440Warning(RuntimeWarning):
     """
     Used when there is an issue with a version or specifier not complying with
@@ -914,9 +923,7 @@ def find_plugins(self, plugin_env, full_env=None, installer=None, fallback=True)
         list(map(shadow_set.add, self))
 
         for project_name in plugin_projects:
-
             for dist in plugin_env[project_name]:
-
                 req = [dist.as_requirement()]
 
                 try:
@@ -1822,7 +1829,6 @@ def _get_date_and_size(zip_stat):
 
     # FIXME: 'ZipProvider._extract_resource' is too complex (12)
     def _extract_resource(self, manager, zip_path):  # noqa: C901
-
         if zip_path in self._index():
             for name in self._index()[zip_path]:
                 last = self._extract_resource(manager, os.path.join(zip_path, name))
@@ -1836,7 +1842,6 @@ def _extract_resource(self, manager, zip_path):  # noqa: C901
                 '"os.rename" and "os.unlink" are not supported ' 'on this platform'
             )
         try:
-
             real_path = manager.get_cache_path(self.egg_name, self._parts(zip_path))
 
             if self._is_current(real_path, zip_path):

pytest.ini

@@ -86,3 +86,6 @@ filterwarnings=
 
 	# Avoid errors when testing pkg_resources.declare_namespace
 	ignore:.*pkg_resources\.declare_namespace.*:DeprecationWarning
+
+	# suppress known deprecation
+	ignore:pkg_resources is deprecated:DeprecationWarning

setuptools/tests/contexts.py

@@ -6,7 +6,6 @@
 import site
 import io
 
-import pkg_resources
 from filelock import FileLock
 
 
@@ -28,11 +27,7 @@ def environment(**replacements):
     In a context, patch the environment with replacements. Pass None values
     to clear the values.
     """
-    saved = dict(
-        (key, os.environ[key])
-        for key in replacements
-        if key in os.environ
-    )
+    saved = dict((key, os.environ[key]) for key in replacements if key in os.environ)
 
     # remove values that are null
     remove = (key for (key, value) in replacements.items() if value is None)
@@ -81,6 +76,8 @@ def save_user_site_setting():
 
 @contextlib.contextmanager
 def save_pkg_resources_state():
+    import pkg_resources
+
     pr_state = pkg_resources.__getstate__()
     # also save sys.path
     sys_path = sys.path[:]