Merge branch 'main' into patch-1

Author: ncoghlan

.github/CODEOWNERS

@@ -1,6 +1,9 @@
 source/guides/github-actions-ci-cd-sample/* @webknjaz
 source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @webknjaz
 
+# Sphinx extension
+pug_sphinx_extensions/ @FFY00
+
 # build-details.json
 source/specifications/build-details/ @FFY00
 source/specifications/specs/build-details-*.json @FFY00

.pre-commit-config.yaml

@@ -37,7 +37,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.13.3
+  rev: v0.14.10
   hooks:
     - id: ruff
     - id: ruff-format

pug_sphinx_extensions/__init__.py

@@ -0,0 +1,86 @@
+import os
+import pathlib
+import urllib
+
+import sphinx.application
+import sphinx.util.logging
+
+
+DOMAIN = "packaging.python.org"
+
+
+logger = sphinx.util.logging.getLogger(__name__)
+
+
+def resolve_local_html_link(app: sphinx.application.Sphinx, url_path: str) -> str:
+    """Takes path of a link pointing an HTML render of the current project,
+    and returns local path of the referenced document.
+
+    Support links to renders from both the `html` and `dirhtml` builders.
+
+    Example:
+
+    .. code-block:: python
+
+        >>> resolve_local_html_link('https://packaging.python.org/en/latest/flow/')
+        '{srcdir}/flow.rst'
+        >>> resolve_local_html_link('https://packaging.python.org/en/latest/flow.html')
+        '{srcdir}/flow.rst'
+        >>> resolve_local_html_link('https://packaging.python.org/en/latest/specifications/schemas/')
+        '{srcdir}/specifications/schemas/index.rst'
+        >>> resolve_local_html_link('https://packaging.python.org/en/latest/specifications/schemas/build-details-v1.0.schema.json')
+        '{html_extra_path0}/specifications/schemas/build-details-v1.0.schema.json'
+
+    """
+    # Search for document in html_extra_path
+    for entry in app.config.html_extra_path:
+        candidate = (app.confdir / entry / url_path).resolve()
+        if candidate.is_dir():
+            candidate = candidate / "index.html"
+        if candidate.exists():
+            return os.fspath(candidate)
+    # Convert html path to source path
+    url_path = url_path.removesuffix("/")  # Normalize
+    if url_path.endswith(".html"):
+        document = url_path.removesuffix(".html")
+    elif (candidate := f"{url_path}/index") in app.project.docnames:
+        document = candidate
+    else:
+        document = url_path
+    return app.env.doc2path(document)
+
+
+def rewrite_local_uri(app: sphinx.application.Sphinx, uri: str) -> str:
+    """Replace remote URIs targeting https://packaging.python.org/en/latest/...
+    with local ones, so that local changes are taken into account by linkcheck.
+
+    Additionally, resolve local relative links to html_extra_path.
+    """
+    local_uri = uri
+    parsed = urllib.parse.urlparse(uri)
+    # Links to https://packaging.python.org/en/latest/...
+    if parsed.hostname == DOMAIN and parsed.path.startswith("/en/latest/"):
+        document = parsed.path.removeprefix("/en/latest/")
+        local_uri = resolve_local_html_link(app, document)
+        logger.verbose(
+            f"{uri!s} is a remote URL that points to local sources, "
+            "replacing it with a local URL in linkcheck to take new changes "
+            "into account (pass -vv for more info)"
+        )
+        logger.debug(f"Replacing linkcheck URL {uri!r} with {local_uri!r}")
+    # Local relative links
+    if not parsed.scheme and not parsed.netloc and parsed.path:
+        full_path = pathlib.Path(app.env.docname).parent / parsed.path
+        local_uri = resolve_local_html_link(app, os.fspath(full_path))
+        if local_uri != uri:
+            logger.verbose(f"Local linkcheck URL {uri!r} resolved as {local_uri!r}")
+    return local_uri
+
+
+def setup(app: sphinx.application.Sphinx) -> dict[str, bool]:
+    app.connect("linkcheck-process-uri", rewrite_local_uri)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

source/conf.py

@@ -2,6 +2,11 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 import os
+import pathlib
+import sys
+
+_ROOT = pathlib.Path(__file__).resolve().parent.parent
+sys.path.append(os.fspath(_ROOT))
 
 # Some options are only enabled for the main packaging.python.org deployment builds
 RTD_BUILD = bool(os.getenv("READTHEDOCS"))
@@ -22,6 +27,7 @@
 root_doc = "index"
 
 extensions = [
+    "pug_sphinx_extensions",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
@@ -133,7 +139,6 @@
 
 linkcheck_ignore = [
     r"http://localhost:\d+",
-    r"https://packaging\.python\.org/en/latest/specifications/schemas/.*",
     r"https://test\.pypi\.org/project/example-package-YOUR-USERNAME-HERE",
     r"https://pypi\.org/manage/.*",
     r"https://test\.pypi\.org/manage/.*",
@@ -151,6 +156,10 @@
     r"https://click\.palletsprojects\.com/.*",
     r"https://typer\.tiangolo\.com/.*",
     r"https://www.npmjs.com/.*",
+    r"https://docutils\.sourceforge\.io/.*",
+    # Temporarily ignored due to expired TLS cert.
+    # Ref: https://github.com/pypa/packaging.python.org/issues/1998
+    r"https://blog\.ganssle\.io/.*",
 ]
 linkcheck_retries = 5
 # Ignore anchors for common targets when we know they likely won't be found
@@ -162,9 +171,6 @@
     # https://github.com/pypa/packaging.python.org/issues/1744
     r"https://pypi\.org/",
 ]
-linkcheck_exclude_documents = [
-    "specifications/schemas/index",
-]
 
 # -- Options for extlinks ----------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html#configuration

source/glossary.rst

@@ -160,7 +160,7 @@ Glossary
 
         A string with valid SPDX license expression syntax,
         including one or more SPDX :term:`License Identifier`\(s),
-        which describes a :term:`Project`'s license(s)
+        which describes a :term:`Distribution Archive`'s license(s)
         and how they inter-relate.
         Examples:
         ``GPL-3.0-or-later``,
@@ -287,8 +287,7 @@ Glossary
         PyPA is a working group that maintains many of the relevant
         projects in Python packaging. They maintain a site at
         :doc:`pypa.io <pypa:index>`, host projects on `GitHub
-        <https://github.com/pypa>`_ and `Bitbucket
-        <https://bitbucket.org/pypa>`_, and discuss issues on the
+        <https://github.com/pypa>`_, and discuss issues on the
         `distutils-sig mailing list
         <https://mail.python.org/mailman3/lists/distutils-sig.python.org/>`_
 	and `the Python Discourse forum <https://discuss.python.org/c/packaging>`__.

source/guides/creating-command-line-tools.rst

@@ -154,7 +154,7 @@ To just run the program without installing it permanently, use ``pipx run``, whi
 	$ pipx run --spec . greet --doctor
 
 This syntax is a bit impractical, however; as the name of the entry point we defined above does not match the package name,
-we need to state explicitly which executable script to run (even though there is only on in existence).
+we need to state explicitly which executable script to run (even though there is only one in existence).
 
 There is, however, a more practical solution to this problem, in the form of an entry point specific to ``pipx run``.
 The same can be defined as follows in :file:`pyproject.toml`:

source/guides/github-actions-ci-cd-sample/publish-to-pypi.yml

@@ -8,11 +8,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         persist-credentials: false
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: "3.x"
     - name: Install pypa/build
@@ -24,7 +24,7 @@ jobs:
     - name: Build a binary wheel and a source tarball
       run: python3 -m build
     - name: Store the distribution packages
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v5
       with:
         name: python-package-distributions
         path: dist/
@@ -44,7 +44,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v6
       with:
         name: python-package-distributions
         path: dist/
@@ -66,7 +66,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v6
       with:
         name: python-package-distributions
         path: dist/

source/guides/licensing-examples-and-user-scenarios.rst

@@ -6,8 +6,8 @@ Licensing examples and user scenarios
 =====================================
 
 
-:pep:`639` has specified the way to declare a project's license and paths to
-license files and other legally required information.
+:pep:`639` has specified the way to declare a :term:`Distribution Archive`'s
+license and paths to license files and other legally required information.
 This document aims to provide clear guidance how to migrate from the legacy
 to the standardized way of declaring licenses.
 Make sure your preferred build backend supports :pep:`639` before
@@ -53,7 +53,7 @@ Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:
     [metadata]
     license = MIT
 
-The output Core Metadata for the distribution packages would then be:
+The output Core Metadata for the :term:`Distribution Package` would then be:
 
 .. code-block:: email
 
@@ -63,8 +63,9 @@ The output Core Metadata for the distribution packages would then be:
 The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/LICENSE`
 in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/LICENSE`
 in the wheel, and unpacked from there into the site directory (e.g.
-:file:`site-packages/`) on installation; :file:`/` is the root of the respective archive
-and ``{VERSION}`` the version of the Setuptools release in the Core Metadata.
+:file:`site-packages/`) on installation; :file:`/` is the root of the respective
+archive and ``{VERSION}`` the version of the Setuptools release in the Core
+Metadata.
 
 
 .. _licensing-example-advanced:
@@ -83,7 +84,7 @@ directories; specifically:
     ordered-set==3.1.1
     more_itertools==8.8.0
 
-The license expressions for these projects are:
+The appropriate license expressions are:
 
 .. code-block:: text
 
@@ -287,7 +288,7 @@ and make sure to remove any legacy ``license`` table subkeys or
 ``License ::`` classifiers. Your existing ``license`` value may already
 be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc);
 otherwise, check the `SPDX license list <spdxlist_>`__ for the identifier
-that matches the license used in your project.
+that matches the license used.
 
 Make sure to list your license files under ``license-files``
 under ``[project]`` in :file:`pyproject.toml`
@@ -312,12 +313,11 @@ to describe the licenses involved and the relationship
 between them.
 
 In short, ``License-1 AND License-2`` mean that *both* licenses apply
-to your project, or parts of it (for example, you included a file
-under another license), and ``License-1 OR License-2`` means that
-*either* of the licenses can be used, at the user's option (for example,
-you want to allow users a choice of multiple licenses). You can use
-parenthesis (``()``) for grouping to form expressions that cover even the most
-complex situations.
+(for example, you included a file under another license), and
+``License-1 OR License-2`` means that *either* of the licenses can be used, at
+the user's option (for example, you want to allow users a choice of multiple
+licenses). You can use parenthesis (``()``) for grouping to form expressions
+that cover even the most complex situations.
 
 In your project config file, enter your license expression under
 ``license`` (``[project]`` table of :file:`pyproject.toml`),

source/guides/multi-version-installs.rst

@@ -37,7 +37,3 @@ time, but that approach does mean that standard command line invocations of
 the affected tools can't be used - it's necessary to write a custom
 wrapper script or use ``python3 -c '<command>'`` to invoke the application's
 main entry point directly.
-
-Refer to the `pkg_resources documentation
-<https://setuptools.readthedocs.io/en/latest/pkg_resources.html#workingset-objects>`__
-for more details.

source/guides/packaging-namespace-packages.rst

@@ -159,8 +159,7 @@ Legacy namespace packages
 
 These two methods, that were used to create namespace packages prior to :pep:`420`,
 are now considered to be obsolete and should not be used unless you need compatibility
-with packages already using this method. Also, :doc:`pkg_resources <setuptools:pkg_resources>`
-has been deprecated.
+with packages already using one of these methods.
 
 To migrate an existing package, all packages sharing the namespace must be migrated simultaneously.
 
@@ -176,7 +175,7 @@ pkgutil-style namespace packages
 Python 2.3 introduced the :doc:`pkgutil <python:library/pkgutil>` module and the
 :py:func:`python:pkgutil.extend_path` function. This can be used to declare namespace
 packages that need to be compatible with both Python 2.3+ and Python 3. This
-is the recommended approach for the highest level of compatibility.
+was the recommended approach for the highest level of compatibility.
 
 To create a pkgutil-style namespace package, you need to provide an
 :file:`__init__.py` file for the namespace package:
@@ -216,10 +215,18 @@ in the `pkgutil namespace example project`_.
 pkg_resources-style namespace packages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-:doc:`Setuptools <setuptools:index>` provides the `pkg_resources.declare_namespace`_ function and
+.. warning::
+
+    The information in this section is obsolete and is no longer functional
+    (as of Setuptools 82.0.0). It is only retained for historical reference.
+
+    ``pkg_resources`` has been deprecated and was fully removed in Setuptools 82.0.0.
+
+:doc:`Setuptools <setuptools:index>` previously provided the ``pkg_resources.declare_namespace`` function and
 the ``namespace_packages`` argument to :func:`~setuptools.setup`. Together
-these can be used to declare namespace packages. While this approach is no
-longer recommended, it is widely present in most existing namespace packages.
+these could be used to declare namespace packages. While this approach is no
+longer supported, it may still be encountered in environments using older
+``setuptools`` versions.
 If you are creating a new distribution within an existing namespace package that
 uses this method then it's recommended to continue using this as the different
 methods are not cross-compatible and it's not advisable to try to migrate an
@@ -281,11 +288,3 @@ to :func:`~setuptools.setup` in :file:`setup.py`. For example:
         packages=find_packages()
         namespace_packages=['mynamespace']
     )
-
-A complete working example of two pkg_resources-style namespace packages can be found
-in the `pkg_resources namespace example project`_.
-
-.. _pkg_resources.declare_namespace:
-    https://setuptools.readthedocs.io/en/latest/pkg_resources.html#namespace-package-support
-.. _pkg_resources namespace example project:
-    https://github.com/pypa/sample-namespace-packages/tree/master/pkg_resources