From f1f5829955d2384f49e6eb52eb3dd4077ccc4825 Mon Sep 17 00:00:00 2001 From: Varun Chawla Date: Tue, 10 Feb 2026 00:11:44 -0800 Subject: [PATCH] Update stale docs references to pkg_resources as active module Remove or update documentation that still refers to ``pkg_resources`` as an actively maintained module, following the deprecation completed in #5173. Changes include: - docs/setuptools.rst: Rewrite Transitional Note to reflect that pkg_resources-style namespace packages are deprecated - docs/development/index.rst: Remove mention of pkg_resources module and reference manual - docs/userguide/distribution.rst: Replace pkg_resources.parse_version() with packaging.version.parse() - docs/userguide/extension.rst: Reference importlib.metadata as the primary API for EGG-INFO access - docs/userguide/package_discovery.rst: Fix ``pkg_resource`` typo (missing 's'), fix ``pkgutils`` typo, add deprecation admonition to Legacy Namespace Packages section - setuptools/dist.py: Replace pkg_resources.require() format reference with PEP 508 in install_requires docstring Closes #5179 Co-Authored-By: Claude Opus 4.6 --- docs/development/index.rst | 12 +++++------ docs/setuptools.rst | 32 +++++++++++++--------------- docs/userguide/distribution.rst | 10 ++++----- docs/userguide/extension.rst | 5 +++-- docs/userguide/package_discovery.rst | 25 ++++++++++++++-------- newsfragments/5179.doc.rst | 1 + setuptools/dist.py | 16 +++++++------- 7 files changed, 53 insertions(+), 48 deletions(-) create mode 100644 newsfragments/5179.doc.rst diff --git a/docs/development/index.rst b/docs/development/index.rst index 7ee52361ec..a645592b22 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -7,13 +7,11 @@ Authority (PyPA) and led by Jason R. Coombs. This document describes the process by which Setuptools is developed. This document assumes the reader has some passing familiarity with -*using* setuptools, the ``pkg_resources`` module, and pip. It -does not attempt to explain basic concepts like inter-project -dependencies, nor does it contain detailed lexical syntax for most -file formats. Neither does it explain concepts like "namespace -packages" or "resources" in any detail, as all of these subjects are -covered at length in the setuptools developer's guide and the -``pkg_resources`` reference manual. +*using* setuptools and pip. It does not attempt to explain basic +concepts like inter-project dependencies, nor does it contain detailed +lexical syntax for most file formats. Neither does it explain concepts +like "namespace packages" or "resources" in any detail, as all of these +subjects are covered at length in the setuptools developer's guide. Instead, this is **internal** documentation for how those concepts and features are *implemented* in concrete terms. It is intended for people diff --git a/docs/setuptools.rst b/docs/setuptools.rst index ce1962706c..933eab8e81 100644 --- a/docs/setuptools.rst +++ b/docs/setuptools.rst @@ -86,23 +86,21 @@ The developer's guide has been updated. See the :doc:`most recent version >> from pkg_resources import parse_version - >>> parse_version("1.9.a.dev") == parse_version("1.9a0dev") + >>> from packaging.version import parse + >>> parse("1.9a0.dev0") == parse("1.9a0.dev0") True - >>> parse_version("2.1-rc2") < parse_version("2.1") + >>> parse("2.1rc2") < parse("2.1") True - >>> parse_version("0.6a9dev-r41475") < parse_version("0.6a9") + >>> parse("0.6a9.dev0") < parse("0.6a9") True Once you've decided on a version numbering scheme for your project, you can diff --git a/docs/userguide/extension.rst b/docs/userguide/extension.rst index ef5e33f3a8..06d1704d27 100644 --- a/docs/userguide/extension.rst +++ b/docs/userguide/extension.rst @@ -179,8 +179,9 @@ Adding new EGG-INFO Files Some extensible applications or frameworks may want to allow third parties to develop plugins with application or framework-specific metadata included in -the plugins' EGG-INFO directory, for easy access via the ``pkg_resources`` -metadata API. The easiest way to allow this is to create an extension +the plugins' EGG-INFO directory, for easy access via the +:mod:`importlib.metadata` API (or its predecessor ``pkg_resources``). +The easiest way to allow this is to create an extension to be used from the plugin projects' setup scripts (via ``setup_requires``) that defines a new setup keyword, and then uses that data to write an EGG-INFO file when the ``egg_info`` command is run. diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst index c33877e1f6..1a3ea7a2e4 100644 --- a/docs/userguide/package_discovery.rst +++ b/docs/userguide/package_discovery.rst @@ -505,19 +505,26 @@ available to your interpreter. Legacy Namespace Packages ========================= + +.. deprecated:: + The ``pkg_resources``-style and ``pkgutil``-style namespace packages + described below are **deprecated and no longer supported**. + Please migrate to :pep:`420`-style implicit namespace packages. + The fact you can create namespace packages so effortlessly above is credited to :pep:`420`. It used to be more cumbersome to accomplish the same result. Historically, there were two methods -to create namespace packages. One is the ``pkg_resources`` style supported by -``setuptools`` and the other one being ``pkgutils`` style offered by -``pkgutils`` module in Python. Both are now considered *deprecated* despite the -fact they still linger in many existing packages. These two differ in many -subtle yet significant aspects and you can find out more on `Python packaging -user guide `_. +to create namespace packages. One is the ``pkg_resources`` style formerly +supported by ``setuptools`` and the other one being ``pkgutil`` style offered +by the ``pkgutil`` module in Python. Both are now **deprecated and no longer +supported** despite the fact they still linger in many existing packages. +These two differ in many subtle yet significant aspects and you can find out +more on the `Python packaging user guide +`_. -``pkg_resource`` style namespace package ----------------------------------------- +``pkg_resources`` style namespace package +----------------------------------------- This is the method ``setuptools`` directly supports. Starting with the same layout, there are two pieces you need to add to it. First, an ``__init__.py`` file directly under your namespace package directory that contains the @@ -562,7 +569,7 @@ the previous section. ``pkgutil`` style namespace package ----------------------------------- -This method is almost identical to the ``pkg_resource`` except that the +This method is almost identical to the ``pkg_resources`` style except that the ``namespace_packages`` declaration is omitted and the ``__init__.py`` file contains the following: diff --git a/newsfragments/5179.doc.rst b/newsfragments/5179.doc.rst new file mode 100644 index 0000000000..c0ec05e901 --- /dev/null +++ b/newsfragments/5179.doc.rst @@ -0,0 +1 @@ +Updated documentation to remove stale references to ``pkg_resources`` as an active module -- by :user:`veeceey` diff --git a/setuptools/dist.py b/setuptools/dist.py index a224b3ee44..197f21482f 100644 --- a/setuptools/dist.py +++ b/setuptools/dist.py @@ -246,14 +246,14 @@ class Distribution(_Distribution): effectively adds the following new optional keyword arguments to 'setup()': 'install_requires' -- a string or sequence of strings specifying project - versions that the distribution requires when installed, in the format - used by 'pkg_resources.require()'. They will be installed - automatically when the package is installed. If you wish to use - packages that are not available in PyPI, or want to give your users an - alternate download location, you can add a 'find_links' option to the - '[easy_install]' section of your project's 'setup.cfg' file, and then - setuptools will scan the listed web pages for links that satisfy the - requirements. + versions that the distribution requires when installed, in the + :pep:`508` format (e.g. ``'requests>=2.0'``). They will be + installed automatically when the package is installed. If you wish + to use packages that are not available in PyPI, or want to give your + users an alternate download location, you can add a 'find_links' + option to the '[easy_install]' section of your project's 'setup.cfg' + file, and then setuptools will scan the listed web pages for links + that satisfy the requirements. 'extras_require' -- a dictionary mapping names of optional "extras" to the additional requirement(s) that using those extras incurs. For example,