From 75072c432953c574393a9d150bd626ad9512be1e Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Mon, 9 Feb 2026 13:04:39 +0000 Subject: [PATCH 1/3] Move pkg_resources documentation to deprecated --- docs/conf.py | 1 + docs/deprecated/index.rst | 1 + docs/{ => deprecated}/pkg_resources.rst | 0 docs/index.rst | 1 - 4 files changed, 2 insertions(+), 1 deletion(-) rename docs/{ => deprecated}/pkg_resources.rst (100%) diff --git a/docs/conf.py b/docs/conf.py index 3ddba1b505..3aee1141be 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -146,6 +146,7 @@ redirects = { "userguide/keywords": "/deprecated/changed_keywords.html", "userguide/commands": "/deprecated/commands.html", + "pkg_resources": "/deprecated/pkg_resources.html", } # Add support for inline tabs diff --git a/docs/deprecated/index.rst b/docs/deprecated/index.rst index 3f6e400fa2..9db1729a40 100644 --- a/docs/deprecated/index.rst +++ b/docs/deprecated/index.rst @@ -23,6 +23,7 @@ objectives. distutils-legacy functionalities commands + pkg_resources Notes for Consumers of Packages Built with Setuptools ===================================================== diff --git a/docs/pkg_resources.rst b/docs/deprecated/pkg_resources.rst similarity index 100% rename from docs/pkg_resources.rst rename to docs/deprecated/pkg_resources.rst diff --git a/docs/index.rst b/docs/index.rst index 2d4089d52b..a2163422f6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,7 +21,6 @@ with :pypi:`pip` and uploaded to `PyPI `_. User guide build_meta - pkg_resources references/keywords setuptools From 56c3a526fd29c294d9165034f7e65db97e72538a Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Mon, 9 Feb 2026 13:53:25 +0000 Subject: [PATCH 2/3] Add removal note with alternatives to the pkg_resources docs --- docs/deprecated/pkg_resources.rst | 58 +++++++++++++++++++++++++------ 1 file changed, 48 insertions(+), 10 deletions(-) diff --git a/docs/deprecated/pkg_resources.rst b/docs/deprecated/pkg_resources.rst index e999a37e2e..148e34fda9 100644 --- a/docs/deprecated/pkg_resources.rst +++ b/docs/deprecated/pkg_resources.rst @@ -2,7 +2,54 @@ Package Discovery and Resource Access using ``pkg_resources`` ============================================================= -The ``pkg_resources`` module distributed with ``setuptools`` provides an API +.. attention:: **This documentation is retained solely for historical purposes** + + ``pkg_resources`` has long been **discouraged** due to architectural + limitations that led to persistent performance issues. + These limitations were inherent to its design (e.g. importing on startup, + scanning the entire environment for metadata, and eager, global + working‑set management) and could not be corrected. + + .. version-deprecated:: v67.5.0 + ``pkg_resources`` issued official deprecation warnings as early as + ``setuptools`` **v67.5.0**. + + .. version-removed:: v82.0.0 + ``pkg_resources`` is no longer maintained, no longer used internally by + ``setuptools``, and is no longer included in current + distributions/installations as of ``setuptools`` **v82.0.0**. + + Projects must migrate away from ``pkg_resources``. The recommended + replacements are: + + * Resource access: use :mod:`importlib.resources` + (or its backport :pypi:`importlib_resources`). + * Distribution metadata & entry points: use :mod:`importlib.metadata` + (or its backport :pypi:`importlib_metadata`). + * Requirement and version parsing: use :pypi:`packaging`. + This includes parsing and evaluating ``extras`` and markers via + ``packaging.requirements.Requirement`` and ``packaging.markers.Marker`. + Note that automatic installation or detection of extras is not provided; + projects requiring that behaviour must implement it themselves using + a combination of ``packaging``, ``importlib.metadata`` and other tools + as building blocks. + * Coexistence of multiple versions of a package: please consider using a different + approach, as this functionality is not supported by Python itself. + Alternatives include isolated environments and orchestration tools + (:mod:`venv`, :pypi:`tox`, :pypi:`nox`, etc.). + * Handling of ``.egg`` distributions: please consider using a different + approach, as the ``.egg`` and ``easy_install`` mechanisms have also been + discontinued. + Please use currently supported packaging formats + (see :external+PyPUG:`specifications/section-distribution-formats`) + and build/installation workflows (see :pep:`517`). + + **Note:** The following documentation may no longer accurately describe the + behaviour of the distributed package and has been frozen at the last + ``setuptools`` release that still contained ``pkg_resources``. + + +The ``pkg_resources`` module provides an API for Python libraries to access their resource files, and for extensible applications and frameworks to automatically discover plugins. It also provides runtime support for using C extensions that are inside zipfile-format @@ -10,15 +57,6 @@ eggs, support for merging packages that have separately-distributed modules or subpackages, and APIs for managing Python's current "working set" of active packages. -.. attention:: - Use of ``pkg_resources`` is deprecated in favor of - :mod:`importlib.resources`, :mod:`importlib.metadata` - and their backports (:pypi:`importlib_resources`, :pypi:`importlib_metadata`). - Some useful APIs are also provided by :pypi:`packaging` (e.g. requirements - and version parsing). - Users should refrain from new usage of ``pkg_resources`` and - should work to port to importlib-based solutions. - -------- Overview From 99113844059df4aa1f5684f58325f9892179d37f Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Mon, 9 Feb 2026 13:59:37 +0000 Subject: [PATCH 3/3] Fix RST syntax errors in pkg_resources docs --- docs/deprecated/pkg_resources.rst | 42 +++++++++++++++---------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/deprecated/pkg_resources.rst b/docs/deprecated/pkg_resources.rst index 148e34fda9..8caae9e606 100644 --- a/docs/deprecated/pkg_resources.rst +++ b/docs/deprecated/pkg_resources.rst @@ -22,27 +22,27 @@ Package Discovery and Resource Access using ``pkg_resources`` Projects must migrate away from ``pkg_resources``. The recommended replacements are: - * Resource access: use :mod:`importlib.resources` - (or its backport :pypi:`importlib_resources`). - * Distribution metadata & entry points: use :mod:`importlib.metadata` - (or its backport :pypi:`importlib_metadata`). - * Requirement and version parsing: use :pypi:`packaging`. - This includes parsing and evaluating ``extras`` and markers via - ``packaging.requirements.Requirement`` and ``packaging.markers.Marker`. - Note that automatic installation or detection of extras is not provided; - projects requiring that behaviour must implement it themselves using - a combination of ``packaging``, ``importlib.metadata`` and other tools - as building blocks. - * Coexistence of multiple versions of a package: please consider using a different - approach, as this functionality is not supported by Python itself. - Alternatives include isolated environments and orchestration tools - (:mod:`venv`, :pypi:`tox`, :pypi:`nox`, etc.). - * Handling of ``.egg`` distributions: please consider using a different - approach, as the ``.egg`` and ``easy_install`` mechanisms have also been - discontinued. - Please use currently supported packaging formats - (see :external+PyPUG:`specifications/section-distribution-formats`) - and build/installation workflows (see :pep:`517`). + * Resource access: use :mod:`importlib.resources` + (or its backport :pypi:`importlib_resources`). + * Distribution metadata & entry points: use :mod:`importlib.metadata` + (or its backport :pypi:`importlib_metadata`). + * Requirement and version parsing: use :pypi:`packaging`. + This includes parsing and evaluating ``extras`` and markers via + ``packaging.requirements.Requirement`` and ``packaging.markers.Marker``. + Note that automatic installation or detection of extras is not provided; + projects requiring that behaviour must implement it themselves using + a combination of ``packaging``, ``importlib.metadata`` and other tools + as building blocks. + * Coexistence of multiple versions of a package: please consider using a different + approach, as this functionality is not supported by Python itself. + Alternatives include isolated environments and orchestration tools + (:mod:`venv`, :pypi:`tox`, :pypi:`nox`, etc.). + * Handling of ``.egg`` distributions: please consider using a different + approach, as the ``.egg`` and ``easy_install`` mechanisms have also been + discontinued. + Please use currently supported packaging formats + (see :external+PyPUG:`specifications/section-distribution-formats`) + and build/installation workflows (see :pep:`517`). **Note:** The following documentation may no longer accurately describe the behaviour of the distributed package and has been frozen at the last