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 <noreply@anthropic.com>

Author: veeceey

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

docs/setuptools.rst

@@ -86,23 +86,21 @@ The developer's guide has been updated. See the :doc:`most recent version <userg
 TRANSITIONAL NOTE
 ~~~~~~~~~~~~~~~~~
 
-Setuptools automatically calls ``declare_namespace()`` for you at runtime,
-but future versions may *not*.  This is because the automatic declaration
-feature has some negative side effects, such as needing to import all namespace
-packages during the initialization of the ``pkg_resources`` runtime, and also
-the need for ``pkg_resources`` to be explicitly imported before any namespace
-packages work at all.  In some future releases, you'll be responsible
-for including your own declaration lines, and the automatic declaration feature
-will be dropped to get rid of the negative side effects.
-
-During the remainder of the current development cycle, therefore, setuptools
-will warn you about missing ``declare_namespace()`` calls in your
-``__init__.py`` files, and you should correct these as soon as possible
-before the compatibility support is removed.
-Namespace packages without declaration lines will not work
-correctly once a user has upgraded to a later version, so it's important that
-you make this change now in order to avoid having your code break in the field.
-Our apologies for the inconvenience, and thank you for your patience.
+.. note::
+   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.
+   See :doc:`userguide/package_discovery` for details.
+
+Setuptools historically called ``declare_namespace()`` at runtime using
+``pkg_resources``, but this mechanism has been deprecated. The
+``pkg_resources`` runtime required importing all namespace packages during
+initialization and needed to be explicitly imported before any namespace
+packages would work at all.
+
+Projects should migrate to :pep:`420`-style implicit namespace packages,
+which do not require ``declare_namespace()`` calls or special
+``__init__.py`` files.
 
 
 

docs/userguide/distribution.rst

@@ -80,15 +80,15 @@ but here are a few tips that will keep you out of trouble in the corner cases:
   :pep:`440`-compliant.
 
 * If you want to be certain that your chosen numbering scheme works the way
-  you think it will, you can use the ``pkg_resources.parse_version()`` function
+  you think it will, you can use the ``packaging.version.parse()`` function
   to compare different version numbers::
 
-    >>> 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

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.

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 <https://packaging.python.org/guides/packaging-namespace-packages/>`_.
+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
+<https://packaging.python.org/guides/packaging-namespace-packages/>`_.
 
 
-``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:
 

newsfragments/5179.doc.rst

@@ -0,0 +1 @@
+Updated documentation to remove stale references to ``pkg_resources`` as an active module -- by :user:`veeceey`

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,