From 9b0bc495a5ed6338160a2c7fcba9749a883a0c3f Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Wed, 31 Aug 2022 12:23:51 +0200 Subject: [PATCH 001/733] Added obsolete fields: requires, provides and obsoletes closes: #1107 --- source/specifications/core-metadata.rst | 86 +++++++++++++++++++++++++ 1 file changed, 86 insertions(+) diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index 2e85d0909..4a335ec10 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -755,6 +755,92 @@ Examples:: Obsoletes-Dist: OtherProject (<3.0) Obsoletes-Dist: Foo; os_name == "posix" + +Deprecated Fields +================= + +Requires +-------- + +.. versionadded:: 1.1 +.. deprecated:: 1.2 + in favour of ``Requires-Dist`` + +Each entry contains a string describing some other module or package required +by this package. + +The format of a requirement string is identical to that of a module or package +name usable with the ‘import’ statement, optionally followed by a version +declaration within parentheses. + +A version declaration is a series of conditional operators and version numbers, +separated by commas. Conditional operators must be one of "<", ">"', "<=", +">=", "==", and "!=". Version numbers must be in the format accepted by the +``distutils.version.StrictVersion`` class: two or three dot-separated numeric +components, with an optional "pre-release" tag on the end consisting of the +letter 'a' or 'b' followed by a number. Example version numbers are "1.0", +"2.3a2", "1.3.99", + +Any number of conditional operators can be specified, e.g. the string ">1.0, +!=1.3.4, <2.0" is a legal version declaration. + +All of the following are possible requirement strings: "rfc822", "zlib +(>=1.1.4)", "zope". + +There’s no canonical list of what strings should be used; the Python community +is left to choose its own standards. + +Examples:: + + Requires: re + Requires: sys + Requires: zlib + Requires: xml.parsers.expat (>1.0) + Requires: psycopg + + +Provides +-------- + +.. versionadded:: 1.1 +.. deprecated:: 1.2 + in favour of ``Provides-Dist`` + +Each entry contains a string describing a package or module that will be +provided by this package once it is installed. These strings should match the +ones used in Requirements fields. A version declaration may be supplied +(without a comparison operator); the package’s version number will be implied +if none is specified. + +Examples:: + + Provides: xml + Provides: xml.utils + Provides: xml.utils.iso8601 + Provides: xml.dom + Provides: xmltools (1.3) + + +Obsoletes +--------- + +.. versionadded:: 1.1 +.. deprecated:: 1.2 + in favour of ``Obsoletes-Dist`` + +Each entry contains a string describing a package or module that this package +renders obsolete, meaning that the two packages should not be installed at the +same time. Version declarations can be supplied. + +The most common use of this field will be in case a package name changes, e.g. +Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install Torqued +Python, the Gorgon package should be removed. + +Example:: + + Obsoletes: Gorgon + + ---- .. [1] reStructuredText markup: From e89d5f2d1bbd6b8d4a7262058443ab2d3aa4f9ba Mon Sep 17 00:00:00 2001 From: Brian Rutledge Date: Mon, 5 Dec 2022 09:35:39 -0500 Subject: [PATCH 002/733] Update source/specifications/core-metadata.rst --- source/specifications/core-metadata.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index 4a335ec10..04213aedc 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -770,7 +770,7 @@ Each entry contains a string describing some other module or package required by this package. The format of a requirement string is identical to that of a module or package -name usable with the ‘import’ statement, optionally followed by a version +name usable with the ``import`` statement, optionally followed by a version declaration within parentheses. A version declaration is a series of conditional operators and version numbers, From 3ab0328dbd8208c4dae3aad9a5182ef6052a0b3a Mon Sep 17 00:00:00 2001 From: konstin Date: Mon, 12 Dec 2022 00:13:22 +0100 Subject: [PATCH 003/733] Dependency Specifiers: Don't require whitespace after URL otherwise would `numpy @ https://example.org/numpy` is not a valid specifier (missing whitespace after the URL). This already what pip and packaging do and also what the parsley grammar says --- source/specifications/dependency-specifiers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst index a5bc52bc7..5453e367c 100644 --- a/source/specifications/dependency-specifiers.rst +++ b/source/specifications/dependency-specifiers.rst @@ -113,7 +113,7 @@ Giving us a rule for name based requirements:: And a rule for direct reference specifications:: - url_req = name wsp* extras? wsp* urlspec wsp+ quoted_marker? + url_req = name wsp* extras? wsp* urlspec (wsp+ quoted_marker?)? Leading to the unified rule that can specify a dependency.:: From 4193e048f5bac6b5e996000e329cddc069a0a40a Mon Sep 17 00:00:00 2001 From: konstin Date: Mon, 12 Dec 2022 00:17:35 +0100 Subject: [PATCH 004/733] Dependency Specifiers: Require whitespace before `in` and `not in` Otherwise `numpy; os_namein 'posix'` would be a valid specifier which it isn't --- source/specifications/dependency-specifiers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst index 5453e367c..9b29669d9 100644 --- a/source/specifications/dependency-specifiers.rst +++ b/source/specifications/dependency-specifiers.rst @@ -70,7 +70,7 @@ URI is defined in :rfc:`std-66 <3986>`):: Environment markers allow making a specification only take effect in some environments:: - marker_op = version_cmp | (wsp* 'in') | (wsp* 'not' wsp+ 'in') + marker_op = version_cmp | (wsp+ 'in') | (wsp+ 'not' wsp+ 'in') python_str_c = (wsp | letter | digit | '(' | ')' | '.' | '{' | '}' | '-' | '_' | '*' | '#' | ':' | ';' | ',' | '/' | '?' | '[' | ']' | '!' | '~' | '`' | '@' | '$' | '%' | '^' | From f91e32f29244fb8a9d313a9701b81036de25842e Mon Sep 17 00:00:00 2001 From: konstin Date: Mon, 12 Dec 2022 00:19:24 +0100 Subject: [PATCH 005/733] Dependency Specifiers: Require whitespace after `in` and `not in` Otherwise `numpy; os_name in'posix'` and `numpy; os_name inos_name` would be valid. pypa/packaging 22.0 actually allows currently `numpy; os_name in'posix'` --- source/specifications/dependency-specifiers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst index 9b29669d9..8fc445013 100644 --- a/source/specifications/dependency-specifiers.rst +++ b/source/specifications/dependency-specifiers.rst @@ -70,7 +70,7 @@ URI is defined in :rfc:`std-66 <3986>`):: Environment markers allow making a specification only take effect in some environments:: - marker_op = version_cmp | (wsp+ 'in') | (wsp+ 'not' wsp+ 'in') + marker_op = version_cmp | (wsp+ 'in' wsp+) | (wsp+ 'not' wsp+ 'in' wsp+) python_str_c = (wsp | letter | digit | '(' | ')' | '.' | '{' | '}' | '-' | '_' | '*' | '#' | ':' | ';' | ',' | '/' | '?' | '[' | ']' | '!' | '~' | '`' | '@' | '$' | '%' | '^' | From 7ebb12fa35b86aef643c62b4f679d2c499083a1b Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Fri, 23 Dec 2022 22:54:38 +0000 Subject: [PATCH 006/733] Partially flesh out the "Implementing binary extensions" section This makes the bullet points into proper headings and fleshes out the section on the stable ABI. --- source/guides/packaging-binary-extensions.rst | 57 +++++++++++++++---- 1 file changed, 47 insertions(+), 10 deletions(-) diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index f27eb4730..e7bf37c03 100644 --- a/source/guides/packaging-binary-extensions.rst +++ b/source/guides/packaging-binary-extensions.rst @@ -169,7 +169,7 @@ wrapper modules up to date. for automatic wrapping with Cython. It also supports performance-oriented Python implementations that provide a CPython-like C-API, such as PyPy and Pyston. - + * :doc:`pybind11 ` is a pure C++11 library that provides a clean C++ interface to the CPython (and PyPy) C API. It does not require a pre-processing step; it is written entirely in @@ -230,18 +230,55 @@ The CPython :doc:`Extending and Embedding ` guide includes an introduction to writing a :doc:`custom extension module in C `. -.. +FIXME: Elaborate that all this is one of the reasons why you probably +*don't* want to handcode your extension modules :) - FIXME - * mention the stable ABI (3.2+, link to the CPython C API docs) - * mention the module lifecycle - * mention the challenges of shared static state and subinterpreters - * mention the implications of the GIL for extension modules - * mention the memory allocation APIs in 3.4+ +Extension module lifecycle +-------------------------- + +FIXME: This section needs to be fleshed out. + + +Implications of shared static state and subinterpreters +------------------------------------------------------- + +FIXME: This section needs to be fleshed out. + + +Implications of the GIL +----------------------- + +FIXME: This section needs to be fleshed out. + + +Memory allocation APIs +---------------------- + +FIXME: This section needs to be fleshed out. + + +.. _cpython-stable-abi: + +ABI Compatibility +----------------- + +The CPython C API does not guarantee ABI stability between minor releases +(3.2, 3.3, 3.4, etc.). This means that, typically, if you build an +extension module against one version of Python, it is only guaranteed to +work with the same minor version of Python and not with any other minor +versions. + +Python 3.2 introduced the Limited API, with is a well-defined subset of +Python's C API. The symbols needed for the Limited API form the +"Stable ABI" which is guaranteed to be compatible across all Python 3.x +versions. Wheels containing extensions built against the stable ABI use +the ``abi3`` ABI tag, to reflect that they're compatible with all Python +3.x versions. - * mention again that all this is one of the reasons why you probably *don't* - want to handcode your extension modules :) +CPython's :doc:`C API stability` page provides +detailed information about the API / ABI stability guarantees, how to use +the Limited API and the exact contents of the "Limited API". Building binary extensions From b18fd614fb5ad43bc4468396bf2d98410ea2d11a Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Fri, 23 Dec 2022 23:01:15 +0000 Subject: [PATCH 007/733] Clarify how building extensions for multiple platforms scales This also mentions the use-case for the stable ABI for reducing the wheel compatibility matrix sizes. --- source/guides/packaging-binary-extensions.rst | 23 +++++++++++++------ 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index e7bf37c03..6a4ba6c52 100644 --- a/source/guides/packaging-binary-extensions.rst +++ b/source/guides/packaging-binary-extensions.rst @@ -288,13 +288,22 @@ Building extensions for multiple platforms ------------------------------------------ If you plan to distribute your extension, you should provide -:term:`wheels ` for all the platforms you intend to support. For most -extensions, this is at least one package per Python version times the number of -OS and architectures you support. These are usually built on continuous -integration (CI) systems. There are tools to help you build highly -redistributable binaries from CI; these include :ref:`cibuildwheel` and -:ref:`multibuild`. - +:term:`wheels ` for all the platforms you intend to support. These +are usually built on continuous integration (CI) systems. There are tools +to help you build highly redistributable binaries from CI; these include +:ref:`cibuildwheel` and :ref:`multibuild`. + +For most extensions, you will need to build wheels for all the platforms +you intend to support. This means that the number of wheels you need to +build is the product of:: + + count(Python minor versions) * count(OS) * count(architectures) + +Using CPython's :ref:`Stable ABI ` can help significantly +reduce the number of wheels you need to provide, since a single wheel on a +platform can be used with all Python minor versions; eliminating one dimension +of the matrix. It also removes the need to generate new wheels for each new +minor version of Python. Binary extensions for Windows ----------------------------- From 04bf1bbe261b3a5323280ca637229cfe0b3d57b5 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Fri, 23 Dec 2022 23:03:40 +0000 Subject: [PATCH 008/733] Partially flesh out "Publishing binary extensions" section This converts the items from the existing FIXME that are still relevant while fleshing out the topic of binary-only releases. --- source/guides/packaging-binary-extensions.rst | 24 +++++++++++-------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index 6a4ba6c52..eebbb10d6 100644 --- a/source/guides/packaging-binary-extensions.rst +++ b/source/guides/packaging-binary-extensions.rst @@ -356,20 +356,24 @@ Spinning Wheels wiki Publishing binary extensions ============================ -For interim guidance on this topic, see the discussion in -:issue:`this issue <284>`. +Publishing binary extensions through PyPI uses the same upload mechanisms as +publishing pure Python packages. You build a wheel file for your extension +using the build-backend and upload it to PyPI using +`twine `_. -.. +Avoid binary-only releases +-------------------------- - FIXME +It is strongly recommended that you publish your binary extensions as +well as the source code that was used to build them. This allows users to +build the extension from source if they need to. Notably, this is required +for certain Linux distributions that build from source within their +own build systems for the distro package repositories. - * cover publishing as wheel files on PyPI or a custom index server - * cover creation of Windows and macOS installers - * cover weak linking - * mention the fact that Linux distros have a requirement to build from - source in their own build systems, so binary-only releases are strongly - discouraged +Weak linking +------------ +FIXME: This section needs to be fleshed out. Additional resources ==================== From 42ba363fc32c34ccb053b18582e9cbfa9d66632b Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Fri, 23 Dec 2022 23:04:03 +0000 Subject: [PATCH 009/733] Add a FIXME for covering build-backends for extension building --- source/guides/packaging-binary-extensions.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index eebbb10d6..0c6187c29 100644 --- a/source/guides/packaging-binary-extensions.rst +++ b/source/guides/packaging-binary-extensions.rst @@ -284,6 +284,8 @@ the Limited API and the exact contents of the "Limited API". Building binary extensions ========================== +FIXME: Cover the build-backends available for building extensions. + Building extensions for multiple platforms ------------------------------------------ From 34a2f84bf94e5d590e8f9bd32f67fee33582e836 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=A9mie=20Tarot?= Date: Fri, 9 Jun 2023 14:09:17 +0200 Subject: [PATCH 010/733] Fix typos in Recording installed packages spec --- source/specifications/recording-installed-packages.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst index bac887b2b..fe33df438 100644 --- a/source/specifications/recording-installed-packages.rst +++ b/source/specifications/recording-installed-packages.rst @@ -234,7 +234,7 @@ packages into a Python environment to ensure that other tools are not used to uninstall or otherwise modify that installed package, as doing so may cause compatibility problems with the wider environment. -To achieve this, affected tools should take the folllowing steps: +To achieve this, affected tools should take the following steps: * Rename or remove the ``RECORD`` file to prevent changes via other tools (e.g. appending a suffix to create a non-standard ``RECORD.tool`` file if the tool @@ -246,7 +246,7 @@ To achieve this, affected tools should take the folllowing steps: Python runtime providers may also prevent inadvertent modification of platform provided packages by modifying the default Python package installation scheme -to use a location other than that used by platform provided packages (while also +to use a location other than that used by distribution packages (while also ensuring both locations appear on the default Python import path). In some circumstances, it may be desirable to block even installation of From 7451a0b16e7c01517ec061d78d9fffdd66ab690f Mon Sep 17 00:00:00 2001 From: chrysle Date: Fri, 16 Jun 2023 15:53:59 +0200 Subject: [PATCH 011/733] Integrate pre-commit and add trailing-whitespace hook --- .github/workflows/test.yml | 2 +- .pre-commit-config.yaml | 5 +++++ noxfile.py | 19 ++++++++++++++++-- .../deploying-python-applications.rst | 20 +++++++++---------- source/glossary.rst | 2 +- .../guides/dropping-older-python-versions.rst | 8 ++++---- ...talling-stand-alone-command-line-tools.rst | 2 +- .../guides/installing-using-linux-tools.rst | 6 +++--- .../guides/making-a-pypi-friendly-readme.rst | 2 +- source/guides/packaging-binary-extensions.rst | 2 +- .../guides/packaging-namespace-packages.rst | 4 ++-- ...s-using-github-actions-ci-cd-workflows.rst | 2 +- .../direct-url-data-structure.rst | 14 ++++++------- .../specifications/simple-repository-api.rst | 2 +- source/tutorials/creating-documentation.rst | 2 +- 15 files changed, 56 insertions(+), 36 deletions(-) create mode 100644 .pre-commit-config.yaml diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index b0fc5300c..58505e1a5 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,6 +1,6 @@ name: Test -on: +on: push: pull_request: schedule: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000..1c21dbb04 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,5 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: trailing-whitespace diff --git a/noxfile.py b/noxfile.py index fe7872995..884b6ad08 100644 --- a/noxfile.py +++ b/noxfile.py @@ -18,13 +18,14 @@ def translation(session): session.install("-r", "requirements.txt") target_dir = "locales" session.run( - "sphinx-build", + "sphinx-build", "-b", "gettext", # build gettext-style message catalogs (.pot file) "-d", ".nox/.doctrees/", # path to put the cache "source/", # where the rst files are located target_dir, # where to put the .pot file ) + @nox.session() def build(session, autobuild=False): """ @@ -75,10 +76,24 @@ def linkcheck(session): """ session.install("-r", "requirements.txt") session.run( - "sphinx-build", + "sphinx-build", "-b", "linkcheck", # use linkcheck builder "--color", "-n", "-W", "--keep-going", # be strict "source", # where the rst files are located "build", # where to put the check output ) + + +@nox.session() +def checkqa(session): + """ + Format the guide using pre-commit. + """ + session.install("pre-commit") + session.run( + "pre-commit", + "run", + "--all-files", + "--show-diff-on-failure", + ) diff --git a/source/discussions/deploying-python-applications.rst b/source/discussions/deploying-python-applications.rst index de781d9fd..62e29448f 100644 --- a/source/discussions/deploying-python-applications.rst +++ b/source/discussions/deploying-python-applications.rst @@ -92,12 +92,12 @@ py2exe ^^^^^^ `py2exe `__ is a distutils extension which -allows to build standalone Windows executable programs (32-bit and 64-bit) -from Python scripts. Python versions included in the official development +allows to build standalone Windows executable programs (32-bit and 64-bit) +from Python scripts. Python versions included in the official development cycle are supported (refers to `Status of Python branches`__). py2exe can build console executables and windows (GUI) executables. Building windows services, and DLL/EXE COM servers might work but it is not actively supported. -The distutils extension is released under the MIT-licence and Mozilla +The distutils extension is released under the MIT-licence and Mozilla Public License 2.0. .. __: https://devguide.python.org/#status-of-python-branches @@ -108,8 +108,8 @@ macOS py2app ^^^^^^ -`py2app `__ is a Python setuptools -command which will allow you to make standalone macOS application +`py2app `__ is a Python setuptools +command which will allow you to make standalone macOS application bundles and plugins from Python scripts. Note that py2app MUST be used on macOS to build applications, it cannot create Mac applications on other platforms. py2app is released under the MIT-license. @@ -120,11 +120,11 @@ Unix (including Linux and macOS) pex ^^^ -`pex `__ is a library for generating .pex -(Python EXecutable) files which are executable Python environments in the -spirit of virtualenvs. pex is an expansion upon the ideas outlined in :pep:`441` -and makes the deployment of Python applications as simple as cp. pex files may -even include multiple platform-specific Python distributions, meaning that a +`pex `__ is a library for generating .pex +(Python EXecutable) files which are executable Python environments in the +spirit of virtualenvs. pex is an expansion upon the ideas outlined in :pep:`441` +and makes the deployment of Python applications as simple as cp. pex files may +even include multiple platform-specific Python distributions, meaning that a single pex file can be portable across Linux and macOS. pex is released under the Apache License 2.0. diff --git a/source/glossary.rst b/source/glossary.rst index 2cbde7bed..f8392dbd0 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -42,7 +42,7 @@ Glossary Egg A :term:`Built Distribution` format introduced by :ref:`setuptools`, - which is being replaced by :term:`Wheel`. For details, see + which is being replaced by :term:`Wheel`. For details, see :doc:`The Internal Structure of Python Eggs ` and `Python Eggs `_ diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst index ecb4e59c6..d4fc83c81 100644 --- a/source/guides/dropping-older-python-versions.rst +++ b/source/guides/dropping-older-python-versions.rst @@ -6,7 +6,7 @@ Dropping support for older Python versions Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a "Requires-Python" attribute. -Metadata 1.2+ clients, such as Pip 9.0+, will adhere to this specification by matching the current Python runtime and comparing it with the required version +Metadata 1.2+ clients, such as Pip 9.0+, will adhere to this specification by matching the current Python runtime and comparing it with the required version in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime. This mechanism can be used to drop support for older Python versions, by amending the "Requires-Python" attribute in the package metadata. @@ -102,8 +102,8 @@ metadata values based on the argument you provide in ``python_requires``. Within a Python source package (the zip or the tar-gz file you download) is a text file called PKG-INFO. -This file is generated by Distutils or :ref:`setuptools` when it generates the source package. -The file contains a set of keys and values, the list of keys is part of the PyPa standard metadata format. +This file is generated by Distutils or :ref:`setuptools` when it generates the source package. +The file contains a set of keys and values, the list of keys is part of the PyPa standard metadata format. You can see the contents of the generated file like this: @@ -113,7 +113,7 @@ You can see the contents of the generated file like this: Validate that the following is in place, before publishing the package: -- If you have upgraded correctly, the Metadata-Version value should be 1.2 or higher. +- If you have upgraded correctly, the Metadata-Version value should be 1.2 or higher. - The Requires-Python field is set and matches your specification in setup.py. 4. Using Twine to publish diff --git a/source/guides/installing-stand-alone-command-line-tools.rst b/source/guides/installing-stand-alone-command-line-tools.rst index 78e18fccb..f584cf996 100644 --- a/source/guides/installing-stand-alone-command-line-tools.rst +++ b/source/guides/installing-stand-alone-command-line-tools.rst @@ -66,7 +66,7 @@ For example: \ ^__^ (oo)\_______ - (__)\ )\/ + (__)\ )\/ || || ||----w | diff --git a/source/guides/installing-using-linux-tools.rst b/source/guides/installing-using-linux-tools.rst index 772bbfcbc..8c1fd3f00 100644 --- a/source/guides/installing-using-linux-tools.rst +++ b/source/guides/installing-using-linux-tools.rst @@ -38,7 +38,7 @@ Fedora sudo dnf install python3-pip python3-wheel To learn more about Python in Fedora, please visit the `official Fedora docs`_, -`Python Classroom`_ or `Fedora Loves Python`_. +`Python Classroom`_ or `Fedora Loves Python`_. .. _official Fedora docs: https://developer.fedoraproject.org/tech/languages/python/python-installation.html .. _Python Classroom: https://labs.fedoraproject.org/en/python-classroom/ @@ -54,7 +54,7 @@ To install pip and wheel for the system Python, there are two options: 1. Enable the `EPEL repository `_ using `these instructions - `__. + `__. On EPEL 7, you can install pip and wheel like so: .. code-block:: bash @@ -111,7 +111,7 @@ openSUSE ~~~~~~~~ .. code-block:: bash - + sudo zypper install python3-pip python3-setuptools python3-wheel diff --git a/source/guides/making-a-pypi-friendly-readme.rst b/source/guides/making-a-pypi-friendly-readme.rst index 5e6eef4c7..4f85d5054 100644 --- a/source/guides/making-a-pypi-friendly-readme.rst +++ b/source/guides/making-a-pypi-friendly-readme.rst @@ -58,7 +58,7 @@ such as ``text/plain``, ``text/x-rst`` (for reStructuredText), or ``text/markdow py -m pip install --user --upgrade setuptools wheel twine The minimum required versions of the respective tools are: - + - ``setuptools >= 38.6.0`` - ``wheel >= 0.31.0`` - ``twine >= 1.11.0`` diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index f27eb4730..29d3de303 100644 --- a/source/guides/packaging-binary-extensions.rst +++ b/source/guides/packaging-binary-extensions.rst @@ -169,7 +169,7 @@ wrapper modules up to date. for automatic wrapping with Cython. It also supports performance-oriented Python implementations that provide a CPython-like C-API, such as PyPy and Pyston. - + * :doc:`pybind11 ` is a pure C++11 library that provides a clean C++ interface to the CPython (and PyPy) C API. It does not require a pre-processing step; it is written entirely in diff --git a/source/guides/packaging-namespace-packages.rst b/source/guides/packaging-namespace-packages.rst index 64bce312c..301b53d63 100644 --- a/source/guides/packaging-namespace-packages.rst +++ b/source/guides/packaging-namespace-packages.rst @@ -9,7 +9,7 @@ single :term:`package ` across multiple, separate have the following package structure: .. code-block:: text - + mynamespace/ __init__.py subpackage_a/ @@ -29,7 +29,7 @@ And you use this package in your code like so:: Then you can break these sub-packages into two separate distributions: .. code-block:: text - + mynamespace-subpackage-a/ setup.py mynamespace/ diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 8945821cb..19f70f040 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -138,7 +138,7 @@ Now, whenever you push a tagged commit to your Git repository remote on GitHub, this workflow will publish it to PyPI. And it'll publish any push to TestPyPI which is useful for providing test builds to your alpha users as well as making -sure that your release pipeline remains healthy! +sure that your release pipeline remains healthy! .. _API token: https://pypi.org/help/#apitoken diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst index 2fa567a62..eced739c2 100644 --- a/source/specifications/direct-url-data-structure.rst +++ b/source/specifications/direct-url-data-structure.rst @@ -70,20 +70,20 @@ When ``url`` refers to a source archive or a wheel, the ``archive_info`` key MUST be present as a dictionary with the following keys: - A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a hex - encoded digest of the file. - + encoded digest of the file. + Multiple hashes can be included, and it is up to the consumer to decide what to do with multiple hashes (it may validate all of them or a subset of them, or nothing at - all). - - These hash names SHOULD always be normalized to be lowercase. - + all). + + These hash names SHOULD always be normalized to be lowercase. + Any hash algorithm available via ``hashlib`` (specifically any that can be passed to ``hashlib.new()`` and do not require additional parameters) can be used as a key for the hashes dictionary. At least one secure algorithm from ``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of writing, ``sha256`` specifically is recommended. - + - A deprecated ``hash`` key (type ``string``) MAY be present for backwards compatibility purposes, with value ``=``. diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst index f54713d99..164290310 100644 --- a/source/specifications/simple-repository-api.rst +++ b/source/specifications/simple-repository-api.rst @@ -9,5 +9,5 @@ The current interface for querying available package versions and retrieving packages from an index server is defined in :pep:`503`, with the addition of "yank" support (allowing a kind of file deletion) in :pep:`592`, specifying the interface version provided -by an index server in :pep:`629`, and providing package metadata +by an index server in :pep:`629`, and providing package metadata independently from a package in :pep:`658`. diff --git a/source/tutorials/creating-documentation.rst b/source/tutorials/creating-documentation.rst index 26cffb383..ec960ada0 100644 --- a/source/tutorials/creating-documentation.rst +++ b/source/tutorials/creating-documentation.rst @@ -61,7 +61,7 @@ For more details on the build process, see this `guide`_ by Read The Docs. Other Sources ------------- -For a more detailed guide on how to use Sphinx and reStructuredText, please see this `documentation tutorial`_ on Hitchhiker's Guide to Python. +For a more detailed guide on how to use Sphinx and reStructuredText, please see this `documentation tutorial`_ on Hitchhiker's Guide to Python. .. _documentation tutorial: https://docs.python-guide.org/writing/documentation/ From 2902232cfbfa5880c822002933488ac39c3bcaf7 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Sat, 17 Jun 2023 00:58:33 +0200 Subject: [PATCH 012/733] Update .pre-commit-config.yaml --- .pre-commit-config.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 1c21dbb04..a1a5f58c8 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,5 +1,5 @@ repos: - - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.4.0 - hooks: - - id: trailing-whitespace +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: trailing-whitespace From 036656aff5de261968e89f70624be0d0064222bb Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Thu, 20 Jul 2023 11:10:22 -0500 Subject: [PATCH 013/733] Add warning about reference interop for build numbers --- source/specifications/binary-distribution-format.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst index 317626b18..8f0cb541f 100644 --- a/source/specifications/binary-distribution-format.rst +++ b/source/specifications/binary-distribution-format.rst @@ -134,6 +134,18 @@ build tag the first item being the initial digits as an ``int``, and the second item being the remainder of the tag as a ``str``. + .. warning:: + + Build numbers are not a part of the distribution version and thus are difficult + to reference externally, especially so outside the Python ecosystem of tools and standards. + A common case where a distribution would need to referenced externally is when + resolving a security vulnerability. + + Due to this limitation new distributions which need to be referenced externally + **should not** use build numbers when building the new distribution. + Instead a **new distribution version** should be created for such cases. + + language implementation and version tag E.g. 'py27', 'py2', 'py3'. From 4d2e9ddfd4231fba822fce40d6e5d8be5fb25d37 Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Sat, 22 Jul 2023 21:09:13 -0500 Subject: [PATCH 014/733] Update source/specifications/binary-distribution-format.rst Co-authored-by: Brett Cannon --- source/specifications/binary-distribution-format.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst index 8f0cb541f..0428f15a4 100644 --- a/source/specifications/binary-distribution-format.rst +++ b/source/specifications/binary-distribution-format.rst @@ -141,7 +141,7 @@ build tag A common case where a distribution would need to referenced externally is when resolving a security vulnerability. - Due to this limitation new distributions which need to be referenced externally + Due to this limitation, new distributions which need to be referenced externally **should not** use build numbers when building the new distribution. Instead a **new distribution version** should be created for such cases. From b348a341ffa7a2be530cf76b333a04d58ea47f69 Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Wed, 26 Jul 2023 13:28:15 -0500 Subject: [PATCH 015/733] Add comment about use-case for build numbers --- source/specifications/binary-distribution-format.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst index 0428f15a4..9855ad8ff 100644 --- a/source/specifications/binary-distribution-format.rst +++ b/source/specifications/binary-distribution-format.rst @@ -134,6 +134,11 @@ build tag the first item being the initial digits as an ``int``, and the second item being the remainder of the tag as a ``str``. + A common use-case for build numbers is rebuilding a binary + distribution due to a change in the build environment, + like when using the manylinux image to build + distributions using pre-release CPython versions. + .. warning:: Build numbers are not a part of the distribution version and thus are difficult From 62072b70d7be5a3b5bc8f236b8183524d07000bd Mon Sep 17 00:00:00 2001 From: Dustin Ingram Date: Tue, 1 Aug 2023 11:31:35 -0400 Subject: [PATCH 016/733] Fix broken links (#1279) --- source/guides/single-sourcing-package-version.rst | 2 +- source/specifications/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/guides/single-sourcing-package-version.rst b/source/guides/single-sourcing-package-version.rst index ec85d084d..97a9cb026 100644 --- a/source/guides/single-sourcing-package-version.rst +++ b/source/guides/single-sourcing-package-version.rst @@ -9,7 +9,7 @@ There are many techniques to maintain a single source of truth for the version number of your project: #. Read the file in :file:`setup.py` and get the version. Example (from `pip setup.py - `_):: + `_):: import codecs import os.path diff --git a/source/specifications/index.rst b/source/specifications/index.rst index d7b787b47..4f622d845 100644 --- a/source/specifications/index.rst +++ b/source/specifications/index.rst @@ -6,7 +6,7 @@ PyPA specifications This is a list of currently active interoperability specifications maintained by the Python Packaging Authority. The process for updating these standards, and for proposing new ones, is documented on -`pypa.io `__. +`pypa.io `__. Package Distribution Metadata From c022989c310d0bbeda55afce2234b03fb76a02d0 Mon Sep 17 00:00:00 2001 From: Mike Fiedler Date: Tue, 1 Aug 2023 11:33:44 -0400 Subject: [PATCH 017/733] docs: add notice about PEP 715 (#1278) Refs: https://peps.python.org/pep-0715/ Signed-off-by: Mike Fiedler --- source/discussions/wheel-vs-egg.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/discussions/wheel-vs-egg.rst b/source/discussions/wheel-vs-egg.rst index 9e1bcf3dc..d4a1114fb 100644 --- a/source/discussions/wheel-vs-egg.rst +++ b/source/discussions/wheel-vs-egg.rst @@ -44,6 +44,10 @@ Here's a breakdown of the important differences between :term:`Wheel` and :term: `_, therefore making it easier to convert to other formats. +* :term:`Egg` uploads have been disabled for upload to PyPI, per :pep:`715`. + Read the `deprecation notice `_ + for more information. + ---- .. [1] Circumstantially, in some cases, wheels can be used as an importable From 137713c5be94adb6e4985f2b01bd0d2cc6c7f7c9 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 3 Aug 2023 13:27:34 +0200 Subject: [PATCH 018/733] Add Source distribution archive features (PEP 721) --- .../source-distribution-format.rst | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst index 385828e31..a2fad4873 100644 --- a/source/specifications/source-distribution-format.rst +++ b/source/specifications/source-distribution-format.rst @@ -67,3 +67,73 @@ whatever information they need in the sdist to build the project. The tarball should use the modern POSIX.1-2001 pax tar format, which specifies UTF-8 based file names. In particular, source distribution files must be readable using the standard library tarfile module with the open flag 'r:gz'. + + +.. _sdist-archive-features: + +Source distribution archive features +==================================== + +Because extracting tar files as-is is dangerous, and the results are +platform-specific, archive features of source distributions are limited. + +Unpacking with the data filter +------------------------------ + +When extracting a source distribution, tools MUST either use +``tarfile.data_filter`` (e.g. ``TarFile.extractall(..., filter='data')``), OR +follow the *Unpacking without the data filter* section below. + +As an exception, on Python interpreters without ``hasattr(tarfile, 'data_filter')`` +(:pep:`706`), tools that normally use that filter (directly on indirectly) +MAY warn the user and ignore this specification. +The trade-off between usability (e.g. fully trusting the archive) and +security (e.g. refusing to unpack) is left up to the tool in this case. + + +Unpacking without the data filter +--------------------------------- + +Tools that do not use the ``data`` filter directly (e.g. for backwards +compatibility, allowing additional features, or not using Python) MUST follow +this section. +(At the time of this writing, the ``data`` filter also follows this section, +but it may get out of sync in the future.) + +The following files are invalid in an ``sdist`` archive. +Upon encountering such an entry, tools SHOULD notify the user, +MUST NOT unpack the entry, and MAY abort with a failure: + +- Files that would be placed outside the destination directory. +- Links (symbolic or hard) pointing outside the destination directory. +- Device files (including pipes). + +The following are also invalid. Tools MAY treat them as above, +but are NOT REQUIRED to do so: + +- Files with a ``..`` component in the filename or link target. +- Links pointing to a file that is not part of the archive. + +Tools MAY unpack links (symbolic or hard) as regular files, +using content from the archive. + +When extracting ``sdist`` archives: + +- Leading slashes in file names MUST be dropped. + (This is nowadays standard behaviour for ``tar`` unpacking.) +- For each ``mode`` (Unix permission) bit, tools MUST either: + + - use the platform's default for a new file/directory (respectively), + - set the bit according to the archive, or + - use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or + ``rwxr-xr-x`` (``0o755``) for executable files and directories. + +- High ``mode`` bits (setuid, setgid, sticky) MUST be cleared. +- It is RECOMMENDED to preserve the user *executable* bit. + + +Further hints +------------- + +Tool authors are encouraged to consider how *hints for further +verification* in ``tarfile`` documentation apply for their tool. From 215f801d7bdc0fb3d0bfd0c664db791c6dd62007 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 3 Aug 2023 15:55:32 +0200 Subject: [PATCH 019/733] Add a history section See: https://github.com/pypa/packaging.python.org/issues/1203 --- source/specifications/source-distribution-format.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst index a2fad4873..9706051c6 100644 --- a/source/specifications/source-distribution-format.rst +++ b/source/specifications/source-distribution-format.rst @@ -137,3 +137,13 @@ Further hints Tool authors are encouraged to consider how *hints for further verification* in ``tarfile`` documentation apply for their tool. + + +History +======= + +* August 2023: Stanardized the source distribution archive features (:pep:`721`) +* September 2022: Stanardized the filename of a source distribution (:pep:`625`) +* July 2021: Defined what a source tree is +* November 2020: PEP 643 converted to this specification +* December 2000: Source distributions standardized in :pep:`643` From d07e055f817d63e500768d52f33677a28c6f5397 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sun, 6 Aug 2023 16:38:04 -0700 Subject: [PATCH 020/733] Add missing anchors for core metadata --- source/specifications/core-metadata.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index 644380962..3873090c7 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -40,6 +40,8 @@ to a new format. .. contents:: Contents :local: +.. _core-metadata-metadata-version: + Metadata-Version ================ @@ -133,6 +135,7 @@ project. Full details of the semantics of ``Dynamic`` are described in :pep:`643`. +.. _core-metadata-platform: Platform (multiple use) ======================= @@ -148,6 +151,7 @@ Examples:: Platform: ObscureUnix Platform: RareDOS +.. _core-metadata-supported-platform: Supported-Platform (multiple use) ================================= @@ -340,6 +344,7 @@ Example:: easier to update the specification to match the de facto standard. .. _home-page-optional: +.. _core-metadata-home-page: Home-page ========= @@ -352,6 +357,7 @@ Example:: Home-page: http://www.example.com/~cschultz/bvote/ +.. _core-metadata-download-url: Download-URL ============ @@ -558,6 +564,7 @@ Examples:: Requires-Python: >2.6,!=3.0.*,!=3.1.* Requires-Python: ~=2.6 +.. _core-metadata-requires-external Requires-External (multiple use) ================================ @@ -682,6 +689,7 @@ as they're still potentially useful for informational purposes, and can also be used for their originally intended purpose in combination with a curated package repository. +.. _core-metadata-provides-dist Provides-Dist (multiple use) ---------------------------- @@ -723,6 +731,7 @@ Examples:: Provides-Dist: AnotherProject (3.4) Provides-Dist: virtual_package; python_version >= "3.4" +.. _core-metadata-obsoletes-dist Obsoletes-Dist (multiple use) ----------------------------- From 943e90e7e46f1cdbfd9fe6d62ba85ca2dbb4f9c6 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sun, 6 Aug 2023 16:41:30 -0700 Subject: [PATCH 021/733] Fix malformed hyperlink targets --- source/specifications/core-metadata.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index 3873090c7..453f9d30c 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -564,7 +564,7 @@ Examples:: Requires-Python: >2.6,!=3.0.*,!=3.1.* Requires-Python: ~=2.6 -.. _core-metadata-requires-external +.. _core-metadata-requires-external: Requires-External (multiple use) ================================ @@ -689,7 +689,7 @@ as they're still potentially useful for informational purposes, and can also be used for their originally intended purpose in combination with a curated package repository. -.. _core-metadata-provides-dist +.. _core-metadata-provides-dist: Provides-Dist (multiple use) ---------------------------- @@ -731,7 +731,7 @@ Examples:: Provides-Dist: AnotherProject (3.4) Provides-Dist: virtual_package; python_version >= "3.4" -.. _core-metadata-obsoletes-dist +.. _core-metadata-obsoletes-dist: Obsoletes-Dist (multiple use) ----------------------------- From 0544c45594eee545b25faa4721e1e3a4ea86cdc7 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Mon, 7 Aug 2023 14:40:34 +0200 Subject: [PATCH 022/733] Links & typo fixes Co-authored-by: Sviatoslav Sydorenko --- source/specifications/source-distribution-format.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst index 9706051c6..e154e2952 100644 --- a/source/specifications/source-distribution-format.rst +++ b/source/specifications/source-distribution-format.rst @@ -81,10 +81,10 @@ Unpacking with the data filter ------------------------------ When extracting a source distribution, tools MUST either use -``tarfile.data_filter`` (e.g. ``TarFile.extractall(..., filter='data')``), OR +:py:func:`tarfile.data_filter` (e.g. :py:meth:`TarFile.extractall(..., filter='data') `), OR follow the *Unpacking without the data filter* section below. -As an exception, on Python interpreters without ``hasattr(tarfile, 'data_filter')`` +As an exception, on Python interpreters without :py:func:`hasattr(tarfile, 'data_filter') ` (:pep:`706`), tools that normally use that filter (directly on indirectly) MAY warn the user and ignore this specification. The trade-off between usability (e.g. fully trusting the archive) and @@ -136,14 +136,14 @@ Further hints ------------- Tool authors are encouraged to consider how *hints for further -verification* in ``tarfile`` documentation apply for their tool. +verification* in ``tarfile`` documentation apply to their tool. History ======= -* August 2023: Stanardized the source distribution archive features (:pep:`721`) -* September 2022: Stanardized the filename of a source distribution (:pep:`625`) +* August 2023: Standardized the source distribution archive features (:pep:`721`) +* September 2022: Standardized the filename of a source distribution (:pep:`625`) * July 2021: Defined what a source tree is -* November 2020: PEP 643 converted to this specification +* November 2020: :pep:`643` converted to this specification * December 2000: Source distributions standardized in :pep:`643` From 1416a463fd1ca398e7d87f3692abcd2b9adc47cc Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Mon, 7 Aug 2023 14:43:03 +0200 Subject: [PATCH 023/733] Mark up *sdist* as it's marked up in the definition above --- source/specifications/source-distribution-format.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst index e154e2952..93531430f 100644 --- a/source/specifications/source-distribution-format.rst +++ b/source/specifications/source-distribution-format.rst @@ -100,7 +100,7 @@ this section. (At the time of this writing, the ``data`` filter also follows this section, but it may get out of sync in the future.) -The following files are invalid in an ``sdist`` archive. +The following files are invalid in an *sdist* archive. Upon encountering such an entry, tools SHOULD notify the user, MUST NOT unpack the entry, and MAY abort with a failure: @@ -117,7 +117,7 @@ but are NOT REQUIRED to do so: Tools MAY unpack links (symbolic or hard) as regular files, using content from the archive. -When extracting ``sdist`` archives: +When extracting *sdist* archives: - Leading slashes in file names MUST be dropped. (This is nowadays standard behaviour for ``tar`` unpacking.) From c1718eeb07ca18c93543b25632eeb63de958e5e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BCrgen=20Gmach?= Date: Thu, 10 Aug 2023 09:14:51 +0200 Subject: [PATCH 024/733] Add current URL for Bazaar Both the development of Bazaar and the project's URL `https://bazaar.canonical.com` have been discontinued. Breezy is the community maintained continuation. --- source/specifications/direct-url-data-structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst index eced739c2..eae9d3071 100644 --- a/source/specifications/direct-url-data-structure.rst +++ b/source/specifications/direct-url-data-structure.rst @@ -188,7 +188,7 @@ Bazaar Home page - _`https://bazaar.canonical.com` *(Not responding as of 5/2023)* + https://www.breezy-vcs.org/ vcs command From d441b5b423f9e67754b4817ca956cddd41a265ca Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Thu, 17 Aug 2023 10:42:12 +0200 Subject: [PATCH 025/733] fixed broken link this is unrelated to the pr but satisfies the CI pipeline... --- source/key_projects.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/key_projects.rst b/source/key_projects.rst index a1c2cac7b..0c7b97fa8 100644 --- a/source/key_projects.rst +++ b/source/key_projects.rst @@ -558,7 +558,7 @@ resolution by locally caching metadata about dependencies. pypiserver ========== -`Docs `__ | +`Docs `__ | `GitHub `__ | `PyPI `__ From ffce75bc903f80ffbc9c33eddcb6def4b2636e49 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 18 Aug 2023 17:42:23 -0700 Subject: [PATCH 026/733] Add references to PEPs 691, 700, and 714 to the simple repository API spec page --- .../specifications/simple-repository-api.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst index 164290310..70c0040d2 100644 --- a/source/specifications/simple-repository-api.rst +++ b/source/specifications/simple-repository-api.rst @@ -5,9 +5,16 @@ Simple repository API ===================== -The current interface for querying available package versions and -retrieving packages from an index server is defined in :pep:`503`, -with the addition of "yank" support (allowing a kind of file deletion) -in :pep:`592`, specifying the interface version provided -by an index server in :pep:`629`, and providing package metadata -independently from a package in :pep:`658`. +The interface for querying available package versions and +retrieving packages from an index server comes in two forms: +HTML and JSON. + +The HTML format is defined in :pep:`503`, with the addition of "yank" +support (allowing a kind of file deletion) in :pep:`592`, specifying +the interface version provided by an index server in :pep:`629`, and +providing package metadata independently from a package in +:pep:`658` and revised in :pep:`714`. + +The JSON format is defined in :pep:`691`, with additional fields +added in :pep:`700`, and revisions around providing package metadata +independently from a package in :pep:`714`. From 718e7ef0378027af1f7f2354e754ca071ca7780c Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Mon, 21 Aug 2023 12:58:56 -0700 Subject: [PATCH 027/733] Fix an unrelated URL to get CI passing --- source/key_projects.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/key_projects.rst b/source/key_projects.rst index a1c2cac7b..0c7b97fa8 100644 --- a/source/key_projects.rst +++ b/source/key_projects.rst @@ -558,7 +558,7 @@ resolution by locally caching metadata about dependencies. pypiserver ========== -`Docs `__ | +`Docs `__ | `GitHub `__ | `PyPI `__ From e6c97407c135764387b4d6f17db9bd83ca2e640f Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Wed, 23 Aug 2023 12:11:30 -0700 Subject: [PATCH 028/733] Drop a redundant link --- source/key_projects.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/source/key_projects.rst b/source/key_projects.rst index 0c7b97fa8..d7cf57f4d 100644 --- a/source/key_projects.rst +++ b/source/key_projects.rst @@ -558,7 +558,6 @@ resolution by locally caching metadata about dependencies. pypiserver ========== -`Docs `__ | `GitHub `__ | `PyPI `__ From b869257a3b4011f4c26df89a8758305f03764c7f Mon Sep 17 00:00:00 2001 From: chrysle Date: Wed, 24 May 2023 16:11:08 +0200 Subject: [PATCH 029/733] Add guidance for trusted publishing --- ...s-using-github-actions-ci-cd-workflows.rst | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 19f70f040..9b4d93dac 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -51,6 +51,31 @@ Let's begin! 🚀 create it. It's not the same as a regular PyPI account. +Using trusted publishing +------------------------ + +It is also possible to authenticate to PyPI without having to provide +an `API token`_. This can be done using +PyPI's `trusted publishing`_ implementation. This is recommended +also for security reasons, since the generated tokens are created for each of your projects +individually and expire automatically. + +The following steps will lead you through creating a "pending" publisher. + +1. Go to https://pypi.org/manage/account/publishing/ +2. Now fill in the name you wish to publish your new project under, + your repository data and the name of the release workflow file + under the ``.github/`` folder, see :ref:`workflow-definition`. + Finally add the name of the GitHub Actions environment + running under your repository. + Add the trusted publisher. +3. Your "pending" publisher is no ready for its first use and will + create your project automatically once you use it + for the first time. + + +.. _workflow-definition: + Creating a workflow definition ============================== @@ -150,3 +175,4 @@ sure that your release pipeline remains healthy! https://github.com/marketplace/actions/pypi-publish .. _Secrets: https://docs.github.com/en/actions/reference/encrypted-secrets +.. _trusted publishing: https://docs.pypi.org/trusted-publishers/ From 17993ef46a407c576722645554277d1115991298 Mon Sep 17 00:00:00 2001 From: chrysle Date: Thu, 25 May 2023 10:24:39 +0200 Subject: [PATCH 030/733] Remove steps to generate and use API token --- .../publish-to-test-pypi.yml | 5 +- ...s-using-github-actions-ci-cd-workflows.rst | 68 +++++++------------ 2 files changed, 25 insertions(+), 48 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index 35a2f653d..527cf4a82 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -6,6 +6,8 @@ jobs: build-n-publish: name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI runs-on: ubuntu-latest + permissions: + id-token: write steps: - uses: actions/checkout@v3 @@ -31,10 +33,7 @@ jobs: - name: Publish distribution 📦 to Test PyPI uses: pypa/gh-action-pypi-publish@release/v1 with: - password: ${{ secrets.TEST_PYPI_API_TOKEN }} repository-url: https://test.pypi.org/legacy/ - name: Publish distribution 📦 to PyPI if: startsWith(github.ref, 'refs/tags') uses: pypa/gh-action-pypi-publish@release/v1 - with: - password: ${{ secrets.PYPI_API_TOKEN }} diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 9b4d93dac..95b83886d 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -17,62 +17,40 @@ It will use the `pypa/gh-action-pypi-publish GitHub Action`_. details of building platform specific projects. If you have binary components, check out :ref:`cibuildwheel`'s GitHub Action examples. -Saving credentials on GitHub -============================ - -In this guide, we'll demonstrate uploading to both -PyPI and TestPyPI, meaning that we'll have two separate sets -of credentials. And we'll need to save them in the GitHub repository -settings. - -Let's begin! 🚀 - -1. Go to https://pypi.org/manage/account/#api-tokens and - create a new `API token`_. If you have the project on PyPI - already, limit the token scope to just that project. - You can call it something like - ``GitHub Actions CI/CD — project-org/project-repo`` - in order for it to be easily distinguishable in the token - list. - **Don't close the page just yet — you won't see that token - again.** -2. In a separate browser tab or window, go to the ``Settings`` - tab of your target repository and then click on `Secrets`_ - in the left sidebar. -3. Create a new secret called ``PYPI_API_TOKEN`` and copy-paste - the token from the first step. -4. Now, go to https://test.pypi.org/manage/account/#api-tokens - and repeat the steps. Save that TestPyPI token on GitHub - as ``TEST_PYPI_API_TOKEN``. - - .. attention:: - - If you don't have a TestPyPI account, you'll need to - create it. It's not the same as a regular PyPI account. - +Configuring trusted publishing +============================== -Using trusted publishing ------------------------- +This guide relies on PyPI's `trusted publishing`_ implementation to connect +to `GitHub Actions CI/CD`_. This is recommended for security reasons, since +the generated tokens are created for each of your projects +individually and expire automatically. Otherwise you'll need to generate an +`API token`_ or provide a username/password combination for both PyPI and +TestPyPI. -It is also possible to authenticate to PyPI without having to provide -an `API token`_. This can be done using -PyPI's `trusted publishing`_ implementation. This is recommended -also for security reasons, since the generated tokens are created for each of your projects -individually and expire automatically. +Since this guide will demonstrate uploading to both +PyPI and TestPyPI, we'll need two trusted publishers configured. +The following steps will lead you through creating the "pending" publishers. -The following steps will lead you through creating a "pending" publisher. +Let's begin! 🚀 1. Go to https://pypi.org/manage/account/publishing/ -2. Now fill in the name you wish to publish your new project under, +2. Fill in the name you wish to publish your new project under, your repository data and the name of the release workflow file under the ``.github/`` folder, see :ref:`workflow-definition`. Finally add the name of the GitHub Actions environment running under your repository. - Add the trusted publisher. -3. Your "pending" publisher is no ready for its first use and will - create your project automatically once you use it + Register the trusted publisher. +3. Now, go to https://test.pypi.org/manage/account/publishing/ and repeat + the second step. +4. Your "pending" publishers are now ready for their first use and will + create your projects automatically once you use them for the first time. + .. attention:: + + If you don't have a TestPyPI account, you'll need to + create it. It's not the same as a regular PyPI account. + .. _workflow-definition: From 4c5786743a9fe1fcb0cf8c57ef6713bef33ae372 Mon Sep 17 00:00:00 2001 From: chrysle Date: Mon, 29 May 2023 09:28:11 +0200 Subject: [PATCH 031/733] Apply feedback from code review --- .../publish-to-test-pypi.yml | 44 +++++++++++-- ...s-using-github-actions-ci-cd-workflows.rst | 63 ++++++++++++------- 2 files changed, 80 insertions(+), 27 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index 527cf4a82..f71b44f27 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -3,9 +3,45 @@ name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI on: push jobs: - build-n-publish: - name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI + build-n-publish-pypi: + name: Build and publish Python 🐍 distributions 📦 to PyPI runs-on: ubuntu-latest + environment: + name: pypi + url: https://pypi.org/p/ + permissions: + id-token: write + + steps: + - uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: "3.x" + - name: Install pypa/build + run: >- + python3 -m + pip install + build + --user + - name: Build a binary wheel and a source tarball + run: >- + python3 -m + build + --sdist + --wheel + --outdir dist/ + . + # Actually publish to PyPI + - name: Publish distribution 📦 to PyPI + if: startsWith(github.ref, 'refs/tags') + uses: pypa/gh-action-pypi-publish@release/v1 + build-n-publish-testpypi: + name: Build and publish Python 🐍 distributions 📦 to TestPyPI + runs-on: ubuntu-latest + environment: + name: testpypi + url: https://test.pypi.org/p/ permissions: id-token: write @@ -29,11 +65,7 @@ jobs: --wheel --outdir dist/ . - # Actually publish to PyPI/TestPyPI - name: Publish distribution 📦 to Test PyPI uses: pypa/gh-action-pypi-publish@release/v1 with: repository-url: https://test.pypi.org/legacy/ - - name: Publish distribution 📦 to PyPI - if: startsWith(github.ref, 'refs/tags') - uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 95b83886d..d8b6b7d2f 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -24,19 +24,23 @@ This guide relies on PyPI's `trusted publishing`_ implementation to connect to `GitHub Actions CI/CD`_. This is recommended for security reasons, since the generated tokens are created for each of your projects individually and expire automatically. Otherwise you'll need to generate an -`API token`_ or provide a username/password combination for both PyPI and -TestPyPI. +`API token`_ for both PyPI and TestPyPI. In case of publishing to third-party +indexes like :doc:`devpi `, you will need to provide a +username/password combination. Since this guide will demonstrate uploading to both PyPI and TestPyPI, we'll need two trusted publishers configured. -The following steps will lead you through creating the "pending" publishers. +The following steps will lead you through creating the "pending" publishers +for your new project. However it is also possible to add `trusted publishing`_ +to any pre-existing project, if you are its owner. Let's begin! 🚀 -1. Go to https://pypi.org/manage/account/publishing/ +1. Go to https://pypi.org/manage/account/publishing/. 2. Fill in the name you wish to publish your new project under, - your repository data and the name of the release workflow file - under the ``.github/`` folder, see :ref:`workflow-definition`. + your GitHub username and repository name and + the name of the release workflow file under + the ``.github/`` folder, see :ref:`workflow-definition`. Finally add the name of the GitHub Actions environment running under your repository. Register the trusted publisher. @@ -74,21 +78,24 @@ should make GitHub run this workflow: Defining a workflow job environment =================================== -Now, let's add initial setup for our job. It's a process that -will execute commands that we'll define later. +We will have to define two jobs to publish to PyPI +and TestPyPI respectively. + +Now, let's add initial setup for our job that will publish to PyPI. +It's a process that will execute commands that we'll define later. In this guide, we'll use the latest stable Ubuntu LTS version provided by GitHub Actions: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml :start-after: on: - :end-before: steps: + :end-before: environment: Checking out the project and building distributions =================================================== -Then, add the following under the ``build-n-publish`` section: +Then, add the following under the ``build-n-publish-pypi`` section: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml @@ -96,7 +103,10 @@ Then, add the following under the ``build-n-publish`` section: :end-before: Install pypa/build This will download your repository into the CI runner and then -install and activate the newest available Python 3 release. +install and activate the newest available Python 3 release. It +also defines the package index to publish to, PyPI, and grants +a permission to the action that is mandatory for trusted +publishing. And now we can build dists from source. In this example, we'll use ``build`` package. @@ -114,25 +124,36 @@ So add this to the steps list: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml :start-after: version: "3.x" - :end-before: Actually publish to PyPI/TestPyPI + :end-before: Actually publish to PyPI -Publishing the distribution to PyPI and TestPyPI -================================================ +Publishing the distribution to PyPI +=================================== Finally, add the following steps at the end: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml - :start-after: Actually publish to PyPI/TestPyPI - -These two steps use the `pypa/gh-action-pypi-publish`_ GitHub -Action: the first one uploads contents of the ``dist/`` folder -into TestPyPI unconditionally and the second does that to -PyPI, but only if the current commit is tagged. It is recommended -you use the latest release tag; a tool like GitHub's dependabot can keep + :start-after: Actually publish to PyPI + :end-before: build-n-publish-testpypi + +This step uses the `pypa/gh-action-pypi-publish`_ GitHub +Action: It uploads the contents of the ``dist/`` folder +into PyPI unconditionally, but only if the current commit +is tagged. It is recommended you use the latest release +tag; a tool like GitHub's dependabot can keep these updated regularly. +Separate workflow for publishing to TestPyPI +============================================ + +Now, repeat these steps and create another job for +publishing to the TestPyPI package index under the ``jobs`` +section: + +.. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml + :language: yaml + :start-after: uses: pypa/gh-action-pypi-publish@release/v1 That's all, folks! ================== From b998292a30a71ecbf2cc68de58148ef752d2e996 Mon Sep 17 00:00:00 2001 From: chrysle Date: Fri, 2 Jun 2023 16:40:04 +0200 Subject: [PATCH 032/733] Temporary state --- .../publish-to-test-pypi.yml | 57 +++++++++---------- ...s-using-github-actions-ci-cd-workflows.rst | 3 +- 2 files changed, 28 insertions(+), 32 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index f71b44f27..c6e7c5091 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -3,15 +3,10 @@ name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI on: push jobs: - build-n-publish-pypi: - name: Build and publish Python 🐍 distributions 📦 to PyPI + build: + name: Build the source package runs-on: ubuntu-latest - environment: - name: pypi - url: https://pypi.org/p/ - permissions: - id-token: write - + steps: - uses: actions/checkout@v3 - name: Set up Python @@ -28,11 +23,25 @@ jobs: run: >- python3 -m build - --sdist - --wheel - --outdir dist/ - . - # Actually publish to PyPI + - name: Store the distribution packages + uses: actions/upload-artifact@v3 + with: + name: python-package-distributions + build-n-publish-pypi: + name: Build and publish Python 🐍 distributions 📦 to PyPI + runs-on: ubuntu-latest + environment: + name: pypi + url: https://pypi.org/p/ + permissions: + id-token: write + + steps: + - name: Download all the dists + uses: actions/download-artifact@v3 + with: + name: python-package-distributions + path: dist/ - name: Publish distribution 📦 to PyPI if: startsWith(github.ref, 'refs/tags') uses: pypa/gh-action-pypi-publish@release/v1 @@ -46,25 +55,11 @@ jobs: id-token: write steps: - - uses: actions/checkout@v3 - - name: Set up Python - uses: actions/setup-python@v4 + - name: Download all the dists + uses: actions/download-artifact@v3 with: - python-version: "3.x" - - name: Install pypa/build - run: >- - python3 -m - pip install - build - --user - - name: Build a binary wheel and a source tarball - run: >- - python3 -m - build - --sdist - --wheel - --outdir dist/ - . + name: python-package-distributions + path: dist/ - name: Publish distribution 📦 to Test PyPI uses: pypa/gh-action-pypi-publish@release/v1 with: diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index d8b6b7d2f..e9b4666da 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -79,7 +79,8 @@ Defining a workflow job environment =================================== We will have to define two jobs to publish to PyPI -and TestPyPI respectively. +and TestPyPI respectively, and an additional job to +build the distribution packages. Now, let's add initial setup for our job that will publish to PyPI. It's a process that will execute commands that we'll define later. From 6c43bf4c6b61dbfb3a9128b7cbe75c26edd63142 Mon Sep 17 00:00:00 2001 From: chrysle Date: Tue, 6 Jun 2023 17:36:26 +0200 Subject: [PATCH 033/733] Move build steps into separate job --- ...s-using-github-actions-ci-cd-workflows.rst | 78 +++++++++---------- 1 file changed, 36 insertions(+), 42 deletions(-) diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index e9b4666da..44e626385 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -8,7 +8,9 @@ popular choice is having a workflow that's triggered by a ``push`` event. This guide shows you how to publish a Python distribution whenever a tagged commit is pushed. -It will use the `pypa/gh-action-pypi-publish GitHub Action`_. +It will use the `pypa/gh-action-pypi-publish GitHub Action`_ for +publishing and `upload-artifact`_ and `download-artifact`_ actions +for temporarily storing and downloading the source packages. .. attention:: @@ -74,59 +76,47 @@ should make GitHub run this workflow: :language: yaml :end-before: jobs: - -Defining a workflow job environment -=================================== +Checking out the project and building distributions +=================================================== We will have to define two jobs to publish to PyPI and TestPyPI respectively, and an additional job to build the distribution packages. -Now, let's add initial setup for our job that will publish to PyPI. -It's a process that will execute commands that we'll define later. -In this guide, we'll use the latest stable Ubuntu LTS version -provided by GitHub Actions: - -.. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml - :language: yaml - :start-after: on: - :end-before: environment: - - -Checking out the project and building distributions -=================================================== - -Then, add the following under the ``build-n-publish-pypi`` section: +First, we'll define the job for building the dist packages of +your project and storing them for later use: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml - :start-after: runs-on: + :start-after: jobs: :end-before: Install pypa/build This will download your repository into the CI runner and then -install and activate the newest available Python 3 release. It -also defines the package index to publish to, PyPI, and grants -a permission to the action that is mandatory for trusted -publishing. - -And now we can build dists from source. In this example, we'll -use ``build`` package. - -.. tip:: - - You can use any other method for building distributions as long as - it produces ready-to-upload artifacts saved into the - ``dist/`` folder. You can even use ``actions/upload-artifact`` and - ``actions/download-artifact`` to tranfer files between jobs or make them - accessable for download from the web CI interface. +install and activate the newest available Python 3 release. +And now we can build the dists from source and store them. +In this example, we'll use the ``build`` package. So add this to the steps list: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml :start-after: version: "3.x" - :end-before: Actually publish to PyPI + :end-before: build-n-publish-pypi + +Defining a workflow job environment +=================================== +Now, let's add initial setup for our job that will publish to PyPI. +It's a process that will execute commands that we'll define later. +In this guide, we'll use the latest stable Ubuntu LTS version +provided by GitHub Actions. This also defines the package index +to publish to, PyPI, and grants a permission to the action that +is mandatory for trusted publishing. + +.. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml + :language: yaml + :start-after: name: python-package-distributions + :end-before: steps: Publishing the distribution to PyPI =================================== @@ -135,14 +125,14 @@ Finally, add the following steps at the end: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml - :start-after: Actually publish to PyPI - :end-before: build-n-publish-testpypi + :lines: 39-47 This step uses the `pypa/gh-action-pypi-publish`_ GitHub -Action: It uploads the contents of the ``dist/`` folder -into PyPI unconditionally, but only if the current commit -is tagged. It is recommended you use the latest release -tag; a tool like GitHub's dependabot can keep +Action: After the stored distribution package has been +downloaded by the `download-artifact`_ action, it uploads +the contents of the ``dist/`` folder into PyPI unconditionally, +but only if the current commit is tagged. It is recommended you +use the latest release tag; a tool like GitHub's dependabot can keep these updated regularly. Separate workflow for publishing to TestPyPI @@ -173,6 +163,10 @@ sure that your release pipeline remains healthy! https://github.com/pypa/gh-action-pypi-publish .. _`pypa/gh-action-pypi-publish GitHub Action`: https://github.com/marketplace/actions/pypi-publish +.. _`download-artifact`: + https://github.com/actions/download-artifact +.. _`upload-artifact`: + https://github.com/actions/upload-artifact .. _Secrets: https://docs.github.com/en/actions/reference/encrypted-secrets .. _trusted publishing: https://docs.pypi.org/trusted-publishers/ From 9fe96b6955da3331e86f9c9068d28c249aad68e9 Mon Sep 17 00:00:00 2001 From: chrysle Date: Tue, 13 Jun 2023 17:10:59 +0200 Subject: [PATCH 034/733] Apply suggestions from code review Co-authored-by: Sviatoslav Sydorenko --- .../publish-to-test-pypi.yml | 7 +++---- ...n-releases-using-github-actions-ci-cd-workflows.rst | 10 +++++----- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index c6e7c5091..f82ab400a 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -6,7 +6,6 @@ jobs: build: name: Build the source package runs-on: ubuntu-latest - steps: - uses: actions/checkout@v3 - name: Set up Python @@ -26,8 +25,8 @@ jobs: - name: Store the distribution packages uses: actions/upload-artifact@v3 with: - name: python-package-distributions - build-n-publish-pypi: + name: python-package-distributions + publish-to-pypi: name: Build and publish Python 🐍 distributions 📦 to PyPI runs-on: ubuntu-latest environment: @@ -45,7 +44,7 @@ jobs: - name: Publish distribution 📦 to PyPI if: startsWith(github.ref, 'refs/tags') uses: pypa/gh-action-pypi-publish@release/v1 - build-n-publish-testpypi: + publish-to-testpypi: name: Build and publish Python 🐍 distributions 📦 to TestPyPI runs-on: ubuntu-latest environment: diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 44e626385..d917ca21b 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -9,7 +9,7 @@ popular choice is having a workflow that's triggered by a This guide shows you how to publish a Python distribution whenever a tagged commit is pushed. It will use the `pypa/gh-action-pypi-publish GitHub Action`_ for -publishing and `upload-artifact`_ and `download-artifact`_ actions +publishing. It also uses GitHub's `upload-artifact`_ and `download-artifact`_ actions for temporarily storing and downloading the source packages. .. attention:: @@ -40,11 +40,11 @@ Let's begin! 🚀 1. Go to https://pypi.org/manage/account/publishing/. 2. Fill in the name you wish to publish your new project under, - your GitHub username and repository name and - the name of the release workflow file under - the ``.github/`` folder, see :ref:`workflow-definition`. + your GitHub username and repository name and + the name of the release workflow file under + the ``.github/`` folder, see :ref:`workflow-definition`. Finally add the name of the GitHub Actions environment - running under your repository. + set up under your repository. Register the trusted publisher. 3. Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the second step. From 25ef74516bd1f90289e1aba59cc28b46005dd220 Mon Sep 17 00:00:00 2001 From: chrysle Date: Tue, 13 Jun 2023 17:45:10 +0200 Subject: [PATCH 035/733] Apply more suggestions and fix included fragments --- .../publish-to-test-pypi.yml | 4 +++- ...s-using-github-actions-ci-cd-workflows.rst | 19 +++++++++++-------- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index f82ab400a..d9812596d 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -2,6 +2,9 @@ name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI on: push +# Only trigger this for tag changes. +if: startsWith(github.ref, 'refs/tags/') + jobs: build: name: Build the source package @@ -42,7 +45,6 @@ jobs: name: python-package-distributions path: dist/ - name: Publish distribution 📦 to PyPI - if: startsWith(github.ref, 'refs/tags') uses: pypa/gh-action-pypi-publish@release/v1 publish-to-testpypi: name: Build and publish Python 🐍 distributions 📦 to TestPyPI diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index d917ca21b..76aba47b6 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -44,10 +44,11 @@ Let's begin! 🚀 the name of the release workflow file under the ``.github/`` folder, see :ref:`workflow-definition`. Finally add the name of the GitHub Actions environment - set up under your repository. + (``pypi``) we're going set up under your repository. Register the trusted publisher. 3. Now, go to https://test.pypi.org/manage/account/publishing/ and repeat - the second step. + the second step, but now enter ``testpypi`` as the name of the + GitHub Actions environment. 4. Your "pending" publishers are now ready for their first use and will create your projects automatically once you use them for the first time. @@ -76,6 +77,11 @@ should make GitHub run this workflow: :language: yaml :end-before: jobs: +This will also assure that the release workflow is only triggered +if the current commit is tagged. It is recommended you use the +latest release tag; a tool like GitHub's dependabot can keep +these updated regularly. + Checking out the project and building distributions =================================================== @@ -101,7 +107,7 @@ So add this to the steps list: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml :start-after: version: "3.x" - :end-before: build-n-publish-pypi + :end-before: publish-to-pypi Defining a workflow job environment =================================== @@ -125,15 +131,12 @@ Finally, add the following steps at the end: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml - :lines: 39-47 + :lines: 41-48 This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: After the stored distribution package has been downloaded by the `download-artifact`_ action, it uploads -the contents of the ``dist/`` folder into PyPI unconditionally, -but only if the current commit is tagged. It is recommended you -use the latest release tag; a tool like GitHub's dependabot can keep -these updated regularly. +the contents of the ``dist/`` folder into PyPI unconditionally. Separate workflow for publishing to TestPyPI ============================================ From 1851d9f5d7841b68dd4384d69b281c56885dee84 Mon Sep 17 00:00:00 2001 From: chrysle Date: Fri, 30 Jun 2023 08:56:18 +0200 Subject: [PATCH 036/733] Apply suggestions from code review Co-authored-by: Sviatoslav Sydorenko --- .../publish-to-test-pypi.yml | 28 +++++++++++++------ ...s-using-github-actions-ci-cd-workflows.rst | 17 ++++++----- 2 files changed, 30 insertions(+), 15 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index d9812596d..3c418017f 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -2,13 +2,11 @@ name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI on: push -# Only trigger this for tag changes. -if: startsWith(github.ref, 'refs/tags/') - jobs: build: name: Build the source package runs-on: ubuntu-latest + steps: - uses: actions/checkout@v3 - name: Set up Python @@ -22,15 +20,19 @@ jobs: build --user - name: Build a binary wheel and a source tarball - run: >- - python3 -m - build + run: python3 -m build - name: Store the distribution packages uses: actions/upload-artifact@v3 with: name: python-package-distributions + path: dist/ + publish-to-pypi: - name: Build and publish Python 🐍 distributions 📦 to PyPI + name: >- + Publish Python 🐍 distributions 📦 to PyPI + and sign them with Sigstore + needs: + - build runs-on: ubuntu-latest environment: name: pypi @@ -46,8 +48,18 @@ jobs: path: dist/ - name: Publish distribution 📦 to PyPI uses: pypa/gh-action-pypi-publish@release/v1 + - name: Sign the dists with Sigstore + uses: sigstore/gh-action-sigstore-python@v1.2.3 + with: + inputs: >- + ./dist/*.tar.gz + ./dist/*.whl + publish-to-testpypi: name: Build and publish Python 🐍 distributions 📦 to TestPyPI + if: startsWith(github.ref, 'refs/tags/') # only publish to PyPI on tag pushes + needs: + - build runs-on: ubuntu-latest environment: name: testpypi @@ -61,7 +73,7 @@ jobs: with: name: python-package-distributions path: dist/ - - name: Publish distribution 📦 to Test PyPI + - name: Publish distribution 📦 to TestPyPI uses: pypa/gh-action-pypi-publish@release/v1 with: repository-url: https://test.pypi.org/legacy/ diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 76aba47b6..94f35a0dd 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -25,9 +25,9 @@ Configuring trusted publishing This guide relies on PyPI's `trusted publishing`_ implementation to connect to `GitHub Actions CI/CD`_. This is recommended for security reasons, since the generated tokens are created for each of your projects -individually and expire automatically. Otherwise you'll need to generate an +individually and expire automatically. Otherwise, you'll need to generate an `API token`_ for both PyPI and TestPyPI. In case of publishing to third-party -indexes like :doc:`devpi `, you will need to provide a +indexes like :doc:`devpi `, you may need to provide a username/password combination. Since this guide will demonstrate uploading to both @@ -77,7 +77,7 @@ should make GitHub run this workflow: :language: yaml :end-before: jobs: -This will also assure that the release workflow is only triggered +This will also ensure that the release workflow is only triggered if the current commit is tagged. It is recommended you use the latest release tag; a tool like GitHub's dependabot can keep these updated regularly. @@ -115,9 +115,11 @@ Defining a workflow job environment Now, let's add initial setup for our job that will publish to PyPI. It's a process that will execute commands that we'll define later. In this guide, we'll use the latest stable Ubuntu LTS version -provided by GitHub Actions. This also defines the package index -to publish to, PyPI, and grants a permission to the action that -is mandatory for trusted publishing. +provided by GitHub Actions. This also defines a GitHub Environment +for the job to run in its context and a URL to be displayed in GitHub's +UI nicely. Additionally, it allows aqcuiring an OpenID Connect token +which is mandartory that the ``pypi-publish`` actions needs to +implement secretless trusted publishing to PyPI. .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml @@ -134,9 +136,10 @@ Finally, add the following steps at the end: :lines: 41-48 This step uses the `pypa/gh-action-pypi-publish`_ GitHub -Action: After the stored distribution package has been +Action: after the stored distribution package has been downloaded by the `download-artifact`_ action, it uploads the contents of the ``dist/`` folder into PyPI unconditionally. +This job also signs the artifacts with Sigstore right after publishing them to PyPI. Separate workflow for publishing to TestPyPI ============================================ From 3653382278caaf4a9bc49801545d1a24e4973d2c Mon Sep 17 00:00:00 2001 From: chrysle Date: Fri, 30 Jun 2023 14:39:48 +0200 Subject: [PATCH 037/733] Apply further improvements --- .../publish-to-test-pypi.yml | 6 +-- ...s-using-github-actions-ci-cd-workflows.rst | 42 ++++++++++++++----- 2 files changed, 35 insertions(+), 13 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index 3c418017f..898da663e 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -1,10 +1,10 @@ -name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI +name: Publish Python 🐍 distribution packages 📦 to PyPI and TestPyPI on: push jobs: build: - name: Build the source package + name: Build distribution packages runs-on: ubuntu-latest steps: @@ -29,7 +29,7 @@ jobs: publish-to-pypi: name: >- - Publish Python 🐍 distributions 📦 to PyPI + Publish Python 🐍 distribution packages 📦 to PyPI and sign them with Sigstore needs: - build diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 94f35a0dd..51a3ea598 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -33,13 +33,25 @@ username/password combination. Since this guide will demonstrate uploading to both PyPI and TestPyPI, we'll need two trusted publishers configured. The following steps will lead you through creating the "pending" publishers -for your new project. However it is also possible to add `trusted publishing`_ -to any pre-existing project, if you are its owner. +for your new :term:`PyPI project `. +However it is also possible to add `trusted publishing`_ to any +pre-existing project, if you are its owner. + + .. attention:: + + If you followed earlier versions of this guide, you will + have created the secrets ``PYPI_API_TOKEN`` and ``TEST_PYPI_API_TOKEN`` + for direct PyPI and TestPyPI access. These are obsolete now and + you should remove them from your GitHub repository and revoke + them in your PyPI and TestPyPI account settings. + Let's begin! 🚀 1. Go to https://pypi.org/manage/account/publishing/. -2. Fill in the name you wish to publish your new project under, +2. Fill in the name you wish to publish your new + :term:`PyPI project ` under + (the ``name`` value in your ``setup.cfg`` or ``pyproject.toml``), your GitHub username and repository name and the name of the release workflow file under the ``.github/`` folder, see :ref:`workflow-definition`. @@ -53,12 +65,18 @@ Let's begin! 🚀 create your projects automatically once you use them for the first time. - .. attention:: + .. note:: If you don't have a TestPyPI account, you'll need to create it. It's not the same as a regular PyPI account. + .. hint:: + + For security reasons, you should require manual approval + on each run for the ``pypi`` environment. + + .. _workflow-definition: Creating a workflow definition @@ -79,8 +97,7 @@ should make GitHub run this workflow: This will also ensure that the release workflow is only triggered if the current commit is tagged. It is recommended you use the -latest release tag; a tool like GitHub's dependabot can keep -these updated regularly. +latest release tag. Checking out the project and building distributions =================================================== @@ -123,7 +140,7 @@ implement secretless trusted publishing to PyPI. .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml - :start-after: name: python-package-distributions + :start-after: path: dist/ :end-before: steps: Publishing the distribution to PyPI @@ -133,13 +150,15 @@ Finally, add the following steps at the end: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml - :lines: 41-48 + :start-after: id-token: write + :end-before: publish-to-testpypi: This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the stored distribution package has been downloaded by the `download-artifact`_ action, it uploads the contents of the ``dist/`` folder into PyPI unconditionally. -This job also signs the artifacts with Sigstore right after publishing them to PyPI. +This job also signs the artifacts with the `sigstore/gh-action-sigstore-python`_ +GitHub Action publishing them to PyPI. Separate workflow for publishing to TestPyPI ============================================ @@ -150,7 +169,8 @@ section: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml - :start-after: uses: pypa/gh-action-pypi-publish@release/v1 + :start-after: ./dist/*.whl + That's all, folks! ================== @@ -173,6 +193,8 @@ sure that your release pipeline remains healthy! https://github.com/actions/download-artifact .. _`upload-artifact`: https://github.com/actions/upload-artifact +.. _`sigstore/gh-action-sigstore-python`: + https://github.com/marketplace/actions/gh-action-sigstore-python .. _Secrets: https://docs.github.com/en/actions/reference/encrypted-secrets .. _trusted publishing: https://docs.pypi.org/trusted-publishers/ From 4580825dae3209228331334c3d7cd2d57134e533 Mon Sep 17 00:00:00 2001 From: chrysle Date: Mon, 24 Jul 2023 16:22:54 +0200 Subject: [PATCH 038/733] Apply suggestions from code review Co-authored-by: Sviatoslav Sydorenko --- .../github-actions-ci-cd-sample/publish-to-test-pypi.yml | 4 ++-- ...bution-releases-using-github-actions-ci-cd-workflows.rst | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index 898da663e..7026aad5f 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -1,4 +1,4 @@ -name: Publish Python 🐍 distribution packages 📦 to PyPI and TestPyPI +name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI on: push @@ -29,7 +29,7 @@ jobs: publish-to-pypi: name: >- - Publish Python 🐍 distribution packages 📦 to PyPI + Publish Python 🐍 distribution 📦 to PyPI and sign them with Sigstore needs: - build diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 51a3ea598..234593670 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -39,11 +39,11 @@ pre-existing project, if you are its owner. .. attention:: - If you followed earlier versions of this guide, you will + If you followed earlier versions of this guide, you have created the secrets ``PYPI_API_TOKEN`` and ``TEST_PYPI_API_TOKEN`` for direct PyPI and TestPyPI access. These are obsolete now and you should remove them from your GitHub repository and revoke - them in your PyPI and TestPyPI account settings. + them in your PyPI and TestPyPI account settings in case you are replacing your old setup with the new one. Let's begin! 🚀 @@ -135,7 +135,7 @@ In this guide, we'll use the latest stable Ubuntu LTS version provided by GitHub Actions. This also defines a GitHub Environment for the job to run in its context and a URL to be displayed in GitHub's UI nicely. Additionally, it allows aqcuiring an OpenID Connect token -which is mandartory that the ``pypi-publish`` actions needs to +which is mandatory that the ``pypi-publish`` actions needs to implement secretless trusted publishing to PyPI. .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml From 1f4a242fc383e276422af9f7168e682d237d3d91 Mon Sep 17 00:00:00 2001 From: chrysle Date: Sat, 26 Aug 2023 11:18:49 +0200 Subject: [PATCH 039/733] Apply further suggestions and improvements Add `sphinx-toolbox` dependency. --- requirements.txt | 1 + source/conf.py | 1 + .../publish-to-test-pypi.yml | 52 +++++++++----- ...s-using-github-actions-ci-cd-workflows.rst | 67 ++++++++++++------- 4 files changed, 79 insertions(+), 42 deletions(-) diff --git a/requirements.txt b/requirements.txt index 125f0cf33..17492e03c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,3 +4,4 @@ sphinx-inline-tabs==2021.4.11b9 python-docs-theme==2022.1 sphinx-copybutton==0.5.0 pypa-docs-theme @ git+https://github.com/pypa/pypa-docs-theme.git +sphinx-toolbox==3.5.0 diff --git a/source/conf.py b/source/conf.py index 7ff60c18c..9113b8c68 100644 --- a/source/conf.py +++ b/source/conf.py @@ -36,6 +36,7 @@ 'sphinx.ext.todo', 'sphinx_inline_tabs', 'sphinx_copybutton', + 'sphinx_toolbox.collapse', ] # config for copy button diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index 7026aad5f..28663d51f 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -1,10 +1,10 @@ -name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI +name: Publish Python 🐍 distribution 📦 to PyPI and TestPyPI on: push jobs: build: - name: Build distribution packages + name: Build distribution 📦 runs-on: ubuntu-latest steps: @@ -30,34 +30,52 @@ jobs: publish-to-pypi: name: >- Publish Python 🐍 distribution 📦 to PyPI - and sign them with Sigstore + if: startsWith(github.ref, 'refs/tags/') # only publish to PyPI on tag pushes needs: - build runs-on: ubuntu-latest environment: name: pypi + # Fill in your project (e.g. repository) name + # for url: https://pypi.org/p/ permissions: id-token: write steps: - name: Download all the dists - uses: actions/download-artifact@v3 - with: - name: python-package-distributions - path: dist/ - - name: Publish distribution 📦 to PyPI - uses: pypa/gh-action-pypi-publish@release/v1 - - name: Sign the dists with Sigstore - uses: sigstore/gh-action-sigstore-python@v1.2.3 - with: - inputs: >- - ./dist/*.tar.gz - ./dist/*.whl + uses: actions/download-artifact@v3 + with: + name: python-package-distributions + path: dist/ + - name: Publish distribution 📦 to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 + + github-release: + name: >- + Sign the Python 🐍 distribution 📦 with Sigstore + and upload them to GitHub Release + needs: + - publish-to-pypi + steps: + - name: Sign the dists with Sigstore + uses: sigstore/gh-action-sigstore-python@v1.2.3 + with: + inputs: >- + ./dist/*.tar.gz + ./dist/*.whl + - name: Upload artifact signatures to GitHub Release + # Confusingly, this action also supports updating releases, not + # just creating them. This is what we want here, since we've manually + # created the release above. + uses: softprops/action-gh-release@v1 + with: + # dist/ contains the built packages, which smoketest-artifacts/ + # contains the signatures and certificates. + files: dist/** publish-to-testpypi: - name: Build and publish Python 🐍 distributions 📦 to TestPyPI - if: startsWith(github.ref, 'refs/tags/') # only publish to PyPI on tag pushes + name: Publish Python 🐍 distribution 📦 to TestPyPI needs: - build runs-on: ubuntu-latest diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 234593670..500379c9f 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -9,7 +9,7 @@ popular choice is having a workflow that's triggered by a This guide shows you how to publish a Python distribution whenever a tagged commit is pushed. It will use the `pypa/gh-action-pypi-publish GitHub Action`_ for -publishing. It also uses GitHub's `upload-artifact`_ and `download-artifact`_ actions +publishing. It also uses GitHub's `upload-artifact`_ and `download-artifact`_ actions for temporarily storing and downloading the source packages. .. attention:: @@ -23,7 +23,7 @@ Configuring trusted publishing ============================== This guide relies on PyPI's `trusted publishing`_ implementation to connect -to `GitHub Actions CI/CD`_. This is recommended for security reasons, since +to `GitHub Actions CI/CD`_. This is recommended for security reasons, since the generated tokens are created for each of your projects individually and expire automatically. Otherwise, you'll need to generate an `API token`_ for both PyPI and TestPyPI. In case of publishing to third-party @@ -31,7 +31,7 @@ indexes like :doc:`devpi `, you may need to provide a username/password combination. Since this guide will demonstrate uploading to both -PyPI and TestPyPI, we'll need two trusted publishers configured. +PyPI and TestPyPI, we'll need two trusted publishers configured. The following steps will lead you through creating the "pending" publishers for your new :term:`PyPI project `. However it is also possible to add `trusted publishing`_ to any @@ -52,8 +52,8 @@ Let's begin! 🚀 2. Fill in the name you wish to publish your new :term:`PyPI project ` under (the ``name`` value in your ``setup.cfg`` or ``pyproject.toml``), - your GitHub username and repository name and - the name of the release workflow file under + the GitHub repository owner's name (org or user) + and repository name and the name of the release workflow file under the ``.github/`` folder, see :ref:`workflow-definition`. Finally add the name of the GitHub Actions environment (``pypi``) we're going set up under your repository. @@ -61,8 +61,8 @@ Let's begin! 🚀 3. Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the second step, but now enter ``testpypi`` as the name of the GitHub Actions environment. -4. Your "pending" publishers are now ready for their first use and will - create your projects automatically once you use them +4. Your "pending" publishers are now ready for their first use and will + create your projects automatically once you use them for the first time. .. note:: @@ -95,23 +95,19 @@ should make GitHub run this workflow: :language: yaml :end-before: jobs: -This will also ensure that the release workflow is only triggered -if the current commit is tagged. It is recommended you use the -latest release tag. - Checking out the project and building distributions =================================================== -We will have to define two jobs to publish to PyPI -and TestPyPI respectively, and an additional job to +We will have to define two jobs to publish to PyPI +and TestPyPI respectively, and an additional job to build the distribution packages. -First, we'll define the job for building the dist packages of +First, we'll define the job for building the dist packages of your project and storing them for later use: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml - :start-after: jobs: + :start-at: jobs: :end-before: Install pypa/build This will download your repository into the CI runner and then @@ -123,7 +119,7 @@ So add this to the steps list: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml - :start-after: version: "3.x" + :start-at: Install pypa/build :end-before: publish-to-pypi Defining a workflow job environment @@ -135,14 +131,18 @@ In this guide, we'll use the latest stable Ubuntu LTS version provided by GitHub Actions. This also defines a GitHub Environment for the job to run in its context and a URL to be displayed in GitHub's UI nicely. Additionally, it allows aqcuiring an OpenID Connect token -which is mandatory that the ``pypi-publish`` actions needs to -implement secretless trusted publishing to PyPI. +that the ``pypi-publish`` actions needs to implement secretless +trusted publishing to PyPI. .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml :start-after: path: dist/ :end-before: steps: +This will also ensure that the PyPI publishing workflow is only triggered +if the current commit is tagged. It is recommended you use the +latest release tag. + Publishing the distribution to PyPI =================================== @@ -151,14 +151,24 @@ Finally, add the following steps at the end: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml :start-after: id-token: write - :end-before: publish-to-testpypi: + :end-before: github-release: This step uses the `pypa/gh-action-pypi-publish`_ GitHub -Action: after the stored distribution package has been -downloaded by the `download-artifact`_ action, it uploads +Action: after the stored distribution package has been +downloaded by the `download-artifact`_ action, it uploads the contents of the ``dist/`` folder into PyPI unconditionally. -This job also signs the artifacts with the `sigstore/gh-action-sigstore-python`_ -GitHub Action publishing them to PyPI. + +Signing the distribution packages +================================= + +This additional job signs the distribution packages with the +`sigstore/gh-action-sigstore-python GitHub Action`_ and then uploads +them to GitHub Release. + +.. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml + :language: yaml + :start-at: github-release: + :end-before: publish-to-testpypi Separate workflow for publishing to TestPyPI ============================================ @@ -169,8 +179,15 @@ section: .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml - :start-after: ./dist/*.whl + :start-at: publish-to-testpypi + +The whole CD workflow +===================== + +.. collapse:: Load file + .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml + :language: yaml That's all, folks! ================== @@ -193,7 +210,7 @@ sure that your release pipeline remains healthy! https://github.com/actions/download-artifact .. _`upload-artifact`: https://github.com/actions/upload-artifact -.. _`sigstore/gh-action-sigstore-python`: +.. _`sigstore/gh-action-sigstore-python GitHub Action`: https://github.com/marketplace/actions/gh-action-sigstore-python .. _Secrets: https://docs.github.com/en/actions/reference/encrypted-secrets From eca62e47aba879690e081ed47ef0a50096eda7f6 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Wed, 6 Sep 2023 22:17:41 +0200 Subject: [PATCH 040/733] Enable testing merge queues @ GitHub Actions CI/CD --- .github/workflows/test.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 58505e1a5..81ba983f6 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,6 +1,7 @@ name: Test on: + merge_group: push: pull_request: schedule: From ac29d07bed72418d4f5e4fda883a260f9423cb39 Mon Sep 17 00:00:00 2001 From: Dimitri Papadopoulos <3234522+DimitriPapadopoulos@users.noreply.github.com> Date: Mon, 17 Jul 2023 10:51:17 +0200 Subject: [PATCH 041/733] Fix typos found by codespell --- source/contribute.rst | 2 +- ...tion-releases-using-github-actions-ci-cd-workflows.rst | 4 ++-- source/key_projects.rst | 2 +- source/news.rst | 4 ++-- source/specifications/recording-installed-packages.rst | 8 ++++---- source/specifications/virtual-environments.rst | 2 +- 6 files changed, 11 insertions(+), 11 deletions(-) diff --git a/source/contribute.rst b/source/contribute.rst index 10ea0c025..0c538aaec 100644 --- a/source/contribute.rst +++ b/source/contribute.rst @@ -63,7 +63,7 @@ document `. Specifications -------------- -Specifications are reference documention focused on comprehensively documenting +Specifications are reference documentation focused on comprehensively documenting an agreed-upon interface for interoperability between packaging tools. :doc:`example specification-style document `. diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 19f70f040..382fb9fd8 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -103,8 +103,8 @@ use ``build`` package. You can use any other method for building distributions as long as it produces ready-to-upload artifacts saved into the ``dist/`` folder. You can even use ``actions/upload-artifact`` and - ``actions/download-artifact`` to tranfer files between jobs or make them - accessable for download from the web CI interface. + ``actions/download-artifact`` to transfer files between jobs or make them + accessible for download from the web CI interface. So add this to the steps list: diff --git a/source/key_projects.rst b/source/key_projects.rst index d7cf57f4d..7648f3b65 100644 --- a/source/key_projects.rst +++ b/source/key_projects.rst @@ -184,7 +184,7 @@ check for CVEs in `Pipfile` using `safety `_. Pipenv aims to help users manage environments, dependencies, and imported packages on the command line. It also works well on Windows -(which other tools often underserve), makes and checkes file hashes, +(which other tools often underserve), makes and checks file hashes, to ensure compliance with hash-locked dependency specifiers, and eases uninstallation of packages and dependencies. diff --git a/source/news.rst b/source/news.rst index f6bdbbf27..09415fddd 100644 --- a/source/news.rst +++ b/source/news.rst @@ -118,7 +118,7 @@ March 2018 - Updated "installing scientific packages". (:pr:`455`) - Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`) - Clarified a long description classifier on pypi.org. (:pr:`456`) -- Updated Core Metadata spec to follw PEP 556. (:pr:`412`) +- Updated Core Metadata spec to follow PEP 556. (:pr:`412`) February 2018 ------------- @@ -214,7 +214,7 @@ April 2017 - Added documentation explaining prominently how to install ``pip`` in ``/usr/local``. (:pr:`230`) - Updated development mode documentation to mention that order of local packages matters. (:pr:`208`) - Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted projects (:pr:`239`) -- Swaped order of :file:`setup.py` arguments for the upload command, as order +- Swapped order of :file:`setup.py` arguments for the upload command, as order is significant. (:pr:`260`) - Explained how to install from unsupported sources using a helper application. (:pr:`289`) diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst index bac887b2b..11d2c3bfa 100644 --- a/source/specifications/recording-installed-packages.rst +++ b/source/specifications/recording-installed-packages.rst @@ -59,14 +59,14 @@ encouraged to start normalizing those fields. .. note:: - The ``.dist-info`` directory's name is formatted to unambigiously represent + The ``.dist-info`` directory's name is formatted to unambiguously represent a distribution as a filesystem path. Tools presenting a distribution name to a user should avoid using the normalized name, and instead present the specified name (when needed prior to resolution to an installed package), or read the respective fields in Core Metadata, since values listed there are unescaped and accurately reflect the distribution. Libraries should provide API for such tools to consume, so tools can have access to the - unnormalized name when displaying distrubution information. + unnormalized name when displaying distribution information. This ``.dist-info`` directory may contain the following files, described in detail below: @@ -234,7 +234,7 @@ packages into a Python environment to ensure that other tools are not used to uninstall or otherwise modify that installed package, as doing so may cause compatibility problems with the wider environment. -To achieve this, affected tools should take the folllowing steps: +To achieve this, affected tools should take the following steps: * Rename or remove the ``RECORD`` file to prevent changes via other tools (e.g. appending a suffix to create a non-standard ``RECORD.tool`` file if the tool @@ -251,4 +251,4 @@ ensuring both locations appear on the default Python import path). In some circumstances, it may be desirable to block even installation of additional packages via Python-specific tools. For these cases refer to -:ref:`externally-managed-environments` \ No newline at end of file +:ref:`externally-managed-environments` diff --git a/source/specifications/virtual-environments.rst b/source/specifications/virtual-environments.rst index c38c2faeb..77c8c3627 100644 --- a/source/specifications/virtual-environments.rst +++ b/source/specifications/virtual-environments.rst @@ -19,7 +19,7 @@ Runtime detection of virtual environments At runtime, virtual environments can be identified by virtue of ``sys.prefix`` (the filesystem location of the running interpreter) having a different value -from ``sys.base_prefix`` (the default filesytem location of the standard library +from ``sys.base_prefix`` (the default filesystem location of the standard library directories). :ref:`venv-explanation` in the Python standard library documentation for the From 04c2d07f0dda985e7f6164eca6735fff518cdd1b Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Wed, 6 Sep 2023 22:24:32 +0200 Subject: [PATCH 042/733] Add a gate job to GHA CI/CD --- .github/workflows/test.yml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 81ba983f6..a5095d774 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -39,3 +39,21 @@ jobs: - name: Nox ${{ matrix.noxenv }} run: | python -m nox -s ${{ matrix.noxenv }} + + + check: + # This job does nothing and is only used for the branch protection + # or multi-stage CI jobs, like making sure that all tests pass before + # a publishing job is started. + if: always() + + needs: + - build + + runs-on: ubuntu-latest + + steps: + - name: Decide whether the needed jobs succeeded or failed + uses: re-actors/alls-green@release/v1 + with: + jobs: ${{ toJSON(needs) }} From 8f959b0661d170a7bc243731d6477d9f1539436d Mon Sep 17 00:00:00 2001 From: Mike Fiedler Date: Mon, 4 Sep 2023 10:36:13 -0400 Subject: [PATCH 043/733] chore: update python versions used Updated in different places at different times. Make consistent for now. Refs: https://github.com/pypa/packaging.python.org/pull/820/commits/675acbb5eb3f9ebfa954bf603ecdc3d24b202533 Refs: https://github.com/pypa/packaging.python.org/pull/1247/commits/90a1d075646846a3a56dbbc0164ec7efaf729d5b Signed-off-by: Mike Fiedler --- .github/workflows/test.yml | 2 +- source/contribute.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index a5095d774..5da04a342 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -28,7 +28,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v4 with: - python-version: 3.9 + python-version: "3.11" cache: 'pip' cache-dependency-path: 'requirements.txt' diff --git a/source/contribute.rst b/source/contribute.rst index 0c538aaec..0dbdc1adc 100644 --- a/source/contribute.rst +++ b/source/contribute.rst @@ -131,9 +131,9 @@ need: python -m pip install --user nox -2. Python 3.8. Our build scripts are usually tested with Python 3.8 only. +2. Python 3.11. Our build scripts are usually tested with Python 3.11 only. See the :doc:`Hitchhiker's Guide to Python installation instructions ` - to install Python 3.8 on your operating system. + to install Python 3.11 on your operating system. To build the guide, run the following shell command in the project's root folder: From 7b86e9c2d1e6c8cd27f3d3930261526e8ca96b97 Mon Sep 17 00:00:00 2001 From: chrysle Date: Tue, 12 Sep 2023 18:19:47 +0200 Subject: [PATCH 044/733] Apply suggestions from code review Co-authored-by: Sviatoslav Sydorenko --- .../publish-to-test-pypi.yml | 30 ++++++++++++------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index 28663d51f..4021ac585 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -40,16 +40,16 @@ jobs: # for url: https://pypi.org/p/ permissions: - id-token: write + id-token: write # IMPORTANT: mandatory for trusted publishing steps: - - name: Download all the dists - uses: actions/download-artifact@v3 - with: - name: python-package-distributions - path: dist/ - - name: Publish distribution 📦 to PyPI - uses: pypa/gh-action-pypi-publish@release/v1 + - name: Download all the dists + uses: actions/download-artifact@v3 + with: + name: python-package-distributions + path: dist/ + - name: Publish distribution 📦 to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 github-release: name: >- @@ -57,6 +57,12 @@ jobs: and upload them to GitHub Release needs: - publish-to-pypi + runs-on: ubuntu-latest + + permissions: + contents: write # IMPORTANT: mandatory for making GitHub Releases + id-token: write # IMPORTANT: mandatory for sigstore + steps: - name: Sign the dists with Sigstore uses: sigstore/gh-action-sigstore-python@v1.2.3 @@ -70,8 +76,8 @@ jobs: # created the release above. uses: softprops/action-gh-release@v1 with: - # dist/ contains the built packages, which smoketest-artifacts/ - # contains the signatures and certificates. + # `dist/` contains the built packages, and the + # sigstore-produced signatures and certificates. files: dist/** publish-to-testpypi: @@ -79,11 +85,13 @@ jobs: needs: - build runs-on: ubuntu-latest + environment: name: testpypi url: https://test.pypi.org/p/ + permissions: - id-token: write + id-token: write # IMPORTANT: mandatory for trusted publishing steps: - name: Download all the dists From 73725c7cda299a0a60ac783362ae22f777e9bfcf Mon Sep 17 00:00:00 2001 From: chrysle Date: Tue, 12 Sep 2023 19:02:42 +0200 Subject: [PATCH 045/733] Address more review comments --- .../publish-to-test-pypi.yml | 36 ++++++++++--------- ...s-using-github-actions-ci-cd-workflows.rst | 16 +++++++-- 2 files changed, 32 insertions(+), 20 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index 4021ac585..5592f7bae 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -36,8 +36,7 @@ jobs: runs-on: ubuntu-latest environment: name: pypi - # Fill in your project (e.g. repository) name - # for + # Fill in your project (e.g. repository) name for url: https://pypi.org/p/ permissions: id-token: write # IMPORTANT: mandatory for trusted publishing @@ -64,21 +63,24 @@ jobs: id-token: write # IMPORTANT: mandatory for sigstore steps: - - name: Sign the dists with Sigstore - uses: sigstore/gh-action-sigstore-python@v1.2.3 - with: - inputs: >- - ./dist/*.tar.gz - ./dist/*.whl - - name: Upload artifact signatures to GitHub Release - # Confusingly, this action also supports updating releases, not - # just creating them. This is what we want here, since we've manually - # created the release above. - uses: softprops/action-gh-release@v1 - with: - # `dist/` contains the built packages, and the - # sigstore-produced signatures and certificates. - files: dist/** + - name: Download all the dists + uses: actions/download-artifact@v3 + with: + name: python-package-distributions + path: dist/ + - name: Sign the dists with Sigstore + uses: sigstore/gh-action-sigstore-python@v1.2.3 + with: + inputs: >- + ./dist/*.tar.gz + ./dist/*.whl + - name: Upload artifact signatures to GitHub Release + env: + GH_TOKEN: ${{ github.token }} + # Upload to GitHub Release using the `gh` CLI. + # `dist/` contains the built packages, and the + # sigstore-produced signatures and certificates. + run: gh release upload "${{ github.ref_name }}" dist/** --repo "${{ github.repository }}" publish-to-testpypi: name: Publish Python 🐍 distribution 📦 to TestPyPI diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 500379c9f..0c54f282f 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -170,6 +170,14 @@ them to GitHub Release. :start-at: github-release: :end-before: publish-to-testpypi + +.. note:: + + This is a replacement for GPG signatures, for which support has been + `removed `_ by PyPI. + However, this job is not mandatory for defining the workflow. + + Separate workflow for publishing to TestPyPI ============================================ @@ -181,10 +189,12 @@ section: :language: yaml :start-at: publish-to-testpypi -The whole CD workflow -===================== +The whole CI/CD workflow +======================== + +This paragraph showcases the whole workflow after following the above guide. -.. collapse:: Load file +.. collapse:: Click here to display the entire GitHub Actions CI/CD workflow definition .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml From 234b18c1523cd7d0c0780962530d9ab8361eadb4 Mon Sep 17 00:00:00 2001 From: chrysle Date: Wed, 13 Sep 2023 10:54:53 +0200 Subject: [PATCH 046/733] Address more review comments Co-authored-by: Stephen Rosen <1300022+sirosen@users.noreply.github.com> Co-authored-by: Sviatoslav Sydorenko --- .../publish-to-test-pypi.yml | 8 ++--- ...s-using-github-actions-ci-cd-workflows.rst | 33 +++++++++++-------- 2 files changed, 24 insertions(+), 17 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index 5592f7bae..70f4d39c7 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -8,7 +8,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: @@ -36,7 +36,7 @@ jobs: runs-on: ubuntu-latest environment: name: pypi - # Fill in your project (e.g. repository) name for + # Replace below with your PyPI project name: url: https://pypi.org/p/ permissions: id-token: write # IMPORTANT: mandatory for trusted publishing @@ -76,11 +76,11 @@ jobs: ./dist/*.whl - name: Upload artifact signatures to GitHub Release env: - GH_TOKEN: ${{ github.token }} + GITHUB_TOKEN: ${{ github.token }} # Upload to GitHub Release using the `gh` CLI. # `dist/` contains the built packages, and the # sigstore-produced signatures and certificates. - run: gh release upload "${{ github.ref_name }}" dist/** --repo "${{ github.repository }}" + run: gh release upload "${{ github.ref_name }}" dist/** publish-to-testpypi: name: Publish Python 🐍 distribution 📦 to TestPyPI diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index 719de7455..df9173b5f 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -52,15 +52,15 @@ Let's begin! 🚀 2. Fill in the name you wish to publish your new :term:`PyPI project ` under (the ``name`` value in your ``setup.cfg`` or ``pyproject.toml``), - the GitHub repository owner's name (org or user) - and repository name and the name of the release workflow file under + the GitHub repository owner's name (org or user), + and repository name, and the name of the release workflow file under the ``.github/`` folder, see :ref:`workflow-definition`. - Finally add the name of the GitHub Actions environment + Finally, add the name of the GitHub Environment (``pypi``) we're going set up under your repository. Register the trusted publisher. 3. Now, go to https://test.pypi.org/manage/account/publishing/ and repeat - the second step, but now enter ``testpypi`` as the name of the - GitHub Actions environment. + the second step, but this time, enter ``testpypi`` as the name of the + GitHub Environment. 4. Your "pending" publishers are now ready for their first use and will create your projects automatically once you use them for the first time. @@ -71,9 +71,9 @@ Let's begin! 🚀 create it. It's not the same as a regular PyPI account. - .. hint:: + .. attention:: - For security reasons, you should require manual approval + For security reasons, you must require `manual approval `_ on each run for the ``pypi`` environment. @@ -140,7 +140,7 @@ trusted publishing to PyPI. :end-before: steps: This will also ensure that the PyPI publishing workflow is only triggered -if the current commit is tagged. It is recommended you use the +if the current commit is tagged. It is recommended that you commit using the latest release tag. Publishing the distribution to PyPI @@ -161,9 +161,11 @@ the contents of the ``dist/`` folder into PyPI unconditionally. Signing the distribution packages ================================= -This additional job signs the distribution packages with `Sigstore`_, -using the `sigstore/gh-action-sigstore-python GitHub Action`_, -and then uploads them to GitHub Release. +The following job signs the distribution packages with `Sigstore`_, +the same artifact signing system `used to sign CPython `_. + +It uses the `sigstore/gh-action-sigstore-python GitHub Action`_, +and then uploads them to a GitHub Release. .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml @@ -174,8 +176,8 @@ and then uploads them to GitHub Release. .. note:: This is a replacement for GPG signatures, for which support has been - `removed `_ by PyPI. - However, this job is not mandatory for defining the workflow. + `removed from PyPI `_. + However, this job is not mandatory for uploading to PyPI and can be omitted. Separate workflow for publishing to TestPyPI @@ -189,6 +191,11 @@ section: :language: yaml :start-at: publish-to-testpypi +.. tip:: + + Requiring manual approvals in the ``testpypi`` GitHub Environment is typically unnecessary as it's designed to run on each commit to the main branch and is often used to indicate a healthy release publishing pipeline. + + The whole CI/CD workflow ======================== From 0d71546dfb04d91b61faef06381099082614fbc3 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Wed, 13 Sep 2023 17:45:02 +0200 Subject: [PATCH 047/733] Move the env URL comment inline @ pypi job --- .../github-actions-ci-cd-sample/publish-to-test-pypi.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index 70f4d39c7..aa207f429 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -36,8 +36,7 @@ jobs: runs-on: ubuntu-latest environment: name: pypi - # Replace below with your PyPI project name: - url: https://pypi.org/p/ + url: https://pypi.org/p/ # Replace with your PyPI project name permissions: id-token: write # IMPORTANT: mandatory for trusted publishing From 63f738a9ef7a8b0c4e5de54ece427ddd2316563a Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Wed, 13 Sep 2023 17:47:54 +0200 Subject: [PATCH 048/733] Restore passing `--repo` to `gh` @ sigstore job --- .../github-actions-ci-cd-sample/publish-to-test-pypi.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index aa207f429..20ed37740 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -79,7 +79,10 @@ jobs: # Upload to GitHub Release using the `gh` CLI. # `dist/` contains the built packages, and the # sigstore-produced signatures and certificates. - run: gh release upload "${{ github.ref_name }}" dist/** + run: >- + gh release upload + '${{ github.ref_name }}' dist/** + --repo '${{ github.repository }}' publish-to-testpypi: name: Publish Python 🐍 distribution 📦 to TestPyPI From 922208b72c6b1f1fec8a4c08ce82598271c7ab08 Mon Sep 17 00:00:00 2001 From: chrysle Date: Thu, 14 Sep 2023 08:16:55 +0200 Subject: [PATCH 049/733] Move suggestion to update actions to note block --- ...tion-releases-using-github-actions-ci-cd-workflows.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index df9173b5f..f5ba918db 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -140,8 +140,7 @@ trusted publishing to PyPI. :end-before: steps: This will also ensure that the PyPI publishing workflow is only triggered -if the current commit is tagged. It is recommended that you commit using the -latest release tag. +if the current commit is tagged. Publishing the distribution to PyPI =================================== @@ -215,6 +214,11 @@ And it'll publish any push to TestPyPI which is useful for providing test builds to your alpha users as well as making sure that your release pipeline remains healthy! +.. note:: + + It is recommended to keep the integrated GitHub Actions at their latest + versions, updating them frequently. + .. _API token: https://pypi.org/help/#apitoken .. _GitHub Actions CI/CD: https://github.com/features/actions From 53632e4b6915d82cc37ccc4b9049b3c869ab7e99 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Fri, 15 Sep 2023 12:42:18 +0200 Subject: [PATCH 050/733] empty commit to trigger ci-pipeline From eba15849b684ce3b361f61cad137fa22e9efbd16 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Fri, 15 Sep 2023 12:49:48 +0200 Subject: [PATCH 051/733] another empty commit From 9b4342f1ef70cb3f7821ed74678af2d43e271314 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Wed, 31 Aug 2022 12:23:51 +0200 Subject: [PATCH 052/733] Added obsolete fields: requires, provides and obsoletes closes: #1107 --- source/specifications/core-metadata.rst | 86 +++++++++++++++++++++++++ 1 file changed, 86 insertions(+) diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index 453f9d30c..9b5e2cb51 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -761,6 +761,92 @@ Examples:: Obsoletes-Dist: OtherProject (<3.0) Obsoletes-Dist: Foo; os_name == "posix" + +Deprecated Fields +================= + +Requires +-------- + +.. versionadded:: 1.1 +.. deprecated:: 1.2 + in favour of ``Requires-Dist`` + +Each entry contains a string describing some other module or package required +by this package. + +The format of a requirement string is identical to that of a module or package +name usable with the ‘import’ statement, optionally followed by a version +declaration within parentheses. + +A version declaration is a series of conditional operators and version numbers, +separated by commas. Conditional operators must be one of "<", ">"', "<=", +">=", "==", and "!=". Version numbers must be in the format accepted by the +``distutils.version.StrictVersion`` class: two or three dot-separated numeric +components, with an optional "pre-release" tag on the end consisting of the +letter 'a' or 'b' followed by a number. Example version numbers are "1.0", +"2.3a2", "1.3.99", + +Any number of conditional operators can be specified, e.g. the string ">1.0, +!=1.3.4, <2.0" is a legal version declaration. + +All of the following are possible requirement strings: "rfc822", "zlib +(>=1.1.4)", "zope". + +There’s no canonical list of what strings should be used; the Python community +is left to choose its own standards. + +Examples:: + + Requires: re + Requires: sys + Requires: zlib + Requires: xml.parsers.expat (>1.0) + Requires: psycopg + + +Provides +-------- + +.. versionadded:: 1.1 +.. deprecated:: 1.2 + in favour of ``Provides-Dist`` + +Each entry contains a string describing a package or module that will be +provided by this package once it is installed. These strings should match the +ones used in Requirements fields. A version declaration may be supplied +(without a comparison operator); the package’s version number will be implied +if none is specified. + +Examples:: + + Provides: xml + Provides: xml.utils + Provides: xml.utils.iso8601 + Provides: xml.dom + Provides: xmltools (1.3) + + +Obsoletes +--------- + +.. versionadded:: 1.1 +.. deprecated:: 1.2 + in favour of ``Obsoletes-Dist`` + +Each entry contains a string describing a package or module that this package +renders obsolete, meaning that the two packages should not be installed at the +same time. Version declarations can be supplied. + +The most common use of this field will be in case a package name changes, e.g. +Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install Torqued +Python, the Gorgon package should be removed. + +Example:: + + Obsoletes: Gorgon + + ---- .. [1] reStructuredText markup: From 057ce0a9ee5907df05900a073af0c94f80fbcc90 Mon Sep 17 00:00:00 2001 From: Brian Rutledge Date: Mon, 5 Dec 2022 09:35:39 -0500 Subject: [PATCH 053/733] Update source/specifications/core-metadata.rst --- source/specifications/core-metadata.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index 9b5e2cb51..0c4f4b490 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -776,7 +776,7 @@ Each entry contains a string describing some other module or package required by this package. The format of a requirement string is identical to that of a module or package -name usable with the ‘import’ statement, optionally followed by a version +name usable with the ``import`` statement, optionally followed by a version declaration within parentheses. A version declaration is a series of conditional operators and version numbers, From 61663e324ed741de2d1b225f269396729bfa5988 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Fri, 15 Sep 2023 12:56:54 +0200 Subject: [PATCH 054/733] fixed broken link this is unrelated to the pr but satisfies the CI pipeline... --- source/key_projects.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/key_projects.rst b/source/key_projects.rst index 7648f3b65..bbdf4edfc 100644 --- a/source/key_projects.rst +++ b/source/key_projects.rst @@ -558,6 +558,7 @@ resolution by locally caching metadata about dependencies. pypiserver ========== +`Docs `__ | `GitHub `__ | `PyPI `__ From 4f465dc077417572437af1de991add2f14226711 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Fri, 15 Sep 2023 12:42:18 +0200 Subject: [PATCH 055/733] empty commit to trigger ci-pipeline From b6e4c768cd8a810190cf5c158ff00a4174d0c165 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Fri, 15 Sep 2023 12:49:48 +0200 Subject: [PATCH 056/733] another empty commit From c439a75609907287c3f7210f37220e3d28ad2497 Mon Sep 17 00:00:00 2001 From: Dimitri Papadopoulos <3234522+DimitriPapadopoulos@users.noreply.github.com> Date: Sun, 17 Sep 2023 15:44:02 +0200 Subject: [PATCH 057/733] Fix a typo found by codespell --- ...stribution-releases-using-github-actions-ci-cd-workflows.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index f5ba918db..f572e4096 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -130,7 +130,7 @@ It's a process that will execute commands that we'll define later. In this guide, we'll use the latest stable Ubuntu LTS version provided by GitHub Actions. This also defines a GitHub Environment for the job to run in its context and a URL to be displayed in GitHub's -UI nicely. Additionally, it allows aqcuiring an OpenID Connect token +UI nicely. Additionally, it allows acquiring an OpenID Connect token that the ``pypi-publish`` actions needs to implement secretless trusted publishing to PyPI. From b42e89ffcc3d5b842d6f640194bca02babb4201e Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Mon, 18 Sep 2023 09:02:11 +0200 Subject: [PATCH 058/733] Revert "fixed broken link" This reverts commit 61663e324ed741de2d1b225f269396729bfa5988. --- source/key_projects.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/source/key_projects.rst b/source/key_projects.rst index bbdf4edfc..7648f3b65 100644 --- a/source/key_projects.rst +++ b/source/key_projects.rst @@ -558,7 +558,6 @@ resolution by locally caching metadata about dependencies. pypiserver ========== -`Docs `__ | `GitHub `__ | `PyPI `__ From a19593997203e5af96b2eaad71781fed4de6cc5c Mon Sep 17 00:00:00 2001 From: Eric Ti Yu Chiang Date: Wed, 14 Jun 2023 09:18:51 +0800 Subject: [PATCH 059/733] Add history to package name normalization spec. --- source/specifications/name-normalization.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/specifications/name-normalization.rst b/source/specifications/name-normalization.rst index 4fd885afc..7a1a0e083 100644 --- a/source/specifications/name-normalization.rst +++ b/source/specifications/name-normalization.rst @@ -37,3 +37,9 @@ This means that the following names are all equivalent: * ``friendly_bard`` * ``friendly--bard`` * ``FrIeNdLy-._.-bArD`` (a _terrible_ way to write a name, but it is valid) + +History +======= + +- `September 2015 `_: normalized name was originally specified in :pep:`503#normalized-names`. +- `November 2015 `_: valid non-normalized name was originally specified in :pep:`508#names`. \ No newline at end of file From d14e4e6ff08e303e2369344f370eb05994e1c617 Mon Sep 17 00:00:00 2001 From: chrysle Date: Fri, 29 Sep 2023 17:49:32 +0200 Subject: [PATCH 060/733] Add step to create empty GH Release before upload --- .../github-actions-ci-cd-sample/publish-to-test-pypi.yml | 5 +++++ ...ion-releases-using-github-actions-ci-cd-workflows.rst | 9 +++++++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index 20ed37740..71aca9881 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -73,6 +73,11 @@ jobs: inputs: >- ./dist/*.tar.gz ./dist/*.whl + - name: Create GitHub Release + run: >- + gh release create + '${{ github.ref_name }}' + --notes "" - name: Upload artifact signatures to GitHub Release env: GITHUB_TOKEN: ${{ github.token }} diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst index f572e4096..33cc88017 100644 --- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst +++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @@ -163,8 +163,13 @@ Signing the distribution packages The following job signs the distribution packages with `Sigstore`_, the same artifact signing system `used to sign CPython `_. -It uses the `sigstore/gh-action-sigstore-python GitHub Action`_, -and then uploads them to a GitHub Release. +Firstly, it uses the `sigstore/gh-action-sigstore-python GitHub Action`_ +to sign the distribution packages. In the next step, an empty GitHub Release +from the current tag is created using the ``gh`` CLI. Note this step can be further +customised. See the `gh release documentation `_ +as a reference. + +Finally, the signed distributions are uploaded to the GitHub Release. .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml :language: yaml From 1f856d86512ff5a30a4dd967d982bac2da0ea531 Mon Sep 17 00:00:00 2001 From: Eric Ti Yu Chiang Date: Tue, 3 Oct 2023 17:14:40 -0400 Subject: [PATCH 061/733] Add history section to externally managed environments spec. --- source/specifications/externally-managed-environments.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/specifications/externally-managed-environments.rst b/source/specifications/externally-managed-environments.rst index 3876d8e34..e4ee921d2 100644 --- a/source/specifications/externally-managed-environments.rst +++ b/source/specifications/externally-managed-environments.rst @@ -20,3 +20,7 @@ installation to indicate to Python-specific tools such as ``pip`` that they neither install nor remove packages into the interpreter’s default installation environment, and should instead guide the end user towards using :ref:`virtual-environments`. + +History +======= +- `June 2022 `_: ``EXTERNALLY-MANAGED`` marker file was originally specified in :pep:`668#marking-an-interpreter-as-using-an-external-package-manager`. \ No newline at end of file From 28dd1afdf79a7f16ee4354533994c695430c49ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Thu, 5 Oct 2023 12:13:48 +0200 Subject: [PATCH 062/733] Remove `setup.py` direct invocation in glossary https://pypa-build.readthedocs.io/en/latest/#python--m-build---sdist --- source/glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/glossary.rst b/source/glossary.rst index f8392dbd0..707bc4756 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -208,7 +208,7 @@ Glossary Source Distribution (or "sdist") A :term:`distribution ` format (usually generated - using ``python setup.py sdist``) that provides metadata and the + using ``python -m build --sdist``) that provides metadata and the essential source files needed for installing by a tool like :ref:`pip`, or for generating a :term:`Built Distribution`. From 42268c4ac44447237698727eb9584d3c18968c4b Mon Sep 17 00:00:00 2001 From: ValentinMerlet Date: Sat, 7 Oct 2023 12:24:18 +0200 Subject: [PATCH 063/733] Fix typo --- source/tutorials/installing-packages.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst index 23645459a..5d4957519 100644 --- a/source/tutorials/installing-packages.rst +++ b/source/tutorials/installing-packages.rst @@ -9,7 +9,7 @@ This section covers the basics of how to install Python :term:`packages It's important to note that the term "package" in this context is being used to describe a bundle of software to be installed (i.e. as a synonym for a -:term:`distribution `). It does not to refer to the kind +:term:`distribution `). It does not refer to the kind of :term:`package ` that you import in your Python source code (i.e. a container of modules). It is common in the Python community to refer to a :term:`distribution ` using the term "package". Using From 174b29bc691149f80894de377472ea9688db430f Mon Sep 17 00:00:00 2001 From: wim glenn Date: Wed, 6 Sep 2023 19:29:45 -0500 Subject: [PATCH 064/733] Change wording of Requires-Python and offer a lower bound example. This should better demonstrate that usage of this field is more commonly about _excluding known incompatible versions_ than it is about specifying _guaranteed compatible versions_. Remove the multiple example code-block because it is not a (multiple use) field, and the other examples seem to exist only to show further usage of PEP 440 version specifiers (which are explained better elsewhere) rather than Requires-Python itself. --- source/specifications/core-metadata.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index 0c4f4b490..5749e618e 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -551,18 +551,17 @@ Requires-Python .. versionadded:: 1.2 This field specifies the Python version(s) that the distribution is -guaranteed to be compatible with. Installation tools may look at this when +compatible with. Installation tools may look at this when picking which version of a project to install. The value must be in the format specified in :doc:`version-specifiers`. -This field cannot be followed by an environment marker. +For example, if a distribution uses `f-strings `_ +then it may prevent installation on Python < 3.6 by specifying: -Examples:: + Requires-Python: >=3.6 - Requires-Python: >=3 - Requires-Python: >2.6,!=3.0.*,!=3.1.* - Requires-Python: ~=2.6 +This field cannot be followed by an environment marker. .. _core-metadata-requires-external: From e604f4360bea19bd5f6025ecee44450d23113b1a Mon Sep 17 00:00:00 2001 From: wim glenn Date: Sat, 7 Oct 2023 13:58:02 -0500 Subject: [PATCH 065/733] review suggestions --- source/specifications/core-metadata.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index 5749e618e..cccd611e0 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -556,8 +556,8 @@ picking which version of a project to install. The value must be in the format specified in :doc:`version-specifiers`. -For example, if a distribution uses `f-strings `_ -then it may prevent installation on Python < 3.6 by specifying: +For example, if a distribution uses :ref:`f-strings ` +then it may prevent installation on Python < 3.6 by specifying:: Requires-Python: >=3.6 From 513c97819c3cbaf7da3eb38b4e07c6dd0bb69a68 Mon Sep 17 00:00:00 2001 From: chrysle Date: Tue, 10 Oct 2023 17:12:32 +0200 Subject: [PATCH 066/733] Address `distutils` removal from Python stdlib --- source/guides/distributing-packages-using-setuptools.rst | 4 ++-- source/guides/dropping-older-python-versions.rst | 2 +- source/guides/tool-recommendations.rst | 2 +- source/key_projects.rst | 7 +++---- source/overview.rst | 2 +- source/specifications/platform-compatibility-tags.rst | 4 +++- 6 files changed, 11 insertions(+), 10 deletions(-) diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst index a704dd048..eb99b3ff0 100644 --- a/source/guides/distributing-packages-using-setuptools.rst +++ b/source/guides/distributing-packages-using-setuptools.rst @@ -484,7 +484,7 @@ Each file name in ``files`` is interpreted relative to the :file:`setup.py` script at the top of the project source distribution. For more information see the distutils section on :ref:`Installing Additional Files -`. +`. .. note:: @@ -498,7 +498,7 @@ For more information see the distutils section on :ref:`Installing Additional Fi ~~~~~~~~~~~ Although ``setup()`` supports a :ref:`scripts -` +` keyword for pointing to pre-made scripts to install, the recommended approach to achieve cross-platform compatibility is to use :ref:`console_scripts` entry points (see below). diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst index d4fc83c81..aec65b48d 100644 --- a/source/guides/dropping-older-python-versions.rst +++ b/source/guides/dropping-older-python-versions.rst @@ -102,7 +102,7 @@ metadata values based on the argument you provide in ``python_requires``. Within a Python source package (the zip or the tar-gz file you download) is a text file called PKG-INFO. -This file is generated by Distutils or :ref:`setuptools` when it generates the source package. +This file is generated by :ref:`distutils` or :ref:`setuptools` when it generates the source package. The file contains a set of keys and values, the list of keys is part of the PyPa standard metadata format. You can see the contents of the generated file like this: diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst index fc0afd1df..1a59201fa 100644 --- a/source/guides/tool-recommendations.rst +++ b/source/guides/tool-recommendations.rst @@ -93,7 +93,7 @@ migration, and what settings to change in your clients. :ref:`virtualenv`. However, using :ref:`virtualenv` will still be recommended for users that need cross-version consistency. -.. [5] Although you can use pure ``distutils`` for many projects, it does not +.. [5] Although you can use pure :ref:`distutils` for many projects, it does not support defining dependencies on other projects and is missing several convenience utilities for automatically populating distribution metadata correctly that are provided by ``setuptools``. Being outside the diff --git a/source/key_projects.rst b/source/key_projects.rst index 7648f3b65..8d1d42b40 100644 --- a/source/key_projects.rst +++ b/source/key_projects.rst @@ -676,21 +676,20 @@ build of the Python distribution. distutils ========= -`Docs `__ | -`Issues `__ - The original Python packaging system, added to the standard library in Python 2.0. Due to the challenges of maintaining a packaging system where feature updates are tightly coupled to language runtime updates, -direct usage of :ref:`distutils` is now actively discouraged, with +direct usage of :ref:`distutils` has been actively discouraged, with :ref:`Setuptools` being the preferred replacement. :ref:`Setuptools` not only provides features that plain :ref:`distutils` doesn't offer (such as dependency declarations and entry point declarations), it also provides a consistent build interface and feature set across all supported Python versions. +Consequently, :ref:`distutils` was deprecated in Python 3.10 by :pep:`632` and +has been :doc:`removed ` from the standard library in Python 3.12. .. _venv: diff --git a/source/overview.rst b/source/overview.rst index f0f7cdbce..256510bb8 100644 --- a/source/overview.rst +++ b/source/overview.rst @@ -95,7 +95,7 @@ you can use Python's native packaging tools to create a *source* Python's *sdists* are compressed archives (``.tar.gz`` files) containing one or more packages or modules. If your code is pure-Python, and you only depend on other Python packages, you can -:doc:`go here to learn more `. +go to the :ref:`source-distribution-format` specification to learn more. If you rely on any non-Python code, or non-Python packages (such as `libxml2 `_ in the case of diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst index 5ef47f9af..df7da59c5 100644 --- a/source/specifications/platform-compatibility-tags.rst +++ b/source/specifications/platform-compatibility-tags.rst @@ -92,8 +92,10 @@ decide how to best use the ABI tag. Platform Tag ------------ -The platform tag is simply ``distutils.util.get_platform()`` with all +The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-`` and periods ``.`` replaced with underscore ``_``. +Until the removal of :ref:`distutils` in Python 3.12, this +was ``distutils.util.get_platform()``. * win32 * linux_i386 From 23c38bed6edfe23c9b6a38b8626460a822356875 Mon Sep 17 00:00:00 2001 From: Peter Hill Date: Wed, 18 Oct 2023 15:33:18 +0100 Subject: [PATCH 067/733] Bump version of python-docs-theme --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 17492e03c..7ee85ca01 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,7 +1,7 @@ sphinx==4.5.0 sphinx-autobuild==0.7.1 sphinx-inline-tabs==2021.4.11b9 -python-docs-theme==2022.1 +python-docs-theme==2023.9 sphinx-copybutton==0.5.0 pypa-docs-theme @ git+https://github.com/pypa/pypa-docs-theme.git sphinx-toolbox==3.5.0 From fd73358924a4a5d9a14239958cefa533f10307c5 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Tue, 24 Oct 2023 01:52:14 +0200 Subject: [PATCH 068/733] Unduplicate GHA runs for merge queues and pushes --- .github/workflows/test.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 5da04a342..581b644ca 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -3,6 +3,8 @@ name: Test on: merge_group: push: + branches-ignore: + - gh-readonly-queue/** # Temporary merge queue-related GH-made branches pull_request: schedule: - cron: "0 6 * * *" # daily at 6am From 9301fb75b9bb32862a1d3ad376263089cadb331f Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Tue, 24 Oct 2023 01:56:49 +0200 Subject: [PATCH 069/733] Temporarily ignore www.breezy-vcs.org @ linkcheck Ref: * https://github.com/pypa/packaging.python.org/pull/1308#issuecomment-1775347690 --- source/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/conf.py b/source/conf.py index 9113b8c68..16a231133 100644 --- a/source/conf.py +++ b/source/conf.py @@ -393,6 +393,9 @@ # Ignoring it as it will redirect to login page if reader hasn't logged in. "https://pypi.org/manage/*", "https://test.pypi.org/manage/*", + # Temporarily ignored. Ref: + # https://github.com/pypa/packaging.python.org/pull/1308#issuecomment-1775347690 + "https://www.breezy-vcs.org/*", ] # Example configuration for intersphinx: refer to the Python standard library. From 750e4b0bf0e4d42e64fbf3c3edba716b05fd6132 Mon Sep 17 00:00:00 2001 From: Henrik Finsberg Date: Wed, 25 Oct 2023 10:10:32 +0200 Subject: [PATCH 070/733] Update packaging-projects.rst Set lower bound on `requires-python` to 3.8 since 3.7 is EOL. --- source/tutorials/packaging-projects.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index 89e1d073d..78baf6b06 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -188,7 +188,7 @@ following this tutorial. ] description = "A small example package" readme = "README.md" - requires-python = ">=3.7" + requires-python = ">=3.8" classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", From be1c9798428fd711aafaccd820146a89aed54118 Mon Sep 17 00:00:00 2001 From: Matthias Bussonnier Date: Wed, 25 Oct 2023 12:00:32 +0200 Subject: [PATCH 071/733] say that flit is lifted and by whom --- source/key_projects.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/key_projects.rst b/source/key_projects.rst index 8d1d42b40..8267883aa 100644 --- a/source/key_projects.rst +++ b/source/key_projects.rst @@ -103,6 +103,11 @@ such as :ref:`setuptools` to build distributions, or :ref:`twine` to upload them to PyPI. Flit requires Python 3, but you can use it to distribute modules for Python 2, so long as they can be imported on Python 3. +The flit packaged is lifted by `Matthias Bussonnier +`__ since October 2023 on the `tidelift paltform +` Date: Wed, 25 Oct 2023 05:51:42 -0700 Subject: [PATCH 072/733] Apply suggestions from code review Co-authored-by: Paul Moore --- source/key_projects.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/key_projects.rst b/source/key_projects.rst index 8267883aa..1e9b58e51 100644 --- a/source/key_projects.rst +++ b/source/key_projects.rst @@ -103,8 +103,8 @@ such as :ref:`setuptools` to build distributions, or :ref:`twine` to upload them to PyPI. Flit requires Python 3, but you can use it to distribute modules for Python 2, so long as they can be imported on Python 3. -The flit packaged is lifted by `Matthias Bussonnier -`__ since October 2023 on the `tidelift paltform +The flit package is lifted by `Matthias Bussonnier +`__ since October 2023 on the `tidelift platform ` Date: Thu, 26 Oct 2023 11:25:35 -0700 Subject: [PATCH 073/733] Fix issue with creation of GitHub release caused by missing cli switch Reference: #1307 The command added, `gh release create`, fails without the `--repo` siwtch. This change adds it. Here is an Action run that fails without it https://github.com/uclahs-cds/BL_Python/actions/runs/6658063247/job/18094142825 And a successful Action run that succeeds with it. https://github.com/uclahs-cds/BL_Python/actions/runs/6658181985/job/18094515444 --- .../guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index 71aca9881..a77aac1c1 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -77,6 +77,7 @@ jobs: run: >- gh release create '${{ github.ref_name }}' + --repo '${{ github.repository }}' --notes "" - name: Upload artifact signatures to GitHub Release env: From ba7a8d9a38a694b8d1f13141739366ada3bce80f Mon Sep 17 00:00:00 2001 From: Aaron Holmes Date: Thu, 26 Oct 2023 12:23:28 -0700 Subject: [PATCH 074/733] Fix authorization issue when creating a GitHub release. The envvar `GITHUB_TOKEN` that is defined for the step that runs `gh release up` must also be defined for the step that runs `gh release create`. This change removes the definition from the step, and adds it to the job so that the envvar is available to all steps in the job. This fixes the authorization issue that can be seen [here](https://github.com/uclahs-cds/BL_Python/actions/runs/6658013371/job/18093994984). Note: the output of the Action specifies `GH_TOKEN`, but in fact either `GH_TOKEN` or `GITHUB_TOKEN` can be defined per [gh environment](https://cli.github.com/manual/gh_help_environment). --- .../github-actions-ci-cd-sample/publish-to-test-pypi.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml index a77aac1c1..02d1f8e84 100644 --- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml +++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml @@ -61,6 +61,9 @@ jobs: contents: write # IMPORTANT: mandatory for making GitHub Releases id-token: write # IMPORTANT: mandatory for sigstore + env: + GITHUB_TOKEN: ${{ github.token }} + steps: - name: Download all the dists uses: actions/download-artifact@v3 @@ -80,8 +83,6 @@ jobs: --repo '${{ github.repository }}' --notes "" - name: Upload artifact signatures to GitHub Release - env: - GITHUB_TOKEN: ${{ github.token }} # Upload to GitHub Release using the `gh` CLI. # `dist/` contains the built packages, and the # sigstore-produced signatures and certificates. From c6b8bbde182dd68a81ba3e0af558d6c8b1ebc47f Mon Sep 17 00:00:00 2001 From: Steve Dower Date: Wed, 1 Nov 2023 20:28:02 +0000 Subject: [PATCH 075/733] Update Choosing a build backend section --- source/tutorials/packaging-projects.rst | 43 +++++++++++++++++-------- 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index 89e1d073d..fe0f4c414 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -103,15 +103,17 @@ Creating a test directory :file:`tests/` is a placeholder for test files. Leave it empty for now. -Creating pyproject.toml +Choosing a build backend ----------------------- -.. TODO: Add an intro sentence about pyproject.toml, and a sub-heading for - "Configuring build tools" +Tools like :ref:`pip` and :ref:`build` do not actually convert your sources +into a :term:`distribution package `; +that job is performed by a _build backend_. The build backend determines how +your project will specify its configuration, including metadata (information +about the project, for example, the name and tags that are displayed on PyPI) +and input files. Build backends have different levels of functionality, and +you should choose one that suits your needs, but also meets your preferences. -:file:`pyproject.toml` tells "frontend" build tools like :ref:`pip` and -:ref:`build` what "backend" tool to use to create -:term:`distribution packages ` for your project. You can choose from a number of backends; this tutorial uses :ref:`Hatchling ` by default, but it will work identically with :ref:`setuptools`, :ref:`Flit `, :ref:`PDM `, and others that support the ``[project]`` @@ -124,7 +126,10 @@ table for :ref:`metadata `. management, as well as building, uploading, and installing packages. This tutorial uses single-purpose tools that work independently. -Open :file:`pyproject.toml` and enter one of these ``[build-system]`` tables: +The :file:`pyproject.toml` tells "front end" build tools like :ref:`pip` and +:ref:`build` which backend to use for your project. Below are some +examples for common build backends, but check your backend's own documentation +for more details. .. tab:: Hatchling @@ -159,14 +164,24 @@ Open :file:`pyproject.toml` and enter one of these ``[build-system]`` tables: build-backend = "pdm.backend" -- ``requires`` is a list of packages that are needed to build your package. You - don't need to install them; build frontends like :ref:`pip` will install them - automatically in a temporary, isolated virtual environment for use during the - build process. -- ``build-backend`` is the name of the Python object that frontends will use to - perform the build. +The ``requires`` key is a list of packages that are needed to build your package. +The front end should install them automatically when building your package. +There will always be your build backend package, and potentially other build-time +dependencies. -.. TODO: Add note to check the tools' documentation for the current snippet? +The ``build-backend`` key is the name of the Python object that frontends will use +to perform the build. + +Both of these values will be given to you by the documentation for your build +backend, or generated by its command line interface. There should be no need for +you to customize these settings. + +Additional configuration of the build tool will either be in a ``tool`` section +of the ``pyproject.toml``, or in a special file defined by the build tool. For +example, when using ``setuptools`` as your build backend, additional configuration +may be added to a ``setup.py`` or ``setup.cfg`` file, and specifying +``setuptools.build_meta`` in your build allows the tools to locate and use these +automatically. .. _configuring metadata: From 0049ff80e608cb5137a2dc49c73e8e97520bbb60 Mon Sep 17 00:00:00 2001 From: Steve Dower Date: Wed, 1 Nov 2023 20:34:48 +0000 Subject: [PATCH 076/733] Apply suggestions from code review --- source/tutorials/packaging-projects.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index fe0f4c414..943136705 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -166,13 +166,13 @@ for more details. The ``requires`` key is a list of packages that are needed to build your package. The front end should install them automatically when building your package. -There will always be your build backend package, and potentially other build-time +This should always include your backend's package, and might have other build-time dependencies. The ``build-backend`` key is the name of the Python object that frontends will use to perform the build. -Both of these values will be given to you by the documentation for your build +Both of these values will be provided by the documentation for your build backend, or generated by its command line interface. There should be no need for you to customize these settings. From c8fafd8d3f56851e7fd3cf498493985bbbd38f13 Mon Sep 17 00:00:00 2001 From: Steve Dower Date: Wed, 1 Nov 2023 21:36:06 +0000 Subject: [PATCH 077/733] Apply suggestions from code review --- source/tutorials/packaging-projects.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index 943136705..0fc2e65d6 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -107,12 +107,13 @@ Choosing a build backend ----------------------- Tools like :ref:`pip` and :ref:`build` do not actually convert your sources -into a :term:`distribution package `; +into a :term:`distribution package ` (like a wheel); that job is performed by a _build backend_. The build backend determines how your project will specify its configuration, including metadata (information about the project, for example, the name and tags that are displayed on PyPI) -and input files. Build backends have different levels of functionality, and -you should choose one that suits your needs, but also meets your preferences. +and input files. Build backends have different levels of functionality, such as +whether they support building :term:`extension modules `, and +you should choose one that suits your needs and preferences. You can choose from a number of backends; this tutorial uses :ref:`Hatchling ` by default, but it will work identically with :ref:`setuptools`, @@ -165,7 +166,9 @@ for more details. The ``requires`` key is a list of packages that are needed to build your package. -The front end should install them automatically when building your package. +The frontend should install them automatically when building your package. +Frontends usually run builds in isolated environments, so omitting dependencies +here may cause build-time errors. This should always include your backend's package, and might have other build-time dependencies. From dae7a5561cc03ab89a801a7f62551b35c9c15aee Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 2 Nov 2023 10:23:47 -0400 Subject: [PATCH 078/733] chore: add and update some backends Signed-off-by: Henry Schreiner --- source/key_projects.rst | 75 +++++++++++++++++++++++++++++------------ 1 file changed, 54 insertions(+), 21 deletions(-) diff --git a/source/key_projects.rst b/source/key_projects.rst index 8d1d42b40..73c3aefa5 100644 --- a/source/key_projects.rst +++ b/source/key_projects.rst @@ -84,6 +84,30 @@ behaviours when asked to handle legacy packages and metadata that predate the modern interoperability standards and fall into the subset of packages that are incompatible with those standards. + +.. _distutils: + +distutils +========= + +The original Python packaging system, added to the standard library in +Python 2.0 and removed in 3.12. + +Due to the challenges of maintaining a packaging system +where feature updates are tightly coupled to language runtime updates, +direct usage of :ref:`distutils` has been actively discouraged, with +:ref:`Setuptools` being the preferred replacement. :ref:`Setuptools` +not only provides features that plain :ref:`distutils` doesn't offer +(such as dependency declarations and entry point declarations), it +also provides a consistent build interface and feature set across all +supported Python versions. + +Consequently, :ref:`distutils` was deprecated in Python 3.10 by :pep:`632` and +has been :doc:`removed ` from the standard library in +Python 3.12. Setuptools bundles the standalone copy of distutils, and it is +injected even on Python < 3.12 if you import setuptools first or use pip. + + .. _flit: flit @@ -452,6 +476,19 @@ problem of installing scientific software, and making package distribution stateless, cached, and branchable. It is used by some researchers but has been lacking in maintenance since 2016. +.. _maturin: + +Maturin +======= + +`Docs `__ | +`GitHub `__ + +Maturin is a PEP 517 build backend for Rust extension modules, also written in +Rust. It supports building wheels for python 3.7+ on Windows, Linux, macOS and +FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support. + + .. _meson-python: meson-python @@ -472,7 +509,7 @@ of most complex build configurations. multibuild ========== -`GitHub `__ +`GitHub `__ Multibuild is a set of CI scripts for building and testing Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :ref:`cibuildwheel`. @@ -604,6 +641,22 @@ build requirements. To speed up and parallelize the build of large projects, the user can install `ninja `__ (also available on PyPI). +.. _scikit-build-core: + +scikit-build-core +================= + +`Docs `__ | +`GitHub `__ | +`PyPI `__ + +Scikit-build-core is a PEP 517 backend for CPython C/C++/Fortran/Cython +extensions. It enables users to write extensions with `cmake +`__ (available on PyPI) to provide better +support for additional compilers, build systems, cross compilation, and +locating dependencies and their associated build requirements. CMake/Ninja +are automatically downloaded from PyPI if not available on the system. + .. _shiv: shiv @@ -671,26 +724,6 @@ cases, end users won't use this module, but rather it will be used during the build of the Python distribution. -.. _distutils: - -distutils -========= - -The original Python packaging system, added to the standard library in -Python 2.0. - -Due to the challenges of maintaining a packaging system -where feature updates are tightly coupled to language runtime updates, -direct usage of :ref:`distutils` has been actively discouraged, with -:ref:`Setuptools` being the preferred replacement. :ref:`Setuptools` -not only provides features that plain :ref:`distutils` doesn't offer -(such as dependency declarations and entry point declarations), it -also provides a consistent build interface and feature set across all -supported Python versions. - -Consequently, :ref:`distutils` was deprecated in Python 3.10 by :pep:`632` and -has been :doc:`removed ` from the standard library in Python 3.12. - .. _venv: venv From a1a3c7f49104ea0c2b8ca168bd6f059e8a9e666d Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 2 Nov 2023 10:50:59 -0400 Subject: [PATCH 079/733] chore: add some more pre-commit checks Signed-off-by: Henry Schreiner --- .pre-commit-config.yaml | 28 +++++++++++++++++++ source/contribute.rst | 4 +-- .../deploying-python-applications.rst | 2 +- ...distributing-packages-using-setuptools.rst | 2 +- .../guides/dropping-older-python-versions.rst | 4 +-- .../supporting-multiple-python-versions.rst | 2 +- .../supporting-windows-using-appveyor.rst | 6 ++-- source/key_projects.rst | 4 +-- source/specifications/core-metadata.rst | 2 +- .../declaring-build-dependencies.rst | 2 +- .../specifications/dependency-specifiers.rst | 1 - .../externally-managed-environments.rst | 2 +- source/specifications/name-normalization.rst | 2 +- source/tutorials/creating-documentation.rst | 4 --- source/tutorials/packaging-projects.rst | 3 +- 15 files changed, 45 insertions(+), 23 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a1a5f58c8..4c70a3f63 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -2,4 +2,32 @@ repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.4.0 hooks: + - id: check-added-large-files + - id: check-case-conflict + - id: check-merge-conflict + - id: check-symlinks + - id: check-yaml + - id: end-of-file-fixer + - id: mixed-line-ending - id: trailing-whitespace + +- repo: https://github.com/codespell-project/codespell + rev: v2.2.6 + hooks: + - id: codespell + args: ["-L", "ned"] + +- repo: local + hooks: + - id: disallow-caps + name: Disallow improper capitalization + language: pygrep + entry: PyBind|Numpy|Cmake|CCache|Github|PyTest + exclude: .pre-commit-config.yaml + +- repo: https://github.com/pre-commit/pygrep-hooks + rev: v1.10.0 + hooks: + - id: rst-backticks + - id: rst-directive-colons + - id: rst-inline-touching-normal diff --git a/source/contribute.rst b/source/contribute.rst index 0dbdc1adc..afac9e4f7 100644 --- a/source/contribute.rst +++ b/source/contribute.rst @@ -75,7 +75,7 @@ We use `Weblate`_ to manage translations of this project. Please visit the `packaging.python.org`_ project on Weblate to contribute. If you are experiencing issues while you are working on translations, -please open an issue on `Github`_. +please open an issue on `GitHub`_. .. tip:: @@ -83,7 +83,7 @@ please open an issue on `Github`_. .. _Weblate: https://weblate.org/ .. _packaging.python.org: https://hosted.weblate.org/projects/pypa/packaging-python-org/ -.. _Github: https://github.com/pypa/packaging.python.org/issues +.. _GitHub: https://github.com/pypa/packaging.python.org/issues .. _reStructuredText syntax: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html Adding a language diff --git a/source/discussions/deploying-python-applications.rst b/source/discussions/deploying-python-applications.rst index 62e29448f..d9246d563 100644 --- a/source/discussions/deploying-python-applications.rst +++ b/source/discussions/deploying-python-applications.rst @@ -73,7 +73,7 @@ directory, independent of any other Python installation on the computer. A big advantage of Pynsist is that the Windows packages can be built on Linux. There are several examples for different kinds of programs (console, GUI) in -the `documentation `. The tool is released +the :any:`documentation `. The tool is released under the MIT-licence. Application bundles diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst index eb99b3ff0..db982071d 100644 --- a/source/guides/distributing-packages-using-setuptools.rst +++ b/source/guides/distributing-packages-using-setuptools.rst @@ -241,7 +241,7 @@ can be specified with the ``long_description_content_type`` argument, which can be one of ``text/plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no formatting, `reStructuredText (reST) `_, -and the Github-flavored Markdown dialect of `Markdown +and the GitHub-flavored Markdown dialect of `Markdown `_ respectively. ``url`` diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst index aec65b48d..2ac193b4c 100644 --- a/source/guides/dropping-older-python-versions.rst +++ b/source/guides/dropping-older-python-versions.rst @@ -41,7 +41,7 @@ explicitly set ``universal`` to ``0``: # setup.cfg [bdist_wheel] - universal = 0 # Make the generated wheels have `py3` tag + universal = 0 # Make the generated wheels have "py3" tag .. tip:: @@ -71,7 +71,7 @@ Steps: py -m pip install --upgrade setuptools twine -`setuptools` version should be above 24.0.0. +``setuptools`` version should be above 24.0.0. 2. Specify the version ranges for supported Python distributions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/guides/supporting-multiple-python-versions.rst b/source/guides/supporting-multiple-python-versions.rst index 23c1f51c0..0471a1f2f 100644 --- a/source/guides/supporting-multiple-python-versions.rst +++ b/source/guides/supporting-multiple-python-versions.rst @@ -52,7 +52,7 @@ Automated testing and continuous integration Several hosted services for automated testing are available. These services will typically monitor your source code repository (e.g. at -`Github `_ or `Bitbucket `_) +`GitHub `_ or `Bitbucket `_) and run your project's test suite every time a new commit is made. These services also offer facilities to run your project's test suite on diff --git a/source/guides/supporting-windows-using-appveyor.rst b/source/guides/supporting-windows-using-appveyor.rst index 79242510c..1f43c443b 100644 --- a/source/guides/supporting-windows-using-appveyor.rst +++ b/source/guides/supporting-windows-using-appveyor.rst @@ -25,7 +25,7 @@ non-trivial, and may require buying software licenses. The Appveyor service is a continuous integration service, much like the better-known `Travis`_ service that is commonly used for testing by projects -hosted on `Github`_. However, unlike Travis, the build workers on Appveyor are +hosted on `GitHub`_. However, unlike Travis, the build workers on Appveyor are Windows hosts and have the necessary compilers installed to build Python extensions. @@ -44,7 +44,7 @@ have an account on the service. Instructions on setting up an account are given in `the Appveyor documentation `__. The free tier of account is perfectly adequate for open source projects. -Appveyor provides integration with `Github`_ and `Bitbucket`_, so as long as +Appveyor provides integration with `GitHub`_ and `Bitbucket`_, so as long as your project is hosted on one of those two services, setting up Appveyor integration is straightforward. @@ -241,5 +241,5 @@ For reference, the SDK setup support script is listed here: .. _Appveyor: https://www.appveyor.com/ .. _Travis: https://travis-ci.org/ -.. _Github: https://github.com +.. _GitHub: https://github.com .. _Bitbucket: https://bitbucket.org/ diff --git a/source/key_projects.rst b/source/key_projects.rst index 8d1d42b40..03c736e6b 100644 --- a/source/key_projects.rst +++ b/source/key_projects.rst @@ -34,7 +34,7 @@ Content Delivery Network (CDN). build ===== -`Docs ` | +:any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__ @@ -180,7 +180,7 @@ Pipenv Pipenv is a project that aims to bring the best of all packaging worlds to the Python world. It harnesses :ref:`Pipfile`, :ref:`pip`, and :ref:`virtualenv` into one single toolchain. It can autoimport ``requirements.txt`` and also -check for CVEs in `Pipfile` using `safety `_. +check for CVEs in `Pipfile`_ using `safety `_. Pipenv aims to help users manage environments, dependencies, and imported packages on the command line. It also works well on Windows diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index 0c4f4b490..cefd68950 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -285,7 +285,7 @@ Other parameters might be specific to the chosen subtype. For example, for the specifying the variant of Markdown in use (defaults to ``GFM`` if not specified). Currently, two variants are recognized: -- ``GFM`` for :rfc:`Github-flavored Markdown <7764#section-3.2>` +- ``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>` - ``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>` Example:: diff --git a/source/specifications/declaring-build-dependencies.rst b/source/specifications/declaring-build-dependencies.rst index 74f9c3ca2..9e5b72308 100644 --- a/source/specifications/declaring-build-dependencies.rst +++ b/source/specifications/declaring-build-dependencies.rst @@ -5,6 +5,6 @@ Declaring build system dependencies =================================== -`pyproject.toml` is a build system independent file format defined in :pep:`518` +``pyproject.toml`` is a build system independent file format defined in :pep:`518` that projects may provide in order to declare any Python level dependencies that must be installed in order to run the project's build system successfully. diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst index 43b362109..009b8a592 100644 --- a/source/specifications/dependency-specifiers.rst +++ b/source/specifications/dependency-specifiers.rst @@ -488,4 +488,3 @@ References .. [#future_versions] Future Python versions might be problematic with the definition of Environment Marker Variable ``python_version`` (https://github.com/python/peps/issues/560) - diff --git a/source/specifications/externally-managed-environments.rst b/source/specifications/externally-managed-environments.rst index e4ee921d2..979b72aec 100644 --- a/source/specifications/externally-managed-environments.rst +++ b/source/specifications/externally-managed-environments.rst @@ -23,4 +23,4 @@ environment, and should instead guide the end user towards using History ======= -- `June 2022 `_: ``EXTERNALLY-MANAGED`` marker file was originally specified in :pep:`668#marking-an-interpreter-as-using-an-external-package-manager`. \ No newline at end of file +- `June 2022 `_: ``EXTERNALLY-MANAGED`` marker file was originally specified in :pep:`668#marking-an-interpreter-as-using-an-external-package-manager`. diff --git a/source/specifications/name-normalization.rst b/source/specifications/name-normalization.rst index 7a1a0e083..4756d1631 100644 --- a/source/specifications/name-normalization.rst +++ b/source/specifications/name-normalization.rst @@ -42,4 +42,4 @@ History ======= - `September 2015 `_: normalized name was originally specified in :pep:`503#normalized-names`. -- `November 2015 `_: valid non-normalized name was originally specified in :pep:`508#names`. \ No newline at end of file +- `November 2015 `_: valid non-normalized name was originally specified in :pep:`508#names`. diff --git a/source/tutorials/creating-documentation.rst b/source/tutorials/creating-documentation.rst index ec960ada0..483fb0d72 100644 --- a/source/tutorials/creating-documentation.rst +++ b/source/tutorials/creating-documentation.rst @@ -64,7 +64,3 @@ Other Sources For a more detailed guide on how to use Sphinx and reStructuredText, please see this `documentation tutorial`_ on Hitchhiker's Guide to Python. .. _documentation tutorial: https://docs.python-guide.org/writing/documentation/ - - - - diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index 89e1d073d..e92870030 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -245,7 +245,7 @@ if you'd like. # Example Package This is a simple example package. You can use - [Github-flavored Markdown](https://guides.github.com/features/mastering-markdown/) + [GitHub-flavored Markdown](https://guides.github.com/features/mastering-markdown/) to write your content. @@ -517,4 +517,3 @@ some things you can do: :ref:`pdm`, and :ref:`poetry`. * Read :pep:`517` and :pep:`518` for background and details on build tool configuration. * Read about :doc:`/guides/packaging-binary-extensions`. - From aa364050b2312651ece11ee32eb13722bc47a1de Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 2 Nov 2023 11:38:39 -0400 Subject: [PATCH 080/733] refactor: address feedback Signed-off-by: Henry Schreiner --- source/key_projects.rst | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/source/key_projects.rst b/source/key_projects.rst index 73c3aefa5..6bee5b7f1 100644 --- a/source/key_projects.rst +++ b/source/key_projects.rst @@ -484,7 +484,7 @@ Maturin `Docs `__ | `GitHub `__ -Maturin is a PEP 517 build backend for Rust extension modules, also written in +Maturin is a build backend for Rust extension modules, also written in Rust. It supports building wheels for python 3.7+ on Windows, Linux, macOS and FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support. @@ -632,14 +632,13 @@ scikit-build `GitHub `__ | `PyPI `__ -Scikit-build is an improved build system generator for CPython -C/C++/Fortran/Cython extensions that integrates with :ref:`setuptools`, :ref:`wheel` -and :ref:`pip`. It internally uses `cmake `__ (available -on PyPI) to provide better support for additional compilers, build systems, -cross compilation, and locating dependencies and their associated -build requirements. To speed up and parallelize the build of large projects, -the user can install `ninja `__ (also available -on PyPI). +Scikit-build is a :ref:`setuptools` wrapper for CPython that builds +C/C++/Fortran/Cython extensions It uses +`cmake `__ (available on PyPI) to provide +better support for additional compilers, build systems, cross compilation, and +locating dependencies and their associated build requirements. To speed up and +parallelize the build of large projects, the user can install `ninja +`__ (also available on PyPI). .. _scikit-build-core: @@ -650,7 +649,7 @@ scikit-build-core `GitHub `__ | `PyPI `__ -Scikit-build-core is a PEP 517 backend for CPython C/C++/Fortran/Cython +Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython extensions. It enables users to write extensions with `cmake `__ (available on PyPI) to provide better support for additional compilers, build systems, cross compilation, and From 5c774716bd0c8671d376e47a6d7c3e8222226fec Mon Sep 17 00:00:00 2001 From: Steve Dower Date: Thu, 2 Nov 2023 16:25:54 +0000 Subject: [PATCH 081/733] Apply suggestions from code review Co-authored-by: Henry Schreiner --- source/tutorials/packaging-projects.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index 0fc2e65d6..77211f876 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -104,11 +104,11 @@ Creating a test directory Choosing a build backend ------------------------ +------------------------ Tools like :ref:`pip` and :ref:`build` do not actually convert your sources into a :term:`distribution package ` (like a wheel); -that job is performed by a _build backend_. The build backend determines how +that job is performed by a *build backend*. The build backend determines how your project will specify its configuration, including metadata (information about the project, for example, the name and tags that are displayed on PyPI) and input files. Build backends have different levels of functionality, such as From b4da615f09c846e3cbf976ca4aba3f259c87d816 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Thu, 2 Nov 2023 13:40:31 -0700 Subject: [PATCH 082/733] Update sphinx-autobuild version --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 7ee85ca01..d6e0d750f 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,5 @@ sphinx==4.5.0 -sphinx-autobuild==0.7.1 +sphinx-autobuild==2021.3.14 sphinx-inline-tabs==2021.4.11b9 python-docs-theme==2023.9 sphinx-copybutton==0.5.0 From b4c0c7a627e3c19e712b8d93dba2c97808f55181 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Thu, 2 Nov 2023 13:52:59 -0700 Subject: [PATCH 083/733] Update CLI arg for sphinx-autobuild host --- noxfile.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/noxfile.py b/noxfile.py index 884b6ad08..b5d994701 100644 --- a/noxfile.py +++ b/noxfile.py @@ -39,7 +39,7 @@ def build(session, autobuild=False): if autobuild: command = "sphinx-autobuild" - extra_args = "-H", "0.0.0.0" + extra_args = "--host", "0.0.0.0" else: # NOTE: This branch adds options that are unsupported by autobuild command = "sphinx-build" From c1abfc2a8351655b5cbc9a082c1b1ea698e139f6 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Thu, 2 Nov 2023 14:06:35 -0700 Subject: [PATCH 084/733] Sort index to diataxis areas --- source/index.rst | 42 ++++++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/source/index.rst b/source/index.rst index 4cd8c8425..2c36d3570 100644 --- a/source/index.rst +++ b/source/index.rst @@ -32,34 +32,48 @@ happily accept any :doc:`contributions and feedback `. 😊 .. _GitHub: https://github.com/pypa/packaging.python.org -Get started -=========== +Overview +======== + +* To get an overview of packaging options for Python libraries and + applications, see the :doc:`Overview of Python Packaging ` + +Tutorials +========= Essential tools and concepts for working within the Python -development ecosystem are covered in our :doc:`tutorials/index` section: +development ecosystem are covered in our :doc:`tutorials/index` section. -* To get an overview of the flow used to publish your code, see the - :doc:`packaging flow ` * To learn how to install packages, see the :doc:`tutorial on installing packages ` * To learn how to manage dependencies in a version controlled project, see the :doc:`tutorial on managing application dependencies ` * To learn how to package and distribute your projects, see the :doc:`tutorial on packaging and distributing ` -* To get an overview of packaging options for Python libraries and - applications, see the :doc:`Overview of Python Packaging ` - -Learn more -========== - -Beyond our :doc:`tutorials/index`, this guide has several other resources: +Guides +====== * The :doc:`guides/index` section for walk throughs, such as :doc:`guides/installing-using-linux-tools` or :doc:`guides/packaging-binary-extensions`. + +Explanations and Discussions +============================ + +* To get an overview of the flow used to publish your code, see the + :doc:`packaging flow ` * The :doc:`discussions/index` section for in-depth references on topics such as :doc:`discussions/deploying-python-applications` or :doc:`discussions/pip-vs-easy-install`. -* The :doc:`specifications/index` section for packaging interoperability specifications. -Additionally, there is a list of :doc:`other projects ` maintained +Reference +========= + +* The :doc:`specifications/index` section for packaging interoperability specifications. +* Additionally, there is a list of :doc:`other projects ` maintained by members of the Python Packaging Authority. + +Get started +=========== + + + From 356dabd9f6bb9d31c77530b85ae6ae0036382b87 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Thu, 2 Nov 2023 18:04:53 -0700 Subject: [PATCH 085/733] Add prose for readability --- source/index.rst | 68 +++++++++++++++++++++++++++++------------------- 1 file changed, 41 insertions(+), 27 deletions(-) diff --git a/source/index.rst b/source/index.rst index 2c36d3570..c00ed0ad8 100644 --- a/source/index.rst +++ b/source/index.rst @@ -27,53 +27,67 @@ references to help you distribute and install Python packages with modern tools. This guide is maintained on `GitHub`_ by the :doc:`Python Packaging Authority `. We -happily accept any :doc:`contributions and feedback `. 😊 +happily accept :doc:`contributions and feedback `. 😊 .. _GitHub: https://github.com/pypa/packaging.python.org -Overview -======== +Overview and Flow +================= -* To get an overview of packaging options for Python libraries and - applications, see the :doc:`Overview of Python Packaging ` +.. note:: + + Building your understanding of Python packaging is a journey. Patience and + continuous improvement are key to success. The overview and flow sections + provide a starting point for understanding the Python packaging ecosystem. + +The :doc:`Overview of Python Packaging ` explains Python packaging +and its use when preparing and distributing projects. +This section helps you build understanding about selecting the tools and +processes that are most suitable for your use case. +It includes what packaging is, the problems that it solves, and +key considerations. + +To get an overview of the workflow used to publish your code, see +:doc:`packaging flow `. Tutorials ========= -Essential tools and concepts for working within the Python -development ecosystem are covered in our :doc:`tutorials/index` section. +Tutorials walk through the steps needed to complete a project for the first time. +Tutorials aim to help you succeed and provide a starting point for future +exploration. +The :doc:`tutorials/index` section includes: -* To learn how to install packages, see the - :doc:`tutorial on installing packages ` -* To learn how to manage dependencies in a version controlled project, see the - :doc:`tutorial on managing application dependencies ` -* To learn how to package and distribute your projects, see the - :doc:`tutorial on packaging and distributing ` +* A :doc:`tutorial on installing packages ` +* A :doc:`tutorial on managing application dependencies ` + in a version controlled project +* A :doc:`tutorial on packaging and distributing ` + your project Guides ====== -* The :doc:`guides/index` section for walk throughs, such as - :doc:`guides/installing-using-linux-tools` or :doc:`guides/packaging-binary-extensions`. +Guides provide steps to perform a specific task. Guides are more focused on +users who are already familiar with Python packaging and are looking for +specific information. + +The :doc:`guides/index` section provides "how to" instructions in three major +areas: package installation; building and distributing packages; miscellaneous +topics. Explanations and Discussions ============================ -* To get an overview of the flow used to publish your code, see the - :doc:`packaging flow ` -* The :doc:`discussions/index` section for in-depth references on topics such as - :doc:`discussions/deploying-python-applications` or :doc:`discussions/pip-vs-easy-install`. +The :doc:`discussions/index` section for in-depth explanations and discussion +about topics, such as: + +* :doc:`discussions/deploying-python-applications` +* :doc:`discussions/pip-vs-easy-install` Reference ========= * The :doc:`specifications/index` section for packaging interoperability specifications. -* Additionally, there is a list of :doc:`other projects ` maintained -by members of the Python Packaging Authority. - -Get started -=========== - - - +* The list of :doc:`other projects ` maintained by members of the Python Packaging Authority. +* The :doc:`glossary` for definitions of terms used in Python packaging. From 98cfc01a2db3fa80a87026b629c984511608278a Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Fri, 3 Nov 2023 18:03:32 +0100 Subject: [PATCH 086/733] Import PEP 518 text unchanged --- .../declaring-build-dependencies.rst | 561 ++++++++++++++++++ 1 file changed, 561 insertions(+) diff --git a/source/specifications/declaring-build-dependencies.rst b/source/specifications/declaring-build-dependencies.rst index 9e5b72308..fd882373c 100644 --- a/source/specifications/declaring-build-dependencies.rst +++ b/source/specifications/declaring-build-dependencies.rst @@ -8,3 +8,564 @@ Declaring build system dependencies ``pyproject.toml`` is a build system independent file format defined in :pep:`518` that projects may provide in order to declare any Python level dependencies that must be installed in order to run the project's build system successfully. + + +PEP: 518 +Title: Specifying Minimum Build System Requirements for Python Projects +Author: Brett Cannon , + Nathaniel J. Smith , + Donald Stufft +BDFL-Delegate: Alyssa Coghlan +Discussions-To: distutils-sig@python.org +Status: Final +Type: Standards Track +Topic: Packaging +Content-Type: text/x-rst +Created: 10-May-2016 +Post-History: 10-May-2016, + 11-May-2016, + 13-May-2016 +Resolution: https://mail.python.org/pipermail/distutils-sig/2016-May/028969.html + + +Abstract +======== + +This PEP specifies how Python software packages should specify what +build dependencies they have in order to execute their chosen build +system. As part of this specification, a new configuration file is +introduced for software packages to use to specify their build +dependencies (with the expectation that the same configuration file +will be used for future configuration details). + + +Rationale +========= + +When Python first developed its tooling for building distributions of +software for projects, distutils [#distutils]_ was the chosen +solution. As time went on, setuptools [#setuptools]_ gained popularity +to add some features on top of distutils. Both used the concept of a +``setup.py`` file that project maintainers executed to build +distributions of their software (as well as users to install said +distribution). + +Using an executable file to specify build requirements under distutils +isn't an issue as distutils is part of Python's standard library. +Having the build tool as part of Python means that a ``setup.py`` has +no external dependency that a project maintainer needs to worry about +to build a distribution of their project. There was no need to specify +any dependency information as the only dependency is Python. + +But when a project chooses to use setuptools, the use of an executable +file like ``setup.py`` becomes an issue. You can't execute a +``setup.py`` file without knowing its dependencies, but currently +there is no standard way to know what those dependencies are in an +automated fashion without executing the ``setup.py`` file where that +information is stored. It's a catch-22 of a file not being runnable +without knowing its own contents which can't be known programmatically +unless you run the file. + +Setuptools tried to solve this with a ``setup_requires`` argument to +its ``setup()`` function [#setup_args]_. This solution has a number +of issues, such as: + +* No tooling (besides setuptools itself) can access this information + without executing the ``setup.py``, but ``setup.py`` can't be + executed without having these items installed. +* While setuptools itself will install anything listed in this, they + won't be installed until *during* the execution of the ``setup()`` + function, which means that the only way to actually use anything + added here is through increasingly complex machinations that delay + the import and usage of these modules until later on in the + execution of the ``setup()`` function. +* This cannot include ``setuptools`` itself nor can it include a + replacement to ``setuptools``, which means that projects such as + ``numpy.distutils`` are largely incapable of utilizing it and + projects cannot take advantage of newer setuptools features until + their users naturally upgrade the version of setuptools to a newer + one. +* The items listed in ``setup_requires`` get implicitly installed + whenever you execute the ``setup.py`` but one of the common ways + that the ``setup.py`` is executed is via another tool, such as + ``pip``, who is already managing dependencies. This means that + a command like ``pip install spam`` might end up having both + pip and setuptools downloading and installing packages and end + users needing to configure *both* tools (and for ``setuptools`` + without being in control of the invocation) to change settings + like which repository it installs from. It also means that users + need to be aware of the discovery rules for both tools, as one + may support different package formats or determine the latest + version differently. + +This has culminated in a situation where use of ``setup_requires`` +is rare, where projects tend to either simply copy and paste snippets +between ``setup.py`` files or they eschew it all together in favor +of simply documenting elsewhere what they expect the user to have +manually installed prior to attempting to build or install their +project. + +All of this has led pip [#pip]_ to simply assume that setuptools is +necessary when executing a ``setup.py`` file. The problem with this, +though, is it doesn't scale if another project began to gain traction +in the community as setuptools has. It also prevents other projects +from gaining traction due to the friction required to use it with a +project when pip can't infer the fact that something other than +setuptools is required. + +This PEP attempts to rectify the situation by specifying a way to list +the minimal dependencies of the build system of a project in a +declarative fashion in a specific file. This allows a project to list +what build dependencies it has to go from e.g. source checkout to +wheel, while not falling into the catch-22 trap that a ``setup.py`` +has where tooling can't infer what a project needs to build itself. +Implementing this PEP will allow projects to specify what build system +they depend on upfront so that tools like pip can make sure that they +are installed in order to run the build system to build the project. + +To provide more context and motivation for this PEP, think of the +(rough) steps required to produce a built artifact for a project: + +1. The source checkout of the project. +2. Installation of the build system. +3. Execute the build system. + +This PEP covers step #2. :pep:`517` covers step #3, including how to have +the build system dynamically specify more dependencies that the build +system requires to perform its job. The purpose of this PEP though, is +to specify the minimal set of requirements for the build system to +simply begin execution. + + +Specification +============= + +File Format +----------- + +The build system dependencies will be stored in a file named +``pyproject.toml`` that is written in the TOML format [#toml]_. + +This format was chosen as it is human-usable (unlike JSON [#json]_), +it is flexible enough (unlike configparser [#configparser]_), stems +from a standard (also unlike configparser [#configparser]_), and it +is not overly complex (unlike YAML [#yaml]_). The TOML format is +already in use by the Rust community as part of their +Cargo package manager [#cargo]_ and in private email stated they have +been quite happy with their choice of TOML. A more thorough +discussion as to why various alternatives were not chosen can be read +in the `Other file formats`_ section. The authors do realize, though, +that choice of configuration file format is ultimately subjective and +a choice had to be made and the authors prefer TOML for this situation. + +Below we list the tables that tools are expected to recognize/respect. +Tables not specified in this PEP are reserved for future use by other +PEPs. + +build-system table +------------------ + +The ``[build-system]`` table is used to store build-related data. +Initially only one key of the table will be valid and is mandatory +for the table: ``requires``. This key must have a value of a list +of strings representing :pep:`508` dependencies required to execute the +build system (currently that means what dependencies are required to +execute a ``setup.py`` file). + +For the vast majority of Python projects that rely upon setuptools, +the ``pyproject.toml`` file will be:: + + [build-system] + # Minimum requirements for the build system to execute. + requires = ["setuptools", "wheel"] # PEP 508 specifications. + +Because the use of setuptools and wheel are so expansive in the +community at the moment, build tools are expected to use the example +configuration file above as their default semantics when a +``pyproject.toml`` file is not present. + +Tools should not require the existence of the ``[build-system]`` table. +A ``pyproject.toml`` file may be used to store configuration details +other than build-related data and thus lack a ``[build-system]`` table +legitimately. If the file exists but is lacking the ``[build-system]`` +table then the default values as specified above should be used. +If the table is specified but is missing required fields then the tool +should consider it an error. + + +tool table +---------- + +The ``[tool]`` table is where any tool related to your Python +project, not just build tools, can have users specify configuration +data as long as they use a sub-table within ``[tool]``, e.g. the +`flit `_ tool would store its +configuration in ``[tool.flit]``. + +We need some mechanism to allocate names within the ``tool.*`` +namespace, to make sure that different projects don't attempt to use +the same sub-table and collide. Our rule is that a project can use +the subtable ``tool.$NAME`` if, and only if, they own the entry for +``$NAME`` in the Cheeseshop/PyPI. + +JSON Schema +----------- + +To provide a type-specific representation of the resulting data from +the TOML file for illustrative purposes only, the following JSON +Schema [#jsonschema]_ would match the data format:: + + { + "$schema": "http://json-schema.org/schema#", + + "type": "object", + "additionalProperties": false, + + "properties": { + "build-system": { + "type": "object", + "additionalProperties": false, + + "properties": { + "requires": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": ["requires"] + }, + + "tool": { + "type": "object" + } + } + } + + +Rejected Ideas +============== + +A semantic version key +---------------------- + +For future-proofing the structure of the configuration file, a +``semantics-version`` key was initially proposed. Defaulting to ``1``, +the idea was that if any semantics changes to previously defined keys +or tables occurred which were not backwards-compatible, then the +``semantics-version`` would be incremented to a new number. + +In the end, though, it was decided that this was a premature +optimization. The expectation is that changes to what is pre-defined +semantically in the configuration file will be rather conservative. +And in the instances where a backwards-incompatible change would have +occurred, different names can be used for the new semantics to avoid +breaking older tools. + + +A more nested namespace +----------------------- + +An earlier draft of this PEP had a top-level ``[package]`` table. The +idea was to impose some scoping for a semantics versioning scheme +(see `A semantic version key`_ for why that idea was rejected). +With the need for scoping removed, the point of having a top-level +table became superfluous. + + +Other table names +----------------- + +Another name proposed for the ``[build-system]`` table was +``[build]``. The alternative name is shorter, but doesn't convey as +much of the intention of what information is stored in the table. After +a vote on the distutils-sig mailing list, the current name won out. + + +Other file formats +------------------ + +Several other file formats were put forward for consideration, all +rejected for various reasons. Key requirements were that the format +be editable by human beings and have an implementation that can be +vendored easily by projects. This outright excluded certain formats +like XML which are not friendly towards human beings and were never +seriously discussed. + +Overview of file formats considered +''''''''''''''''''''''''''''''''''' + +The key reasons for rejecting the other alternatives considered are +summarised in the following sections, while the full review (including +positive arguments in favour of TOML) can be found at [#file_formats]_. + +TOML was ultimately selected as it provided all the features we +were interested in, while avoiding the downsides introduced by +the alternatives. + +======================= ==== ==== ==== ======= +Feature TOML YAML JSON CFG/INI +======================= ==== ==== ==== ======= +Well-defined yes yes yes +Real data types yes yes yes +Reliable Unicode yes yes yes +Reliable comments yes yes +Easy for humans to edit yes ?? ?? +Easy for tools to edit yes ?? yes ?? +In standard library yes yes +Easy for pip to vendor yes n/a n/a +======================= ==== ==== ==== ======= + +("??" in the table indicates items where most folks would be +inclined to answer "yes", but there turn out to be a lot of +quirks and edge cases that arise in practice due to either +the lack of a clear specification, or else the underlying +file format specification being surprisingly complicated) + +The ``pytoml`` TOML parser is ~300 lines of pure Python code, +so being outside the standard library didn't count heavily +against it. + +Python literals were also discussed as a potential format, but +weren't considered in the file format review (since they're not +a common pre-existing file format). + + +JSON +'''' + +The JSON format [#json]_ was initially considered but quickly +rejected. While great as a human-readable, string-based data exchange +format, the syntax does not lend itself to easy editing by a human +being (e.g. the syntax is more verbose than necessary while not +allowing for comments). + +An example JSON file for the proposed data would be:: + + { + "build": { + "requires": [ + "setuptools", + "wheel>=0.27" + ] + } + } + + +YAML +'''' + +The YAML format [#yaml]_ was designed to be a superset of JSON +[#json]_ while being easier to work with by hand. There are three main +issues with YAML. + +One is that the specification is large: 86 pages if printed on +letter-sized paper. That leaves the possibility that someone may use a +feature of YAML that works with one parser but not another. It has +been suggested to standardize on a subset, but that basically means +creating a new standard specific to this file which is not tractable +long-term. + +Two is that YAML itself is not safe by default. The specification +allows for the arbitrary execution of code which is best avoided when +dealing with configuration data. It is of course possible to avoid +this behavior -- for example, PyYAML provides a ``safe_load`` operation +-- but if any tool carelessly uses ``load`` instead then they open +themselves up to arbitrary code execution. While this PEP is focused on +the building of projects which inherently involves code execution, +other configuration data such as project name and version number may +end up in the same file someday where arbitrary code execution is not +desired. + +And finally, the most popular Python implementation of YAML is +PyYAML [#pyyaml]_ which is a large project of a few thousand lines of +code and an optional C extension module. While in and of itself this +isn't necessarily an issue, this becomes more of a problem for +projects like pip where they would most likely need to vendor PyYAML +as a dependency so as to be fully self-contained (otherwise you end +up with your install tool needing an install tool to work). A +proof-of-concept re-working of PyYAML has been done to see how easy +it would be to potentially vendor a simpler version of the library +which shows it is a possibility. + +An example YAML file is:: + + build: + requires: + - setuptools + - wheel>=0.27 + + +configparser +'''''''''''' + +An INI-style configuration file based on what +configparser [#configparser]_ accepts was considered. Unfortunately +there is no specification of what configparser accepts, leading to +support skew between versions. For instance, what ConfigParser in +Python 2.7 accepts is not the same as what configparser in Python 3 +accepts. While one could standardize on what Python 3 accepts and +simply vendor the backport of the configparser module, that does mean +this PEP would have to codify that the backport of configparser must +be used by all project wishes to consume the metadata specified by +this PEP. This is overly restrictive and could lead to confusion if +someone is not aware of that a specific version of configparser is +expected. + +An example INI file is:: + + [build] + requires = + setuptools + wheel>=0.27 + + +Python literals +''''''''''''''' + +Someone proposed using Python literals as the configuration format. +The file would contain one dict at the top level, with the data all +inside that dict, with sections defined by the keys. All Python +programmers would be used to the format, there would implicitly be no +third-party dependency to read the configuration data, and it can be +safe if parsed by ``ast.literal_eval()`` [#ast_literal_eval]_. +Python literals can be identical to JSON, with the added benefit of +supporting trailing commas and comments. In addition, Python's richer +data model may be useful for some future configuration needs (e.g. non-string +dict keys, floating point vs. integer values). + +On the other hand, python literals are a Python-specific format, and +it is anticipated that these data may need to be read by packaging +tools, etc. that are not written in Python. + +An example Python literal file for the proposed data would be:: + + # The build configuration + {"build": {"requires": ["setuptools", + "wheel>=0.27", # note the trailing comma + # "numpy>=1.10" # a commented out data line + ] + # and here is an arbitrary comment. + } + } + + +Sticking with ``setup.cfg`` +--------------------------- + +There are two issues with ``setup.cfg`` used by setuptools as a general +format. One is that they are ``.ini`` files which have issues as mentioned +in the configparser_ discussion above. The other is that the schema for +that file has never been rigorously defined and thus it's unknown which +format would be safe to use going forward without potentially confusing +setuptools installations. + + + +Other file names +---------------- + +Several other file names were considered and rejected (although this +is very much a bikeshedding topic, and so the decision comes down to +mostly taste). + +pysettings.toml + Most reasonable alternative. + +pypa.toml + While it makes sense to reference the PyPA [#pypa]_, it is a + somewhat niche term. It's better to have the file name make sense + without having domain-specific knowledge. + +pybuild.toml + From the restrictive perspective of this PEP this filename makes + sense, but if any non-build metadata ever gets added to the file + then the name ceases to make sense. + +pip.toml + Too tool-specific. + +meta.toml + Too generic; project may want to have its own metadata file. + +setup.toml + While keeping with traditional thanks to ``setup.py``, it does not + necessarily match what the file may contain in the future (e.g. is + knowing the name of a project inherently part of its setup?). + +pymeta.toml + Not obvious to newcomers to programming and/or Python. + +pypackage.toml & pypackaging.toml + Name conflation of what a "package" is (project versus namespace). + +pydevelop.toml + The file may contain details not specific to development. + +pysource.toml + Not directly related to source code. + +pytools.toml + Misleading as the file is (currently) aimed at project management. + +dstufft.toml + Too person-specific. ;) + + +References +========== + +.. [#distutils] distutils + (https://docs.python.org/3/library/distutils.html#module-distutils) + +.. [#setuptools] setuptools + (https://pypi.python.org/pypi/setuptools) + +.. [#setup_args] setuptools: New and Changed setup() Keywords + (http://pythonhosted.org/setuptools/setuptools.html#new-and-changed-setup-keywords) + +.. [#pip] pip + (https://pypi.python.org/pypi/pip) + +.. [#wheel] wheel + (https://pypi.python.org/pypi/wheel) + +.. [#toml] TOML + (https://github.com/toml-lang/toml) + +.. [#json] JSON + (http://json.org/) + +.. [#yaml] YAML + (http://yaml.org/) + +.. [#configparser] configparser + (https://docs.python.org/3/library/configparser.html#module-configparser) + +.. [#pyyaml] PyYAML + (https://pypi.python.org/pypi/PyYAML) + +.. [#pypa] PyPA + (https://www.pypa.io) + +.. [#bazel] Bazel + (http://bazel.io/) + +.. [#ast_literal_eval] ``ast.literal_eval()`` + (https://docs.python.org/3/library/ast.html#ast.literal_eval) + +.. [#cargo] Cargo, Rust's package manager + (http://doc.crates.io/) + +.. [#jsonschema] JSON Schema + (http://json-schema.org/) + +.. [#file_formats] Nathaniel J. Smith's file format review + (https://gist.github.com/njsmith/78f68204c5d969f8c8bc645ef77d4a8f) + + +Copyright +========= + +This document has been placed in the public domain. From 001a68f7cf9008b8cfe820abadacf1487cb8c6d7 Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Fri, 3 Nov 2023 18:06:44 +0100 Subject: [PATCH 087/733] PEP 518: Trim rationale and boilerplate parts --- .../declaring-build-dependencies.rst | 441 ------------------ 1 file changed, 441 deletions(-) diff --git a/source/specifications/declaring-build-dependencies.rst b/source/specifications/declaring-build-dependencies.rst index fd882373c..d66597d43 100644 --- a/source/specifications/declaring-build-dependencies.rst +++ b/source/specifications/declaring-build-dependencies.rst @@ -10,24 +10,6 @@ that projects may provide in order to declare any Python level dependencies that must be installed in order to run the project's build system successfully. -PEP: 518 -Title: Specifying Minimum Build System Requirements for Python Projects -Author: Brett Cannon , - Nathaniel J. Smith , - Donald Stufft -BDFL-Delegate: Alyssa Coghlan -Discussions-To: distutils-sig@python.org -Status: Final -Type: Standards Track -Topic: Packaging -Content-Type: text/x-rst -Created: 10-May-2016 -Post-History: 10-May-2016, - 11-May-2016, - 13-May-2016 -Resolution: https://mail.python.org/pipermail/distutils-sig/2016-May/028969.html - - Abstract ======== @@ -39,104 +21,6 @@ dependencies (with the expectation that the same configuration file will be used for future configuration details). -Rationale -========= - -When Python first developed its tooling for building distributions of -software for projects, distutils [#distutils]_ was the chosen -solution. As time went on, setuptools [#setuptools]_ gained popularity -to add some features on top of distutils. Both used the concept of a -``setup.py`` file that project maintainers executed to build -distributions of their software (as well as users to install said -distribution). - -Using an executable file to specify build requirements under distutils -isn't an issue as distutils is part of Python's standard library. -Having the build tool as part of Python means that a ``setup.py`` has -no external dependency that a project maintainer needs to worry about -to build a distribution of their project. There was no need to specify -any dependency information as the only dependency is Python. - -But when a project chooses to use setuptools, the use of an executable -file like ``setup.py`` becomes an issue. You can't execute a -``setup.py`` file without knowing its dependencies, but currently -there is no standard way to know what those dependencies are in an -automated fashion without executing the ``setup.py`` file where that -information is stored. It's a catch-22 of a file not being runnable -without knowing its own contents which can't be known programmatically -unless you run the file. - -Setuptools tried to solve this with a ``setup_requires`` argument to -its ``setup()`` function [#setup_args]_. This solution has a number -of issues, such as: - -* No tooling (besides setuptools itself) can access this information - without executing the ``setup.py``, but ``setup.py`` can't be - executed without having these items installed. -* While setuptools itself will install anything listed in this, they - won't be installed until *during* the execution of the ``setup()`` - function, which means that the only way to actually use anything - added here is through increasingly complex machinations that delay - the import and usage of these modules until later on in the - execution of the ``setup()`` function. -* This cannot include ``setuptools`` itself nor can it include a - replacement to ``setuptools``, which means that projects such as - ``numpy.distutils`` are largely incapable of utilizing it and - projects cannot take advantage of newer setuptools features until - their users naturally upgrade the version of setuptools to a newer - one. -* The items listed in ``setup_requires`` get implicitly installed - whenever you execute the ``setup.py`` but one of the common ways - that the ``setup.py`` is executed is via another tool, such as - ``pip``, who is already managing dependencies. This means that - a command like ``pip install spam`` might end up having both - pip and setuptools downloading and installing packages and end - users needing to configure *both* tools (and for ``setuptools`` - without being in control of the invocation) to change settings - like which repository it installs from. It also means that users - need to be aware of the discovery rules for both tools, as one - may support different package formats or determine the latest - version differently. - -This has culminated in a situation where use of ``setup_requires`` -is rare, where projects tend to either simply copy and paste snippets -between ``setup.py`` files or they eschew it all together in favor -of simply documenting elsewhere what they expect the user to have -manually installed prior to attempting to build or install their -project. - -All of this has led pip [#pip]_ to simply assume that setuptools is -necessary when executing a ``setup.py`` file. The problem with this, -though, is it doesn't scale if another project began to gain traction -in the community as setuptools has. It also prevents other projects -from gaining traction due to the friction required to use it with a -project when pip can't infer the fact that something other than -setuptools is required. - -This PEP attempts to rectify the situation by specifying a way to list -the minimal dependencies of the build system of a project in a -declarative fashion in a specific file. This allows a project to list -what build dependencies it has to go from e.g. source checkout to -wheel, while not falling into the catch-22 trap that a ``setup.py`` -has where tooling can't infer what a project needs to build itself. -Implementing this PEP will allow projects to specify what build system -they depend on upfront so that tools like pip can make sure that they -are installed in order to run the build system to build the project. - -To provide more context and motivation for this PEP, think of the -(rough) steps required to produce a built artifact for a project: - -1. The source checkout of the project. -2. Installation of the build system. -3. Execute the build system. - -This PEP covers step #2. :pep:`517` covers step #3, including how to have -the build system dynamically specify more dependencies that the build -system requires to perform its job. The purpose of this PEP though, is -to specify the minimal set of requirements for the build system to -simply begin execution. - - Specification ============= @@ -146,18 +30,6 @@ File Format The build system dependencies will be stored in a file named ``pyproject.toml`` that is written in the TOML format [#toml]_. -This format was chosen as it is human-usable (unlike JSON [#json]_), -it is flexible enough (unlike configparser [#configparser]_), stems -from a standard (also unlike configparser [#configparser]_), and it -is not overly complex (unlike YAML [#yaml]_). The TOML format is -already in use by the Rust community as part of their -Cargo package manager [#cargo]_ and in private email stated they have -been quite happy with their choice of TOML. A more thorough -discussion as to why various alternatives were not chosen can be read -in the `Other file formats`_ section. The authors do realize, though, -that choice of configuration file format is ultimately subjective and -a choice had to be made and the authors prefer TOML for this situation. - Below we list the tables that tools are expected to recognize/respect. Tables not specified in this PEP are reserved for future use by other PEPs. @@ -244,328 +116,15 @@ Schema [#jsonschema]_ would match the data format:: } -Rejected Ideas -============== - -A semantic version key ----------------------- - -For future-proofing the structure of the configuration file, a -``semantics-version`` key was initially proposed. Defaulting to ``1``, -the idea was that if any semantics changes to previously defined keys -or tables occurred which were not backwards-compatible, then the -``semantics-version`` would be incremented to a new number. - -In the end, though, it was decided that this was a premature -optimization. The expectation is that changes to what is pre-defined -semantically in the configuration file will be rather conservative. -And in the instances where a backwards-incompatible change would have -occurred, different names can be used for the new semantics to avoid -breaking older tools. - - -A more nested namespace ------------------------ - -An earlier draft of this PEP had a top-level ``[package]`` table. The -idea was to impose some scoping for a semantics versioning scheme -(see `A semantic version key`_ for why that idea was rejected). -With the need for scoping removed, the point of having a top-level -table became superfluous. - - -Other table names ------------------ - -Another name proposed for the ``[build-system]`` table was -``[build]``. The alternative name is shorter, but doesn't convey as -much of the intention of what information is stored in the table. After -a vote on the distutils-sig mailing list, the current name won out. - - -Other file formats ------------------- - -Several other file formats were put forward for consideration, all -rejected for various reasons. Key requirements were that the format -be editable by human beings and have an implementation that can be -vendored easily by projects. This outright excluded certain formats -like XML which are not friendly towards human beings and were never -seriously discussed. - -Overview of file formats considered -''''''''''''''''''''''''''''''''''' - -The key reasons for rejecting the other alternatives considered are -summarised in the following sections, while the full review (including -positive arguments in favour of TOML) can be found at [#file_formats]_. - -TOML was ultimately selected as it provided all the features we -were interested in, while avoiding the downsides introduced by -the alternatives. - -======================= ==== ==== ==== ======= -Feature TOML YAML JSON CFG/INI -======================= ==== ==== ==== ======= -Well-defined yes yes yes -Real data types yes yes yes -Reliable Unicode yes yes yes -Reliable comments yes yes -Easy for humans to edit yes ?? ?? -Easy for tools to edit yes ?? yes ?? -In standard library yes yes -Easy for pip to vendor yes n/a n/a -======================= ==== ==== ==== ======= - -("??" in the table indicates items where most folks would be -inclined to answer "yes", but there turn out to be a lot of -quirks and edge cases that arise in practice due to either -the lack of a clear specification, or else the underlying -file format specification being surprisingly complicated) - -The ``pytoml`` TOML parser is ~300 lines of pure Python code, -so being outside the standard library didn't count heavily -against it. - -Python literals were also discussed as a potential format, but -weren't considered in the file format review (since they're not -a common pre-existing file format). - - -JSON -'''' - -The JSON format [#json]_ was initially considered but quickly -rejected. While great as a human-readable, string-based data exchange -format, the syntax does not lend itself to easy editing by a human -being (e.g. the syntax is more verbose than necessary while not -allowing for comments). - -An example JSON file for the proposed data would be:: - - { - "build": { - "requires": [ - "setuptools", - "wheel>=0.27" - ] - } - } - - -YAML -'''' - -The YAML format [#yaml]_ was designed to be a superset of JSON -[#json]_ while being easier to work with by hand. There are three main -issues with YAML. - -One is that the specification is large: 86 pages if printed on -letter-sized paper. That leaves the possibility that someone may use a -feature of YAML that works with one parser but not another. It has -been suggested to standardize on a subset, but that basically means -creating a new standard specific to this file which is not tractable -long-term. - -Two is that YAML itself is not safe by default. The specification -allows for the arbitrary execution of code which is best avoided when -dealing with configuration data. It is of course possible to avoid -this behavior -- for example, PyYAML provides a ``safe_load`` operation --- but if any tool carelessly uses ``load`` instead then they open -themselves up to arbitrary code execution. While this PEP is focused on -the building of projects which inherently involves code execution, -other configuration data such as project name and version number may -end up in the same file someday where arbitrary code execution is not -desired. - -And finally, the most popular Python implementation of YAML is -PyYAML [#pyyaml]_ which is a large project of a few thousand lines of -code and an optional C extension module. While in and of itself this -isn't necessarily an issue, this becomes more of a problem for -projects like pip where they would most likely need to vendor PyYAML -as a dependency so as to be fully self-contained (otherwise you end -up with your install tool needing an install tool to work). A -proof-of-concept re-working of PyYAML has been done to see how easy -it would be to potentially vendor a simpler version of the library -which shows it is a possibility. - -An example YAML file is:: - - build: - requires: - - setuptools - - wheel>=0.27 - - -configparser -'''''''''''' - -An INI-style configuration file based on what -configparser [#configparser]_ accepts was considered. Unfortunately -there is no specification of what configparser accepts, leading to -support skew between versions. For instance, what ConfigParser in -Python 2.7 accepts is not the same as what configparser in Python 3 -accepts. While one could standardize on what Python 3 accepts and -simply vendor the backport of the configparser module, that does mean -this PEP would have to codify that the backport of configparser must -be used by all project wishes to consume the metadata specified by -this PEP. This is overly restrictive and could lead to confusion if -someone is not aware of that a specific version of configparser is -expected. - -An example INI file is:: - - [build] - requires = - setuptools - wheel>=0.27 - - -Python literals -''''''''''''''' - -Someone proposed using Python literals as the configuration format. -The file would contain one dict at the top level, with the data all -inside that dict, with sections defined by the keys. All Python -programmers would be used to the format, there would implicitly be no -third-party dependency to read the configuration data, and it can be -safe if parsed by ``ast.literal_eval()`` [#ast_literal_eval]_. -Python literals can be identical to JSON, with the added benefit of -supporting trailing commas and comments. In addition, Python's richer -data model may be useful for some future configuration needs (e.g. non-string -dict keys, floating point vs. integer values). - -On the other hand, python literals are a Python-specific format, and -it is anticipated that these data may need to be read by packaging -tools, etc. that are not written in Python. - -An example Python literal file for the proposed data would be:: - - # The build configuration - {"build": {"requires": ["setuptools", - "wheel>=0.27", # note the trailing comma - # "numpy>=1.10" # a commented out data line - ] - # and here is an arbitrary comment. - } - } - - -Sticking with ``setup.cfg`` ---------------------------- - -There are two issues with ``setup.cfg`` used by setuptools as a general -format. One is that they are ``.ini`` files which have issues as mentioned -in the configparser_ discussion above. The other is that the schema for -that file has never been rigorously defined and thus it's unknown which -format would be safe to use going forward without potentially confusing -setuptools installations. - - - -Other file names ----------------- - -Several other file names were considered and rejected (although this -is very much a bikeshedding topic, and so the decision comes down to -mostly taste). - -pysettings.toml - Most reasonable alternative. - -pypa.toml - While it makes sense to reference the PyPA [#pypa]_, it is a - somewhat niche term. It's better to have the file name make sense - without having domain-specific knowledge. - -pybuild.toml - From the restrictive perspective of this PEP this filename makes - sense, but if any non-build metadata ever gets added to the file - then the name ceases to make sense. - -pip.toml - Too tool-specific. - -meta.toml - Too generic; project may want to have its own metadata file. - -setup.toml - While keeping with traditional thanks to ``setup.py``, it does not - necessarily match what the file may contain in the future (e.g. is - knowing the name of a project inherently part of its setup?). - -pymeta.toml - Not obvious to newcomers to programming and/or Python. - -pypackage.toml & pypackaging.toml - Name conflation of what a "package" is (project versus namespace). - -pydevelop.toml - The file may contain details not specific to development. - -pysource.toml - Not directly related to source code. - -pytools.toml - Misleading as the file is (currently) aimed at project management. - -dstufft.toml - Too person-specific. ;) - References ========== -.. [#distutils] distutils - (https://docs.python.org/3/library/distutils.html#module-distutils) - -.. [#setuptools] setuptools - (https://pypi.python.org/pypi/setuptools) - -.. [#setup_args] setuptools: New and Changed setup() Keywords - (http://pythonhosted.org/setuptools/setuptools.html#new-and-changed-setup-keywords) - -.. [#pip] pip - (https://pypi.python.org/pypi/pip) - -.. [#wheel] wheel - (https://pypi.python.org/pypi/wheel) - .. [#toml] TOML (https://github.com/toml-lang/toml) -.. [#json] JSON - (http://json.org/) - .. [#yaml] YAML (http://yaml.org/) -.. [#configparser] configparser - (https://docs.python.org/3/library/configparser.html#module-configparser) - -.. [#pyyaml] PyYAML - (https://pypi.python.org/pypi/PyYAML) - -.. [#pypa] PyPA - (https://www.pypa.io) - -.. [#bazel] Bazel - (http://bazel.io/) - -.. [#ast_literal_eval] ``ast.literal_eval()`` - (https://docs.python.org/3/library/ast.html#ast.literal_eval) - -.. [#cargo] Cargo, Rust's package manager - (http://doc.crates.io/) - .. [#jsonschema] JSON Schema (http://json-schema.org/) - -.. [#file_formats] Nathaniel J. Smith's file format review - (https://gist.github.com/njsmith/78f68204c5d969f8c8bc645ef77d4a8f) - - -Copyright -========= - -This document has been placed in the public domain. From 2ac05b5d801ba198bbe9d586ee4ac44d7d8c251c Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Fri, 3 Nov 2023 18:21:38 +0100 Subject: [PATCH 088/733] PEP 518: Light editing to fit packaging.python.org --- .../declaring-build-dependencies.rst | 139 +++++++----------- 1 file changed, 55 insertions(+), 84 deletions(-) diff --git a/source/specifications/declaring-build-dependencies.rst b/source/specifications/declaring-build-dependencies.rst index d66597d43..faa8542c6 100644 --- a/source/specifications/declaring-build-dependencies.rst +++ b/source/specifications/declaring-build-dependencies.rst @@ -5,56 +5,37 @@ Declaring build system dependencies =================================== -``pyproject.toml`` is a build system independent file format defined in :pep:`518` -that projects may provide in order to declare any Python level dependencies that -must be installed in order to run the project's build system successfully. +The ``pyproject.toml`` file is written in `TOML `_. +Among other metadata (such as :ref:`project metadata `), +it declares any Python level dependencies that must be installed in order to +run the project's build system successfully. +.. TODO: move this sentence elsewhere -Abstract -======== +Tables not defined by PyPA specifications are reserved for future use. -This PEP specifies how Python software packages should specify what -build dependencies they have in order to execute their chosen build -system. As part of this specification, a new configuration file is -introduced for software packages to use to specify their build -dependencies (with the expectation that the same configuration file -will be used for future configuration details). - - -Specification -============= - -File Format ------------ - -The build system dependencies will be stored in a file named -``pyproject.toml`` that is written in the TOML format [#toml]_. - -Below we list the tables that tools are expected to recognize/respect. -Tables not specified in this PEP are reserved for future use by other -PEPs. build-system table ------------------ The ``[build-system]`` table is used to store build-related data. -Initially only one key of the table will be valid and is mandatory +Currently, only one key of the table is be valid and is mandatory for the table: ``requires``. This key must have a value of a list -of strings representing :pep:`508` dependencies required to execute the -build system (currently that means what dependencies are required to -execute a ``setup.py`` file). +of strings representing dependencies required to execute the +build system. The strings in this list follow the :ref:`version specifier +specification `. + +An example ``build-system`` table for a project built with +``setuptools`` is: -For the vast majority of Python projects that rely upon setuptools, -the ``pyproject.toml`` file will be:: +.. code-block:: toml - [build-system] - # Minimum requirements for the build system to execute. - requires = ["setuptools", "wheel"] # PEP 508 specifications. + [build-system] + # Minimum requirements for the build system to execute. + requires = ["setuptools", "wheel"] -Because the use of setuptools and wheel are so expansive in the -community at the moment, build tools are expected to use the example -configuration file above as their default semantics when a -``pyproject.toml`` file is not present. +Build tools are expected to use the example configuration file above as +their default semantics when a ``pyproject.toml`` file is not present. Tools should not require the existence of the ``[build-system]`` table. A ``pyproject.toml`` file may be used to store configuration details @@ -65,6 +46,8 @@ If the table is specified but is missing required fields then the tool should consider it an error. +.. TODO: move elsewhere + tool table ---------- @@ -74,8 +57,8 @@ data as long as they use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``. -We need some mechanism to allocate names within the ``tool.*`` -namespace, to make sure that different projects don't attempt to use +A mechanism is needed to allocate names within the ``tool.*`` +namespace, to make sure that different projects do not attempt to use the same sub-table and collide. Our rule is that a project can use the subtable ``tool.$NAME`` if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI. @@ -84,47 +67,35 @@ JSON Schema ----------- To provide a type-specific representation of the resulting data from -the TOML file for illustrative purposes only, the following JSON -Schema [#jsonschema]_ would match the data format:: - - { - "$schema": "http://json-schema.org/schema#", - - "type": "object", - "additionalProperties": false, - - "properties": { - "build-system": { - "type": "object", - "additionalProperties": false, - - "properties": { - "requires": { - "type": "array", - "items": { - "type": "string" - } - } - }, - "required": ["requires"] - }, - - "tool": { - "type": "object" - } - } - } - - - -References -========== - -.. [#toml] TOML - (https://github.com/toml-lang/toml) - -.. [#yaml] YAML - (http://yaml.org/) - -.. [#jsonschema] JSON Schema - (http://json-schema.org/) +the TOML file for illustrative purposes only, the following +`JSON Schema `_ would match the data format: + +.. code-block:: json + + { + "$schema": "http://json-schema.org/schema#", + + "type": "object", + "additionalProperties": false, + + "properties": { + "build-system": { + "type": "object", + "additionalProperties": false, + + "properties": { + "requires": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": ["requires"] + }, + + "tool": { + "type": "object" + } + } + } From df0126e2daf96aa3da9b0d9bce1768dbe20171fe Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Fri, 3 Nov 2023 23:17:26 +0100 Subject: [PATCH 089/733] PEP 518: Remove wheel from the example requirements since it's a dependency of setuptools --- source/specifications/declaring-build-dependencies.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/declaring-build-dependencies.rst b/source/specifications/declaring-build-dependencies.rst index faa8542c6..5b4b73053 100644 --- a/source/specifications/declaring-build-dependencies.rst +++ b/source/specifications/declaring-build-dependencies.rst @@ -32,7 +32,7 @@ An example ``build-system`` table for a project built with [build-system] # Minimum requirements for the build system to execute. - requires = ["setuptools", "wheel"] + requires = ["setuptools"] Build tools are expected to use the example configuration file above as their default semantics when a ``pyproject.toml`` file is not present. From 3155ba410ebb10b1edc6f0d5e5c974a77ab11a04 Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Fri, 3 Nov 2023 23:18:37 +0100 Subject: [PATCH 090/733] =?UTF-8?q?Currently=20=E2=86=92=20Initially,=20+?= =?UTF-8?q?=20comment?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- source/specifications/declaring-build-dependencies.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/specifications/declaring-build-dependencies.rst b/source/specifications/declaring-build-dependencies.rst index 5b4b73053..3ac94b0b3 100644 --- a/source/specifications/declaring-build-dependencies.rst +++ b/source/specifications/declaring-build-dependencies.rst @@ -18,8 +18,10 @@ Tables not defined by PyPA specifications are reserved for future use. build-system table ------------------ +.. TODO: merge with PEP 517 + The ``[build-system]`` table is used to store build-related data. -Currently, only one key of the table is be valid and is mandatory +Initially, only one key of the table is valid and is mandatory for the table: ``requires``. This key must have a value of a list of strings representing dependencies required to execute the build system. The strings in this list follow the :ref:`version specifier From c665d9ad43fb6e370285609317ce87cd23a7cf11 Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Fri, 3 Nov 2023 23:56:20 +0100 Subject: [PATCH 091/733] Revert "PEP 518: Remove wheel from the example requirements since it's a dependency of setuptools" This reverts commit df0126e2daf96aa3da9b0d9bce1768dbe20171fe. --- source/specifications/declaring-build-dependencies.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/declaring-build-dependencies.rst b/source/specifications/declaring-build-dependencies.rst index 3ac94b0b3..c9a1aac9e 100644 --- a/source/specifications/declaring-build-dependencies.rst +++ b/source/specifications/declaring-build-dependencies.rst @@ -34,7 +34,7 @@ An example ``build-system`` table for a project built with [build-system] # Minimum requirements for the build system to execute. - requires = ["setuptools"] + requires = ["setuptools", "wheel"] Build tools are expected to use the example configuration file above as their default semantics when a ``pyproject.toml`` file is not present. From f8d3a40a19457d3d2585a53829d1df19df549031 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Fri, 3 Nov 2023 20:57:46 -0700 Subject: [PATCH 092/733] Update how to guide for installing using pip and venv --- ...ing-using-pip-and-virtual-environments.rst | 188 +++++++++--------- 1 file changed, 93 insertions(+), 95 deletions(-) diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst index 287c059f5..ce65d971a 100644 --- a/source/guides/installing-using-pip-and-virtual-environments.rst +++ b/source/guides/installing-using-pip-and-virtual-environments.rst @@ -1,22 +1,32 @@ -Installing packages using pip and virtual environments -====================================================== +Installing packages using pip and venv +====================================== This guide discusses how to install packages using :ref:`pip` and -a virtual environment manager: either :ref:`venv` for Python 3 or :ref:`virtualenv` -for Python 2. These are the lowest-level tools for managing Python -packages and are recommended if higher-level tools do not suit your needs. +the standard library's virtual environment manager :ref:`venv`. The guide +covers how to: -.. note:: This doc uses the term **package** to refer to a - :term:`Distribution Package` which is different from an :term:`Import - Package` that which is used to import modules in your Python source code. +* Install and update pip +* Create and use a virtual environment +* Install packages into a virtual environment using the ``pip`` command +* Use and create a requirements file -Installing pip --------------- +.. note:: This guide applies to Python 3.3 and higher. If using a + legacy version of Python 2.x, consider using :ref:`virtualenv`. -:ref:`pip` is the reference Python package manager. It's used to install and -update packages. You'll need to make sure you have the latest version of pip -installed. + +.. note:: This guide uses the term **package** to refer to a + :term:`Distribution Package`, which commonly is installed from an external + host. This differs from the term :term:`Import Package` which refers to + import modules in your Python source code. + + +Install and update pip +---------------------- + +:ref:`pip` is the reference Python package manager. +It's used to install and update packages. +Make sure you have the latest version of pip installed. .. tab:: Unix/macOS @@ -59,94 +69,68 @@ installed. pip 21.1.3 from c:\python39\lib\site-packages (Python 3.9.4) +Create and Use Virtual Environments +----------------------------------- -Installing virtualenv ---------------------- - -.. Note:: If you are using Python 3.3 or newer, the :mod:`venv` module is - the preferred way to create and manage virtual environments. - venv is included in the Python standard library and requires no additional installation. - If you are using venv, you may skip this section. - - -:ref:`virtualenv` is used to manage Python packages for different projects. -Using virtualenv allows you to avoid installing Python packages globally -which could break system tools or other projects. You can install virtualenv -using pip. +Create a new virtual environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:ref:`venv` (for Python 3) allows you to manage separate package installations for +different projects. It creates a "virtual" isolated Python installation. When +you switch projects, you can create a new virtual environment which is isolated +from other virtual environments. You benefit from the virtual environment +since packages can be installed confidently and will not interfere with the +other project environments. -.. tab:: Unix/macOS - - .. code-block:: bash - - python3 -m pip install --user virtualenv - -.. tab:: Windows - - .. code-block:: bat - - py -m pip install --user virtualenv - - - -Creating a virtual environment ------------------------------- - -:ref:`venv` (for Python 3) and :ref:`virtualenv` (for Python 2) allow -you to manage separate package installations for -different projects. They essentially allow you to create a "virtual" isolated -Python installation and install packages into that virtual installation. When -you switch projects, you can simply create a new virtual environment and not -have to worry about breaking the packages installed in the other environments. -It is always recommended to use a virtual environment while developing Python -applications. +.. tip:: + It is always recommended to use a virtual environment while developing Python + applications. To create a virtual environment, go to your project's directory and run -venv. If you are using Python 2, replace ``venv`` with ``virtualenv`` -in the below commands. +``venv``. .. tab:: Unix/macOS .. code-block:: bash - python3 -m venv env + python3 -m venv .venv .. tab:: Windows .. code-block:: bat - py -m venv env + py -m venv .venv The second argument is the location to create the virtual environment. Generally, you -can just create this in your project and call it ``env``. +can just create this in your project and call it ``.venv``. -venv will create a virtual Python installation in the ``env`` folder. +``venv`` will create a virtual Python installation in the ``.venv`` folder. .. Note:: You should exclude your virtual environment directory from your version control system using ``.gitignore`` or similar. -Activating a virtual environment --------------------------------- +Activate a virtual environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before you can start installing or using packages in your virtual environment you'll -need to *activate* it. Activating a virtual environment will put the -virtual environment-specific -``python`` and ``pip`` executables into your shell's ``PATH``. +need to ``activate`` it. Activating a virtual environment will put the +virtual environment-specific ``python`` and ``pip`` executables into your +shell's ``PATH``. .. tab:: Unix/macOS .. code-block:: bash - source env/bin/activate + source .venv/bin/activate .. tab:: Windows .. code-block:: bat - .\env\Scripts\activate + .\.venv\Scripts\activate -You can confirm you're in the virtual environment by checking the location of your +To confirm the virtual environment is activated, check the location of your Python interpreter: .. tab:: Unix/macOS @@ -161,43 +145,56 @@ Python interpreter: where python -It should be in the ``env`` directory: +When the virtual environment is activated, the location will include +the ``.venv`` directory: .. tab:: Unix/macOS .. code-block:: bash - .../env/bin/python + .../.venv/bin/python .. tab:: Windows .. code-block:: bat - ...\env\Scripts\python.exe + ...\.venv\Scripts\python.exe -As long as your virtual environment is activated pip will install packages into that -specific environment and you'll be able to import and use packages in your +While a virtual environment is activated, pip will install packages into that +specific environment. This enables you to import and use packages in your Python application. -Leaving the virtual environment -------------------------------- +Deactivate a virtual environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you want to switch projects or otherwise leave your virtual environment, simply run: +If you want to switch projects or leave your virtual environment, +``deactivate`` the environment: .. code-block:: bash deactivate -If you want to re-enter the virtual environment just follow the same instructions above -about activating a virtual environment. There's no need to re-create the virtual environment. + +Reactivate a virtual environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to reactivate an existing virtual environment, follow the same +instructions about activating a virtual environment. There's no need to create +a new virtual environment. -Installing packages -------------------- +Install packages using pip +-------------------------- -Now that you're in your virtual environment you can install packages. Let's install the +When your virtual environment is activated, you can install packages. Use the +``pip install`` command to install packages. + +Install a package +~~~~~~~~~~~~~~~~~ + +For example,let's install the `Requests`_ library from the :term:`Python Package Index (PyPI)`: .. tab:: Unix/macOS @@ -232,8 +229,8 @@ pip should download requests and all of its dependencies and install them: .. _Requests: https://pypi.org/project/requests/ -Installing specific versions ------------------------------ +Install a specific package version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ pip allows you to specify which version of a package to install using :term:`version specifiers `. For example, to install @@ -280,8 +277,8 @@ To install pre-release versions of packages, use the ``--pre`` flag: py -m pip install --pre requests -Installing extras ------------------ +Install extras +~~~~~~~~~~~~~~ Some packages have optional `extras`_. You can tell pip to install these by specifying the extra in brackets: @@ -302,10 +299,11 @@ specifying the extra in brackets: https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#optional-dependencies -Installing from source ----------------------- +Install a package from source +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -pip can install a package directly from source, for example: +pip can install a package directly from its source code. For example, to install +the source code in the ``google-auth`` directory: .. tab:: Unix/macOS @@ -339,8 +337,8 @@ installed package without needing to re-install: py -m pip install --editable . -Installing from version control systems ---------------------------------------- +Install from version control systems +------------------------------------ pip can install packages directly from their version control system. For example, you can install directly from a git repository: @@ -353,8 +351,8 @@ For more information on supported version control systems and syntax, see pip's documentation on :ref:`VCS Support `. -Installing from local archives ------------------------------- +Install from local archives +~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you have a local copy of a :term:`Distribution Package`'s archive (a zip, wheel, or tar file) you can install it directly with pip: @@ -392,8 +390,8 @@ connectivity or if you want to strictly control the origin of distribution packages. -Using other package indexes ---------------------------- +Install from other package indexes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want to download packages from a different index than the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` flag: @@ -444,8 +442,8 @@ install the latest version of ``requests`` and all of its dependencies: py -m pip install --upgrade requests -Using requirements files ------------------------- +Using a requirements file +------------------------- Instead of installing packages individually, pip allows you to declare all dependencies in a :ref:`Requirements File `. For @@ -504,5 +502,5 @@ Which will output a list of package specifiers such as: six==1.11.0 urllib3==1.22 -This is useful for creating :ref:`pip:Requirements Files` that can re-create -the exact versions of all packages installed in an environment. +The ``pip freeze`` command is useful for creating :ref:`pip:Requirements Files` +that can re-create the exact versions of all packages installed in an environment. From 83e8fc644c6607c40610c24142b80e99de4e192e Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Fri, 3 Nov 2023 21:04:41 -0700 Subject: [PATCH 093/733] fix formatting --- source/guides/installing-using-pip-and-virtual-environments.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst index ce65d971a..af2a1cad5 100644 --- a/source/guides/installing-using-pip-and-virtual-environments.rst +++ b/source/guides/installing-using-pip-and-virtual-environments.rst @@ -338,7 +338,7 @@ installed package without needing to re-install: Install from version control systems ------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ pip can install packages directly from their version control system. For example, you can install directly from a git repository: From 3d8231b000708d100b5b592cc84946b3e6a5da75 Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Fri, 3 Nov 2023 23:17:26 +0100 Subject: [PATCH 094/733] =?UTF-8?q?Re-apply=20=E2=80=9CPEP=20518:=20Remove?= =?UTF-8?q?=20wheel=20from=20the=20example=20requirements=20since=20it's?= =?UTF-8?q?=20a=20dependency=20of=20setuptools=E2=80=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- source/specifications/declaring-build-dependencies.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/declaring-build-dependencies.rst b/source/specifications/declaring-build-dependencies.rst index c9a1aac9e..3ac94b0b3 100644 --- a/source/specifications/declaring-build-dependencies.rst +++ b/source/specifications/declaring-build-dependencies.rst @@ -34,7 +34,7 @@ An example ``build-system`` table for a project built with [build-system] # Minimum requirements for the build system to execute. - requires = ["setuptools", "wheel"] + requires = ["setuptools"] Build tools are expected to use the example configuration file above as their default semantics when a ``pyproject.toml`` file is not present. From 84820945b5287ca5cb23ed19ae2e3fbb4ba91c08 Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Sat, 4 Nov 2023 11:21:21 +0100 Subject: [PATCH 095/733] Import PEP 440 verbatim --- source/specifications/version-specifiers.rst | 1661 ++++++++++++++++++ 1 file changed, 1661 insertions(+) diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst index 66a709a1f..0c18f8c66 100644 --- a/source/specifications/version-specifiers.rst +++ b/source/specifications/version-specifiers.rst @@ -10,3 +10,1664 @@ between versions are defined in :pep:`440`. The version specifiers section in this PEP supersedes the version specifiers section in :pep:`345`. + + +PEP: 440 +Title: Version Identification and Dependency Specification +Author: Alyssa Coghlan , + Donald Stufft +BDFL-Delegate: Alyssa Coghlan +Discussions-To: distutils-sig@python.org +Status: Final +Type: Standards Track +Topic: Packaging +Content-Type: text/x-rst +Created: 18-Mar-2013 +Post-History: 30-Mar-2013, 27-May-2013, 20-Jun-2013, + 21-Dec-2013, 28-Jan-2014, 08-Aug-2014, + 22-Aug-2014 +Replaces: 386 +Resolution: https://mail.python.org/pipermail/distutils-sig/2014-August/024673.html + + +Abstract +======== + +This PEP describes a scheme for identifying versions of Python software +distributions, and declaring dependencies on particular versions. + +This document addresses several limitations of the previous attempt at a +standardized approach to versioning, as described in :pep:`345` and :pep:`386`. + + +Definitions +=========== + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this +document are to be interpreted as described in :rfc:`2119`. + +"Projects" are software components that are made available for integration. +Projects include Python libraries, frameworks, scripts, plugins, +applications, collections of data or other resources, and various +combinations thereof. Public Python projects are typically registered on +the `Python Package Index `__. + +"Releases" are uniquely identified snapshots of a project. + +"Distributions" are the packaged files which are used to publish +and distribute a release. + +"Build tools" are automated tools intended to run on development systems, +producing source and binary distribution archives. Build tools may also be +invoked by integration tools in order to build software distributed as +sdists rather than prebuilt binary archives. + +"Index servers" are active distribution registries which publish version and +dependency metadata and place constraints on the permitted metadata. + +"Publication tools" are automated tools intended to run on development +systems and upload source and binary distribution archives to index servers. + +"Installation tools" are integration tools specifically intended to run on +deployment targets, consuming source and binary distribution archives from +an index server or other designated location and deploying them to the target +system. + +"Automated tools" is a collective term covering build tools, index servers, +publication tools, integration tools and any other software that produces +or consumes distribution version and dependency metadata. + +Version scheme +============== + +Distributions are identified by a public version identifier which +supports all defined version comparison operations + +The version scheme is used both to describe the distribution version +provided by a particular distribution archive, as well as to place +constraints on the version of dependencies needed in order to build or +run the software. + + +Public version identifiers +-------------------------- + +The canonical public version identifiers MUST comply with the following +scheme:: + + [N!]N(.N)*[{a|b|rc}N][.postN][.devN] + +Public version identifiers MUST NOT include leading or trailing whitespace. + +Public version identifiers MUST be unique within a given distribution. + +Installation tools SHOULD ignore any public versions which do not comply with +this scheme but MUST also include the normalizations specified below. +Installation tools MAY warn the user when non-compliant or ambiguous versions +are detected. + +See also ``Appendix B : Parsing version strings with regular expressions`` +which provides a regular expression to check strict conformance with the +canonical format, as well as a more permissive regular expression accepting +inputs that may require subsequent normalization. + +Public version identifiers are separated into up to five segments: + +* Epoch segment: ``N!`` +* Release segment: ``N(.N)*`` +* Pre-release segment: ``{a|b|rc}N`` +* Post-release segment: ``.postN`` +* Development release segment: ``.devN`` + +Any given release will be a "final release", "pre-release", "post-release" or +"developmental release" as defined in the following sections. + +All numeric components MUST be non-negative integers represented as sequences +of ASCII digits. + +All numeric components MUST be interpreted and ordered according to their +numeric value, not as text strings. + +All numeric components MAY be zero. Except as described below for the +release segment, a numeric component of zero has no special significance +aside from always being the lowest possible value in the version ordering. + +.. note:: + + Some hard to read version identifiers are permitted by this scheme in + order to better accommodate the wide range of versioning practices + across existing public and private Python projects. + + Accordingly, some of the versioning practices which are technically + permitted by the PEP are strongly discouraged for new projects. Where + this is the case, the relevant details are noted in the following + sections. + + +Local version identifiers +------------------------- + +Local version identifiers MUST comply with the following scheme:: + + [+] + +They consist of a normal public version identifier (as defined in the +previous section), along with an arbitrary "local version label", separated +from the public version identifier by a plus. Local version labels have +no specific semantics assigned, but some syntactic restrictions are imposed. + +Local version identifiers are used to denote fully API (and, if applicable, +ABI) compatible patched versions of upstream projects. For example, these +may be created by application developers and system integrators by applying +specific backported bug fixes when upgrading to a new upstream release would +be too disruptive to the application or other integrated system (such as a +Linux distribution). + +The inclusion of the local version label makes it possible to differentiate +upstream releases from potentially altered rebuilds by downstream +integrators. The use of a local version identifier does not affect the kind +of a release but, when applied to a source distribution, does indicate that +it may not contain the exact same code as the corresponding upstream release. + +To ensure local version identifiers can be readily incorporated as part of +filenames and URLs, and to avoid formatting inconsistencies in hexadecimal +hash representations, local version labels MUST be limited to the following +set of permitted characters: + +* ASCII letters (``[a-zA-Z]``) +* ASCII digits (``[0-9]``) +* periods (``.``) + +Local version labels MUST start and end with an ASCII letter or digit. + +Comparison and ordering of local versions considers each segment of the local +version (divided by a ``.``) separately. If a segment consists entirely of +ASCII digits then that section should be considered an integer for comparison +purposes and if a segment contains any ASCII letters then that segment is +compared lexicographically with case insensitivity. When comparing a numeric +and lexicographic segment, the numeric section always compares as greater than +the lexicographic segment. Additionally a local version with a great number of +segments will always compare as greater than a local version with fewer +segments, as long as the shorter local version's segments match the beginning +of the longer local version's segments exactly. + +An "upstream project" is a project that defines its own public versions. A +"downstream project" is one which tracks and redistributes an upstream project, +potentially backporting security and bug fixes from later versions of the +upstream project. + +Local version identifiers SHOULD NOT be used when publishing upstream +projects to a public index server, but MAY be used to identify private +builds created directly from the project source. Local +version identifiers SHOULD be used by downstream projects when releasing a +version that is API compatible with the version of the upstream project +identified by the public version identifier, but contains additional changes +(such as bug fixes). As the Python Package Index is intended solely for +indexing and hosting upstream projects, it MUST NOT allow the use of local +version identifiers. + +Source distributions using a local version identifier SHOULD provide the +``python.integrator`` extension metadata (as defined in :pep:`459`). + + +Final releases +-------------- + +A version identifier that consists solely of a release segment and optionally +an epoch identifier is termed a "final release". + +The release segment consists of one or more non-negative integer +values, separated by dots:: + + N(.N)* + +Final releases within a project MUST be numbered in a consistently +increasing fashion, otherwise automated tools will not be able to upgrade +them correctly. + +Comparison and ordering of release segments considers the numeric value +of each component of the release segment in turn. When comparing release +segments with different numbers of components, the shorter segment is +padded out with additional zeros as necessary. + +While any number of additional components after the first are permitted +under this scheme, the most common variants are to use two components +("major.minor") or three components ("major.minor.micro"). + +For example:: + + 0.9 + 0.9.1 + 0.9.2 + ... + 0.9.10 + 0.9.11 + 1.0 + 1.0.1 + 1.1 + 2.0 + 2.0.1 + ... + +A release series is any set of final release numbers that start with a +common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all +part of the ``3.3`` release series. + +.. note:: + + ``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as + the release segment comparison rules implicit expand the two component + form to ``X.Y.0`` when comparing it to any release segment that includes + three components. + +Date based release segments are also permitted. An example of a date based +release scheme using the year and month of the release:: + + 2012.4 + 2012.7 + 2012.10 + 2013.1 + 2013.6 + ... + + +Pre-releases +------------ + +Some projects use an "alpha, beta, release candidate" pre-release cycle to +support testing by their users prior to a final release. + +If used as part of a project's development cycle, these pre-releases are +indicated by including a pre-release segment in the version identifier:: + + X.YaN # Alpha release + X.YbN # Beta release + X.YrcN # Release Candidate + X.Y # Final release + +A version identifier that consists solely of a release segment and a +pre-release segment is termed a "pre-release". + +The pre-release segment consists of an alphabetical identifier for the +pre-release phase, along with a non-negative integer value. Pre-releases for +a given release are ordered first by phase (alpha, beta, release candidate) +and then by the numerical component within that phase. + +Installation tools MAY accept both ``c`` and ``rc`` releases for a common +release segment in order to handle some existing legacy distributions. + +Installation tools SHOULD interpret ``c`` versions as being equivalent to +``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``). + +Build tools, publication tools and index servers SHOULD disallow the creation +of both ``rc`` and ``c`` releases for a common release segment. + + +Post-releases +------------- + +Some projects use post-releases to address minor errors in a final release +that do not affect the distributed software (for example, correcting an error +in the release notes). + +If used as part of a project's development cycle, these post-releases are +indicated by including a post-release segment in the version identifier:: + + X.Y.postN # Post-release + +A version identifier that includes a post-release segment without a +developmental release segment is termed a "post-release". + +The post-release segment consists of the string ``.post``, followed by a +non-negative integer value. Post-releases are ordered by their +numerical component, immediately following the corresponding release, +and ahead of any subsequent release. + +.. note:: + + The use of post-releases to publish maintenance releases containing + actual bug fixes is strongly discouraged. In general, it is better + to use a longer release number and increment the final component + for each maintenance release. + +Post-releases are also permitted for pre-releases:: + + X.YaN.postM # Post-release of an alpha release + X.YbN.postM # Post-release of a beta release + X.YrcN.postM # Post-release of a release candidate + +.. note:: + + Creating post-releases of pre-releases is strongly discouraged, as + it makes the version identifier difficult to parse for human readers. + In general, it is substantially clearer to simply create a new + pre-release by incrementing the numeric component. + + +Developmental releases +---------------------- + +Some projects make regular developmental releases, and system packagers +(especially for Linux distributions) may wish to create early releases +directly from source control which do not conflict with later project +releases. + +If used as part of a project's development cycle, these developmental +releases are indicated by including a developmental release segment in the +version identifier:: + + X.Y.devN # Developmental release + +A version identifier that includes a developmental release segment is +termed a "developmental release". + +The developmental release segment consists of the string ``.dev``, +followed by a non-negative integer value. Developmental releases are ordered +by their numerical component, immediately before the corresponding release +(and before any pre-releases with the same release segment), and following +any previous release (including any post-releases). + +Developmental releases are also permitted for pre-releases and +post-releases:: + + X.YaN.devM # Developmental release of an alpha release + X.YbN.devM # Developmental release of a beta release + X.YrcN.devM # Developmental release of a release candidate + X.Y.postN.devM # Developmental release of a post-release + +.. note:: + + While they may be useful for continuous integration purposes, publishing + developmental releases of pre-releases to general purpose public index + servers is strongly discouraged, as it makes the version identifier + difficult to parse for human readers. If such a release needs to be + published, it is substantially clearer to instead create a new + pre-release by incrementing the numeric component. + + Developmental releases of post-releases are also strongly discouraged, + but they may be appropriate for projects which use the post-release + notation for full maintenance releases which may include code changes. + + +Version epochs +-------------- + +If included in a version identifier, the epoch appears before all other +components, separated from the release segment by an exclamation mark:: + + E!X.Y # Version identifier with epoch + +If no explicit epoch is given, the implicit epoch is ``0``. + +Most version identifiers will not include an epoch, as an explicit epoch is +only needed if a project *changes* the way it handles version numbering in +a way that means the normal version ordering rules will give the wrong +answer. For example, if a project is using date based versions like +``2014.04`` and would like to switch to semantic versions like ``1.0``, then +the new releases would be identified as *older* than the date based releases +when using the normal sorting scheme:: + + 1.0 + 1.1 + 2.0 + 2013.10 + 2014.04 + +However, by specifying an explicit epoch, the sort order can be changed +appropriately, as all versions from a later epoch are sorted after versions +from an earlier epoch:: + + 2013.10 + 2014.04 + 1!1.0 + 1!1.1 + 1!2.0 + +Normalization +------------- + +In order to maintain better compatibility with existing versions there are a +number of "alternative" syntaxes that MUST be taken into account when parsing +versions. These syntaxes MUST be considered when parsing a version, however +they should be "normalized" to the standard syntax defined above. + + +Case sensitivity +~~~~~~~~~~~~~~~~ + +All ascii letters should be interpreted case insensitively within a version and +the normal form is lowercase. This allows versions such as ``1.1RC1`` which +would be normalized to ``1.1rc1``. + + +Integer Normalization +~~~~~~~~~~~~~~~~~~~~~ + +All integers are interpreted via the ``int()`` built in and normalize to the +string form of the output. This means that an integer version of ``00`` would +normalize to ``0`` while ``09000`` would normalize to ``9000``. This does not +hold true for integers inside of an alphanumeric segment of a local version +such as ``1.0+foo0100`` which is already in its normalized form. + + +Pre-release separators +~~~~~~~~~~~~~~~~~~~~~~ + +Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the +release segment and the pre-release segment. The normal form for this is +without a separator. This allows versions such as ``1.1.a1`` or ``1.1-a1`` +which would be normalized to ``1.1a1``. It should also allow a separator to +be used between the pre-release signifier and the numeral. This allows versions +such as ``1.0a.1`` which would be normalized to ``1.0a1``. + + +Pre-release spelling +~~~~~~~~~~~~~~~~~~~~ + +Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, +``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` +respectively. This allows versions such as ``1.1alpha1``, ``1.1beta2``, or +``1.1c3`` which normalize to ``1.1a1``, ``1.1b2``, and ``1.1rc3``. In every +case the additional spelling should be considered equivalent to their normal +forms. + + +Implicit pre-release number +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Pre releases allow omitting the numeral in which case it is implicitly assumed +to be ``0``. The normal form for this is to include the ``0`` explicitly. This +allows versions such as ``1.2a`` which is normalized to ``1.2a0``. + + +Post release separators +~~~~~~~~~~~~~~~~~~~~~~~ + +Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting the +separator all together. The normal form of this is with the ``.`` separator. +This allows versions such as ``1.2-post2`` or ``1.2post2`` which normalize to +``1.2.post2``. Like the pre-release separator this also allows an optional +separator between the post release signifier and the numeral. This allows +versions like ``1.2.post-2`` which would normalize to ``1.2.post2``. + + +Post release spelling +~~~~~~~~~~~~~~~~~~~~~ + +Post-releases allow the additional spellings of ``rev`` and ``r``. This allows +versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As with the +pre-releases the additional spellings should be considered equivalent to their +normal forms. + + +Implicit post release number +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Post releases allow omitting the numeral in which case it is implicitly assumed +to be ``0``. The normal form for this is to include the ``0`` explicitly. This +allows versions such as ``1.2.post`` which is normalized to ``1.2.post0``. + + +Implicit post releases +~~~~~~~~~~~~~~~~~~~~~~ + +Post releases allow omitting the ``post`` signifier all together. When using +this form the separator MUST be ``-`` and no other form is allowed. This allows +versions such as ``1.0-1`` to be normalized to ``1.0.post1``. This particular +normalization MUST NOT be used in conjunction with the implicit post release +number rule. In other words, ``1.0-`` is *not* a valid version and it does *not* +normalize to ``1.0.post0``. + + +Development release separators +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Development releases allow a ``.``, ``-``, or a ``_`` separator as well as +omitting the separator all together. The normal form of this is with the ``.`` +separator. This allows versions such as ``1.2-dev2`` or ``1.2dev2`` which +normalize to ``1.2.dev2``. + + +Implicit development release number +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Development releases allow omitting the numeral in which case it is implicitly +assumed to be ``0``. The normal form for this is to include the ``0`` +explicitly. This allows versions such as ``1.2.dev`` which is normalized to +``1.2.dev0``. + + +Local version segments +~~~~~~~~~~~~~~~~~~~~~~ + +With a local version, in addition to the use of ``.`` as a separator of +segments, the use of ``-`` and ``_`` is also acceptable. The normal form is +using the ``.`` character. This allows versions such as ``1.0+ubuntu-1`` to be +normalized to ``1.0+ubuntu.1``. + + +Preceding v character +~~~~~~~~~~~~~~~~~~~~~ + +In order to support the common version notation of ``v1.0`` versions may be +preceded by a single literal ``v`` character. This character MUST be ignored +for all purposes and should be omitted from all normalized forms of the +version. The same version with and without the ``v`` is considered equivalent. + + +Leading and Trailing Whitespace +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Leading and trailing whitespace must be silently ignored and removed from all +normalized forms of a version. This includes ``" "``, ``\t``, ``\n``, ``\r``, +``\f``, and ``\v``. This allows accidental whitespace to be handled sensibly, +such as a version like ``1.0\n`` which normalizes to ``1.0``. + + +Examples of compliant version schemes +------------------------------------- + +The standard version scheme is designed to encompass a wide range of +identification practices across public and private Python projects. In +practice, a single project attempting to use the full flexibility offered +by the scheme would create a situation where human users had difficulty +figuring out the relative order of versions, even though the rules above +ensure all compliant tools will order them consistently. + +The following examples illustrate a small selection of the different +approaches projects may choose to identify their releases, while still +ensuring that the "latest release" and the "latest stable release" can +be easily determined, both by human users and automated tools. + +Simple "major.minor" versioning:: + + 0.1 + 0.2 + 0.3 + 1.0 + 1.1 + ... + +Simple "major.minor.micro" versioning:: + + 1.1.0 + 1.1.1 + 1.1.2 + 1.2.0 + ... + +"major.minor" versioning with alpha, beta and candidate +pre-releases:: + + 0.9 + 1.0a1 + 1.0a2 + 1.0b1 + 1.0rc1 + 1.0 + 1.1a1 + ... + +"major.minor" versioning with developmental releases, release candidates +and post-releases for minor corrections:: + + 0.9 + 1.0.dev1 + 1.0.dev2 + 1.0.dev3 + 1.0.dev4 + 1.0c1 + 1.0c2 + 1.0 + 1.0.post1 + 1.1.dev1 + ... + +Date based releases, using an incrementing serial within each year, skipping +zero:: + + 2012.1 + 2012.2 + 2012.3 + ... + 2012.15 + 2013.1 + 2013.2 + ... + + +Summary of permitted suffixes and relative ordering +--------------------------------------------------- + +.. note:: + + This section is intended primarily for authors of tools that + automatically process distribution metadata, rather than developers + of Python distributions deciding on a versioning scheme. + +The epoch segment of version identifiers MUST be sorted according to the +numeric value of the given epoch. If no epoch segment is present, the +implicit numeric value is ``0``. + +The release segment of version identifiers MUST be sorted in +the same order as Python's tuple sorting when the normalized release segment is +parsed as follows:: + + tuple(map(int, release_segment.split("."))) + +All release segments involved in the comparison MUST be converted to a +consistent length by padding shorter segments with zeros as needed. + +Within a numeric release (``1.0``, ``2.7.3``), the following suffixes +are permitted and MUST be ordered as shown:: + + .devN, aN, bN, rcN, , .postN + +Note that ``c`` is considered to be semantically equivalent to ``rc`` and must +be sorted as if it were ``rc``. Tools MAY reject the case of having the same +``N`` for both a ``c`` and a ``rc`` in the same release segment as ambiguous +and remain in compliance with the PEP. + +Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate +(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be +ordered as shown:: + + .devN, , .postN + +Within a post-release (``1.0.post1``), the following suffixes are permitted +and MUST be ordered as shown:: + + .devN, + +Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even +when used immediately following a numeric version (e.g. ``1.0.dev456``, +``1.0.post1``). + +Within a pre-release, post-release or development release segment with a +shared prefix, ordering MUST be by the value of the numeric component. + +The following example covers many of the possible combinations:: + + 1.dev0 + 1.0.dev456 + 1.0a1 + 1.0a2.dev456 + 1.0a12.dev456 + 1.0a12 + 1.0b1.dev456 + 1.0b2 + 1.0b2.post345.dev456 + 1.0b2.post345 + 1.0rc1.dev456 + 1.0rc1 + 1.0 + 1.0+abc.5 + 1.0+abc.7 + 1.0+5 + 1.0.post456.dev34 + 1.0.post456 + 1.0.15 + 1.1.dev1 + + +Version ordering across different metadata versions +--------------------------------------------------- + +Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a standard +version identification or ordering scheme. However metadata v1.2 (:pep:`345`) +does specify a scheme which is defined in :pep:`386`. + +Due to the nature of the simple installer API it is not possible for an +installer to be aware of which metadata version a particular distribution was +using. Additionally installers required the ability to create a reasonably +prioritized list that includes all, or as many as possible, versions of +a project to determine which versions it should install. These requirements +necessitate a standardization across one parsing mechanism to be used for all +versions of a project. + +Due to the above, this PEP MUST be used for all versions of metadata and +supersedes :pep:`386` even for metadata v1.2. Tools SHOULD ignore any versions +which cannot be parsed by the rules in this PEP, but MAY fall back to +implementation defined version parsing and ordering schemes if no versions +complying with this PEP are available. + +Distribution users may wish to explicitly remove non-compliant versions from +any private package indexes they control. + + +Compatibility with other version schemes +---------------------------------------- + +Some projects may choose to use a version scheme which requires +translation in order to comply with the public version scheme defined in +this PEP. In such cases, the project specific version can be stored in the +metadata while the translated public version is published in the version field. + +This allows automated distribution tools to provide consistently correct +ordering of published releases, while still allowing developers to use +the internal versioning scheme they prefer for their projects. + + +Semantic versioning +~~~~~~~~~~~~~~~~~~~ + +`Semantic versioning`_ is a popular version identification scheme that is +more prescriptive than this PEP regarding the significance of different +elements of a release number. Even if a project chooses not to abide by +the details of semantic versioning, the scheme is worth understanding as +it covers many of the issues that can arise when depending on other +distributions, and when publishing a distribution that others rely on. + +The "Major.Minor.Patch" (described in this PEP as "major.minor.micro") +aspects of semantic versioning (clauses 1-8 in the 2.0.0 specification) +are fully compatible with the version scheme defined in this PEP, and abiding +by these aspects is encouraged. + +Semantic versions containing a hyphen (pre-releases - clause 10) or a +plus sign (builds - clause 11) are *not* compatible with this PEP +and are not permitted in the public version field. + +One possible mechanism to translate such semantic versioning based source +labels to compatible public versions is to use the ``.devN`` suffix to +specify the appropriate version order. + +Specific build information may also be included in local version labels. + +.. _Semantic versioning: https://semver.org/ + + +DVCS based version labels +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Many build tools integrate with distributed version control systems like +Git and Mercurial in order to add an identifying hash to the version +identifier. As hashes cannot be ordered reliably such versions are not +permitted in the public version field. + +As with semantic versioning, the public ``.devN`` suffix may be used to +uniquely identify such releases for publication, while the original DVCS based +label can be stored in the project metadata. + +Identifying hash information may also be included in local version labels. + + +Olson database versioning +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``pytz`` project inherits its versioning scheme from the corresponding +Olson timezone database versioning scheme: the year followed by a lowercase +character indicating the version of the database within that year. + +This can be translated to a compliant public version identifier as +``.``, where the serial starts at zero or one (for the +'a' release) and is incremented with each subsequent database +update within the year. + +As with other translated version identifiers, the corresponding Olson +database version could be recorded in the project metadata. + + +Version specifiers +================== + +A version specifier consists of a series of version clauses, separated by +commas. For example:: + + ~= 0.9, >= 1.0, != 1.3.4.*, < 2.0 + +The comparison operator determines the kind of version clause: + +* ``~=``: `Compatible release`_ clause +* ``==``: `Version matching`_ clause +* ``!=``: `Version exclusion`_ clause +* ``<=``, ``>=``: `Inclusive ordered comparison`_ clause +* ``<``, ``>``: `Exclusive ordered comparison`_ clause +* ``===``: `Arbitrary equality`_ clause. + +The comma (",") is equivalent to a logical **and** operator: a candidate +version must match all given version clauses in order to match the +specifier as a whole. + +Whitespace between a conditional operator and the following version +identifier is optional, as is the whitespace around the commas. + +When multiple candidate versions match a version specifier, the preferred +version SHOULD be the latest version as determined by the consistent +ordering defined by the standard `Version scheme`_. Whether or not +pre-releases are considered as candidate versions SHOULD be handled as +described in `Handling of pre-releases`_. + +Except where specifically noted below, local version identifiers MUST NOT be +permitted in version specifiers, and local version labels MUST be ignored +entirely when checking if candidate versions match a given version +specifier. + + +Compatible release +------------------ + +A compatible release clause consists of the compatible release operator ``~=`` +and a version identifier. It matches any candidate version that is expected +to be compatible with the specified version. + +The specified version identifier must be in the standard format described in +`Version scheme`_. Local version identifiers are NOT permitted in this +version specifier. + +For a given release identifier ``V.N``, the compatible release clause is +approximately equivalent to the pair of comparison clauses:: + + >= V.N, == V.* + +This operator MUST NOT be used with a single segment version number such as +``~=1``. + +For example, the following groups of version clauses are equivalent:: + + ~= 2.2 + >= 2.2, == 2.* + + ~= 1.4.5 + >= 1.4.5, == 1.4.* + +If a pre-release, post-release or developmental release is named in a +compatible release clause as ``V.N.suffix``, then the suffix is ignored +when determining the required prefix match:: + + ~= 2.2.post3 + >= 2.2.post3, == 2.* + + ~= 1.4.5a4 + >= 1.4.5a4, == 1.4.* + +The padding rules for release segment comparisons means that the assumed +degree of forward compatibility in a compatible release clause can be +controlled by appending additional zeros to the version specifier:: + + ~= 2.2.0 + >= 2.2.0, == 2.2.* + + ~= 1.4.5.0 + >= 1.4.5.0, == 1.4.5.* + + +Version matching +---------------- + +A version matching clause includes the version matching operator ``==`` +and a version identifier. + +The specified version identifier must be in the standard format described in +`Version scheme`_, but a trailing ``.*`` is permitted on public version +identifiers as described below. + +By default, the version matching operator is based on a strict equality +comparison: the specified version must be exactly the same as the requested +version. The *only* substitution performed is the zero padding of the +release segment to ensure the release segments are compared with the same +length. + +Whether or not strict version matching is appropriate depends on the specific +use case for the version specifier. Automated tools SHOULD at least issue +warnings and MAY reject them entirely when strict version matches are used +inappropriately. + +Prefix matching may be requested instead of strict comparison, by appending +a trailing ``.*`` to the version identifier in the version matching clause. +This means that additional trailing segments will be ignored when +determining whether or not a version identifier matches the clause. If the +specified version includes only a release segment, than trailing components +(or the lack thereof) in the release segment are also ignored. + +For example, given the version ``1.1.post1``, the following clauses would +match or not as shown:: + + == 1.1 # Not equal, so 1.1.post1 does not match clause + == 1.1.post1 # Equal, so 1.1.post1 matches clause + == 1.1.* # Same prefix, so 1.1.post1 matches clause + +For purposes of prefix matching, the pre-release segment is considered to +have an implied preceding ``.``, so given the version ``1.1a1``, the +following clauses would match or not as shown:: + + == 1.1 # Not equal, so 1.1a1 does not match clause + == 1.1a1 # Equal, so 1.1a1 matches clause + == 1.1.* # Same prefix, so 1.1a1 matches clause if pre-releases are requested + +An exact match is also considered a prefix match (this interpretation is +implied by the usual zero padding rules for the release segment of version +identifiers). Given the version ``1.1``, the following clauses would +match or not as shown:: + + == 1.1 # Equal, so 1.1 matches clause + == 1.1.0 # Zero padding expands 1.1 to 1.1.0, so it matches clause + == 1.1.dev1 # Not equal (dev-release), so 1.1 does not match clause + == 1.1a1 # Not equal (pre-release), so 1.1 does not match clause + == 1.1.post1 # Not equal (post-release), so 1.1 does not match clause + == 1.1.* # Same prefix, so 1.1 matches clause + +It is invalid to have a prefix match containing a development or local release +such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the development release +segment is always the final segment in the public version, and the local version +is ignored for comparison purposes, so using either in a prefix match wouldn't +make any sense. + +The use of ``==`` (without at least the wildcard suffix) when defining +dependencies for published distributions is strongly discouraged as it +greatly complicates the deployment of security fixes. The strict version +comparison operator is intended primarily for use when defining +dependencies for repeatable *deployments of applications* while using +a shared distribution index. + +If the specified version identifier is a public version identifier (no +local version label), then the local version label of any candidate versions +MUST be ignored when matching versions. + +If the specified version identifier is a local version identifier, then the +local version labels of candidate versions MUST be considered when matching +versions, with the public version identifier being matched as described +above, and the local version label being checked for equivalence using a +strict string equality comparison. + + +Version exclusion +----------------- + +A version exclusion clause includes the version exclusion operator ``!=`` +and a version identifier. + +The allowed version identifiers and comparison semantics are the same as +those of the `Version matching`_ operator, except that the sense of any +match is inverted. + +For example, given the version ``1.1.post1``, the following clauses would +match or not as shown:: + + != 1.1 # Not equal, so 1.1.post1 matches clause + != 1.1.post1 # Equal, so 1.1.post1 does not match clause + != 1.1.* # Same prefix, so 1.1.post1 does not match clause + + +Inclusive ordered comparison +---------------------------- + +An inclusive ordered comparison clause includes a comparison operator and a +version identifier, and will match any version where the comparison is correct +based on the relative position of the candidate version and the specified +version given the consistent ordering defined by the standard +`Version scheme`_. + +The inclusive ordered comparison operators are ``<=`` and ``>=``. + +As with version matching, the release segment is zero padded as necessary to +ensure the release segments are compared with the same length. + +Local version identifiers are NOT permitted in this version specifier. + + +Exclusive ordered comparison +---------------------------- + +The exclusive ordered comparisons ``>`` and ``<`` are similar to the inclusive +ordered comparisons in that they rely on the relative position of the candidate +version and the specified version given the consistent ordering defined by the +standard `Version scheme`_. However, they specifically exclude pre-releases, +post-releases, and local versions of the specified version. + +The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release +of the given version unless ``V`` itself is a post release. You may mandate +that releases are later than a particular post release, including additional +post releases, by using ``>V.postN``. For example, ``>1.7`` will allow +``1.7.1`` but not ``1.7.0.post1`` and ``>1.7.post2`` will allow ``1.7.1`` +and ``1.7.0.post3`` but not ``1.7.0``. + +The exclusive ordered comparison ``>V`` **MUST NOT** match a local version of +the specified version. + +The exclusive ordered comparison ``=`` entry as +part of the URL fragment. + +For version control references, the ``VCS+protocol`` scheme SHOULD be +used to identify both the version control system and the secure transport, +and a version control system with hash based commit identifiers SHOULD be +used. Automated tools MAY omit warnings about missing hashes for version +control systems that do not provide hash based commit identifiers. + +To handle version control systems that do not support including commit or +tag references directly in the URL, that information may be appended to the +end of the URL using the ``@`` or the ``@#`` +notation. + +.. note:: + + This isn't *quite* the same as the existing VCS reference notation + supported by pip. Firstly, the distribution name is moved in front rather + than embedded as part of the URL. Secondly, the commit hash is included + even when retrieving based on a tag, in order to meet the requirement + above that *every* link should include a hash to make things harder to + forge (creating a malicious repo with a particular tag is easy, creating + one with a specific *hash*, less so). + +Remote URL examples:: + + pip @ https://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6de940a148ea686 + pip @ git+https://github.com/pypa/pip.git@7921be1537eac1e97bc40179a57f0349c2aee67d + pip @ git+https://github.com/pypa/pip.git@1.3.1#7921be1537eac1e97bc40179a57f0349c2aee67d + + +File URLs +--------- + +File URLs take the form of ``file:///``. If the ```` is +omitted it is assumed to be ``localhost`` and even if the ```` is omitted +the third slash MUST still exist. The ```` defines what the file path on +the filesystem that is to be accessed. + +On the various \*nix operating systems the only allowed values for ```` +is for it to be omitted, ``localhost``, or another FQDN that the current +machine believes matches its own host. In other words, on \*nix the ``file://`` +scheme can only be used to access paths on the local machine. + +On Windows the file format should include the drive letter if applicable as +part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \*nix on +Windows the ```` parameter may be used to specify a file residing on a +network share. In other words, in order to translate ``\\machine\volume\file`` +to a ``file://`` url, it would end up as ``file://machine/volume/file``. For +more information on ``file://`` URLs on Windows see MSDN [4]_. + + +Updating the versioning specification +===================================== + +The versioning specification may be updated with clarifications without +requiring a new PEP or a change to the metadata version. + +Any technical changes that impact the version identification and comparison +syntax and semantics would require an updated versioning scheme to be +defined in a new PEP. + + +Summary of differences from pkg_resources.parse_version +======================================================= + +* Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at + the time the PEP was written. After the PEP was accepted, setuptools 6.0 and + later versions adopted the behaviour described in this PEP. + +* Local versions sort differently, this PEP requires that they sort as greater + than the same version without a local version, whereas + ``pkg_resources.parse_version`` considers it a pre-release marker. + +* This PEP purposely restricts the syntax which constitutes a valid version + while ``pkg_resources.parse_version`` attempts to provide some meaning from + *any* arbitrary string. + +* ``pkg_resources.parse_version`` allows arbitrarily deeply nested version + signifiers like ``1.0.dev1.post1.dev5``. This PEP however allows only a + single use of each type and they must exist in a certain order. + + +Summary of differences from PEP 386 +=================================== + +* Moved the description of version specifiers into the versioning PEP + +* Added the "direct reference" concept as a standard notation for direct + references to resources (rather than each tool needing to invent its own) + +* Added the "local version identifier" and "local version label" concepts to + allow system integrators to indicate patched builds in a way that is + supported by the upstream tools, as well as to allow the incorporation of + build tags into the versioning of binary distributions. + +* Added the "compatible release" clause + +* Added the trailing wildcard syntax for prefix based version matching + and exclusion + +* Changed the top level sort position of the ``.devN`` suffix + +* Allowed single value version numbers + +* Explicit exclusion of leading or trailing whitespace + +* Explicit support for date based versions + +* Explicit normalisation rules to improve compatibility with + existing version metadata on PyPI where it doesn't introduce + ambiguity + +* Implicitly exclude pre-releases unless they're already present or + needed to satisfy a dependency + +* Treat post releases the same way as unqualified releases + +* Discuss ordering and dependencies across metadata versions + +* Switch from preferring ``c`` to ``rc``. + +The rationale for major changes is given in the following sections. + + +Changing the version scheme +--------------------------- + +One key change in the version scheme in this PEP relative to that in +:pep:`386` is to sort top level developmental releases like ``X.Y.devN`` ahead +of alpha releases like ``X.Ya1``. This is a far more logical sort order, as +projects already using both development releases and alphas/betas/release +candidates do not want their developmental releases sorted in +between their release candidates and their final releases. There is no +rationale for using ``dev`` releases in that position rather than +merely creating additional release candidates. + +The updated sort order also means the sorting of ``dev`` versions is now +consistent between the metadata standard and the pre-existing behaviour +of ``pkg_resources`` (and hence the behaviour of current installation +tools). + +Making this change should make it easier for affected existing projects to +migrate to the latest version of the metadata standard. + +Another change to the version scheme is to allow single number +versions, similar to those used by non-Python projects like Mozilla +Firefox, Google Chrome and the Fedora Linux distribution. This is actually +expected to be more useful for version specifiers, but it is easier to +allow it for both version specifiers and release numbers, rather than +splitting the two definitions. + +The exclusion of leading and trailing whitespace was made explicit after +a couple of projects with version identifiers differing only in a +trailing ``\n`` character were found on PyPI. + +Various other normalisation rules were also added as described in the +separate section on version normalisation below. + +``Appendix A`` shows detailed results of an analysis of PyPI distribution +version information, as collected on 8th August, 2014. This analysis +compares the behavior of the explicitly ordered version scheme defined in +this PEP with the de facto standard defined by the behavior of setuptools. +These metrics are useful, as the intent of this PEP is to follow existing +setuptools behavior as closely as is feasible, while still throwing +exceptions for unorderable versions (rather than trying to guess an +appropriate order as setuptools does). + + +A more opinionated description of the versioning scheme +------------------------------------------------------- + +As in :pep:`386`, the primary focus is on codifying existing practices to make +them more amenable to automation, rather than demanding that existing +projects make non-trivial changes to their workflow. However, the +standard scheme allows significantly more flexibility than is needed +for the vast majority of simple Python packages (which often don't even +need maintenance releases - many users are happy with needing to upgrade to a +new feature release to get bug fixes). + +For the benefit of novice developers, and for experienced developers +wishing to better understand the various use cases, the specification +now goes into much greater detail on the components of the defined +version scheme, including examples of how each component may be used +in practice. + +The PEP also explicitly guides developers in the direction of +semantic versioning (without requiring it), and discourages the use of +several aspects of the full versioning scheme that have largely been +included in order to cover esoteric corner cases in the practices of +existing projects and in repackaging software for Linux distributions. + + +Describing version specifiers alongside the versioning scheme +------------------------------------------------------------- + +The main reason to even have a standardised version scheme in the first place +is to make it easier to do reliable automated dependency analysis. It makes +more sense to describe the primary use case for version identifiers alongside +their definition. + + +Changing the interpretation of version specifiers +------------------------------------------------- + +The previous interpretation of version specifiers made it very easy to +accidentally download a pre-release version of a dependency. This in +turn made it difficult for developers to publish pre-release versions +of software to the Python Package Index, as even marking the package as +hidden wasn't enough to keep automated tools from downloading it, and also +made it harder for users to obtain the test release manually through the +main PyPI web interface. + +The previous interpretation also excluded post-releases from some version +specifiers for no adequately justified reason. + +The updated interpretation is intended to make it difficult to accidentally +accept a pre-release version as satisfying a dependency, while still +allowing pre-release versions to be retrieved automatically when that's the +only way to satisfy a dependency. + +The "some forward compatibility assumed" version constraint is derived from the +Ruby community's "pessimistic version constraint" operator [2]_ to allow +projects to take a cautious approach to forward compatibility promises, while +still easily setting a minimum required version for their dependencies. The +spelling of the compatible release clause (``~=``) is inspired by the Ruby +(``~>``) and PHP (``~``) equivalents. + +Further improvements are also planned to the handling of parallel +installation of multiple versions of the same library, but these will +depend on updates to the installation database definition along with +improved tools for dynamic path manipulation. + +The trailing wildcard syntax to request prefix based version matching was +added to make it possible to sensibly define compatible release clauses. + + +Support for date based version identifiers +------------------------------------------ + +Excluding date based versions caused significant problems in migrating +``pytz`` to the new metadata standards. It also caused concerns for the +OpenStack developers, as they use a date based versioning scheme and would +like to be able to migrate to the new metadata standards without changing +it. + + +Adding version epochs +--------------------- + +Version epochs are added for the same reason they are part of other +versioning schemes, such as those of the Fedora and Debian Linux +distributions: to allow projects to gracefully change their approach to +numbering releases, without having a new release appear to have a lower +version number than previous releases and without having to change the name +of the project. + +In particular, supporting version epochs allows a project that was previously +using date based versioning to switch to semantic versioning by specifying +a new version epoch. + +The ``!`` character was chosen to delimit an epoch version rather than the +``:`` character, which is commonly used in other systems, due to the fact that +``:`` is not a valid character in a Windows directory name. + + +Adding direct references +------------------------ + +Direct references are added as an "escape clause" to handle messy real +world situations that don't map neatly to the standard distribution model. +This includes dependencies on unpublished software for internal use, as well +as handling the more complex compatibility issues that may arise when +wrapping third party libraries as C extensions (this is of especial concern +to the scientific community). + +Index servers are deliberately given a lot of freedom to disallow direct +references, since they're intended primarily as a tool for integrators +rather than publishers. PyPI in particular is currently going through the +process of *eliminating* dependencies on external references, as unreliable +external services have the effect of slowing down installation operations, +as well as reducing PyPI's own apparent reliability. + + +Adding arbitrary equality +------------------------- + +Arbitrary equality is added as an "escape clause" to handle the case where +someone needs to install a project which uses a non compliant version. Although +this PEP is able to attain ~97% compatibility with the versions that are +already on PyPI there are still ~3% of versions which cannot be parsed. This +operator gives a simple and effective way to still depend on them without +having to "guess" at the semantics of what they mean (which would be required +if anything other than strict string based equality was supported). + + +Adding local version identifiers +-------------------------------- + +It's a fact of life that downstream integrators often need to backport +upstream bug fixes to older versions. It's one of the services that gets +Linux distro vendors paid, and application developers may also apply patches +they need to bundled dependencies. + +Historically, this practice has been invisible to cross-platform language +specific distribution tools - the reported "version" in the upstream +metadata is the same as for the unmodified code. This inaccuracy can then +cause problems when attempting to work with a mixture of integrator +provided code and unmodified upstream code, or even just attempting to +identify exactly which version of the software is installed. + +The introduction of local version identifiers and "local version labels" +into the versioning scheme, with the corresponding ``python.integrator`` +metadata extension allows this kind of activity to be represented +accurately, which should improve interoperability between the upstream +tools and various integrated platforms. + +The exact scheme chosen is largely modeled on the existing behavior of +``pkg_resources.parse_version`` and ``pkg_resources.parse_requirements``, +with the main distinction being that where ``pkg_resources`` currently always +takes the suffix into account when comparing versions for exact matches, +the PEP requires that the local version label of the candidate version be +ignored when no local version label is present in the version specifier +clause. Furthermore, the PEP does not attempt to impose any structure on +the local version labels (aside from limiting the set of permitted +characters and defining their ordering). + +This change is designed to ensure that an integrator provided version like +``pip 1.5+1`` or ``pip 1.5+1.git.abc123de`` will still satisfy a version +specifier like ``pip>=1.5``. + +The plus is chosen primarily for readability of local version identifiers. +It was chosen instead of the hyphen to prevent +``pkg_resources.parse_version`` from parsing it as a prerelease, which is +important for enabling a successful migration to the new, more structured, +versioning scheme. The plus was chosen instead of a tilde because of the +significance of the tilde in Debian's version ordering algorithm. + + +Providing explicit version normalization rules +---------------------------------------------- + +Historically, the de facto standard for parsing versions in Python has been the +``pkg_resources.parse_version`` command from the setuptools project. This does +not attempt to reject *any* version and instead tries to make something +meaningful, with varying levels of success, out of whatever it is given. It has +a few simple rules but otherwise it more or less relies largely on string +comparison. + +The normalization rules provided in this PEP exist primarily to either increase +the compatibility with ``pkg_resources.parse_version``, particularly in +documented use cases such as ``rev``, ``r``, ``pre``, etc or to do something +more reasonable with versions that already exist on PyPI. + +All possible normalization rules were weighed against whether or not they were +*likely* to cause any ambiguity (e.g. while someone might devise a scheme where +``v1.0`` and ``1.0`` are considered distinct releases, the likelihood of anyone +actually doing that, much less on any scale that is noticeable, is fairly low). +They were also weighed against how ``pkg_resources.parse_version`` treated a +particular version string, especially with regards to how it was sorted. Finally +each rule was weighed against the kinds of additional versions it allowed, how +"ugly" those versions looked, how hard there were to parse (both mentally and +mechanically) and how much additional compatibility it would bring. + +The breadth of possible normalizations were kept to things that could easily +be implemented as part of the parsing of the version and not pre-parsing +transformations applied to the versions. This was done to limit the side +effects of each transformation as simple search and replace style transforms +increase the likelihood of ambiguous or "junk" versions. + +For an extended discussion on the various types of normalizations that were +considered, please see the proof of concept for :pep:`440` within pip [5]_. + + +Allowing Underscore in Normalization +------------------------------------ + +There are not a lot of projects on PyPI which utilize a ``_`` in the version +string. However this PEP allows its use anywhere that ``-`` is acceptable. The +reason for this is that the Wheel normalization scheme specifies that ``-`` +gets normalized to a ``_`` to enable easier parsing of the filename. + + +Summary of changes to PEP 440 +============================= + +The following changes were made to this PEP based on feedback received after +the initial reference implementation was released in setuptools 8.0 and pip +6.0: + +* The exclusive ordered comparisons were updated to no longer imply a ``!=V.*`` + which was deemed to be surprising behavior which was too hard to accurately + describe. Instead the exclusive ordered comparisons will simply disallow + matching pre-releases, post-releases, and local versions of the specified + version (unless the specified version is itself a pre-release, post-release + or local version). For an extended discussion see the threads on + distutils-sig [6]_ [7]_. + +* The normalized form for release candidates was updated from 'c' to 'rc'. + This change was based on user feedback received when setuptools 8.0 + started applying normalisation to the release metadata generated when + preparing packages for publication on PyPI [8]_. + +* The PEP text and the ``is_canonical`` regex were updated to be explicit + that numeric components are specifically required to be represented as + sequences of ASCII digits, not arbitrary Unicode [Nd] code points. This + was previously implied by the version parsing regex in Appendix B, but + not stated explicitly [10]_. + + + +References +========== + +The initial attempt at a standardised version scheme, along with the +justifications for needing such a standard can be found in :pep:`386`. + +.. [2] `Version compatibility analysis script + `__ + +.. [4] `File URIs in Windows + `__ + +.. [5] `Proof of Concept: PEP 440 within pip + `__ + +.. [6] `PEP440: foo-X.Y.Z does not satisfy "foo>X.Y" + `__ + +.. [7] `PEP440: >1.7 vs >=1.7 + `__ + +.. [8] `Amend PEP 440 with Wider Feedback on Release Candidates + `__ + +.. [10] `PEP 440: regex should not permit Unicode [Nd] characters + `__ + +* `Reference Implementation of PEP 440 Versions and Specifiers + `__ + +* `Pessimistic version constraint + `__ + +* `Changing the status of PEP 440 to Provisional + `__ + +Appendix A +========== + +Metadata v2.0 guidelines versus setuptools:: + + $ invoke check.pep440 + Total Version Compatibility: 245806/250521 (98.12%) + Total Sorting Compatibility (Unfiltered): 45441/47114 (96.45%) + Total Sorting Compatibility (Filtered): 47057/47114 (99.88%) + Projects with No Compatible Versions: 498/47114 (1.06%) + Projects with Differing Latest Version: 688/47114 (1.46%) + +Appendix B : Parsing version strings with regular expressions +============================================================= + +As noted earlier in the ``Public version identifiers`` section, published +version identifiers SHOULD use the canonical format. This section provides +regular expressions that can be used to test whether a version is already +in that form, and if it's not, extract the various components for subsequent +normalization. + +To test whether a version identifier is in the canonical format, you can use +the following function:: + + import re + def is_canonical(version): + return re.match(r'^([1-9][0-9]*!)?(0|[1-9][0-9]*)(\.(0|[1-9][0-9]*))*((a|b|rc)(0|[1-9][0-9]*))?(\.post(0|[1-9][0-9]*))?(\.dev(0|[1-9][0-9]*))?$', version) is not None + +To extract the components of a version identifier, use the following regular +expression (as defined by the `packaging `_ +project):: + + VERSION_PATTERN = r""" + v? + (?: + (?:(?P[0-9]+)!)? # epoch + (?P[0-9]+(?:\.[0-9]+)*) # release segment + (?P
                                          # pre-release
+                [-_\.]?
+                (?P(a|b|c|rc|alpha|beta|pre|preview))
+                [-_\.]?
+                (?P[0-9]+)?
+            )?
+            (?P                                         # post release
+                (?:-(?P[0-9]+))
+                |
+                (?:
+                    [-_\.]?
+                    (?Ppost|rev|r)
+                    [-_\.]?
+                    (?P[0-9]+)?
+                )
+            )?
+            (?P                                          # dev release
+                [-_\.]?
+                (?Pdev)
+                [-_\.]?
+                (?P[0-9]+)?
+            )?
+        )
+        (?:\+(?P[a-z0-9]+(?:[-_\.][a-z0-9]+)*))?       # local version
+    """
+
+    _regex = re.compile(
+        r"^\s*" + VERSION_PATTERN + r"\s*$",
+        re.VERBOSE | re.IGNORECASE,
+    )
+
+
+Copyright
+=========
+
+This document has been placed in the public domain.

From 8997a3ad04df67bad4a8cf8222d139331e5d9190 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 4 Nov 2023 11:52:12 +0100
Subject: [PATCH 096/733] PEP 440: Editing to fit packaging.python.org

---
 source/specifications/version-specifiers.rst | 472 ++-----------------
 1 file changed, 29 insertions(+), 443 deletions(-)

diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index 0c18f8c66..52ef5aca5 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -1,44 +1,16 @@
-
 .. _version-specifiers:
 
 ==================
 Version specifiers
 ==================
 
-Version numbering requirements and the semantics for specifying comparisons
-between versions are defined in :pep:`440`.
-
-The version specifiers section in this PEP supersedes the version specifiers
-section in :pep:`345`.
-
-
-PEP: 440
-Title: Version Identification and Dependency Specification
-Author: Alyssa Coghlan ,
-        Donald Stufft 
-BDFL-Delegate: Alyssa Coghlan 
-Discussions-To: distutils-sig@python.org
-Status: Final
-Type: Standards Track
-Topic: Packaging
-Content-Type: text/x-rst
-Created: 18-Mar-2013
-Post-History: 30-Mar-2013, 27-May-2013, 20-Jun-2013,
-              21-Dec-2013, 28-Jan-2014, 08-Aug-2014,
-              22-Aug-2014
-Replaces: 386
-Resolution: https://mail.python.org/pipermail/distutils-sig/2014-August/024673.html
-
 
 Abstract
 ========
 
-This PEP describes a scheme for identifying versions of Python software
+This specification describes a scheme for identifying versions of Python software
 distributions, and declaring dependencies on particular versions.
 
-This document addresses several limitations of the previous attempt at a
-standardized approach to versioning, as described in :pep:`345` and :pep:`386`.
-
 
 Definitions
 ===========
@@ -47,17 +19,6 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this
 document are to be interpreted as described in :rfc:`2119`.
 
-"Projects" are software components that are made available for integration.
-Projects include Python libraries, frameworks, scripts, plugins,
-applications, collections of data or other resources, and various
-combinations thereof. Public Python projects are typically registered on
-the `Python Package Index `__.
-
-"Releases" are uniquely identified snapshots of a project.
-
-"Distributions" are the packaged files which are used to publish
-and distribute a release.
-
 "Build tools" are automated tools intended to run on development systems,
 producing source and binary distribution archives. Build tools may also be
 invoked by integration tools in order to build software distributed as
@@ -78,6 +39,7 @@ system.
 publication tools, integration tools and any other software that produces
 or consumes distribution version and dependency metadata.
 
+
 Version scheme
 ==============
 
@@ -90,6 +52,8 @@ constraints on the version of dependencies needed in order to build or
 run the software.
 
 
+.. _public-version-identifiers:
+
 Public version identifiers
 --------------------------
 
@@ -107,10 +71,10 @@ this scheme but MUST also include the normalizations specified below.
 Installation tools MAY warn the user when non-compliant or ambiguous versions
 are detected.
 
-See also ``Appendix B : Parsing version strings with regular expressions``
-which provides a regular expression to check strict conformance with the
-canonical format, as well as a more permissive regular expression accepting
-inputs that may require subsequent normalization.
+See also :ref:`version-specifiers-regex` which provides a regular
+expression to check strict conformance with the canonical format, as
+well as a more permissive regular expression accepting inputs that may
+require subsequent normalization.
 
 Public version identifiers are separated into up to five segments:
 
@@ -726,7 +690,7 @@ a project to determine which versions it should install. These requirements
 necessitate a standardization across one parsing mechanism to be used for all
 versions of a project.
 
-Due to the above, this PEP MUST be used for all versions of metadata and
+Due to the above, this specification MUST be used for all versions of metadata and
 supersedes :pep:`386` even for metadata v1.2. Tools SHOULD ignore any versions
 which cannot be parsed by the rules in this PEP, but MAY fall back to
 implementation defined version parsing and ordering schemes if no versions
@@ -765,7 +729,7 @@ are fully compatible with the version scheme defined in this PEP, and abiding
 by these aspects is encouraged.
 
 Semantic versions containing a hyphen (pre-releases - clause 10) or a
-plus sign (builds - clause 11) are *not* compatible with this PEP
+plus sign (builds - clause 11) are *not* compatible with this specification
 and are not permitted in the public version field.
 
 One possible mechanism to translate such semantic versioning based source
@@ -1200,26 +1164,17 @@ part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \*nix on
 Windows the ```` parameter may be used to specify a file residing on a
 network share. In other words, in order to translate ``\\machine\volume\file``
 to a ``file://`` url, it would end up as ``file://machine/volume/file``. For
-more information on ``file://`` URLs on Windows see MSDN [4]_.
-
+more information on ``file://`` URLs on Windows see
+`MSDN `_.
 
-Updating the versioning specification
-=====================================
-
-The versioning specification may be updated with clarifications without
-requiring a new PEP or a change to the metadata version.
-
-Any technical changes that impact the version identification and comparison
-syntax and semantics would require an updated versioning scheme to be
-defined in a new PEP.
 
 
 Summary of differences from pkg_resources.parse_version
 =======================================================
 
 * Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at
-  the time the PEP was written. After the PEP was accepted, setuptools 6.0 and
-  later versions adopted the behaviour described in this PEP.
+  the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 and
+  later versions adopted the behaviour described here.
 
 * Local versions sort differently, this PEP requires that they sort as greater
   than the same version without a local version, whereas
@@ -1234,390 +1189,17 @@ Summary of differences from pkg_resources.parse_version
   single use of each type and they must exist in a certain order.
 
 
-Summary of differences from PEP 386
-===================================
-
-* Moved the description of version specifiers into the versioning PEP
-
-* Added the "direct reference" concept as a standard notation for direct
-  references to resources (rather than each tool needing to invent its own)
-
-* Added the "local version identifier" and "local version label" concepts to
-  allow system integrators to indicate patched builds in a way that is
-  supported by the upstream tools, as well as to allow the incorporation of
-  build tags into the versioning of binary distributions.
-
-* Added the "compatible release" clause
-
-* Added the trailing wildcard syntax for prefix based version matching
-  and exclusion
-
-* Changed the top level sort position of the ``.devN`` suffix
-
-* Allowed single value version numbers
-
-* Explicit exclusion of leading or trailing whitespace
-
-* Explicit support for date based versions
-
-* Explicit normalisation rules to improve compatibility with
-  existing version metadata on PyPI where it doesn't introduce
-  ambiguity
-
-* Implicitly exclude pre-releases unless they're already present or
-  needed to satisfy a dependency
-
-* Treat post releases the same way as unqualified releases
-
-* Discuss ordering and dependencies across metadata versions
-
-* Switch from preferring ``c`` to ``rc``.
-
-The rationale for major changes is given in the following sections.
-
-
-Changing the version scheme
----------------------------
-
-One key change in the version scheme in this PEP relative to that in
-:pep:`386` is to sort top level developmental releases like ``X.Y.devN`` ahead
-of alpha releases like ``X.Ya1``. This is a far more logical sort order, as
-projects already using both development releases and alphas/betas/release
-candidates do not want their developmental releases sorted in
-between their release candidates and their final releases. There is no
-rationale for using ``dev`` releases in that position rather than
-merely creating additional release candidates.
-
-The updated sort order also means the sorting of ``dev`` versions is now
-consistent between the metadata standard and the pre-existing behaviour
-of ``pkg_resources`` (and hence the behaviour of current installation
-tools).
-
-Making this change should make it easier for affected existing projects to
-migrate to the latest version of the metadata standard.
-
-Another change to the version scheme is to allow single number
-versions, similar to those used by non-Python projects like Mozilla
-Firefox, Google Chrome and the Fedora Linux distribution. This is actually
-expected to be more useful for version specifiers, but it is easier to
-allow it for both version specifiers and release numbers, rather than
-splitting the two definitions.
-
-The exclusion of leading and trailing whitespace was made explicit after
-a couple of projects with version identifiers differing only in a
-trailing ``\n`` character were found on PyPI.
-
-Various other normalisation rules were also added as described in the
-separate section on version normalisation below.
-
-``Appendix A`` shows detailed results of an analysis of PyPI distribution
-version information, as collected on 8th August, 2014. This analysis
-compares the behavior of the explicitly ordered version scheme defined in
-this PEP with the de facto standard defined by the behavior of setuptools.
-These metrics are useful, as the intent of this PEP is to follow existing
-setuptools behavior as closely as is feasible, while still throwing
-exceptions for unorderable versions (rather than trying to guess an
-appropriate order as setuptools does).
-
-
-A more opinionated description of the versioning scheme
--------------------------------------------------------
-
-As in :pep:`386`, the primary focus is on codifying existing practices to make
-them more amenable to automation, rather than demanding that existing
-projects make non-trivial changes to their workflow. However, the
-standard scheme allows significantly more flexibility than is needed
-for the vast majority of simple Python packages (which often don't even
-need maintenance releases - many users are happy with needing to upgrade to a
-new feature release to get bug fixes).
-
-For the benefit of novice developers, and for experienced developers
-wishing to better understand the various use cases, the specification
-now goes into much greater detail on the components of the defined
-version scheme, including examples of how each component may be used
-in practice.
-
-The PEP also explicitly guides developers in the direction of
-semantic versioning (without requiring it), and discourages the use of
-several aspects of the full versioning scheme that have largely been
-included in order to cover esoteric corner cases in the practices of
-existing projects and in repackaging software for Linux distributions.
-
-
-Describing version specifiers alongside the versioning scheme
--------------------------------------------------------------
-
-The main reason to even have a standardised version scheme in the first place
-is to make it easier to do reliable automated dependency analysis. It makes
-more sense to describe the primary use case for version identifiers alongside
-their definition.
-
-
-Changing the interpretation of version specifiers
--------------------------------------------------
 
-The previous interpretation of version specifiers made it very easy to
-accidentally download a pre-release version of a dependency. This in
-turn made it difficult for developers to publish pre-release versions
-of software to the Python Package Index, as even marking the package as
-hidden wasn't enough to keep automated tools from downloading it, and also
-made it harder for users to obtain the test release manually through the
-main PyPI web interface.
+.. _version-specifiers-regex:
 
-The previous interpretation also excluded post-releases from some version
-specifiers for no adequately justified reason.
+Appendix: Parsing version strings with regular expressions
+==========================================================
 
-The updated interpretation is intended to make it difficult to accidentally
-accept a pre-release version as satisfying a dependency, while still
-allowing pre-release versions to be retrieved automatically when that's the
-only way to satisfy a dependency.
-
-The "some forward compatibility assumed" version constraint is derived from the
-Ruby community's "pessimistic version constraint" operator [2]_ to allow
-projects to take a cautious approach to forward compatibility promises, while
-still easily setting a minimum required version for their dependencies. The
-spelling of the compatible release clause (``~=``) is inspired by the Ruby
-(``~>``) and PHP (``~``) equivalents.
-
-Further improvements are also planned to the handling of parallel
-installation of multiple versions of the same library, but these will
-depend on updates to the installation database definition along with
-improved tools for dynamic path manipulation.
-
-The trailing wildcard syntax to request prefix based version matching was
-added to make it possible to sensibly define compatible release clauses.
-
-
-Support for date based version identifiers
-------------------------------------------
-
-Excluding date based versions caused significant problems in migrating
-``pytz`` to the new metadata standards. It also caused concerns for the
-OpenStack developers, as they use a date based versioning scheme and would
-like to be able to migrate to the new metadata standards without changing
-it.
-
-
-Adding version epochs
----------------------
-
-Version epochs are added for the same reason they are part of other
-versioning schemes, such as those of the Fedora and Debian Linux
-distributions: to allow projects to gracefully change their approach to
-numbering releases, without having a new release appear to have a lower
-version number than previous releases and without having to change the name
-of the project.
-
-In particular, supporting version epochs allows a project that was previously
-using date based versioning to switch to semantic versioning by specifying
-a new version epoch.
-
-The ``!`` character was chosen to delimit an epoch version rather than the
-``:`` character, which is commonly used in other systems, due to the fact that
-``:`` is not a valid character in a Windows directory name.
-
-
-Adding direct references
-------------------------
-
-Direct references are added as an "escape clause" to handle messy real
-world situations that don't map neatly to the standard distribution model.
-This includes dependencies on unpublished software for internal use, as well
-as handling the more complex compatibility issues that may arise when
-wrapping third party libraries as C extensions (this is of especial concern
-to the scientific community).
-
-Index servers are deliberately given a lot of freedom to disallow direct
-references, since they're intended primarily as a tool for integrators
-rather than publishers. PyPI in particular is currently going through the
-process of *eliminating* dependencies on external references, as unreliable
-external services have the effect of slowing down installation operations,
-as well as reducing PyPI's own apparent reliability.
-
-
-Adding arbitrary equality
--------------------------
-
-Arbitrary equality is added as an "escape clause" to handle the case where
-someone needs to install a project which uses a non compliant version. Although
-this PEP is able to attain ~97% compatibility with the versions that are
-already on PyPI there are still ~3% of versions which cannot be parsed. This
-operator gives a simple and effective way to still depend on them without
-having to "guess" at the semantics of what they mean (which would be required
-if anything other than strict string based equality was supported).
-
-
-Adding local version identifiers
---------------------------------
-
-It's a fact of life that downstream integrators often need to backport
-upstream bug fixes to older versions. It's one of the services that gets
-Linux distro vendors paid, and application developers may also apply patches
-they need to bundled dependencies.
-
-Historically, this practice has been invisible to cross-platform language
-specific distribution tools - the reported "version" in the upstream
-metadata is the same as for the unmodified code. This inaccuracy can then
-cause problems when attempting to work with a mixture of integrator
-provided code and unmodified upstream code, or even just attempting to
-identify exactly which version of the software is installed.
-
-The introduction of local version identifiers and "local version labels"
-into the versioning scheme, with the corresponding ``python.integrator``
-metadata extension allows this kind of activity to be represented
-accurately, which should improve interoperability between the upstream
-tools and various integrated platforms.
-
-The exact scheme chosen is largely modeled on the existing behavior of
-``pkg_resources.parse_version`` and ``pkg_resources.parse_requirements``,
-with the main distinction being that where ``pkg_resources`` currently always
-takes the suffix into account when comparing versions for exact matches,
-the PEP requires that the local version label of the candidate version be
-ignored when no local version label is present in the version specifier
-clause. Furthermore, the PEP does not attempt to impose any structure on
-the local version labels (aside from limiting the set of permitted
-characters and defining their ordering).
-
-This change is designed to ensure that an integrator provided version like
-``pip 1.5+1`` or ``pip 1.5+1.git.abc123de`` will still satisfy a version
-specifier like ``pip>=1.5``.
-
-The plus is chosen primarily for readability of local version identifiers.
-It was chosen instead of the hyphen to prevent
-``pkg_resources.parse_version`` from parsing it as a prerelease, which is
-important for enabling a successful migration to the new, more structured,
-versioning scheme. The plus was chosen instead of a tilde because of the
-significance of the tilde in Debian's version ordering algorithm.
-
-
-Providing explicit version normalization rules
-----------------------------------------------
-
-Historically, the de facto standard for parsing versions in Python has been the
-``pkg_resources.parse_version`` command from the setuptools project. This does
-not attempt to reject *any* version and instead tries to make something
-meaningful, with varying levels of success, out of whatever it is given. It has
-a few simple rules but otherwise it more or less relies largely on string
-comparison.
-
-The normalization rules provided in this PEP exist primarily to either increase
-the compatibility with ``pkg_resources.parse_version``, particularly in
-documented use cases such as ``rev``, ``r``, ``pre``, etc or to do something
-more reasonable with versions that already exist on PyPI.
-
-All possible normalization rules were weighed against whether or not they were
-*likely* to cause any ambiguity (e.g. while someone might devise a scheme where
-``v1.0`` and ``1.0`` are considered distinct releases, the likelihood of anyone
-actually doing that, much less on any scale that is noticeable, is fairly low).
-They were also weighed against how ``pkg_resources.parse_version`` treated a
-particular version string, especially with regards to how it was sorted. Finally
-each rule was weighed against the kinds of additional versions it allowed, how
-"ugly" those versions looked, how hard there were to parse (both mentally and
-mechanically) and how much additional compatibility it would bring.
-
-The breadth of possible normalizations were kept to things that could easily
-be implemented as part of the parsing of the version and not pre-parsing
-transformations applied to the versions. This was done to limit the side
-effects of each transformation as simple search and replace style transforms
-increase the likelihood of ambiguous or "junk" versions.
-
-For an extended discussion on the various types of normalizations that were
-considered, please see the proof of concept for :pep:`440` within pip [5]_.
-
-
-Allowing Underscore in Normalization
-------------------------------------
-
-There are not a lot of projects on PyPI which utilize a ``_`` in the version
-string. However this PEP allows its use anywhere that ``-`` is acceptable. The
-reason for this is that the Wheel normalization scheme specifies that ``-``
-gets normalized to a ``_`` to enable easier parsing of the filename.
-
-
-Summary of changes to PEP 440
-=============================
-
-The following changes were made to this PEP based on feedback received after
-the initial reference implementation was released in setuptools 8.0 and pip
-6.0:
-
-* The exclusive ordered comparisons were updated to no longer imply a ``!=V.*``
-  which was deemed to be surprising behavior which was too hard to accurately
-  describe. Instead the exclusive ordered comparisons will simply disallow
-  matching pre-releases, post-releases, and local versions of the specified
-  version (unless the specified version is itself a pre-release, post-release
-  or local version). For an extended discussion see the threads on
-  distutils-sig [6]_ [7]_.
-
-* The normalized form for release candidates was updated from 'c' to 'rc'.
-  This change was based on user feedback received when setuptools 8.0
-  started applying normalisation to the release metadata generated when
-  preparing packages for publication on PyPI [8]_.
-
-* The PEP text and the ``is_canonical`` regex were updated to be explicit
-  that numeric components are specifically required to be represented as
-  sequences of ASCII digits, not arbitrary Unicode [Nd] code points. This
-  was previously implied by the version parsing regex in Appendix B, but
-  not stated explicitly [10]_.
-
-
-
-References
-==========
-
-The initial attempt at a standardised version scheme, along with the
-justifications for needing such a standard can be found in :pep:`386`.
-
-.. [2] `Version compatibility analysis script
-   `__
-
-.. [4] `File URIs in Windows
-   `__
-
-.. [5] `Proof of Concept: PEP 440 within pip
-    `__
-
-.. [6] `PEP440: foo-X.Y.Z does not satisfy "foo>X.Y"
-    `__
-
-.. [7] `PEP440: >1.7 vs >=1.7
-    `__
-
-.. [8] `Amend PEP 440 with Wider Feedback on Release Candidates
-   `__
-
-.. [10] `PEP 440: regex should not permit Unicode [Nd] characters
-   `__
-
-* `Reference Implementation of PEP 440 Versions and Specifiers
-  `__
-
-* `Pessimistic version constraint
-  `__
-
-* `Changing the status of PEP 440 to Provisional
-  `__
-
-Appendix A
-==========
-
-Metadata v2.0 guidelines versus setuptools::
-
-    $ invoke check.pep440
-    Total Version Compatibility:              245806/250521 (98.12%)
-    Total Sorting Compatibility (Unfiltered): 45441/47114 (96.45%)
-    Total Sorting Compatibility (Filtered):   47057/47114 (99.88%)
-    Projects with No Compatible Versions:     498/47114 (1.06%)
-    Projects with Differing Latest Version:   688/47114 (1.46%)
-
-Appendix B : Parsing version strings with regular expressions
-=============================================================
-
-As noted earlier in the ``Public version identifiers`` section, published
-version identifiers SHOULD use the canonical format. This section provides
-regular expressions that can be used to test whether a version is already
-in that form, and if it's not, extract the various components for subsequent
-normalization.
+As noted earlier in the :ref:`public-version-identifiers` section,
+published version identifiers SHOULD use the canonical format. This
+section provides regular expressions that can be used to test whether a
+version is already in that form, and if it's not, extract the various
+components for subsequent normalization.
 
 To test whether a version identifier is in the canonical format, you can use
 the following function::
@@ -1667,7 +1249,11 @@ project)::
     )
 
 
-Copyright
-=========
 
-This document has been placed in the public domain.
+History
+=======
+
+This specification was originally approved as :pep:`440`,
+addressing several limitations of the previous attempt
+at standardized versioning, as described in :pep:`345`
+and :pep:`386`.

From 085a016b75110b33c3ae6eaa685a516229b12878 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 4 Nov 2023 12:30:53 +0100
Subject: [PATCH 097/733] PEP 440: Remove "Abstract" heading

---
 source/specifications/version-specifiers.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index 52ef5aca5..1b2507eeb 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -5,9 +5,6 @@ Version specifiers
 ==================
 
 
-Abstract
-========
-
 This specification describes a scheme for identifying versions of Python software
 distributions, and declaring dependencies on particular versions.
 

From 367e5e8471b236d6a92da47054d08cea5fe8ab01 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 4 Nov 2023 12:50:11 +0100
Subject: [PATCH 098/733] Update references to PEP 440

---
 source/glossary.rst                           |  9 +++----
 .../binary-distribution-format.rst            |  4 +--
 source/specifications/core-metadata.rst       | 12 +++++----
 .../declaring-project-metadata.rst            |  3 ++-
 .../specifications/dependency-specifiers.rst  | 27 ++++++++++---------
 .../direct-url-data-structure.rst             |  2 +-
 .../recording-installed-packages.rst          | 11 ++++----
 source/specifications/version-specifiers.rst  |  5 ++++
 source/tutorials/installing-packages.rst      |  8 +++---
 9 files changed, 45 insertions(+), 36 deletions(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index 707bc4756..70ad4ccda 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -222,11 +222,10 @@ Glossary
     Version Specifier
 
        The version component of a :term:`Requirement Specifier`. For example,
-       the ">=1.3" portion of "foo>=1.3".  :pep:`440` contains
-       a :pep:`full specification
-       <440#version-specifiers>` of the
-       specifiers that Python packaging currently supports.  Support for PEP440
-       was implemented in :ref:`setuptools` v8.0 and :ref:`pip` v6.0.
+       the ">=1.3" portion of "foo>=1.3".  Read the :ref:`Version specifier specification
+       ` for a full description of the
+       specifiers that Python packaging currently supports.  Support for this
+       specification was implemented in :ref:`setuptools` v8.0 and :ref:`pip` v6.0.
 
     Virtual Environment
 
diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index 9855ad8ff..04367cc85 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -182,8 +182,8 @@ this character cannot appear within any component. This is handled as follows:
   Tools consuming wheels must be prepared to accept ``.`` (FULL STOP) and
   uppercase letters, however, as these were allowed by an earlier version of
   this specification.
-- Version numbers should be normalised according to :pep:`440`. Normalised
-  version numbers cannot contain ``-``.
+- Version numbers should be normalised according to the :ref:`Version specifier
+  specification `. Normalised version numbers cannot contain ``-``.
 - The remaining components may not contain ``-`` characters, so no escaping
   is necessary.
 
diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index cefd68950..2c2cf96cb 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -53,8 +53,9 @@ Version of the file format; legal values are "1.0", "1.1", "1.2", "2.1",
 Automated tools consuming metadata SHOULD warn if ``metadata_version`` is
 greater than the highest version they support, and MUST fail if
 ``metadata_version`` has a greater major version than the highest
-version they support (as described in :pep:`440`, the major version is the
-value before the first dot).
+version they support (as described in the
+:ref:`Version specifier specification `,
+the major version is the value before the first dot).
 
 For broader compatibility, build tools MAY choose to produce
 distribution metadata using the lowest metadata version that includes
@@ -96,7 +97,8 @@ Version
 .. versionadded:: 1.0
 
 A string containing the distribution's version number.  This
-field  must be in the format specified in :pep:`440`.
+field  must be in the format specified in the
+:ref:`Version specifier specification `.
 
 Example::
 
@@ -587,8 +589,8 @@ This field may be followed by an environment marker after a semicolon.
 
 Because they refer to non-Python software releases, version numbers
 for this field are **not** required to conform to the format
-specified in :pep:`440`:  they should correspond to the
-version scheme used by the external dependency.
+specified in the :ref:`Version specifier specification `:
+they should correspond to the version scheme used by the external dependency.
 
 Notice that there is no particular rule on the strings to be used.
 
diff --git a/source/specifications/declaring-project-metadata.rst b/source/specifications/declaring-project-metadata.rst
index 4f1d4199d..1c4ce7ce2 100644
--- a/source/specifications/declaring-project-metadata.rst
+++ b/source/specifications/declaring-project-metadata.rst
@@ -87,7 +87,8 @@ as it is read for internal consistency.
 - Corresponding :ref:`core metadata ` field:
   :ref:`Version `
 
-The version of the project as supported by :pep:`440`.
+The version of the project, as defined in the
+:ref:`Version specifier specification `.
 
 Users SHOULD prefer to specify already-normalized versions.
 
diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index 009b8a592..0389ce3cb 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -16,8 +16,8 @@ acceptable, so the language permits describing all these cases.
 The language defined is a compact line based format which is already in
 widespread use in pip requirements files, though we do not specify the command
 line option handling that those files permit. There is one caveat - the
-URL reference form, specified in :pep:`440` is not actually
-implemented in pip, but since :pep:`440` is accepted, we use that format rather
+URL reference form, specified in :ref:`Versioning specifier specification `
+is not actually implemented in pip, but we use that format rather
 than pip's current native format.
 
 Specification
@@ -57,7 +57,8 @@ as comments, multiple line support via continuations, or other such features.
 The full grammar including annotations to build a useful parse tree is
 included at the end of this document.
 
-Versions may be specified according to the :pep:`440` rules. (Note:
+Versions may be specified according to the rules of the
+:ref:`Version specifier specification `. (Note:
 URI is defined in :rfc:`std-66 <3986>`)::
 
     version_cmp   = wsp* '<' | '<=' | '!=' | '==' | '>=' | '>' | '~=' | '==='
@@ -159,12 +160,13 @@ If multiple extras are listed, all the dependencies are unioned together.
 Versions
 --------
 
-See :pep:`440` for more detail on both version numbers and version
-comparisons. Version specifications limit the versions of a distribution that
-can be used. They only apply to distributions looked up by name, rather than
+See the :ref:`Version specifier specification ` for
+more detail on both version numbers and version comparisons. Version
+specifications limit the versions of a distribution that can be
+used. They only apply to distributions looked up by name, rather than
 via a URL. Version comparison are also used in the markers feature. The
-optional brackets around a version are present for compatibility with :pep:`345`
-but should not be generated, only accepted.
+optional brackets around a version are present for compatibility with
+:pep:`345` but should not be generated, only accepted.
 
 Environment Markers
 -------------------
@@ -186,10 +188,11 @@ fixes some issues that were observed in the design described in :pep:`426`.
 
 Comparisons in marker expressions are typed by the comparison operator.  The
  operators that are not in  perform the same as they
-do for strings in Python. The  operators use the :pep:`440`
-version comparison rules when those are defined (that is when both
-sides have a valid version specifier). If there is no defined :pep:`440`
-behaviour and the operator exists in Python, then the operator falls back to
+do for strings in Python. The  operators use the version comparison
+rules of the :ref:`Version specifier specification `
+when those are defined (that is when both sides have a valid
+version specifier). If there is no defined behaviour of this specification
+and the operator exists in Python, then the operator falls back to
 the Python behaviour. Otherwise an error should be raised. e.g. the following
 will result in  errors::
 
diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index eae9d3071..3983b8520 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -11,7 +11,7 @@ source trees, source distributions and wheels.
 
 The representation of the components of this data structure as a :rfc:`1738` URL
 is not formally specified at time of writing. A common representation is the pip URL
-format. Other examples are provided in :pep:`440`.
+format. Other examples are provided in the :ref:`Version specifier specification `.
 
 .. contents:: Contents
    :local:
diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst
index 11d2c3bfa..2610717d6 100644
--- a/source/specifications/recording-installed-packages.rst
+++ b/source/specifications/recording-installed-packages.rst
@@ -42,12 +42,11 @@ packages (commonly, the ``site-packages`` directory).
 
 This directory is named as ``{name}-{version}.dist-info``, with ``name`` and
 ``version`` fields corresponding to :ref:`core-metadata`. Both fields must be
-normalized (see :ref:`name-normalization` and
-:pep:`PEP 440 <440#normalization>` for the definition of normalization for
-each field respectively), and replace dash (``-``) characters with
-underscore (``_``) characters, so the ``.dist-info`` directory always has
-exactly one dash (``-``) character in its stem, separating the ``name`` and
-``version`` fields.
+normalized (see the :ref:`name normalization specification `
+and the :ref:`version normalization specification `),
+and replace dash (``-``) characters with underscore (``_``) characters,
+so the ``.dist-info`` directory always has exactly one dash (``-``) character in
+its stem, separating the ``name`` and ``version`` fields.
 
 Historically, tools have failed to replace dot characters or normalize case in
 the ``name`` field, or not perform normalization in the ``version`` field.
diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index 1b2507eeb..0d8b22334 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -385,6 +385,9 @@ from an earlier epoch::
     1!1.1
     1!2.0
 
+
+.. _version-specifiers-normalization:
+
 Normalization
 -------------
 
@@ -805,6 +808,8 @@ entirely when checking if candidate versions match a given version
 specifier.
 
 
+.. _version-specifiers-compatible-release:
+
 Compatible release
 ------------------
 
diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
index 5d4957519..233a7c41b 100644
--- a/source/tutorials/installing-packages.rst
+++ b/source/tutorials/installing-packages.rst
@@ -308,9 +308,9 @@ The most common usage of :ref:`pip` is to install from the :term:`Python Package
 Index ` using a :term:`requirement specifier
 `. Generally speaking, a requirement specifier is
 composed of a project name followed by an optional :term:`version specifier
-`.  :pep:`440` contains a :pep:`full
-specification <440#version-specifiers>`
-of the currently supported specifiers. Below are some examples.
+`.  A full description of the supported specifiers can be
+found in the :ref:`Version specifier specification `.
+Below are some examples.
 
 To install the latest version of "SomeProject":
 
@@ -355,7 +355,7 @@ To install greater than or equal to one version and less than another:
         py -m pip install "SomeProject>=1,<2"
 
 
-To install a version that's :pep:`"compatible" <440#compatible-release>`
+To install a version that's :ref:`compatible `
 with a certain version: [4]_
 
 .. tab:: Unix/macOS

From 64a7c8ed96d241e137a562e0ea927e8d87f2c2a2 Mon Sep 17 00:00:00 2001
From: sinoroc 
Date: Thu, 2 Nov 2023 12:02:40 +0100
Subject: [PATCH 099/733] Add build backend and frontend to the glossary

GitHub: fixes https://github.com/pypa/packaging.python.org/issues/1327
---
 source/flow.rst                               |  9 ++++--
 source/glossary.rst                           | 30 +++++++++++++++++++
 source/key_projects.rst                       |  2 +-
 .../declaring-project-metadata.rst            |  2 +-
 .../source-distribution-format.rst            |  3 +-
 source/tutorials/packaging-projects.rst       |  8 ++---
 6 files changed, 44 insertions(+), 10 deletions(-)

diff --git a/source/flow.rst b/source/flow.rst
index 8a7d390b8..974cfd6e9 100644
--- a/source/flow.rst
+++ b/source/flow.rst
@@ -82,9 +82,12 @@ For example, here is a table for using :ref:`hatch`:
     requires = ["hatchling"]
     build-backend = "hatchling.build"
 
-With such a table in the :file:`pyproject.toml` file, a "frontend" tool like
-:ref:`build` can run your chosen build tool's "backend" to create the build
-artifacts. Your build tool may also provide its own frontend. An install tool
+With such a table in the :file:`pyproject.toml` file,
+a ":term:`frontend `" tool like
+:ref:`build` can run your chosen
+build tool's ":term:`backend `"
+to create the build artifacts.
+Your build tool may also provide its own frontend. An install tool
 like :ref:`pip` also acts as a frontend when it runs your build tool's backend
 to install from a source distribution.
 
diff --git a/source/glossary.rst b/source/glossary.rst
index 707bc4756..5b1ca8951 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -12,6 +12,36 @@ Glossary
         extensions.
 
 
+    Build Backend
+
+        A library that takes a source tree or
+        :term:`source distribution `
+        and builds a source distribution or :term:`wheel ` from it.
+        The build is delegated to the backend by a
+        :term:`frontend `.
+        All backends offer a standardized interface.
+
+        Examples of build backends are
+        :ref:`flit's flit-core `,
+        :ref:`hatch's hatchling `,
+        :ref:`maturin`,
+        :ref:`meson-python`,
+        :ref:`scikit-build-core`,
+        and :ref:`setuptools`.
+
+
+    Build Frontend
+
+        A tool that users might run
+        that takes arbitrary source trees or
+        :term:`source distributions `
+        and builds source distributions or :term:`wheels ` from them.
+        The actual building is delegated to each source tree's
+        :term:`build backend `.
+
+        Examples of build frontends are :ref:`pip` and :ref:`build`.
+
+
     Built Distribution
 
         A :term:`Distribution ` format containing files
diff --git a/source/key_projects.rst b/source/key_projects.rst
index b81dccd2f..dfb46b9a5 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -140,7 +140,7 @@ hatch
 
 Hatch is a unified command-line tool meant to conveniently manage
 dependencies and environment isolation for Python developers. Python
-package developers use Hatch and its build backend Hatchling to
+package developers use Hatch and its :term:`build backend ` Hatchling to
 configure, version, specify dependencies for, and publish packages
 to PyPI. Its plugin system allows for easily extending functionality.
 
diff --git a/source/specifications/declaring-project-metadata.rst b/source/specifications/declaring-project-metadata.rst
index 4f1d4199d..119635087 100644
--- a/source/specifications/declaring-project-metadata.rst
+++ b/source/specifications/declaring-project-metadata.rst
@@ -27,7 +27,7 @@ table which are not defined by this specification. For tools wishing
 to store their own settings in ``pyproject.toml``, they may use the
 ``[tool]`` table as defined in the
 :ref:`build dependency declaration specification `.
-The lack of a ``[project]`` table implicitly means the build back-end
+The lack of a ``[project]`` table implicitly means the :term:`build backend `
 will dynamically provide all keys.
 
 The only keys required to be statically defined are:
diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst
index 93531430f..8ef55df96 100644
--- a/source/specifications/source-distribution-format.rst
+++ b/source/specifications/source-distribution-format.rst
@@ -43,7 +43,8 @@ The name and version components of the filename MUST match the values stored
 in the metadata contained in the file.
 
 Code that produces a source distribution file MUST give the file a name that matches
-this specification. This includes the ``build_sdist`` hook of a build backend.
+this specification. This includes the ``build_sdist`` hook of a
+:term:`build backend `.
 
 Code that processes source distribution files MAY recognise source distribution files
 by the ``.tar.gz`` suffix and the presence of precisely *one* hyphen in the filename.
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 0b6b60d81..8901a2281 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -107,8 +107,8 @@ Choosing a build backend
 ------------------------
 
 Tools like :ref:`pip` and :ref:`build` do not actually convert your sources
-into a :term:`distribution package ` (like a wheel); 
-that job is performed by a *build backend*. The build backend determines how
+into a :term:`distribution package ` (like a wheel);
+that job is performed by a :term:`build backend `. The build backend determines how
 your project will specify its configuration, including metadata (information
 about the project, for example, the name and tags that are displayed on PyPI)
 and input files. Build backends have different levels of functionality, such as
@@ -127,7 +127,7 @@ table for :ref:`metadata `.
    management, as well as building, uploading, and installing packages. This
    tutorial uses single-purpose tools that work independently.
 
-The :file:`pyproject.toml` tells "front end" build tools like :ref:`pip` and
+The :file:`pyproject.toml` tells :term:`build frontend ` tools like :ref:`pip` and
 :ref:`build` which backend to use for your project. Below are some
 examples for common build backends, but check your backend's own documentation
 for more details.
@@ -166,7 +166,7 @@ for more details.
 
 
 The ``requires`` key is a list of packages that are needed to build your package.
-The frontend should install them automatically when building your package.
+The :term:`frontend ` should install them automatically when building your package.
 Frontends usually run builds in isolated environments, so omitting dependencies
 here may cause build-time errors.
 This should always include your backend's package, and might have other build-time

From 9e0b14b4605a869f2bd985786ea267fb14d4a444 Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sat, 4 Nov 2023 07:49:24 -0700
Subject: [PATCH 100/733] Apply @sinoroc review suggestions

---
 .../installing-using-pip-and-virtual-environments.rst       | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index af2a1cad5..c475ca299 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -2,7 +2,7 @@ Installing packages using pip and venv
 ======================================
 
 This guide discusses how to install packages using :ref:`pip` and
-the standard library's virtual environment manager :ref:`venv`. The guide
+the standard library's virtual environment :ref:`venv`. The guide
 covers how to:
 
 * Install and update pip
@@ -83,8 +83,8 @@ since packages can be installed confidently and will not interfere with the
 other project environments.
 
 .. tip::
-   It is always recommended to use a virtual environment while developing Python
-   applications.
+   It is recommended to use a virtual environment when working with third
+   party packages.
 
 To create a virtual environment, go to your project's directory and run
 ``venv``.

From 0671716efede7103c3f80e10b642dc4fe036dd40 Mon Sep 17 00:00:00 2001
From: sinoroc 
Date: Sat, 4 Nov 2023 20:28:31 +0100
Subject: [PATCH 101/733] Clarify sentence about empty __init__.py

GitHub: fixes https://github.com/pypa/packaging.python.org/issues/1292
---
 source/tutorials/packaging-projects.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 0b6b60d81..5da846c9c 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -54,8 +54,8 @@ Create the following file structure locally:
 The directory containing the Python files should match the project name. This
 simplifies the configuration and is more obvious to users who install the package.
 
-:file:`__init__.py` is required to import the directory as a package, and
-should be empty.
+:file:`__init__.py` is required to import the directory as a package,
+even if as is our case for this tutorial that file is empty.
 
 :file:`example.py` is an example of a module within the package that could
 contain the logic (functions, classes, constants, etc.) of your package.
@@ -107,7 +107,7 @@ Choosing a build backend
 ------------------------
 
 Tools like :ref:`pip` and :ref:`build` do not actually convert your sources
-into a :term:`distribution package ` (like a wheel); 
+into a :term:`distribution package ` (like a wheel);
 that job is performed by a *build backend*. The build backend determines how
 your project will specify its configuration, including metadata (information
 about the project, for example, the name and tags that are displayed on PyPI)

From d6fd58451784f6e1c773420e60f4d3841a065e45 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 4 Nov 2023 21:16:44 +0100
Subject: [PATCH 102/733] Use correct reST syntax for emphasis

xref: https://github.com/sphinx-contrib/sphinx-lint/issues/98
---
 source/specifications/name-normalization.rst | 2 +-
 source/tutorials/installing-packages.rst     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/specifications/name-normalization.rst b/source/specifications/name-normalization.rst
index 4756d1631..64be4a1d1 100644
--- a/source/specifications/name-normalization.rst
+++ b/source/specifications/name-normalization.rst
@@ -36,7 +36,7 @@ This means that the following names are all equivalent:
 * ``friendly.bard``
 * ``friendly_bard``
 * ``friendly--bard``
-* ``FrIeNdLy-._.-bArD`` (a _terrible_ way to write a name, but it is valid)
+* ``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)
 
 History
 =======
diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
index 5d4957519..46957f93b 100644
--- a/source/tutorials/installing-packages.rst
+++ b/source/tutorials/installing-packages.rst
@@ -277,7 +277,7 @@ that the virtual environment's variables are set within the current
 shell, and not in a subprocess (which then disappears, having no
 useful effect).
 
-In both of the above cases, Windows users should _not_ use the
+In both of the above cases, Windows users should *not* use the
 :command:`source` command, but should rather run the :command:`activate`
 script directly from the command shell like so:
 

From aff0be6437f8455d712610eee311c1e3701ab147 Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sat, 4 Nov 2023 13:58:48 -0700
Subject: [PATCH 103/733] Apply @Kwpolska suggestion to scope to using pip in a
 virtual environment

---
 ...ing-using-pip-and-virtual-environments.rst | 133 +++++++++++-------
 1 file changed, 79 insertions(+), 54 deletions(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index c475ca299..a5d6533c3 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -1,12 +1,12 @@
-Installing packages using pip and venv
-======================================
+Install packages in a virtual environment using pip and venv
+============================================================
 
-This guide discusses how to install packages using :ref:`pip` and
-the standard library's virtual environment :ref:`venv`. The guide
-covers how to:
+This guide discusses how to create and activate a virtual environment using
+the standard library's virtual environment :ref:`venv` and install packages.
+The guide covers how to:
 
-* Install and update pip
-* Create and use a virtual environment
+* Create and activate a virtual environment
+* Prepare pip
 * Install packages into a virtual environment using the ``pip`` command
 * Use and create a requirements file
 
@@ -21,52 +21,11 @@ covers how to:
     import modules in your Python source code.
 
 
-Install and update pip
-----------------------
-
-:ref:`pip` is the reference Python package manager.
-It's used to install and update packages.
-Make sure you have the latest version of pip installed.
-
-
-.. tab:: Unix/macOS
-
-    Debian and most other distributions include a `python-pip`_ package; if you
-    want to use the Linux distribution-provided versions of pip, see
-    :doc:`/guides/installing-using-linux-tools`.
-
-    You can also install pip yourself to ensure you have the latest version. It's
-    recommended to use the system pip to bootstrap a user installation of pip:
-
-    .. code-block:: bash
-
-        python3 -m pip install --user --upgrade pip
-        python3 -m pip --version
-
-    Afterwards, you should have the latest version of pip installed in your
-    user site:
-
-    .. code-block:: text
-
-        pip 21.1.3 from $HOME/.local/lib/python3.9/site-packages (python 3.9)
-
-    .. _python-pip: https://packages.debian.org/stable/python/python3-pip
-
-.. tab:: Windows
-
-    The Python installers for Windows include pip. You can make sure that pip is
-    up-to-date by running:
-
-    .. code-block:: bat
-
-        py -m pip install --upgrade pip
-        py -m pip --version
-
-    Afterwards, you should have the latest version of pip:
-
-    .. code-block:: text
-
-        pip 21.1.3 from c:\python39\lib\site-packages (Python 3.9.4)
+.. important::
+    This guide has the prerequisite that an official Python version from
+    . If you are using your operating
+    system's package manager to install Python, please ensure that Python is
+    installed before proceeding with these steps.
 
 
 Create and Use Virtual Environments
@@ -80,7 +39,7 @@ different projects. It creates a "virtual" isolated Python installation. When
 you switch projects, you can create a new virtual environment which is isolated
 from other virtual environments. You benefit from the virtual environment
 since packages can be installed confidently and will not interfere with the
-other project environments.
+another project's environment.
 
 .. tip::
    It is recommended to use a virtual environment when working with third
@@ -185,6 +144,72 @@ instructions about activating a virtual environment. There's no need to create
 a new virtual environment.
 
 
+Prepare pip
+-----------
+
+:ref:`pip` is the reference Python package manager.
+It's used to install and update packages into a virtual environment.
+
+
+.. tab:: Unix
+
+    Debian and most other distributions include a `python-pip`_ package; if you
+    want to use the Linux distribution-provided versions of pip, see
+    :doc:`/guides/installing-using-linux-tools`.
+
+    You can also install pip yourself to ensure you have the latest version. It's
+    recommended to use the system pip to bootstrap a user installation of pip:
+
+    .. code-block:: bash
+
+        python3 -m pip install --user --upgrade pip
+        python3 -m pip --version
+
+    Afterwards, you should have the latest version of pip installed in your
+    user site:
+
+    .. code-block:: text
+
+        pip 21.1.3 from $HOME/.local/lib/python3.9/site-packages (python 3.9)
+
+    .. _python-pip: https://packages.debian.org/stable/python/python3-pip
+
+.. tab:: macOS
+
+    The Python installers for macOS include pip. You can make sure that pip is
+    up-to-date by running:
+
+    .. code-block:: bash
+
+        python3 -m pip install --upgrade pip
+        python3 -m pip --version
+
+    Afterwards, you should have the latest version of pip installed in your
+    user site:
+
+    .. code-block:: text
+
+        pip 21.1.3 from $HOME/.local/lib/python3.9/site-packages (python 3.9)
+
+    .. _python-pip: https://packages.debian.org/stable/python/python3-pip
+
+.. tab:: Windows
+
+    The Python installers for Windows include pip. You can make sure that pip is
+    up-to-date by running:
+
+    .. code-block:: bat
+
+        py -m pip install --upgrade pip
+        py -m pip --version
+
+    Afterwards, you should have the latest version of pip:
+
+    .. code-block:: text
+
+        pip 21.1.3 from c:\python39\lib\site-packages (Python 3.9.4)
+
+
 Install packages using pip
 --------------------------
 

From eba4e49b088e9dae8fddc25cbd3b8ae2c3cc2e9d Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sat, 4 Nov 2023 14:01:31 -0700
Subject: [PATCH 104/733] add missing sentence fragment

---
 source/guides/installing-using-pip-and-virtual-environments.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index a5d6533c3..bd43a919b 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -23,7 +23,7 @@ The guide covers how to:
 
 .. important::
     This guide has the prerequisite that an official Python version from
-    . If you are using your operating
+     is installed. If you are using your operating
     system's package manager to install Python, please ensure that Python is
     installed before proceeding with these steps.
 

From 660d634149c6c1b07eedfd1286c4fea4138e080f Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sat, 4 Nov 2023 16:14:10 -0700
Subject: [PATCH 105/733] Update
 source/guides/installing-using-pip-and-virtual-environments.rst

Co-authored-by: sinoroc <5529267+sinoroc@users.noreply.github.com>
---
 source/guides/installing-using-pip-and-virtual-environments.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index bd43a919b..9601a47c4 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -2,7 +2,7 @@ Install packages in a virtual environment using pip and venv
 ============================================================
 
 This guide discusses how to create and activate a virtual environment using
-the standard library's virtual environment :ref:`venv` and install packages.
+the standard library's virtual environment tool :ref:`venv` and install packages.
 The guide covers how to:
 
 * Create and activate a virtual environment

From 6e705b64b5a344a0185adab6be70955416369c6d Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sat, 4 Nov 2023 16:14:31 -0700
Subject: [PATCH 106/733] Update
 source/guides/installing-using-pip-and-virtual-environments.rst

Co-authored-by: sinoroc <5529267+sinoroc@users.noreply.github.com>
---
 source/guides/installing-using-pip-and-virtual-environments.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index 9601a47c4..28c562373 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -22,7 +22,7 @@ The guide covers how to:
 
 
 .. important::
-    This guide has the prerequisite that an official Python version from
+    This guide has the prerequisite that you are using an official Python version obtained from
      is installed. If you are using your operating
     system's package manager to install Python, please ensure that Python is
     installed before proceeding with these steps.

From bb47ed25456d01e886d2c8be82333033347f27a9 Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sat, 4 Nov 2023 17:09:24 -0700
Subject: [PATCH 107/733] remove debian specific content and add mention
 closing shell deactivates

---
 ...ing-using-pip-and-virtual-environments.rst | 31 ++++++++-----------
 1 file changed, 13 insertions(+), 18 deletions(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index 28c562373..893db6ce1 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -23,7 +23,7 @@ The guide covers how to:
 
 .. important::
     This guide has the prerequisite that you are using an official Python version obtained from
-     is installed. If you are using your operating
+    . If you are using your operating
     system's package manager to install Python, please ensure that Python is
     installed before proceeding with these steps.
 
@@ -46,7 +46,7 @@ another project's environment.
    party packages.
 
 To create a virtual environment, go to your project's directory and run
-``venv``.
+``venv``. This will create a new virtual environment in a local folder ``.venv``:
 
 .. tab:: Unix/macOS
 
@@ -87,7 +87,7 @@ shell's ``PATH``.
 
     .. code-block:: bat
 
-        .\.venv\Scripts\activate
+        .venv\bin\Activate.bat
 
 To confirm the virtual environment is activated, check the location of your
 Python interpreter:
@@ -117,7 +117,7 @@ the ``.venv`` directory:
 
     .. code-block:: bat
 
-        ...\.venv\Scripts\python.exe
+        ...\.venv\bin\python.exe
 
 
 While a virtual environment is activated, pip will install packages into that
@@ -135,6 +135,10 @@ If you want to switch projects or leave your virtual environment,
 
     deactivate
 
+.. note::
+    Closing your shell will deactivate the virtual environment. If
+    you open a new shell window and want to use the virtual environment,
+    reactivate it.
 
 Reactivate a virtual environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -153,16 +157,11 @@ It's used to install and update packages into a virtual environment.
 
 .. tab:: Unix
 
-    Debian and most other distributions include a `python-pip`_ package; if you
-    want to use the Linux distribution-provided versions of pip, see
-    :doc:`/guides/installing-using-linux-tools`.
-
-    You can also install pip yourself to ensure you have the latest version. It's
-    recommended to use the system pip to bootstrap a user installation of pip:
+    You can make sure that pip is up-to-date by running:
 
     .. code-block:: bash
 
-        python3 -m pip install --user --upgrade pip
+        python3 -m pip install --upgrade pip
         python3 -m pip --version
 
     Afterwards, you should have the latest version of pip installed in your
@@ -170,9 +169,7 @@ It's used to install and update packages into a virtual environment.
 
     .. code-block:: text
 
-        pip 21.1.3 from $HOME/.local/lib/python3.9/site-packages (python 3.9)
-
-    .. _python-pip: https://packages.debian.org/stable/python/python3-pip
+        pip 21.1.3 from ../.venv/lib/python3.9/site-packages (python 3.9)
 
 .. tab:: macOS
 
@@ -189,9 +186,7 @@ It's used to install and update packages into a virtual environment.
 
     .. code-block:: text
 
-        pip 21.1.3 from $HOME/.local/lib/python3.9/site-packages (python 3.9)
-
-    .. _python-pip: https://packages.debian.org/stable/python/python3-pip
+        pip 23.3.1 from $HOME/.venv/lib/python3.9/site-packages (python 3.9)
 
 .. tab:: Windows
 
@@ -207,7 +202,7 @@ It's used to install and update packages into a virtual environment.
 
     .. code-block:: text
 
-        pip 21.1.3 from c:\python39\lib\site-packages (Python 3.9.4)
+        pip 23.3.1 from .venv\lib\site-packages (Python 3.9.4)
 
 
 Install packages using pip

From e05aad7762e416cad1d66c82eddfeebe946f906b Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sat, 4 Nov 2023 17:14:36 -0700
Subject: [PATCH 108/733] make output consistent

---
 .../guides/installing-using-pip-and-virtual-environments.rst  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index 893db6ce1..07ef2d26a 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -169,7 +169,7 @@ It's used to install and update packages into a virtual environment.
 
     .. code-block:: text
 
-        pip 21.1.3 from ../.venv/lib/python3.9/site-packages (python 3.9)
+        pip 23.3.1 from .../.venv/lib/python3.9/site-packages (python 3.9)
 
 .. tab:: macOS
 
@@ -186,7 +186,7 @@ It's used to install and update packages into a virtual environment.
 
     .. code-block:: text
 
-        pip 23.3.1 from $HOME/.venv/lib/python3.9/site-packages (python 3.9)
+        pip 23.3.1 from .../.venv/lib/python3.9/site-packages (python 3.9)
 
 .. tab:: Windows
 

From 18ddb70dbf81da59494192ce46781ebf34fe0d4b Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sat, 4 Nov 2023 17:23:08 -0700
Subject: [PATCH 109/733] remove the creating documentation tutorial

---
 source/tutorials/creating-documentation.rst | 66 ---------------------
 source/tutorials/index.rst                  |  1 -
 2 files changed, 67 deletions(-)
 delete mode 100644 source/tutorials/creating-documentation.rst

diff --git a/source/tutorials/creating-documentation.rst b/source/tutorials/creating-documentation.rst
deleted file mode 100644
index 483fb0d72..000000000
--- a/source/tutorials/creating-documentation.rst
+++ /dev/null
@@ -1,66 +0,0 @@
-.. _creating-documentation:
-
-======================
-Creating Documentation
-======================
-
-This section covers the basics of how to create documentation using `Sphinx`_ and
-host the documentation for free in `Read The Docs`_.
-
-.. _Sphinx: https://www.sphinx-doc.org
-.. _Read The Docs: https://readthedocs.org/
-
-Installing Sphinx
------------------
-Use ``pip`` to install Sphinx:
-
-.. tab:: Unix/macOS
-
-    .. code-block:: bash
-
-        python3 -m pip install --upgrade sphinx
-
-.. tab:: Windows
-
-    .. code-block:: bat
-
-        py -m pip install --upgrade sphinx
-
-For other installation methods, see this :doc:`installation guide ` by Sphinx.
-
-
-Getting Started With Sphinx
----------------------------
-
-Create a ``docs`` directory inside your project to hold your documentation:
-
-.. code-block:: bash
-
-	cd /path/to/project
-	mkdir docs
-
-Run ``sphinx-quickstart`` inside the ``docs`` directory:
-
-.. code-block:: bash
-
-	cd docs
-	sphinx-quickstart
-
-This sets up a source directory, walks you through some basic configurations, and creates an ``index.rst`` file as well as a ``conf.py`` file.
-
-You can add some information about your project in ``index.rst``, then build them:
-
-.. code-block:: bash
-
-	make html
-
-For more details on the build process, see this `guide`_ by Read The Docs.
-
-.. _guide: https://docs.readthedocs.io/en/latest/intro/import-guide.html
-
-Other Sources
--------------
-
-For a more detailed guide on how to use Sphinx and reStructuredText, please see this `documentation tutorial`_ on Hitchhiker's Guide to Python.
-
-.. _documentation tutorial: https://docs.python-guide.org/writing/documentation/
diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst
index 40b0620f3..33ab4f98a 100644
--- a/source/tutorials/index.rst
+++ b/source/tutorials/index.rst
@@ -11,4 +11,3 @@ topics, see :doc:`/guides/index`.
     installing-packages
     managing-dependencies
     packaging-projects
-    creating-documentation

From 264ccc6b59a353b8f60ac132191afd6b21f01997 Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sat, 4 Nov 2023 17:33:30 -0700
Subject: [PATCH 110/733] Add diataxis reference in contributing doc

---
 source/contribute.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/source/contribute.rst b/source/contribute.rst
index afac9e4f7..a246751e4 100644
--- a/source/contribute.rst
+++ b/source/contribute.rst
@@ -32,9 +32,12 @@ Documentation types
 ===================
 
 This project consists of four distinct documentation types with specific
-purposes. When proposing new additions to the project please pick the
+purposes. The project aspires to follow the `Diátaxis process`_
+for creating quality documentation. When proposing new additions to the project please pick the
 appropriate documentation type.
 
+.. _Diátaxis process: https://diataxis.fr/
+
 Tutorials
 ---------
 

From 51ca36eebe4c1305f71a2e94e6e808db5d33639a Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sat, 4 Nov 2023 17:48:28 -0700
Subject: [PATCH 111/733] Add another category in guide index to put more
 advanced hosting/mirrors

---
 source/guides/index.rst | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/source/guides/index.rst b/source/guides/index.rst
index 10c189a17..4634dcc23 100644
--- a/source/guides/index.rst
+++ b/source/guides/index.rst
@@ -13,8 +13,6 @@ introduction to packaging, see :doc:`/tutorials/index`.
    installing-stand-alone-command-line-tools
    installing-using-linux-tools
    installing-scientific-packages
-   index-mirrors-and-caches
-   hosting-your-own-index
 
 .. toctree::
    :maxdepth: 1
@@ -31,6 +29,13 @@ introduction to packaging, see :doc:`/tutorials/index`.
    making-a-pypi-friendly-readme
    publishing-package-distribution-releases-using-github-actions-ci-cd-workflows
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Hosting
+
+   index-mirrors-and-caches
+   hosting-your-own-index
+
 .. toctree::
    :maxdepth: 1
    :caption: Miscellaneous:

From 789d02b14297cae24c58a7155df36b7c4d569559 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 5 Nov 2023 16:16:21 +0100
Subject: [PATCH 112/733] Split a pyproject.toml guide out of the "Declaring
 project metadata" specification

Fixes #1349
---
 .../creating-and-discovering-plugins.rst      |   2 +
 source/guides/index.rst                       |   1 +
 source/guides/writing-pyproject-toml.rst      | 383 ++++++++++++++++++
 .../declaring-project-metadata.rst            | 155 +------
 4 files changed, 392 insertions(+), 149 deletions(-)
 create mode 100644 source/guides/writing-pyproject-toml.rst

diff --git a/source/guides/creating-and-discovering-plugins.rst b/source/guides/creating-and-discovering-plugins.rst
index eceebc843..601f2b4a6 100644
--- a/source/guides/creating-and-discovering-plugins.rst
+++ b/source/guides/creating-and-discovering-plugins.rst
@@ -116,6 +116,8 @@ a list of packages to :func:`setup`'s ``packages`` argument instead of using
     :doc:`packaging-namespace-packages` documentation and clearly document
     which approach is preferred for plugins to your project.
 
+.. _plugin-entry-points:
+
 Using package metadata
 ======================
 
diff --git a/source/guides/index.rst b/source/guides/index.rst
index 4634dcc23..9854eb8b3 100644
--- a/source/guides/index.rst
+++ b/source/guides/index.rst
@@ -18,6 +18,7 @@ introduction to packaging, see :doc:`/tutorials/index`.
    :maxdepth: 1
    :caption: Building and Publishing Projects:
 
+   writing-pyproject-toml
    distributing-packages-using-setuptools
    using-manifest-in
    single-sourcing-package-version
diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
new file mode 100644
index 000000000..af5c2fe18
--- /dev/null
+++ b/source/guides/writing-pyproject-toml.rst
@@ -0,0 +1,383 @@
+.. _writing-pyproject-toml:
+
+===============================
+Writing your ``pyproject.toml``
+===============================
+
+.. TODO: link :term:`build backends` when that's merged
+
+``pyproject.toml`` is a configuration file used by packaging tools. Most
+build backends [#poetry-special]_ allow you to specify your project's
+basic metadata, such as the dependencies, your name, etc., in the ``[project]``
+table of your ``pyproject.toml``.
+
+.. note::
+
+   You may have heard of ``setup.py`` and ``setup.cfg`` for the setuptools_
+   build backend. For new projects, it is recommended to use ``pyproject.toml``
+   for basic metadata, and keep ``setup.py`` only if some programmatic configuration
+   is needed (especially building C extensions). However, putting basic project
+   metadata in ``setup.py`` or ``setup.cfg`` is still valid.
+
+.. TODO: link to "is setup.py deprecated?" page when merged
+
+Static vs. dynamic metadata
+===========================
+
+Most of the time, you will directly write the value of a field in
+``pyproject.toml``.  For example: ``requires-python = ">= 3.8"``, or
+``version = "1.0"``.
+
+However, in some cases, it is useful to let your build backend compute
+the metadata for you. For example: many build backends can read the
+version from a ``__version__`` attribute in your code, or similar.
+In such cases, you should mark the field as dynamic using, e.g.,
+
+.. code-block:: toml
+
+   [project]
+   dynamic = ["version"]
+
+
+When a field is dynamic, it is the build backend's responsibility to
+fill it.  Consult your build backend's documentation to learn how it
+does it.
+
+
+Basic information
+=================
+
+``name``
+--------
+
+Put the name of your project on PyPI. This field is required and is the
+only field that cannot be marked as dynamic.
+
+.. code-block:: toml
+
+   [project]
+   name = "spam"
+
+
+``version``
+-----------
+
+Put the version of your project.
+
+.. code-block:: toml
+
+    [project]
+    version = "2020.0.0"
+
+This field is required, although it is often marked as dynamic using
+
+.. code-block:: toml
+
+   [project]
+   dynamic = ["version"]
+
+
+
+Dependencies and requirements
+=============================
+
+``dependencies``/``optional-dependencies``
+------------------------------------------
+
+If your project has dependencies, list them like this:
+
+.. code-block:: toml
+
+   [project]
+   dependencies = [
+     "httpx",
+     "gidgethub[httpx]>4.0.0",
+     "django>2.1; os_name != 'nt'",
+     "django>2.0; os_name == 'nt'",
+   ]
+
+See :ref:`Dependency specifiers ` for the full
+syntax you can use to constrain versions.
+
+You may want to make some of your dependencies optional, if they are
+only needed for a specific feature of your package. In that case, put
+them in ``optional-dependencies``.
+
+.. code-block:: toml
+
+    [project.optional-dependencies]
+    gui = ["PyQt5"]
+    cli = [
+      "rich",
+      "click",
+    ]
+
+Each of the keys defines a "packaging extra". In the example above, one
+could use, e.g., ``pip install your-project-name[gui]`` to install your
+project with GUI support, adding the PyQt5 dependency.
+
+
+``python-requires``
+-------------------
+
+This lets you declare the minimum version of Python that you support
+[#requires-python-upper-bounds]_.
+
+.. code-block:: toml
+
+   [project]
+   requires-python = ">= 3.8"
+
+
+
+Creating executable scripts
+===========================
+
+To install a command as part of your package, declare it in the
+``[project.scripts]`` table.
+
+.. code-block:: toml
+
+   [project.scripts]
+   spam-cli = "spam:main_cli"
+
+In this example, after installing your project, a ``spam-cli`` command
+will be available. Executing this command will do the equivalent of
+``from spam import main_cli; main_cli()``.
+
+On Windows, scripts packaged this way need a terminal, so if you launch
+them from within a graphical application, they will make a terminal pop
+up. To prevent this from happening, use the ``[project.gui-scripts]``
+table instead of ``[project.scripts]``.
+
+.. code-block:: toml
+
+   [project.gui-scripts]
+   spam-gui = "spam:main_gui"
+
+In that case, launching your script from the command line will give back
+control immediately, leaving the script to run in the background.
+
+The difference between ``[project.scripts]`` and
+``[project.gui-scripts]`` is only relevant on Windows.
+
+
+
+About your project
+==================
+
+``authors``/``maintainers``
+---------------------------
+
+Both of these fields contain lists of people identified by a name and/or
+an email address.
+
+.. code-block:: toml
+
+    [project]
+    authors = [
+      {name = "Pradyun Gedam", email = "pradyun@example.com"},
+      {name = "Tzu-Ping Chung", email = "tzu-ping@example.com"},
+      {name = "Another person"},
+      {email = "different.person@example.com"},
+    ]
+    maintainers = [
+      {name = "Brett Cannon", email = "brett@python.org"}
+    ]
+
+
+``description``
+---------------
+
+This should be a one-line description of your project, to show as the
+"headline" of your project page on PyPI (`example `_).
+
+.. code-block:: toml
+
+    [project]
+    description = "Lovely Spam! Wonderful Spam!"
+
+
+``readme``
+----------
+
+This is a longer description of your project, to display on your project
+page on PyPI. Typically, your project will have a ``README.md`` or
+``README.rst`` file and you just put its file name here.
+
+.. code-block:: toml
+
+    [project]
+    readme = "README.md"
+
+The README's format is auto-detected from the extension:
+
+- ``README.md`` → Markdown,
+- ``README.rst`` → reStructuredText (without Sphinx extensions).
+
+You can also specify the format explicitly, like this:
+
+.. code-block:: toml
+
+   [project]
+   readme = {file = "README.txt", content-type = "text/markdown"}
+   # or
+   readme = {file = "README.txt", content-type = "text/x-rst"}
+
+
+``license``
+-----------
+
+This can take two forms. You can put your license in a file, typically
+``LICENSE`` or ``LICENSE.txt``, and link that file here:
+
+.. code-block:: toml
+
+    [project]
+    license = {file = "LICENSE"}
+
+or you can write the name of the license:
+
+
+.. code-block:: toml
+
+    [project]
+    license = {text = "MIT License"}
+
+
+
+``keywords``
+------------
+
+This will help PyPI's search box to suggest your project when people
+search for these keywords.
+
+.. code-block:: toml
+
+    [project]
+    keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
+
+
+``classifiers``
+---------------
+
+A list of PyPI classifiers that apply to your project. Check the
+`full list of possibilities `_.
+
+.. code-block:: toml
+
+    classifiers = [
+      "Development Status :: 4 - Beta",
+      "Programming Language :: Python"
+    ]
+
+
+``urls``
+--------
+
+A list of URLs associated with your project, displayed on the left
+sidebar of your PyPI project page. If the key contains spaces, don't
+forget to quote it.
+
+.. code-block:: toml
+
+    [project.urls]
+    Homepage = "https://example.com"
+    Documentation = "https://readthedocs.org"
+    Repository = "https://github.com/me/spam.git"
+    "Bug Tracker" = "https://github.com/me/spam/issues"
+    Changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
+
+
+Advanced plugins
+================
+
+Some packages can be extended through plugins. Examples include Pytest_
+and Pygments_. To create such a plugin, you need to declare it in a subtable
+of ``[project.entry-points]`` like this:
+
+.. code-block:: toml
+
+   [project.entry-points."spam.magical"]
+   tomatoes = "spam:main_tomatoes"
+
+See the :ref:`Plugin guide ` for more information.
+
+
+
+A full example
+==============
+
+.. code-block:: toml
+
+   [project]
+   name = "spam"
+   version = "2020.0.0"
+   dependencies = [
+     "httpx",
+     "gidgethub[httpx]>4.0.0",
+     "django>2.1; os_name != 'nt'",
+     "django>2.0; os_name == 'nt'",
+   ]
+   requires-python = ">=3.8"
+   authors = [
+     {name = "Pradyun Gedam", email = "pradyun@example.com"},
+     {name = "Tzu-Ping Chung", email = "tzu-ping@example.com"},
+     {name = "Another person"},
+     {email = "different.person@example.com"},
+   ]
+   maintainers = [
+     {name = "Brett Cannon", email = "brett@python.org"}
+   ]
+   description = "Lovely Spam! Wonderful Spam!"
+   readme = "README.rst"
+   license = {file = "LICENSE.txt"}
+   keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
+   classifiers = [
+     "Development Status :: 4 - Beta",
+     "Programming Language :: Python"
+   ]
+
+   # dynamic = ["version", "description"]
+
+   [project.optional-dependencies]
+   gui = ["PyQt5"]
+   cli = [
+     "rich",
+     "click",
+   ]
+
+   [project.urls]
+   Homepage = "https://example.com"
+   Documentation = "https://readthedocs.org"
+   Repository = "https://github.com/me/spam.git"
+   "Bug Tracker" = "https://github.com/me/spam/issues"
+   Changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
+
+   [project.scripts]
+   spam-cli = "spam:main_cli"
+
+   [project.gui-scripts]
+   spam-gui = "spam:main_gui"
+
+   [project.entry-points."spam.magical"]
+   tomatoes = "spam:main_tomatoes"
+
+
+------------------
+
+.. [#poetry-special] At the time of this writing (November 2023), Poetry_
+   is a notable exception.  It uses its own format for this metadata, in
+   the ``[tool.poetry]`` table.
+
+.. [#requires-python-upper-bounds] Think twice before applying an upper bound
+   like ``requires-python = "<= 3.10"`` here. `This blog post `_
+   contains some information regarding possible problems.
+
+.. _setuptools: https://setuptools.pypa.io
+.. _poetry: https://python-poetry.org
+.. _pypi-pip: https://pypi.org/project/pip
+.. _classifier-list: https://pypi.org/classifiers
+.. _requires-python-blog-post: https://iscinumpy.dev/post/bound-version-constraints/#pinning-the-python-version-is-special
+.. _pytest: https://pytest.org
+.. _pygments: https://pygments.org
diff --git a/source/specifications/declaring-project-metadata.rst b/source/specifications/declaring-project-metadata.rst
index 4f1d4199d..c7e7e3040 100644
--- a/source/specifications/declaring-project-metadata.rst
+++ b/source/specifications/declaring-project-metadata.rst
@@ -9,6 +9,12 @@ Declaring project metadata
 packaging-related tools to consume. It defines the following
 specification as the canonical source for the format used.
 
+.. warning::
+
+   This is a **technical, formal specification**. For a gentle,
+   user-friendly guide to ``pyproject.toml``, see
+   :ref:`writing-pyproject-toml`.
+
 
 Specification
 =============
@@ -75,11 +81,6 @@ The name of the project.
 Tools SHOULD :ref:`normalize ` this name, as soon
 as it is read for internal consistency.
 
-.. code-block:: toml
-
-    [project]
-    name = "spam"
-
 ``version``
 -----------
 
@@ -91,10 +92,6 @@ The version of the project as supported by :pep:`440`.
 
 Users SHOULD prefer to specify already-normalized versions.
 
-.. code-block:: toml
-
-    [project]
-    version = "2020.0.0"
 
 ``description``
 ---------------
@@ -105,10 +102,6 @@ Users SHOULD prefer to specify already-normalized versions.
 
 The summary description of the project.
 
-.. code-block:: toml
-
-    [project]
-    description = "Lovely Spam! Wonderful Spam!"
 
 ``readme``
 ----------
@@ -148,13 +141,6 @@ alternative content-types which they can transform to a content-type
 as supported by the :ref:`core metadata `. Otherwise
 tools MUST raise an error for unsupported content-types.
 
-.. code-block:: toml
-
-    [project]
-    # A single pyproject.toml file can only have one of the following.
-    readme = "README.md"
-    readme = "README.rst"
-    readme = {file = "README.txt", content-type = "text/markdown"}
 
 ``requires-python``
 -------------------
@@ -165,10 +151,6 @@ tools MUST raise an error for unsupported content-types.
 
 The Python version requirements of the project.
 
-.. code-block:: toml
-
-    [project]
-    requires-python = ">=3.8"
 
 ``license``
 -----------
@@ -184,12 +166,6 @@ file's encoding is UTF-8. The ``text`` key has a string value which is
 the license of the project.  These keys are mutually exclusive, so a
 tool MUST raise an error if the metadata specifies both keys.
 
-.. code-block:: toml
-
-    [project]
-    # A single pyproject.toml file can only have one of the following.
-    license = {file = "LICENSE"}
-    license = {text = "MIT License"}
 
 ``authors``/``maintainers``
 ---------------------------
@@ -232,19 +208,6 @@ follows:
    as appropriate, with the format ``{name} <{email}>``.
 4. Multiple values should be separated by commas.
 
-.. code-block:: toml
-
-    [project]
-    authors = [
-      {name = "Pradyun Gedam", email = "pradyun@example.com"},
-      {name = "Tzu-Ping Chung", email = "tzu-ping@example.com"},
-      {name = "Another person"},
-      {email = "different.person@example.com"},
-    ]
-    maintainers = [
-      {name = "Brett Cannon", email = "brett@python.org"}
-    ]
-
 
 ``keywords``
 ------------
@@ -255,10 +218,6 @@ follows:
 
 The keywords for the project.
 
-.. code-block:: toml
-
-    [project]
-    keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
 
 ``classifiers``
 ---------------
@@ -269,12 +228,6 @@ The keywords for the project.
 
 Trove classifiers which apply to the project.
 
-.. code-block:: toml
-
-    classifiers = [
-      "Development Status :: 4 - Beta",
-      "Programming Language :: Python"
-    ]
 
 ``urls``
 --------
@@ -286,13 +239,6 @@ Trove classifiers which apply to the project.
 A table of URLs where the key is the URL label and the value is the
 URL itself.
 
-.. code-block:: toml
-
-    [project.urls]
-    Homepage = "https://example.com"
-    Documentation = "https://readthedocs.org"
-    Repository = "https://github.com/me/spam.git"
-    Changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
 
 Entry points
 ------------
@@ -323,17 +269,6 @@ Build back-ends MUST raise an error if the metadata defines a
 be ambiguous in the face of ``[project.scripts]`` and
 ``[project.gui-scripts]``, respectively.
 
-.. code-block:: toml
-
-    [project.scripts]
-    spam-cli = "spam:main_cli"
-
-    [project.gui-scripts]
-    spam-gui = "spam:main_gui"
-
-    [project.entry-points."spam.magical"]
-    tomatoes = "spam:main_tomatoes"
-
 
 ``dependencies``/``optional-dependencies``
 ------------------------------------------
@@ -361,22 +296,6 @@ in the array thus becomes a corresponding
 matching :ref:`Provides-Extra `
 metadata.
 
-.. code-block:: toml
-
-    [project]
-    dependencies = [
-      "httpx",
-      "gidgethub[httpx]>4.0.0",
-      "django>2.1; os_name != 'nt'",
-      "django>2.0; os_name == 'nt'",
-    ]
-
-    [project.optional-dependencies]
-    gui = ["PyQt5"]
-    cli = [
-      "rich",
-      "click",
-    ]
 
 ``dynamic``
 -----------
@@ -415,68 +334,6 @@ provided via tooling later on.
   the data for it (omitting the data, if determined to be the accurate
   value, is acceptable).
 
-.. code-block:: toml
-
-    dynamic = ["version", "description", "optional-dependencies"]
-
-
-Example
-=======
-
-.. code-block:: toml
-
-    [project]
-    name = "spam"
-    version = "2020.0.0"
-    description = "Lovely Spam! Wonderful Spam!"
-    readme = "README.rst"
-    requires-python = ">=3.8"
-    license = {file = "LICENSE.txt"}
-    keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
-    authors = [
-      {name = "Pradyun Gedam", email = "pradyun@example.com"},
-      {name = "Tzu-Ping Chung", email = "tzu-ping@example.com"},
-      {name = "Another person"},
-      {email = "different.person@example.com"},
-    ]
-    maintainers = [
-      {name = "Brett Cannon", email = "brett@python.org"}
-    ]
-    classifiers = [
-      "Development Status :: 4 - Beta",
-      "Programming Language :: Python"
-    ]
-
-    dependencies = [
-      "httpx",
-      "gidgethub[httpx]>4.0.0",
-      "django>2.1; os_name != 'nt'",
-      "django>2.0; os_name == 'nt'",
-    ]
-
-    # dynamic = ["version", "description"]
-
-    [project.optional-dependencies]
-    gui = ["PyQt5"]
-    cli = [
-      "rich",
-      "click",
-    ]
-
-    [project.urls]
-    Homepage = "https://example.com"
-    Documentation = "https://readthedocs.org"
-    Repository = "https://github.com/me/spam.git"
-    Changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
-
-    [project.scripts]
-    spam-cli = "spam:main_cli"
-
-    [project.gui-scripts]
-    spam-gui = "spam:main_gui"
-
-    [project.entry-points."spam.magical"]
-    tomatoes = "spam:main_tomatoes"
 
 
 .. _TOML: https://toml.io

From 45d0b24e73dbcca6c98eaa4f934267b8593d5b52 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 5 Nov 2023 18:19:23 +0100
Subject: [PATCH 113/733] Bump requirements

- Upgrade to latest version of Sphinx (and other dependencies),
- Use "language = 'en'" in configuration since recent Sphinx versions
  do not accept "language = None" anymore,
- Add now required "%s" in extlinks config,
- Refer to setuptools explicitly in :std:doc: because Sphinx no longer
  implicitly uses intersphinx (by default) for this role. See
  https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes

The generated HTML can be compared using

$ diff -u build-old/ build-new | colordiff | diff-highlight

The only visible change is "Permalink to this headling" becoming "Link to this heading".
---
 requirements.txt                                     |  6 +++---
 source/conf.py                                       | 12 ++++++------
 .../distributing-packages-using-setuptools.rst       |  4 ++--
 source/overview.rst                                  |  2 +-
 4 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/requirements.txt b/requirements.txt
index d6e0d750f..6cdad44d2 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,7 +1,7 @@
-sphinx==4.5.0
+sphinx==7.2.6
 sphinx-autobuild==2021.3.14
-sphinx-inline-tabs==2021.4.11b9
+sphinx-inline-tabs==2023.4.21
 python-docs-theme==2023.9
-sphinx-copybutton==0.5.0
+sphinx-copybutton==0.5.2
 pypa-docs-theme @ git+https://github.com/pypa/pypa-docs-theme.git
 sphinx-toolbox==3.5.0
diff --git a/source/conf.py b/source/conf.py
index 9113b8c68..c4d7a5ccc 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -88,7 +88,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 locale_dirs = ['../locales']
 
@@ -379,11 +379,11 @@
 
 # -- Options for extlinks extension ---------------------------------------
 extlinks = {
-    'issue': (f'{github_repo_issues_url}/%s', '#'),  # noqa: WPS323
-    'pr': (f'{github_repo_url}/pull/%s', 'PR #'),  # noqa: WPS323
-    'commit': (f'{github_repo_url}/commit/%s', ''),  # noqa: WPS323
-    'gh': (f'{github_url}/%s', 'GitHub: '),  # noqa: WPS323
-    'user': (f'{github_sponsors_url}/%s', '@'),  # noqa: WPS323
+    'issue': (f'{github_repo_issues_url}/%s', '#%s'),  # noqa: WPS323
+    'pr': (f'{github_repo_url}/pull/%s', 'PR #%s'),  # noqa: WPS323
+    'commit': (f'{github_repo_url}/commit/%s', '%s'),  # noqa: WPS323
+    'gh': (f'{github_url}/%s', 'GitHub: %s'),  # noqa: WPS323
+    'user': (f'{github_sponsors_url}/%s', '@%s'),  # noqa: WPS323
 }
 
 linkcheck_ignore = [
diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
index db982071d..f860cad06 100644
--- a/source/guides/distributing-packages-using-setuptools.rst
+++ b/source/guides/distributing-packages-using-setuptools.rst
@@ -15,7 +15,7 @@ development as a whole.  For example, it does not provide guidance or tool
 recommendations for version control, documentation, or testing.
 
 For more reference material, see :std:doc:`Building and Distributing
-Packages ` in the :ref:`setuptools` docs, but note
+Packages ` in the :ref:`setuptools` docs, but note
 that some advisory content there may be outdated. In the event of
 conflicts, prefer the advice in the Python Packaging User Guide.
 
@@ -717,7 +717,7 @@ Lastly, if you don't want to install any dependencies at all, you can run:
 
 For more information, see the
 :doc:`Development Mode ` section
-of the :doc:`setuptools docs `.
+of the :ref:`setuptools` docs.
 
 .. _`Packaging your project`:
 
diff --git a/source/overview.rst b/source/overview.rst
index 256510bb8..2f3f44007 100644
--- a/source/overview.rst
+++ b/source/overview.rst
@@ -167,7 +167,7 @@ Python's native packaging is mostly built for distributing reusable
 code, called libraries, between developers. You can piggyback
 **tools**, or basic applications for developers, on top of Python's
 library packaging, using technologies like
-:doc:`setuptools entry_points `.
+:doc:`setuptools entry_points `.
 
 Libraries are building blocks, not complete applications. For
 distributing applications, there's a whole new world of technologies

From 2ccba195df7fa75684efeb453c44d2912fdf33a7 Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sun, 5 Nov 2023 11:57:49 -0800
Subject: [PATCH 114/733] remove reference to Python 2 and virtualenv

---
 .../guides/installing-using-pip-and-virtual-environments.rst  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index 07ef2d26a..cb54fe189 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -11,8 +11,8 @@ The guide covers how to:
 * Use and create a requirements file
 
 
-.. note:: This guide applies to Python 3.3 and higher. If using a
-    legacy version of Python 2.x, consider using :ref:`virtualenv`.
+.. note:: This guide applies to supported versions of Python, currently 3.8
+    and higher.
 
 
 .. note:: This guide uses the term **package** to refer to a

From aa57f2edab29f48ca60458ba29adabae60bf23c2 Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sun, 5 Nov 2023 12:14:06 -0800
Subject: [PATCH 115/733] add stub how-to guide for virtualenv

---
 source/guides/index.rst                       |  1 +
 source/guides/installing-using-virtualenv.rst | 17 +++++++++++++++++
 2 files changed, 18 insertions(+)
 create mode 100644 source/guides/installing-using-virtualenv.rst

diff --git a/source/guides/index.rst b/source/guides/index.rst
index 4634dcc23..2f6f1a217 100644
--- a/source/guides/index.rst
+++ b/source/guides/index.rst
@@ -10,6 +10,7 @@ introduction to packaging, see :doc:`/tutorials/index`.
    :caption: Installing Packages:
 
    installing-using-pip-and-virtual-environments
+   installing-using-virtualenv
    installing-stand-alone-command-line-tools
    installing-using-linux-tools
    installing-scientific-packages
diff --git a/source/guides/installing-using-virtualenv.rst b/source/guides/installing-using-virtualenv.rst
new file mode 100644
index 000000000..d498677f0
--- /dev/null
+++ b/source/guides/installing-using-virtualenv.rst
@@ -0,0 +1,17 @@
+Installing packages using virtualenv
+====================================
+
+This guide discusses how to install packages using :ref:`pip` and
+:ref:`virtualenv`, a tool to create isolated Python environments.
+
+.. important::
+    This "how to" guide on installing packages and using :ref:`virtualenv` is
+    under development. Please refer to the `virtualenv's documentation`_ for
+    details on installation and usage.
+
+    .. virtualenv's documentation:: https://virtualenv.pypa.io/
+
+
+.. note:: This doc uses the term **package** to refer to a
+    :term:`Distribution Package`  which is different from an :term:`Import
+    Package` that which is used to import modules in your Python source code.

From 4c6680f58dada4609a337cd0044978fd5f6be8b7 Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sun, 5 Nov 2023 12:21:35 -0800
Subject: [PATCH 116/733] Create an orphan page per @pradyunsg review

---
 source/tutorials/creating-documentation.rst | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 source/tutorials/creating-documentation.rst

diff --git a/source/tutorials/creating-documentation.rst b/source/tutorials/creating-documentation.rst
new file mode 100644
index 000000000..5d9dae787
--- /dev/null
+++ b/source/tutorials/creating-documentation.rst
@@ -0,0 +1,7 @@
+:orphan:
+
+Creating documentation
+======================
+
+This tutorial has been removed since it is not related to packaging and was unmaintained.
+Please see the `Sphinx tutorial `_ instead.

From 6f9034105928e552689c7378fd91b13fb647be2c Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sun, 5 Nov 2023 12:24:40 -0800
Subject: [PATCH 117/733] remove colon

---
 source/guides/installing-using-virtualenv.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/installing-using-virtualenv.rst b/source/guides/installing-using-virtualenv.rst
index d498677f0..f29dcd845 100644
--- a/source/guides/installing-using-virtualenv.rst
+++ b/source/guides/installing-using-virtualenv.rst
@@ -9,7 +9,7 @@ This guide discusses how to install packages using :ref:`pip` and
     under development. Please refer to the `virtualenv's documentation`_ for
     details on installation and usage.
 
-    .. virtualenv's documentation:: https://virtualenv.pypa.io/
+    .. virtualenv's documentation: https://virtualenv.pypa.io/
 
 
 .. note:: This doc uses the term **package** to refer to a

From 85512268afa5b3bd2d0edf472a864fddd12fa1d2 Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sun, 5 Nov 2023 12:33:04 -0800
Subject: [PATCH 118/733] use existing ref

---
 source/guides/installing-using-virtualenv.rst | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/source/guides/installing-using-virtualenv.rst b/source/guides/installing-using-virtualenv.rst
index f29dcd845..a584b89d5 100644
--- a/source/guides/installing-using-virtualenv.rst
+++ b/source/guides/installing-using-virtualenv.rst
@@ -6,11 +6,9 @@ This guide discusses how to install packages using :ref:`pip` and
 
 .. important::
     This "how to" guide on installing packages and using :ref:`virtualenv` is
-    under development. Please refer to the `virtualenv's documentation`_ for
+    under development. Please refer to the :ref:`virtualenv` documentation for
     details on installation and usage.
 
-    .. virtualenv's documentation: https://virtualenv.pypa.io/
-
 
 .. note:: This doc uses the term **package** to refer to a
     :term:`Distribution Package`  which is different from an :term:`Import

From d10c3cfccb32db03fe941b79311843fab7ff4535 Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko 
Date: Mon, 6 Nov 2023 03:22:41 +0100
Subject: [PATCH 119/733] Fix the external flit lift page link RST syntax

Co-authored-by: chrysle 
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 1e9b58e51..a9b57fac4 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -105,7 +105,7 @@ Python 2, so long as they can be imported on Python 3.
 
 The flit package is lifted by `Matthias Bussonnier
 `__ since October 2023 on the `tidelift platform
-``__, and funds sent to the PSF and
 earmarked for PyPA usage.
 
 .. _flit-rationale: https://flit.readthedocs.io/en/latest/rationale.html

From 0b59fc4fa1d897c1d348d5d12eabf0673a0a8803 Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Mon, 6 Nov 2023 10:57:46 +0000
Subject: [PATCH 120/733] Use a ref to the twine index page

Co-authored-by: Sviatoslav Sydorenko 
---
 source/guides/packaging-binary-extensions.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst
index 0c6187c29..73f25fc03 100644
--- a/source/guides/packaging-binary-extensions.rst
+++ b/source/guides/packaging-binary-extensions.rst
@@ -361,7 +361,7 @@ Publishing binary extensions
 Publishing binary extensions through PyPI uses the same upload mechanisms as
 publishing pure Python packages. You build a wheel file for your extension
 using the build-backend and upload it to PyPI using
-`twine `_.
+:doc:`twine `.
 
 Avoid binary-only releases
 --------------------------

From f52d232186ec487fdf489c516d413a25637d4295 Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko 
Date: Mon, 16 Nov 2020 19:25:49 +0100
Subject: [PATCH 121/733] =?UTF-8?q?=F0=9F=92=84=20Change=20Sphinx=20theme?=
 =?UTF-8?q?=20to=20furo?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 requirements.txt     |   3 +--
 source/assets/py.png | Bin 0 -> 695 bytes
 source/conf.py       |  20 +++++++++-----------
 3 files changed, 10 insertions(+), 13 deletions(-)
 create mode 100644 source/assets/py.png

diff --git a/requirements.txt b/requirements.txt
index 6cdad44d2..077adb580 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,7 +1,6 @@
+furo==2023.9.10
 sphinx==7.2.6
 sphinx-autobuild==2021.3.14
 sphinx-inline-tabs==2023.4.21
-python-docs-theme==2023.9
 sphinx-copybutton==0.5.2
-pypa-docs-theme @ git+https://github.com/pypa/pypa-docs-theme.git
 sphinx-toolbox==3.5.0
diff --git a/source/assets/py.png b/source/assets/py.png
new file mode 100644
index 0000000000000000000000000000000000000000..93e4a02c3d321c545898a2ebb8873c26dd8a9e5b
GIT binary patch
literal 695
zcmV;o0!aOdP)Px#24YJ`L;(K){{a7>y{D4^000SaNLh0L01FcU01FcV0GgZ_00007bV*G`2iOD~
z5jY_RGbdgE00K8jL_t(I%Vm>KNL4`;hrfH@vv+$Uln|xSCTLTOHmzE;5FTwpDtJ)a
zz)exE-2_34AR^i+ZCXeh7m*-F5k*FrmbSHs%rX_!{PXUec{69`w(#D(>Vd<+%=bIz
zH_V)XUD5sE?K5ebbKaSDu}#Dnq^Y!3`tis9>wSO*T+WBP3wS3NNBU~*PAtw^yjZ+<
zQ5yK0z%d{y@_Pz6YdL>s7$6Y^hI$}5GUX?Ns>+iCUiRP
z7h|*&%kQa?wQA%pYzqpaf*4?WM!x_ygY0K@07rplx^QhGhnE)r4wbx0x11<&3V?63
z=F8ch)p6iQ88E;iumPmSZif%JIwIgKh$T3)*ab8ImGLVf;IoYtVAb11Z&@wm>96=S
z)!B&hojbAPoik&f)Lp;=N!HK;X~5oyfJ49$pbcorTyADv
dm$H!t;2#0MumAjv0Ga>*002ovPDHLkV1gIiH5UK?

literal 0
HcmV?d00001

diff --git a/source/conf.py b/source/conf.py
index c4d7a5ccc..a55343737 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -133,7 +133,7 @@
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+#pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -150,16 +150,14 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'pypa_theme'
+html_theme = 'furo'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-    'collapsiblesidebar': True,
-    'externalrefs': True,
-    'navigation_depth': 2,
-    'issues_url': github_repo_issues_url,
+    "sidebar_hide_name": True,
+    # 'issues_url': github_repo_issues_url,  # FIXME: support this in furo?
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -177,7 +175,7 @@
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
-# html_logo = None
+html_logo = 'assets/py.png'
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -211,10 +209,10 @@
 #
 
 # Custom sidebar templates, filenames relative to this file.
-html_sidebars = {
-    '**': ['globaltoc.html', 'relations.html'],
-    'index': ['globaltoc.html']
-}
+# html_sidebars = {
+#     '**': ['globaltoc.html', 'relations.html'],
+#     'index': ['globaltoc.html']
+# }
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

From 46c4d048c5beb789144618231df1a9f936128d36 Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri 
Date: Mon, 6 Nov 2023 17:22:32 +0000
Subject: [PATCH 122/733] Clarify that packages don't need __init__.py

But still recommend people that are getting started with Python
packaging to add them.
---
 source/tutorials/packaging-projects.rst | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 251280144..0a5212f77 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -54,8 +54,8 @@ Create the following file structure locally:
 The directory containing the Python files should match the project name. This
 simplifies the configuration and is more obvious to users who install the package.
 
-:file:`__init__.py` is required to import the directory as a package,
-even if as is our case for this tutorial that file is empty.
+:file:`__init__.py` is recommended to import the directory as a regular package,
+even if as is our case for this tutorial that file is empty [#namespace-packages]_.
 
 :file:`example.py` is an example of a module within the package that could
 contain the logic (functions, classes, constants, etc.) of your package.
@@ -535,3 +535,15 @@ some things you can do:
   :ref:`pdm`, and :ref:`poetry`.
 * Read :pep:`517` and :pep:`518` for background and details on build tool configuration.
 * Read about :doc:`/guides/packaging-binary-extensions`.
+
+
+----
+
+.. rubric:: Notes
+
+.. [#namespace-packages]
+   Technically, you can also create Python packages without an ``__init__.py`` file,
+   but those are called :doc:`namespace packages `
+   and considered an **advanced topic** (not covered in this tutorial).
+   If you are only getting started with Python packaging, it is recommended to
+   stick with *regular packages* and ``__init__.py`` (even if the file is empty).

From d1ca49bedc0c453b17d7d49f9e6f96b2e339d86e Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Mon, 6 Nov 2023 09:39:57 -0800
Subject: [PATCH 123/733] Add @chrysle correction

Co-authored-by: chrysle 
---
 source/guides/installing-using-pip-and-virtual-environments.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index cb54fe189..2544aa40a 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -38,7 +38,7 @@ Create a new virtual environment
 different projects. It creates a "virtual" isolated Python installation. When
 you switch projects, you can create a new virtual environment which is isolated
 from other virtual environments. You benefit from the virtual environment
-since packages can be installed confidently and will not interfere with the
+since packages can be installed confidently and will not interfere with
 another project's environment.
 
 .. tip::

From f1c623c35d4613489ce0853fe1891287cba8882c Mon Sep 17 00:00:00 2001
From: Aaron Holmes 
Date: Mon, 6 Nov 2023 10:40:18 -0800
Subject: [PATCH 124/733] Move exposure of github token to only the steps that
 need it.

---
 .../github-actions-ci-cd-sample/publish-to-test-pypi.yml   | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
index 02d1f8e84..72a3eb7b2 100644
--- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
+++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
@@ -61,9 +61,6 @@ jobs:
       contents: write  # IMPORTANT: mandatory for making GitHub Releases
       id-token: write  # IMPORTANT: mandatory for sigstore
 
-    env:
-      GITHUB_TOKEN: ${{ github.token }}
-
     steps:
     - name: Download all the dists
       uses: actions/download-artifact@v3
@@ -77,12 +74,16 @@ jobs:
           ./dist/*.tar.gz
           ./dist/*.whl
     - name: Create GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
       run: >-
         gh release create
         '${{ github.ref_name }}'
         --repo '${{ github.repository }}'
         --notes ""
     - name: Upload artifact signatures to GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
       # Upload to GitHub Release using the `gh` CLI.
       # `dist/` contains the built packages, and the
       # sigstore-produced signatures and certificates.

From cc78e34b90c1ead565e49968b12ed0d308456632 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Mon, 6 Nov 2023 20:42:37 +0100
Subject: [PATCH 125/733] Remove outcommented example of dynamic metadata

---
 source/guides/writing-pyproject-toml.rst | 2 --
 1 file changed, 2 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index af5c2fe18..8e28e305b 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -338,8 +338,6 @@ A full example
      "Programming Language :: Python"
    ]
 
-   # dynamic = ["version", "description"]
-
    [project.optional-dependencies]
    gui = ["PyQt5"]
    cli = [

From cccaa25bc216efd07ccd5940d4a27d630fb78150 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Mon, 6 Nov 2023 21:26:06 +0100
Subject: [PATCH 126/733] Remove contents directives

They're not useful with Furo, which has a right sidebar with the local
TOC, and they make it generate warnings in the rendered documentation.
---
 source/discussions/deploying-python-applications.rst     | 3 ---
 source/discussions/install-requires-vs-requirements.rst  | 3 ---
 source/guides/analyzing-pypi-package-downloads.rst       | 3 ---
 source/guides/distributing-packages-using-setuptools.rst | 2 --
 source/guides/index-mirrors-and-caches.rst               | 3 ---
 source/guides/installing-scientific-packages.rst         | 3 ---
 source/guides/installing-using-linux-tools.rst           | 3 ---
 source/guides/packaging-binary-extensions.rst            | 2 --
 source/guides/supporting-multiple-python-versions.rst    | 3 ---
 source/guides/supporting-windows-using-appveyor.rst      | 3 ---
 source/overview.rst                                      | 3 ---
 source/specifications/core-metadata.rst                  | 2 --
 source/specifications/direct-url-data-structure.rst      | 2 --
 source/specifications/direct-url.rst                     | 2 --
 source/tutorials/installing-packages.rst                 | 4 ----
 15 files changed, 41 deletions(-)

diff --git a/source/discussions/deploying-python-applications.rst b/source/discussions/deploying-python-applications.rst
index d9246d563..19ecd398e 100644
--- a/source/discussions/deploying-python-applications.rst
+++ b/source/discussions/deploying-python-applications.rst
@@ -6,9 +6,6 @@ Deploying Python applications
 :Page Status: Incomplete
 :Last Reviewed: 2021-8-24
 
-.. contents:: Contents
-   :local:
-
 
 Overview
 ========
diff --git a/source/discussions/install-requires-vs-requirements.rst b/source/discussions/install-requires-vs-requirements.rst
index 418785c9b..99e1552b8 100644
--- a/source/discussions/install-requires-vs-requirements.rst
+++ b/source/discussions/install-requires-vs-requirements.rst
@@ -4,9 +4,6 @@
 install_requires vs requirements files
 ======================================
 
-.. contents:: Contents
-   :local:
-
 
 install_requires
 ----------------
diff --git a/source/guides/analyzing-pypi-package-downloads.rst b/source/guides/analyzing-pypi-package-downloads.rst
index 5ee038587..4d2993479 100644
--- a/source/guides/analyzing-pypi-package-downloads.rst
+++ b/source/guides/analyzing-pypi-package-downloads.rst
@@ -7,9 +7,6 @@ to learn more about downloads of a package (or packages) hosted on PyPI. For
 example, you can use it to discover the distribution of Python versions used to
 download a package.
 
-.. contents:: Contents
-   :local:
-
 
 Background
 ==========
diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
index f860cad06..4b570e17b 100644
--- a/source/guides/distributing-packages-using-setuptools.rst
+++ b/source/guides/distributing-packages-using-setuptools.rst
@@ -19,8 +19,6 @@ Packages ` in the :ref:`setuptools` docs, but note
 that some advisory content there may be outdated. In the event of
 conflicts, prefer the advice in the Python Packaging User Guide.
 
-.. contents:: Contents
-   :local:
 
 
 Requirements for packaging and distributing
diff --git a/source/guides/index-mirrors-and-caches.rst b/source/guides/index-mirrors-and-caches.rst
index c186b64a9..9fdea0a1d 100644
--- a/source/guides/index-mirrors-and-caches.rst
+++ b/source/guides/index-mirrors-and-caches.rst
@@ -7,9 +7,6 @@ Package index mirrors and caches
 :Page Status: Incomplete
 :Last Reviewed: 2014-12-24
 
-.. contents:: Contents
-   :local:
-
 
 Mirroring or caching of PyPI can be used to speed up local package installation,
 allow offline work, handle corporate firewalls or just plain Internet flakiness.
diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst
index 404fed83b..5677d382a 100644
--- a/source/guides/installing-scientific-packages.rst
+++ b/source/guides/installing-scientific-packages.rst
@@ -4,9 +4,6 @@
 Installing scientific packages
 ==============================
 
-.. contents:: Contents
-   :local:
-
 
 Scientific software tends to have more complex dependencies than most, and
 it will often have multiple build options to take advantage of different
diff --git a/source/guides/installing-using-linux-tools.rst b/source/guides/installing-using-linux-tools.rst
index 8c1fd3f00..b3d37675f 100644
--- a/source/guides/installing-using-linux-tools.rst
+++ b/source/guides/installing-using-linux-tools.rst
@@ -7,9 +7,6 @@ Installing pip/setuptools/wheel with Linux Package Managers
 :Page Status: Incomplete
 :Last Reviewed: 2021-07-26
 
-.. contents:: Contents
-  :local:
-
 This section covers how to install :ref:`pip`, :ref:`setuptools`, and
 :ref:`wheel` using Linux package managers.
 
diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst
index 73f25fc03..589ed89c8 100644
--- a/source/guides/packaging-binary-extensions.rst
+++ b/source/guides/packaging-binary-extensions.rst
@@ -13,8 +13,6 @@ C API for use by other software. One of the most common uses of this C API
 is to create importable C extensions that allow things which aren't
 always easy to achieve in pure Python code.
 
-.. contents:: Contents
-   :local:
 
 An overview of binary extensions
 ================================
diff --git a/source/guides/supporting-multiple-python-versions.rst b/source/guides/supporting-multiple-python-versions.rst
index 0471a1f2f..8c128ed91 100644
--- a/source/guides/supporting-multiple-python-versions.rst
+++ b/source/guides/supporting-multiple-python-versions.rst
@@ -9,9 +9,6 @@ Supporting multiple Python versions
 :Page Status: Obsolete
 :Last Reviewed: 2014-12-24
 
-.. contents:: Contents
-   :local:
-
 
 ::
 
diff --git a/source/guides/supporting-windows-using-appveyor.rst b/source/guides/supporting-windows-using-appveyor.rst
index 1f43c443b..0044d8c5e 100644
--- a/source/guides/supporting-windows-using-appveyor.rst
+++ b/source/guides/supporting-windows-using-appveyor.rst
@@ -12,9 +12,6 @@ service to provide Windows support for your project. This includes testing
 the code on Windows, and building Windows-targeted binaries for projects
 that use C extensions.
 
-.. contents:: Contents
-   :local:
-
 
 Background
 ==========
diff --git a/source/overview.rst b/source/overview.rst
index 2f3f44007..0bd4393db 100644
--- a/source/overview.rst
+++ b/source/overview.rst
@@ -19,9 +19,6 @@ This overview provides a general-purpose decision tree for reasoning
 about Python's plethora of packaging options. Read on to choose the best
 technology for your next project.
 
-.. contents:: Contents
-   :local:
-
 Thinking about deployment
 -------------------------
 
diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index cefd68950..1099bb685 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -37,8 +37,6 @@ to a new format.
    more relaxed formatting rules even for metadata files that are nominally
    less than version 2.1.
 
-.. contents:: Contents
-   :local:
 
 .. _core-metadata-metadata-version:
 
diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index eae9d3071..fe1eae008 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -13,8 +13,6 @@ The representation of the components of this data structure as a :rfc:`1738` URL
 is not formally specified at time of writing. A common representation is the pip URL
 format. Other examples are provided in :pep:`440`.
 
-.. contents:: Contents
-   :local:
 
 Specification
 =============
diff --git a/source/specifications/direct-url.rst b/source/specifications/direct-url.rst
index aa9a48e9b..5c0bd1b21 100644
--- a/source/specifications/direct-url.rst
+++ b/source/specifications/direct-url.rst
@@ -10,8 +10,6 @@ This document specifies a :file:`direct_url.json` file in the
 Direct URL Origin of the distribution. The general structure and usage of
 ``*.dist-info`` directories is described in :ref:`recording-installed-packages`.
 
-.. contents:: Contents
-   :local:
 
 Specification
 =============
diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
index 46957f93b..4cfcf3f3e 100644
--- a/source/tutorials/installing-packages.rst
+++ b/source/tutorials/installing-packages.rst
@@ -18,10 +18,6 @@ confused with a Linux distribution, or another larger software distribution
 like Python itself.
 
 
-.. contents:: Contents
-   :local:
-
-
 .. _installing_requirements:
 
 Requirements for Installing Packages

From 1415c8dae4485dae3cc4bd434b8a36d81db838ed Mon Sep 17 00:00:00 2001
From: sinoroc 
Date: Thu, 2 Nov 2023 15:40:39 +0100
Subject: [PATCH 127/733] Add discussion "Is setup.py deprecated?"

---
 source/discussions/index.rst               |   1 +
 source/discussions/setup-py-deprecated.rst | 149 +++++++++++++++++++++
 2 files changed, 150 insertions(+)
 create mode 100644 source/discussions/setup-py-deprecated.rst

diff --git a/source/discussions/index.rst b/source/discussions/index.rst
index bc1154507..e5411ece3 100644
--- a/source/discussions/index.rst
+++ b/source/discussions/index.rst
@@ -13,3 +13,4 @@ specific topic. If you're just trying to get stuff done, see
    install-requires-vs-requirements
    wheel-vs-egg
    src-layout-vs-flat-layout
+   setup-py-deprecated
diff --git a/source/discussions/setup-py-deprecated.rst b/source/discussions/setup-py-deprecated.rst
new file mode 100644
index 000000000..29eac241d
--- /dev/null
+++ b/source/discussions/setup-py-deprecated.rst
@@ -0,0 +1,149 @@
+.. _setup-py-deprecated:
+
+
+===========================
+Is ``setup.py`` deprecated?
+===========================
+
+No, :term:`setup.py` is not deprecated,
+it is a valid configuration file for :ref:`setuptools`
+that happens to be written in Python, instead of in *TOML* for example
+(a similar practice is used by other tools
+like *nox* and its :file:`nox.py` configuration file,
+or *pytest* and :file:`conftest.py`).
+
+And of course *setuptools* itself is not deprecated either.
+
+It is however deprecated to run ``python setup.py`` as a command line tool.
+
+This means for example that the following commands **MUST NOT** be run anymore:
+
+* ``python setup.py install``
+* ``python setup.py develop``
+* ``python setup.py sdist``
+* ``python setup.py bdist_wheel``
+
+
+What commands should be used instead?
+=====================================
+
++---------------------------------+----------------------------------------+
+| Deprecated                      | Current recommendation                 |
++=================================+========================================+
+| ``python setup.py install``     | ``python -m pip install .``            |
++---------------------------------+----------------------------------------+
+| ``python setup.py develop``     | ``python -m pip install --editable .`` |
++---------------------------------+----------------------------------------+
+| ``python setup.py sdist``       | ``python -m build`` [#needs-build]_    |
++---------------------------------+                                        |
+| ``python setup.py bdist_wheel`` |                                        |
++---------------------------------+----------------------------------------+
+
+
+.. [#needs-build] This requires the :ref:`build` dependency.
+    It is recommended to always build and publish both the source distribution
+    and wheel of a project, which is what ``python -m build`` does.
+    If necessary the ``--sdist`` and ``--wheel`` options can be used
+    to generate only one or the other.
+
+
+In order to install a setuptools based project,
+it was common to run :file:`setup.py`'s ``install`` command such as:
+``python setup.py install``.
+Nowadays, the recommended method is to use :ref:`pip` directly
+with a command like this one: ``python -m pip install .``.
+Where the dot ``.`` is actually a file system path,
+it is the path notation for the current directory.
+Indeed, *pip* accepts a path to
+a project's source tree directory on the local filesystem
+as argument to its ``install`` sub-command.
+So this would also be a valid command:
+``python -m pip install path/to/project``.
+
+As for the installation in *develop* mode aka *editable* mode,
+instead of ``python setup.py develop``
+one can use the ``--editable`` option of pip's *install* sub-command:
+``python -m pip install --editable .``.
+
+One recommended, simple, and straightforward method of building
+:term:`source distributions `
+and :term:`wheels `
+is to use the :ref:`build` tool with a command like
+``python -m build``
+which triggers the generation of both distribution formats.
+If necessary the ``--sdist`` and ``--wheel`` options can be used
+to generate only one or the other.
+Note that the build tool needs to be installed separately.
+
+The command ``python setup.py install`` was deprecated
+in setuptools version *58.3.0*.
+
+
+What about custom commands?
+===========================
+
+Likewise, custom :file:`setup.py` commands are deprecated.
+The recommendation is to migrate those custom commands
+to a task runner tool or any other similar tool.
+Some examples of such tools are:
+chuy, make, nox or tox, pydoit, pyinvoke, taskipy, and thx.
+
+
+What about custom build steps?
+==============================
+
+Custom build steps that for example
+either overwrite existing steps such as ``build_py``, ``build_ext``, and ``bdist_wheel``
+or add new build steps are not deprecated.
+Those will be automatically called as expected.
+
+
+Should ``setup.py`` be deleted?
+===============================
+
+Although the usage of :file:`setup.py` as an executable script is deprecated,
+its usage as a configuration file for setuptools is absolutely fine.
+There is likely no modification needed in :file:`setup.py`.
+
+.. todo::
+
+    Link to a "How to modernize a setup.py based project?"
+
+
+Is ``pyproject.toml`` mandatory?
+================================
+
+While it is not technically necessary yet,
+it is **STRONGLY RECOMMENDED** for a project to have a :file:`pyproject.toml` file
+at the root of its source tree with a content like this:
+
+.. code:: toml
+
+    [build-system]
+    requires = ["setuptools"]
+    build-backend = "setuptools.build_meta"
+
+
+.. todo::
+
+    Link to "How to modernize a setup.py based project?"
+
+
+The standard fallback behavior for a :term:`build frontend `
+in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` table
+is to assume that the :term:`build backend ` is setuptools.
+
+
+Why? What does it all mean?
+===========================
+
+One way to look at it is that the scope of setuptools
+has now been reduced to the role of a build backend.
+
+
+Where to read more about this?
+==============================
+
+* https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html
+
+* :doc:`setuptools:deprecated/commands`

From b16b99a3f8595361aacd5341af12a18e6c057040 Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Mon, 6 Nov 2023 22:31:46 +0000
Subject: [PATCH 128/733] Use a favicon instead of a logo

---
 source/conf.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index a55343737..b3e4d1bd3 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -175,13 +175,13 @@
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
-html_logo = 'assets/py.png'
+# html_logo = None
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
 #
-# html_favicon = None
+html_favicon = 'assets/py.png'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

From 3d5a5ef36753d7bc609a2550c2300d965a8d1bdd Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 7 Nov 2023 19:40:53 +0100
Subject: [PATCH 129/733] Allow Sphinx to do incremental builds

Fixes #1363
---
 noxfile.py | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/noxfile.py b/noxfile.py
index b5d994701..b0ade2c49 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -33,10 +33,6 @@ def build(session, autobuild=False):
     """
     session.install("-r", "requirements.txt")
 
-    target_build_dir = "build"
-
-    shutil.rmtree(target_build_dir, ignore_errors=True)
-
     if autobuild:
         command = "sphinx-autobuild"
         extra_args = "--host", "0.0.0.0"
@@ -56,7 +52,7 @@ def build(session, autobuild=False):
         "-W",  # Treat warnings as errors.
         *session.posargs,
         "source",  # where the rst files are located
-        target_build_dir,  # where to put the html output
+        "build",  # where to put the html output
     )
 
 

From 5020425702336030ad7c4b975b7843d27f4ab7c1 Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Tue, 7 Nov 2023 21:35:18 +0000
Subject: [PATCH 130/733] Use a shared cache directory for Sphinx builds across
 nox sessions

This enables incremental build with Sphinx.
---
 noxfile.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/noxfile.py b/noxfile.py
index b5d994701..83f890262 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -4,8 +4,8 @@
 #   http://creativecommons.org/licenses/by-sa/3.0.
 
 import shutil
-import nox
 
+import nox
 
 nox.options.sessions = []
 
@@ -20,7 +20,7 @@ def translation(session):
     session.run(
         "sphinx-build",
         "-b", "gettext",  # build gettext-style message catalogs (.pot file)
-        "-d", ".nox/.doctrees/", # path to put the cache
+        "-d", session.cache_dir / ".doctrees", # path to put the cache
         "source/",  # where the rst files are located
         target_dir, # where to put the .pot file
     )
@@ -52,6 +52,7 @@ def build(session, autobuild=False):
         command, *extra_args,
         "-j", "auto",  # parallelize the build
         "-b", "html",  # use HTML builder
+        "-d", session.cache_dir / ".doctrees", # path to put the cache
         "-n",  # nitpicky warn about all missing references
         "-W",  # Treat warnings as errors.
         *session.posargs,
@@ -78,6 +79,7 @@ def linkcheck(session):
     session.run(
         "sphinx-build",
         "-b", "linkcheck", # use linkcheck builder
+        "-d", session.cache_dir / ".doctrees", # path to put the cache
         "--color",
         "-n", "-W", "--keep-going",  # be strict
         "source", # where the rst files are located

From 233bb5138e75acf180c19d20167e7c355ca1d47f Mon Sep 17 00:00:00 2001
From: Laurie O 
Date: Wed, 8 Nov 2023 15:32:18 +1000
Subject: [PATCH 131/733] Add more package index projects

---
 source/guides/hosting-your-own-index.rst   |  71 +++++++++++
 source/guides/index-mirrors-and-caches.rst | 118 +++++++++++++-----
 source/key_projects.rst                    | 135 ++++++++++++++++++++-
 3 files changed, 291 insertions(+), 33 deletions(-)

diff --git a/source/guides/hosting-your-own-index.rst b/source/guides/hosting-your-own-index.rst
index 26ffe2b8c..f469c2a2e 100644
--- a/source/guides/hosting-your-own-index.rst
+++ b/source/guides/hosting-your-own-index.rst
@@ -52,10 +52,81 @@ directory with autoindex enabled. For an example using the built in Web server
 in `Twisted`_, you would simply run ``twistd -n web --path .`` and then
 instruct users to add the URL to their installer's configuration.
 
+
+Existing projects
+=================
+
+.. list-table::
+   :header-rows: 1
+
+   * - Project
+     - Package upload
+     - PyPI fall-through [2]_
+     - Additional notes
+
+   * - :ref:`devpi`
+     - ✔
+     - ✔
+     - multiple indexes with inheritance, with syncing, replication, fail-over;
+       mirroring
+
+   * - :ref:`simpleindex`
+     -
+     - ✔
+     -
+
+   * - :ref:`pypiserver`
+     - ✔
+     -
+     -
+
+   * - :ref:`pypiprivate`
+     -
+     -
+     -
+
+   * - :ref:`pypicloud`
+     -
+     -
+     - unmaintained; also cached proxying; authentication, authorisation
+
+   * - :ref:`pywharf`
+     -
+     -
+     - unmaintained; serve files in GitHub
+
+   * - :ref:`pulppython`
+     - ✔
+     -
+     - also mirroring, proxying; plugin for Pulp
+
+   * - :ref:`pip2pi`
+     -
+     -
+     - also mirroring; manual synchronisation
+
+   * - :ref:`httpserver`
+     -
+     -
+     - standard-library
+
+   * - `Apache `_
+     -
+     - ✔
+     - using
+       `mod_rewrite
+       `_
+       and
+       `mod_cache_disk
+       `_,
+       you can cache requests to package indexes through an Apache server
+
 ----
 
 .. [1] For complete documentation of the simple repository protocol, see
        :ref:`simple repository API `.
 
+.. [2] Can be configured to fall-back to PyPI (or another package index)
+       if a requested package is missing.
 
 .. _Twisted: https://twistedmatrix.com/
diff --git a/source/guides/index-mirrors-and-caches.rst b/source/guides/index-mirrors-and-caches.rst
index 9fdea0a1d..f3b7bd243 100644
--- a/source/guides/index-mirrors-and-caches.rst
+++ b/source/guides/index-mirrors-and-caches.rst
@@ -5,19 +5,24 @@ Package index mirrors and caches
 ================================
 
 :Page Status: Incomplete
-:Last Reviewed: 2014-12-24
+:Last Reviewed: 2023-11-08
 
-
-Mirroring or caching of PyPI can be used to speed up local package installation,
+Mirroring or caching of PyPI (and other
+:term:`package indexes `) can be used to speed up local
+package installation,
 allow offline work, handle corporate firewalls or just plain Internet flakiness.
 
-Three options are available in this area:
+There are multiple classes of options in this area:
+
+1. local/hosted caching of package indexes.
+
+2. local/hosted mirroring of a package index. A mirror is a (whole or
+   partial) copy of a package index, which can be used in place of the
+   original index.
 
-1. pip provides local caching options,
-2. devpi provides higher-level caching option, potentially shared amongst
-   many users or machines, and
-3. bandersnatch provides a local complete mirror of all PyPI :term:`packages
-   `.
+3. private package index with fall-through to public package indexes (for
+   example, to mitigate dependency confusion attacks), also known as a
+   proxy.
 
 
 Caching with pip
@@ -38,26 +43,75 @@ cached copies of :term:`packages `:
       python3 -m pip install --no-index --find-links=/tmp/wheelhouse SomeProject
 
 
-Caching with devpi
-------------------
-
-devpi is a caching proxy server which you run on your laptop, or some other
-machine you know will always be available to you. See the `devpi
-documentation for getting started`__.
-
-__ https://devpi.net/docs/devpi/devpi/latest/+d/quickstart-pypimirror.html
-
-
-Complete mirror with bandersnatch
-----------------------------------
-
-bandersnatch will set up a complete local mirror of all PyPI :term:`packages
-` (externally-hosted packages are not mirrored). See
-the `bandersnatch documentation for getting that going`__.
-
-__ https://github.com/pypa/bandersnatch/
-
-A benefit of devpi is that it will create a mirror which includes
-:term:`packages ` that are external to PyPI, unlike
-bandersnatch which will only cache :term:`packages `
-hosted on PyPI.
+Existing projects
+-----------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Project
+     - Cache
+     - Mirror
+     - Proxy
+     - Additional notes
+
+   * - :ref:`devpi`
+     - ✔
+     - ✔
+     -
+     - multiple indexes with inheritance; syncing, replication, fail-over;
+       package upload
+
+   * - :ref:`bandersnatch`
+     - ✔
+     - ✔
+     -
+     -
+
+   * - :ref:`simpleindex`
+     -
+     -
+     - ✔
+     - custom plugin enables caching; re-routing to other package indexes
+
+   * - :ref:`pypicloud`
+     - ✔
+     -
+     - ✔
+     - unmaintained; authentication, authorisation
+
+   * - :ref:`pulppython`
+     -
+     - ✔
+     - ✔
+     - plugin for Pulp; multiple proxied indexes; package upload
+
+   * - :ref:`proxpi`
+     - ✔
+     -
+     - ✔
+     - multiple proxied indexes
+
+   * - :ref:`nginx_pypi_cache`
+     - ✔
+     -
+     - ✔
+     - multiple proxied indexes
+
+   * - :ref:`flaskpypiproxy`
+     - ✔
+     -
+     - ✔
+     - unmaintained
+
+   * - `Apache `_
+     - ✔
+     -
+     - ✔
+     - using
+       `mod_rewrite
+       `_
+       and
+       `mod_cache_disk
+       `_,
+       you can cache requests to package indexes through an Apache server
diff --git a/source/key_projects.rst b/source/key_projects.rst
index ea5730683..b386a8f2d 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -18,6 +18,7 @@ PyPA Projects
 bandersnatch
 ============
 
+`Docs `__ |
 `Issues `__ |
 `GitHub `__ |
 `PyPI `__
@@ -27,6 +28,7 @@ create a complete mirror of the contents of PyPI. Organizations thus
 save bandwidth and latency on package downloads (especially in the
 context of automated tests) and to prevent heavily loading PyPI's
 Content Delivery Network (CDN).
+Files can be served from a local directory or `AWS S3`_.
 
 
 .. _build:
@@ -442,6 +444,9 @@ devpi features a powerful PyPI-compatible server and PyPI proxy cache
 with a complementary command line tool to drive packaging, testing and
 release activities with Python. devpi also provides a browsable and
 searchable web interface.
+devpi supports mirroring PyPI, multiple
+:term:`package indexes ` with inheritance, syncing between
+these indexes, index replication and fail-over, and package upload.
 
 .. _enscons:
 
@@ -464,6 +469,20 @@ enscons.
 
 .. _SCons: https://scons.org/
 
+.. _flaskpypiproxy:
+
+Flask-Pypi-Proxy
+================
+
+`Docs `__ |
+:gh:`GitHub ` |
+`PyPI `__
+
+.. warning:: Not maintained, project archived
+
+Flask-Pypi-Proxy is a :term:`package index ` as a cached
+proxy for PyPI.
+
 .. _hashdist:
 
 Hashdist
@@ -519,6 +538,16 @@ multibuild
 Multibuild is a set of CI scripts for building and testing Python :term:`wheels ` for
 Linux, macOS, and (less flexibly) Windows. Also see :ref:`cibuildwheel`.
 
+.. _nginx_pypi_cache:
+
+nginx_pypi_cache
+================
+
+:gh:`GitHub `
+
+nginx_pypi_cache is a :term:`package index ` caching proxy
+using `nginx `_.
+
 .. _pdm:
 
 pdm
@@ -564,6 +593,17 @@ requirements from information in other parts of their program, update
 all dependencies (a feature :ref:`pip` currently does not provide), and
 create layers of constraints for the program to obey.
 
+.. _pip2pi:
+
+pip2pi
+=========
+
+:gh:`GitHub ` |
+`PyPI `__
+
+pip2pi is a :term:`package index ` server where specific
+packages are manually synchronised.
+
 .. _piwheels:
 
 piwheels
@@ -595,6 +635,58 @@ functionality within :ref:`pip`, provides its own dependency resolver.
 It attempts to speed users' experience of installation and dependency
 resolution by locally caching metadata about dependencies.
 
+.. _proxpi:
+
+proxpi
+======
+
+:gh:`GitHub ` |
+`PyPI `__
+
+proxpi is a simple :term:`package index ` which proxies PyPI
+and other indexes with caching.
+
+.. _pulppython:
+
+Pulp-python
+===========
+
+`Docs `__ |
+:gh:`GitHub ` |
+`PyPI `__
+
+Pulp-python is the Python :term:`package index ` plugin for
+`Pulp `_. Pulp-python supports mirrors backed by
+local or `AWS S3`_, package upload, and proxying to multiple package
+indexes.
+
+.. _pypicloud:
+
+PyPI Cloud
+==========
+
+`Docs `__ |
+:gh:`GitHub ` |
+`PyPI `__
+
+.. warning:: Not maintained, project archived
+
+PyPI Cloud is a :term:`package index ` server, backed by
+`AWS S3`_ or another cloud storage service, or local files. PyPI Cloud
+supports redirect/cached proxying for PyPI, as well as authentication and
+authorisation.
+
+.. _pypiprivate:
+
+pypiprivate
+===========
+
+:gh:`GitHub ` |
+`PyPI `__
+
+pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as a
+:term:`package index `.
+
 .. _pypiserver:
 
 pypiserver
@@ -604,7 +696,8 @@ pypiserver
 `PyPI `__
 
 pypiserver is a minimalist application that serves as a private Python
-package index within organizations, implementing a simple API and
+:term:`package index ` (from a local directory) within
+organizations, implementing a simple API and
 browser interface. You can upload private packages using standard
 upload tools, and users can download and install them with :ref:`pip`,
 without publishing them publicly. Organizations who use pypiserver
@@ -627,6 +720,18 @@ environment so developers can start coding right away.
 PyScaffold can also be used with existing projects to make packaging
 easier.
 
+.. _pywharf:
+
+pywharf
+=======
+
+:gh:`GitHub ` |
+`PyPI `__
+
+.. warning:: Not maintained, project archived
+
+pywharf is a :term:`package index ` server, serving files
+locally or from `GitHub `_.
 
 .. _scikit-build:
 
@@ -675,6 +780,19 @@ Python zipapps as outlined in :pep:`441`, but with all their
 dependencies included. Its primary goal is making distributing Python
 applications and command line tools fast & easy.
 
+.. _simpleindex:
+
+simpleindex
+===========
+
+:gh:`GitHub ` |
+`PyPI `__
+
+simpleindex is a :term:`package index ` which routes URLs to
+multiple package indexes (including PyPI), serves local (or cloud-hosted,
+for example `AWS S3`_, with a custom plugin) directory of packages, and
+supports custom plugins.
+
 .. _spack:
 
 Spack
@@ -727,6 +845,20 @@ A package in the Python Standard Library that provides support for bootstrapping
 cases, end users won't use this module, but rather it will be used during the
 build of the Python distribution.
 
+.. _httpserver:
+
+http.server
+===========
+
+`Docs `__ |
+`Issues `__
+
+A package and command-line interface which can host a directory as a
+website, for example as a :term:`package index ` (see
+:ref:`Hosting your Own Simple Repository`).
+A package in the Python Standard Library (starting with Python 3.3) for
+creating :term:`Virtual Environments `.  For more
+information, see the section on :ref:`Creating and using Virtual Environments`.
 
 .. _venv:
 
@@ -746,3 +878,4 @@ information, see the section on :ref:`Creating and using Virtual Environments`.
 .. _distribute: https://pypi.org/project/distribute
 .. _Sphinx: https://www.sphinx-doc.org/en/master/
 .. _pytest: https://docs.pytest.org/en/stable/
+.. _`AWS S3`: https://aws.amazon.com/s3/

From 1afb5966a89cc8817117507f1bc0f76f9b3332ba Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Mon, 6 Nov 2023 22:34:28 +0000
Subject: [PATCH 132/733] Bump pre-commit-hooks

---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 4c70a3f63..b517864da 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.4.0
+  rev: v4.5.0
   hooks:
   - id: check-added-large-files
   - id: check-case-conflict

From 07a8f01521ed1e4938eb5e62a4457f503d92f1b3 Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Wed, 8 Nov 2023 18:21:54 +0000
Subject: [PATCH 133/733] Add ruff as a linter

---
 .pre-commit-config.yaml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index b517864da..88494c690 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -31,3 +31,9 @@ repos:
   - id: rst-backticks
   - id: rst-directive-colons
   - id: rst-inline-touching-normal
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.1.4
+  hooks:
+    - id: ruff
+    - id: ruff-format

From 1d7b1abd152e4cb5e6a46e52e6b7e3bf8d366486 Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Wed, 8 Nov 2023 18:22:03 +0000
Subject: [PATCH 134/733] Reformat Python code with ruff

---
 noxfile.py     |  35 +++++----
 source/conf.py | 193 +++++++++++++++++++++++++------------------------
 2 files changed, 122 insertions(+), 106 deletions(-)

diff --git a/noxfile.py b/noxfile.py
index 23dcb977f..698e82f9d 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -3,7 +3,6 @@
 # Attribution-ShareAlike license:
 #   http://creativecommons.org/licenses/by-sa/3.0.
 
-import shutil
 
 import nox
 
@@ -19,10 +18,12 @@ def translation(session):
     target_dir = "locales"
     session.run(
         "sphinx-build",
-        "-b", "gettext",  # build gettext-style message catalogs (.pot file)
-        "-d", session.cache_dir / ".doctrees", # path to put the cache
+        "-b",
+        "gettext",  # build gettext-style message catalogs (.pot file)
+        "-d",
+        session.cache_dir / ".doctrees",  # path to put the cache
         "source/",  # where the rst files are located
-        target_dir, # where to put the .pot file
+        target_dir,  # where to put the .pot file
     )
 
 
@@ -45,10 +46,14 @@ def build(session, autobuild=False):
         )
 
     session.run(
-        command, *extra_args,
-        "-j", "auto",  # parallelize the build
-        "-b", "html",  # use HTML builder
-        "-d", session.cache_dir / ".doctrees", # path to put the cache
+        command,
+        *extra_args,
+        "-j",
+        "auto",  # parallelize the build
+        "-b",
+        "html",  # use HTML builder
+        "-d",
+        session.cache_dir / ".doctrees",  # path to put the cache
         "-n",  # nitpicky warn about all missing references
         "-W",  # Treat warnings as errors.
         *session.posargs,
@@ -74,12 +79,16 @@ def linkcheck(session):
     session.install("-r", "requirements.txt")
     session.run(
         "sphinx-build",
-        "-b", "linkcheck", # use linkcheck builder
-        "-d", session.cache_dir / ".doctrees", # path to put the cache
+        "-b",
+        "linkcheck",  # use linkcheck builder
+        "-d",
+        session.cache_dir / ".doctrees",  # path to put the cache
         "--color",
-        "-n", "-W", "--keep-going",  # be strict
-        "source", # where the rst files are located
-        "build", # where to put the check output
+        "-n",
+        "-W",
+        "--keep-going",  # be strict
+        "source",  # where the rst files are located
+        "build",  # where to put the check output
     )
 
 
diff --git a/source/conf.py b/source/conf.py
index b3e4d1bd3..64b99d0b2 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -31,12 +31,12 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.extlinks',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.todo',
-    'sphinx_inline_tabs',
-    'sphinx_copybutton',
-    'sphinx_toolbox.collapse',
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx_inline_tabs",
+    "sphinx_copybutton",
+    "sphinx_toolbox.collapse",
 ]
 
 # config for copy button
@@ -44,53 +44,53 @@
 copybutton_prompt_is_regexp = True
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The encoding of source files.
 #
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # -- Project information -----------------------------------------------------
 
-github_url = 'https://github.com'
-github_repo_org = 'pypa'
-github_repo_name = 'packaging.python.org'
-github_repo_slug = f'{github_repo_org}/{github_repo_name}'
-github_repo_url = f'{github_url}/{github_repo_slug}'
-github_repo_issues_url = f'{github_url}/{github_repo_slug}/issues'
-github_sponsors_url = f'{github_url}/sponsors'
+github_url = "https://github.com"
+github_repo_org = "pypa"
+github_repo_name = "packaging.python.org"
+github_repo_slug = f"{github_repo_org}/{github_repo_name}"
+github_repo_url = f"{github_url}/{github_repo_slug}"
+github_repo_issues_url = f"{github_url}/{github_repo_slug}/issues"
+github_sponsors_url = f"{github_url}/sponsors"
 
 # General information about the project.
-project = u'Python Packaging User Guide'
-copyright = u'2013–2020, PyPA'
-author = 'Python Packaging Authority'
+project = "Python Packaging User Guide"
+copyright = "2013–2020, PyPA"
+author = "Python Packaging Authority"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = ''
+version = ""
 # The full version, including alpha/beta/rc tags.
-release = ''
+release = ""
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = 'en'
+language = "en"
 
-locale_dirs = ['../locales']
+locale_dirs = ["../locales"]
 
 gettext_auto_build = True  # Build MO files from PO on each build
 
@@ -111,12 +111,12 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
 # Ref: python-attrs/attrs#571
-default_role = 'any'  # makes single backticks autofind targets
+default_role = "any"  # makes single backticks autofind targets
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #
@@ -133,7 +133,7 @@
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-#pygments_style = 'sphinx'
+# pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -150,7 +150,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'furo'
+html_theme = "furo"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -166,7 +166,7 @@
 # The name for this set of Sphinx documents.
 # " v documentation" by default.
 #
-html_title = 'Python Packaging User Guide'
+html_title = "Python Packaging User Guide"
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #
@@ -181,7 +181,7 @@
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
 #
-html_favicon = 'assets/py.png'
+html_favicon = "assets/py.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -198,7 +198,7 @@
 # bottom, using the given strftime format.
 # The empty string is equivalent to '%b %d, %Y'.
 #
-html_last_updated_fmt = ''
+html_last_updated_fmt = ""
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -271,34 +271,36 @@
 # html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'pythonpackagingguide-authdoc'
+htmlhelp_basename = "pythonpackagingguide-authdoc"
 
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-     # The paper size ('letterpaper' or 'a4paper').
-     #
-     # 'papersize': 'letterpaper',
-
-     # The font size ('10pt', '11pt' or '12pt').
-     #
-     # 'pointsize': '10pt',
-
-     # Additional stuff for the LaTeX preamble.
-     #
-     # 'preamble': '',
-
-     # Latex figure (float) alignment
-     #
-     # 'figure_align': 'htbp',
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'pythonpackagingguide.tex', 'Python Packaging User Guide',
-     'Python Packaging Authority', 'manual'),
+    (
+        master_doc,
+        "pythonpackagingguide.tex",
+        "Python Packaging User Guide",
+        "Python Packaging Authority",
+        "manual",
+    ),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -339,8 +341,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'pythonpackagingguide', 'Python Packaging User Guide',
-     [author], 1)
+    (master_doc, "pythonpackagingguide", "Python Packaging User Guide", [author], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -354,9 +355,15 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'pythonpackagingguide', 'Python Packaging User Guide',
-     author, 'pythonpackagingguide', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "pythonpackagingguide",
+        "Python Packaging User Guide",
+        author,
+        "pythonpackagingguide",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -377,11 +384,11 @@
 
 # -- Options for extlinks extension ---------------------------------------
 extlinks = {
-    'issue': (f'{github_repo_issues_url}/%s', '#%s'),  # noqa: WPS323
-    'pr': (f'{github_repo_url}/pull/%s', 'PR #%s'),  # noqa: WPS323
-    'commit': (f'{github_repo_url}/commit/%s', '%s'),  # noqa: WPS323
-    'gh': (f'{github_url}/%s', 'GitHub: %s'),  # noqa: WPS323
-    'user': (f'{github_sponsors_url}/%s', '@%s'),  # noqa: WPS323
+    "issue": (f"{github_repo_issues_url}/%s", "#%s"),  # noqa: WPS323
+    "pr": (f"{github_repo_url}/pull/%s", "PR #%s"),  # noqa: WPS323
+    "commit": (f"{github_repo_url}/commit/%s", "%s"),  # noqa: WPS323
+    "gh": (f"{github_url}/%s", "GitHub: %s"),  # noqa: WPS323
+    "user": (f"{github_sponsors_url}/%s", "@%s"),  # noqa: WPS323
 }
 
 linkcheck_ignore = [
@@ -395,33 +402,33 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'boltons': ('https://boltons.readthedocs.io/en/latest/', None),
-    'bottle': ('https://bottlepy.org/docs/dev/', None),
-    'build': ('https://pypa-build.readthedocs.io/en/stable/', None),
-    'cffi': ('https://cffi.readthedocs.io/en/latest/', None),
-    'conda': ('https://conda.io/en/latest/', None),
-    'devpi': ('https://devpi.net/docs/devpi/devpi/latest/+doc', None),
-    'dh-virtualenv': ('https://dh-virtualenv.readthedocs.io/en/latest/', None),
-    'distlib': ('https://distlib.readthedocs.io/en/latest/', None),
-    'flexx': ('https://flexx.readthedocs.io/en/latest/', None),
-    'nox': ('https://nox.thea.codes/en/latest/', None),
-    'openstack': ('https://docs.openstack.org/glance/latest/', None),
-    'packaging': ('https://packaging.pypa.io/en/latest/', None),
-    'packaging.python.org': ('https://packaging.python.org/en/latest/', None),
-    'pip': ('https://pip.pypa.io/en/latest/', None),
-    'pipenv': ('https://pipenv.pypa.io/en/latest/', None),
-    'piwheels': ('https://piwheels.readthedocs.io/en/latest/', None),
-    'pybind11': ('https://pybind11.readthedocs.io/en/stable/', None),
-    'pynsist': ('https://pynsist.readthedocs.io/en/latest/', None),
-    'pypa': ('https://www.pypa.io/en/latest/', None),
-    'python': ('https://docs.python.org/3', None),
-    'python-guide': ('https://docs.python-guide.org', None),
-    'setuptools': ('https://setuptools.pypa.io/en/latest/', None),
-    'spack': ('https://spack.readthedocs.io/en/latest/', None),
-    'sphinx': ('https://www.sphinx-doc.org/en/master', None),
-    'tox': ('https://tox.wiki/en/latest/', None),
-    'twine': ('https://twine.readthedocs.io/en/stable/', None),
-    'virtualenv': ('https://virtualenv.pypa.io/en/stable/', None),
+    "boltons": ("https://boltons.readthedocs.io/en/latest/", None),
+    "bottle": ("https://bottlepy.org/docs/dev/", None),
+    "build": ("https://pypa-build.readthedocs.io/en/stable/", None),
+    "cffi": ("https://cffi.readthedocs.io/en/latest/", None),
+    "conda": ("https://conda.io/en/latest/", None),
+    "devpi": ("https://devpi.net/docs/devpi/devpi/latest/+doc", None),
+    "dh-virtualenv": ("https://dh-virtualenv.readthedocs.io/en/latest/", None),
+    "distlib": ("https://distlib.readthedocs.io/en/latest/", None),
+    "flexx": ("https://flexx.readthedocs.io/en/latest/", None),
+    "nox": ("https://nox.thea.codes/en/latest/", None),
+    "openstack": ("https://docs.openstack.org/glance/latest/", None),
+    "packaging": ("https://packaging.pypa.io/en/latest/", None),
+    "packaging.python.org": ("https://packaging.python.org/en/latest/", None),
+    "pip": ("https://pip.pypa.io/en/latest/", None),
+    "pipenv": ("https://pipenv.pypa.io/en/latest/", None),
+    "piwheels": ("https://piwheels.readthedocs.io/en/latest/", None),
+    "pybind11": ("https://pybind11.readthedocs.io/en/stable/", None),
+    "pynsist": ("https://pynsist.readthedocs.io/en/latest/", None),
+    "pypa": ("https://www.pypa.io/en/latest/", None),
+    "python": ("https://docs.python.org/3", None),
+    "python-guide": ("https://docs.python-guide.org", None),
+    "setuptools": ("https://setuptools.pypa.io/en/latest/", None),
+    "spack": ("https://spack.readthedocs.io/en/latest/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
+    "tox": ("https://tox.wiki/en/latest/", None),
+    "twine": ("https://twine.readthedocs.io/en/stable/", None),
+    "virtualenv": ("https://virtualenv.pypa.io/en/stable/", None),
 }
 
 
@@ -435,12 +442,12 @@
 # NOTE: consider having a separate ignore file
 # Ref: https://stackoverflow.com/a/30624034/595220
 nitpick_ignore = [
-    ('envvar', 'PATH'),
-    ('py:func', 'find_packages'),
-    ('py:func', 'setup'),
-    ('py:func', 'importlib.metadata.entry_points'),  # remove when 3.10 is released
-    ('py:class', 'importlib.metadata.EntryPoint'),  # remove when 3.10 is released
-    ('py:func', 'setuptools.find_namespace_packages'),
-    ('py:func', 'setuptools.find_packages'),
-    ('py:func', 'setuptools.setup'),
+    ("envvar", "PATH"),
+    ("py:func", "find_packages"),
+    ("py:func", "setup"),
+    ("py:func", "importlib.metadata.entry_points"),  # remove when 3.10 is released
+    ("py:class", "importlib.metadata.EntryPoint"),  # remove when 3.10 is released
+    ("py:func", "setuptools.find_namespace_packages"),
+    ("py:func", "setuptools.find_packages"),
+    ("py:func", "setuptools.setup"),
 ]

From b3057119c8a9d82f18fc506973ddcdccae36e8ea Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Wed, 8 Nov 2023 18:22:55 +0000
Subject: [PATCH 135/733] Ignore the ruff reformatting change

---
 .git-blame-ignore-revs | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 .git-blame-ignore-revs

diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
new file mode 100644
index 000000000..6b26875f1
--- /dev/null
+++ b/.git-blame-ignore-revs
@@ -0,0 +1 @@
+1d7b1abd152e4cb5e6a46e52e6b7e3bf8d366486

From 40b0a8f357c6a71fa1e286cd9ce214e578b3630e Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Mon, 6 Nov 2023 23:02:11 +0000
Subject: [PATCH 136/733] Modernise the conf.py file

This follows the style of the Sphinx 5+ configuration file template,
removing commented out sections and content duplicated from the
documentation.

This also removes a few unused values and uses the newer `root_doc`
name.
---
 source/conf.py | 431 +++++++++----------------------------------------
 1 file changed, 76 insertions(+), 355 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index 64b99d0b2..35eb7ee4c 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -1,35 +1,16 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
-# The Python Packaging Guide documentation build configuration file, created by
-# sphinx-quickstart on Sun Dec 13 14:07:23 2009.
-#
-# This file is execfile()d with the current directory set to its containing
-# dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-# -- General configuration ------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
+# -- Project information ---------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Python Packaging User Guide"
+
+copyright = "2013–2020, PyPA"
+author = "Python Packaging Authority"
+
+# -- General configuration -------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+root_doc = "index"
+
 extensions = [
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
@@ -39,263 +20,57 @@
     "sphinx_toolbox.collapse",
 ]
 
-# config for copy button
-copybutton_prompt_text = r">>> |\.\.\. |\$ |> "
-copybutton_prompt_is_regexp = True
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
-
-# The encoding of source files.
-#
-# source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = "index"
-
-# -- Project information -----------------------------------------------------
+nitpicky = True
+nitpick_ignore = [
+    ("envvar", "PATH"),
+    ("py:func", "find_packages"),
+    ("py:func", "setup"),
+    ("py:func", "importlib.metadata.entry_points"),
+    ("py:class", "importlib.metadata.EntryPoint"),
+    ("py:func", "setuptools.find_namespace_packages"),
+    ("py:func", "setuptools.find_packages"),
+    ("py:func", "setuptools.setup"),
+]
 
-github_url = "https://github.com"
-github_repo_org = "pypa"
-github_repo_name = "packaging.python.org"
-github_repo_slug = f"{github_repo_org}/{github_repo_name}"
-github_repo_url = f"{github_url}/{github_repo_slug}"
-github_repo_issues_url = f"{github_url}/{github_repo_slug}/issues"
-github_sponsors_url = f"{github_url}/sponsors"
+default_role = "any"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-# General information about the project.
-project = "Python Packaging User Guide"
-copyright = "2013–2020, PyPA"
-author = "Python Packaging Authority"
+# -- Options for internationalization --------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-internationalization
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = ""
-# The full version, including alpha/beta/rc tags.
-release = ""
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
 language = "en"
 
 locale_dirs = ["../locales"]
 
-gettext_auto_build = True  # Build MO files from PO on each build
-
-# making all documents use single text domain
+gettext_auto_build = True
 gettext_compact = "messages"
+gettext_location = True
 
-gettext_location = True  # Include location info in the translation files
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#
-# today = ''
-#
-# Else, today_fmt is used as the format for a strftime call.
-#
-# today_fmt = '%B %d, %Y'
+# -- Options for HTML output -----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-# Ref: python-attrs/attrs#571
-default_role = "any"  # makes single backticks autofind targets
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#
-# add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#
-# add_module_names = False
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#
-# show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-# pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-# modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-# keep_warnings = False
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-# todo_include_todos = False
-
-
-# -- Options for HTML output ----------------------------------------------
+html_title = "Python Packaging User Guide"
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
 html_theme = "furo"
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
 html_theme_options = {
     "sidebar_hide_name": True,
-    # 'issues_url': github_repo_issues_url,  # FIXME: support this in furo?
 }
 
-# Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = ['themes']
-
-# The name for this set of Sphinx documents.
-# " v documentation" by default.
-#
-html_title = "Python Packaging User Guide"
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#
-# html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#
-# html_logo = None
-
-# The name of an image file (relative to this directory) to use as a favicon of
-# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#
 html_favicon = "assets/py.png"
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
-
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-#
-# html_extra_path = []
-
-# If not None, a 'Last updated on:' timestamp is inserted at every page
-# bottom, using the given strftime format.
-# The empty string is equivalent to '%b %d, %Y'.
-#
 html_last_updated_fmt = ""
 
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#
-# html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#
-
-# Custom sidebar templates, filenames relative to this file.
-# html_sidebars = {
-#     '**': ['globaltoc.html', 'relations.html'],
-#     'index': ['globaltoc.html']
-# }
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#
-# html_additional_pages = {}
-
-# If false, no module index is generated.
-#
-# html_domain_indices = True
-
-# If false, no index is generated.
-#
-# html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#
-# html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#
-# html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#
-# html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#
-# html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a  tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#
-# html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-# html_file_suffix = None
-
-# Language to be used for generating the HTML full-text search index.
-# Sphinx supports the following languages:
-#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
-#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh'
-#
-# html_search_language = 'en'
-
-# A dictionary with options for the search language support, empty by default.
-# 'ja' uses this config value.
-# 'zh' user can custom change `jieba` dictionary path.
-#
-# html_search_options = {'type': 'default'}
-
-# The name of a javascript file (relative to the configuration directory) that
-# implements a search results scorer. If empty, the default will be used.
-#
-# html_search_scorer = 'scorer.js'
-
-# Output file base name for HTML help builder.
+# -- Options for HTML help output ------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-help-output
+
 htmlhelp_basename = "pythonpackagingguide-authdoc"
 
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
+# -- Options for LaTeX output ----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-latex-output
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
+latex_elements = {}
 latex_documents = [
     (
-        master_doc,
+        root_doc,
         "pythonpackagingguide.tex",
         "Python Packaging User Guide",
         "Python Packaging Authority",
@@ -303,60 +78,19 @@
     ),
 ]
 
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#
-# latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#
-# latex_use_parts = False
-
-# If true, show page references after internal links.
-#
-# latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#
-# latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#
-# latex_appendices = []
-
-# It false, will not define \strong, \code,     itleref, \crossref ... but only
-# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
-# packages.
-#
-# latex_keep_old_macro_names = True
+# -- Options for manual page output ----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-manual-page-output
 
-# If false, no module index is generated.
-#
-# latex_domain_indices = True
-
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, "pythonpackagingguide", "Python Packaging User Guide", [author], 1)
+    (root_doc, "pythonpackagingguide", "Python Packaging User Guide", [author], 1)
 ]
 
-# If true, show URL addresses after external links.
-#
-# man_show_urls = False
+# -- Options for Texinfo output --------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-texinfo-output
 
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
 texinfo_documents = [
     (
-        master_doc,
+        root_doc,
         "pythonpackagingguide",
         "Python Packaging User Guide",
         author,
@@ -366,41 +100,38 @@
     ),
 ]
 
-# Documents to append as an appendix to all manuals.
-#
-# texinfo_appendices = []
-
-# If false, no module index is generated.
-#
-# texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#
-# texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#
-# texinfo_no_detailmenu = False
-
-# -- Options for extlinks extension ---------------------------------------
-extlinks = {
-    "issue": (f"{github_repo_issues_url}/%s", "#%s"),  # noqa: WPS323
-    "pr": (f"{github_repo_url}/pull/%s", "PR #%s"),  # noqa: WPS323
-    "commit": (f"{github_repo_url}/commit/%s", "%s"),  # noqa: WPS323
-    "gh": (f"{github_url}/%s", "GitHub: %s"),  # noqa: WPS323
-    "user": (f"{github_sponsors_url}/%s", "@%s"),  # noqa: WPS323
-}
+# -- Options for the linkcheck builder -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
 
 linkcheck_ignore = [
     "http://localhost:\d+",
-    # This is an example that showing to the reader
     "https://test.pypi.org/project/example-package-YOUR-USERNAME-HERE",
-    # Ignoring it as it will redirect to login page if reader hasn't logged in.
     "https://pypi.org/manage/*",
     "https://test.pypi.org/manage/*",
 ]
 
-# Example configuration for intersphinx: refer to the Python standard library.
+# -- Options for extlinks ----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html#configuration
+
+github_url = "https://github.com"
+github_repo_org = "pypa"
+github_repo_name = "packaging.python.org"
+github_repo_slug = f"{github_repo_org}/{github_repo_name}"
+github_repo_url = f"{github_url}/{github_repo_slug}"
+github_repo_issues_url = f"{github_url}/{github_repo_slug}/issues"
+github_sponsors_url = f"{github_url}/sponsors"
+
+extlinks = {
+    "issue": (f"{github_repo_issues_url}/%s", "#%s"),
+    "pr": (f"{github_repo_url}/pull/%s", "PR #%s"),
+    "commit": (f"{github_repo_url}/commit/%s", "%s"),
+    "gh": (f"{github_url}/%s", "GitHub: %s"),
+    "user": (f"{github_sponsors_url}/%s", "@%s"),
+}
+
+# -- Options for intersphinx ----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+
 intersphinx_mapping = {
     "boltons": ("https://boltons.readthedocs.io/en/latest/", None),
     "bottle": ("https://bottlepy.org/docs/dev/", None),
@@ -431,23 +162,13 @@
     "virtualenv": ("https://virtualenv.pypa.io/en/stable/", None),
 }
 
-
-# If this is True, todo and todolist produce output, else they produce nothing.
-# The default is False.
+# -- Options for todo extension --------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration
 
 todo_include_todos = True
 
-nitpicky = True
+# -- Options for sphinx-copybutton -----------------------------------------------------
+# https://sphinx-copybutton.readthedocs.io/en/latest/use.html
 
-# NOTE: consider having a separate ignore file
-# Ref: https://stackoverflow.com/a/30624034/595220
-nitpick_ignore = [
-    ("envvar", "PATH"),
-    ("py:func", "find_packages"),
-    ("py:func", "setup"),
-    ("py:func", "importlib.metadata.entry_points"),  # remove when 3.10 is released
-    ("py:class", "importlib.metadata.EntryPoint"),  # remove when 3.10 is released
-    ("py:func", "setuptools.find_namespace_packages"),
-    ("py:func", "setuptools.find_packages"),
-    ("py:func", "setuptools.setup"),
-]
+copybutton_prompt_text = r">>> |\.\.\. |\$ |> "
+copybutton_prompt_is_regexp = True

From 328b812d605de9b6c12743f5bedefcbbb530522a Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Mon, 6 Nov 2023 23:04:26 +0000
Subject: [PATCH 137/733] Properly escape `\d`

This raises a SyntaxWarning on new-enough Python versions.
---
 source/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/conf.py b/source/conf.py
index 35eb7ee4c..f191445b9 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -104,7 +104,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
 
 linkcheck_ignore = [
-    "http://localhost:\d+",
+    "http://localhost:\\d+",
     "https://test.pypi.org/project/example-package-YOUR-USERNAME-HERE",
     "https://pypi.org/manage/*",
     "https://test.pypi.org/manage/*",

From e989371ea9e909b65662557a7d0734d9edf3c13d Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Wed, 8 Nov 2023 18:34:41 +0000
Subject: [PATCH 138/733] Stop hiding the name in the sidebar

This makes the homepage accessible via the sidebar.
---
 source/conf.py | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index f191445b9..3ce306397 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -50,11 +50,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_title = "Python Packaging User Guide"
-
 html_theme = "furo"
-html_theme_options = {
-    "sidebar_hide_name": True,
-}
 
 html_favicon = "assets/py.png"
 html_last_updated_fmt = ""

From d90ae924dffefb74175869a9b343b266fda0f5ec Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Wed, 8 Nov 2023 09:30:53 +0000
Subject: [PATCH 139/733] Retitle overview.rst for a shorter sidebar entry

This is the phrase used in the landing page for referencing this page.
---
 source/overview.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/overview.rst b/source/overview.rst
index 0bd4393db..3627e8122 100644
--- a/source/overview.rst
+++ b/source/overview.rst
@@ -1,6 +1,6 @@
-===================================
-An Overview of Packaging for Python
-===================================
+============================
+Overview of Python Packaging
+============================
 
 .. Editors, see notes at the bottom of the document for maintenance info.
 

From bbd1cd2c699c68ae2dfe36ab66ff39ba33721551 Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Wed, 8 Nov 2023 09:32:02 +0000
Subject: [PATCH 140/733] Simplify the reference to `overview` from `index`

The page title now matches the provided name at this reference.
---
 source/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/index.rst b/source/index.rst
index c00ed0ad8..32f85b206 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -41,7 +41,7 @@ Overview and Flow
    continuous improvement are key to success. The overview and flow sections
    provide a starting point for understanding the Python packaging ecosystem.
 
-The :doc:`Overview of Python Packaging ` explains Python packaging
+The :doc:`overview` explains Python packaging
 and its use when preparing and distributing projects.
 This section helps you build understanding about selecting the tools and
 processes that are most suitable for your use case.

From 7773243af520043c01d8eba3cb6a2dd912276276 Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Wed, 8 Nov 2023 18:39:13 +0000
Subject: [PATCH 141/733] Add a document heirarchy for presenting guides

This makes their presentation in the sidebar easier to navigate.
---
 source/guides/index.rst                     | 38 +++------------------
 source/guides/section-build-and-publish.rst | 17 +++++++++
 source/guides/section-hosting.rst           |  9 +++++
 source/guides/section-install.rst           | 12 +++++++
 4 files changed, 42 insertions(+), 34 deletions(-)
 create mode 100644 source/guides/section-build-and-publish.rst
 create mode 100644 source/guides/section-hosting.rst
 create mode 100644 source/guides/section-install.rst

diff --git a/source/guides/index.rst b/source/guides/index.rst
index 2f6f1a217..b87d0b1a8 100644
--- a/source/guides/index.rst
+++ b/source/guides/index.rst
@@ -6,40 +6,10 @@ already familiar with the basics of Python packaging. If you're looking for an
 introduction to packaging, see :doc:`/tutorials/index`.
 
 .. toctree::
-   :maxdepth: 1
-   :caption: Installing Packages:
-
-   installing-using-pip-and-virtual-environments
-   installing-using-virtualenv
-   installing-stand-alone-command-line-tools
-   installing-using-linux-tools
-   installing-scientific-packages
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Building and Publishing Projects:
-
-   distributing-packages-using-setuptools
-   using-manifest-in
-   single-sourcing-package-version
-   dropping-older-python-versions
-   packaging-binary-extensions
-   packaging-namespace-packages
-   creating-and-discovering-plugins
-   using-testpypi
-   making-a-pypi-friendly-readme
-   publishing-package-distribution-releases-using-github-actions-ci-cd-workflows
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Hosting
-
-   index-mirrors-and-caches
-   hosting-your-own-index
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Miscellaneous:
+   :titlesonly:
 
+   section-install
+   section-build-and-publish
+   section-hosting
    tool-recommendations
    analyzing-pypi-package-downloads
diff --git a/source/guides/section-build-and-publish.rst b/source/guides/section-build-and-publish.rst
new file mode 100644
index 000000000..9bb5f08fe
--- /dev/null
+++ b/source/guides/section-build-and-publish.rst
@@ -0,0 +1,17 @@
+=======================
+Building and Publishing
+=======================
+
+.. toctree::
+   :titlesonly:
+
+   distributing-packages-using-setuptools
+   using-manifest-in
+   single-sourcing-package-version
+   dropping-older-python-versions
+   packaging-binary-extensions
+   packaging-namespace-packages
+   creating-and-discovering-plugins
+   using-testpypi
+   making-a-pypi-friendly-readme
+   publishing-package-distribution-releases-using-github-actions-ci-cd-workflows
diff --git a/source/guides/section-hosting.rst b/source/guides/section-hosting.rst
new file mode 100644
index 000000000..f8f708c18
--- /dev/null
+++ b/source/guides/section-hosting.rst
@@ -0,0 +1,9 @@
+=======
+Hosting
+=======
+
+.. toctree::
+   :titlesonly:
+
+   index-mirrors-and-caches
+   hosting-your-own-index
diff --git a/source/guides/section-install.rst b/source/guides/section-install.rst
new file mode 100644
index 000000000..515092b4d
--- /dev/null
+++ b/source/guides/section-install.rst
@@ -0,0 +1,12 @@
+============
+Installation
+============
+
+.. toctree::
+   :titlesonly:
+
+   installing-using-pip-and-virtual-environments
+   installing-using-virtualenv
+   installing-stand-alone-command-line-tools
+   installing-using-linux-tools
+   installing-scientific-packages

From 7ea3f68b33be2721bcb09e7b9d5a441fa318bb0b Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Wed, 8 Nov 2023 18:58:11 +0000
Subject: [PATCH 142/733] Add a GitHub Action to inject preview links in PRs

This makes easier to review pull requests by providing the preview links
in the PR description.
---
 .github/workflows/pr-preview-links.yml | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 .github/workflows/pr-preview-links.yml

diff --git a/.github/workflows/pr-preview-links.yml b/.github/workflows/pr-preview-links.yml
new file mode 100644
index 000000000..90ea9cc73
--- /dev/null
+++ b/.github/workflows/pr-preview-links.yml
@@ -0,0 +1,22 @@
+name: Read the Docs PR preview
+
+on:
+  pull_request_target:
+    types:
+      - opened
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "python-packaging-user-guide"

From b2830611416f030e1211a7e754848a959673f85b Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 4 Nov 2023 23:30:25 +0100
Subject: [PATCH 143/733] Import PEP 668 verbatim

---
 .../externally-managed-environments.rst       | 1096 +++++++++++++++++
 1 file changed, 1096 insertions(+)

diff --git a/source/specifications/externally-managed-environments.rst b/source/specifications/externally-managed-environments.rst
index 979b72aec..8cd3b840a 100644
--- a/source/specifications/externally-managed-environments.rst
+++ b/source/specifications/externally-managed-environments.rst
@@ -21,6 +21,1102 @@ neither install nor remove packages into the interpreter’s default installatio
 environment, and should instead guide the end user towards using
 :ref:`virtual-environments`.
 
+PEP: 668
+Title: Marking Python base environments as “externally managed”
+Author: Geoffrey Thomas ,
+        Matthias Klose ,
+        Filipe Laíns ,
+        Donald Stufft ,
+        Tzu-ping Chung ,
+        Stefano Rivera ,
+        Elana Hashman ,
+        Pradyun Gedam 
+PEP-Delegate: Paul Moore 
+Discussions-To: https://discuss.python.org/t/10302
+Status: Accepted
+Type: Standards Track
+Topic: Packaging
+Content-Type: text/x-rst
+Created: 18-May-2021
+Post-History: 28-May-2021
+Resolution: https://discuss.python.org/t/10302/44
+
+Abstract
+========
+
+A long-standing practical problem for Python users has been conflicts
+between OS package managers and Python-specific package management
+tools like pip. These conflicts include both Python-level API
+incompatibilities and conflicts over file ownership.
+
+Historically, Python-specific package management tools have defaulted
+to installing packages into an implicit global context. With the
+standardization and popularity of virtual environments, a better
+solution for most (but not all) use cases is to use Python-specific
+package management tools only within a virtual environment.
+
+This PEP proposes a mechanism for a Python installation to communicate
+to tools like pip that its global package installation context is
+managed by some means external to Python, such as an OS package
+manager. It specifies that Python-specific package management tools
+should neither install nor remove packages into the interpreter's
+global context, by default, and should instead guide the end user
+towards using a virtual environment.
+
+It also standardizes an interpretation of the ``sysconfig`` schemes so
+that, if a Python-specific package manager is about to install a
+package in an interpreter-wide context, it can do so in a manner that
+will avoid conflicting with the external package manager and reduces
+the risk of breaking software shipped by the external package manager.
+
+Terminology
+===========
+
+A few terms used in this PEP have multiple meanings in the contexts
+that it spans. For clarity, this PEP uses the following terms in
+specific ways:
+
+distro
+    Short for "distribution," a collection of various sorts of
+    software, ideally designed to work properly together, including
+    (in contexts relevant to this document) the Python interpreter
+    itself, software written in Python, and software written in other
+    languages. That is, this is the sense used in phrases such as
+    "Linux distro" or "Berkeley Software Distribution."
+
+    A distro can be an operating system (OS) of its own, such as
+    Debian, Fedora, or FreeBSD. It can also be an overlay distribution
+    that installs on top of an existing OS, such as Homebrew or
+    MacPorts.
+
+    This document uses the short term "distro," because the term
+    "distribution" has another meaning in Python packaging contexts: a
+    source or binary distribution package of a single piece of Python
+    language software, that is, in the sense of
+    ``setuptools.dist.Distribution`` or "sdist". To avoid confusion,
+    this document does not use the plain term "distribution" at all.
+    In the Python packaging sense, it uses the full phrase
+    "distribution package" or just "package" (see below).
+
+    The provider of a distro - the team or company that collects and
+    publishes the software and makes any needed modifications - is its
+    **distributor**.
+package
+    A unit of software that can be installed and used within Python.
+    That is, this refers to what Python-specific packaging tools tend
+    to call a "`distribution package`_" or simply a "distribution";
+    the colloquial abbreviation "package" is used in the sense of the
+    Python Package Index.
+
+    .. _`distribution package`: https://packaging.python.org/glossary/#term-Distribution-Package
+
+    This document does not use "package" in the sense of an importable
+    name that contains Python modules, though in many cases, a
+    distribution package consists of a single importable package of
+    the same name.
+
+    This document generally does not use the term "package" to refer
+    to units of installation by a distro's package manager (such as
+    ``.deb`` or ``.rpm`` files). When needed, it uses phrasing such as
+    "a distro's package." (Again, in many cases, a Python package is
+    shipped inside a distro's package named something like ``python-``
+    plus the Python package name.)
+Python-specific package manager
+    A tool for installing, upgrading, and/or removing Python packages
+    in a manner that conforms to Python packaging standards (such as
+    :pep:`376` and :pep:`427`). The most popular Python-specific package
+    manager is pip [#pip]_; other examples include the old Easy
+    Install command [#easy-install]_ as well as direct usage of a
+    ``setup.py`` command.
+
+    (Conda [#conda]_ is a bit of a special case, as the ``conda``
+    command can install much more than just Python packages, making it
+    more like a distro package manager in some senses. Since the
+    ``conda`` command generally only operates on Conda-created
+    environments, most of the concerns in this document do not apply
+    to ``conda`` when acting as a Python-specific package manager.)
+distro package manager
+    A tool for installing, upgrading, and/or removing a distro's
+    packages in an installed instance of that distro, which is capable
+    of installing Python packages as well as non-Python packages, and
+    therefore generally has its own database of installed software
+    unrelated to :pep:`376`. Examples include ``apt``, ``dpkg``, ``dnf``,
+    ``rpm``, ``pacman``, and ``brew``. The salient feature is that if
+    a package was installed by a distro package manager, removing or
+    upgrading it in a way that would satisfy a Python-specific package
+    manager will generally leave a distro package manager in an
+    inconsistent state.
+
+    This document also uses phrases like "external package manager" or
+    "system's package manager" to refer to a distro package manager in
+    certain contexts.
+shadow
+    To shadow an installed Python package is to cause some other
+    package to be preferred for imports without removing any files
+    from the shadowed package. This requires multiple entries on
+    ``sys.path``: if package A 2.0 installs module ``a.py`` in one
+    ``sys.path`` entry, and package A 1.0 installs module ``a.py`` in
+    a later ``sys.path`` entry, then ``import a`` returns the module
+    from the former, and we say that A 2.0 shadows A 1.0.
+
+Motivation
+==========
+
+Thanks to Python's immense popularity, software distros (by which we
+mean Linux and other OS distros as well as overlay distros like
+Homebrew and MacPorts) generally ship Python for two purposes: as a
+software package to be used in its own right by end users, and as a
+language dependency for other software in the distro.
+
+For example, Fedora and Debian (and their downstream distros, as well
+as many others) ship a ``/usr/bin/python3`` binary which provides the
+``python3`` command available to end users as well as the
+``#!/usr/bin/python3`` shebang for Python-language software included
+in the distro. Because there are no official binary releases of Python
+for Linux/UNIX, almost all Python end users on these OSes use the
+Python interpreter built and shipped with their distro.
+
+The ``python3`` executable available to the users of the distro and
+the ``python3`` executable available as a dependency for other
+software in the distro are typically the same binary. This means that
+if an end user installs a Python package using a tool like ``pip``
+outside the context of a virtual environment, that package is visible
+to Python-language software shipped by the distro. If the
+newly-installed package (or one of its dependencies) is a newer,
+backwards-incompatible version of a package that was installed through
+the distro, it may break software shipped by the distro.
+
+This may pose a critical problem for the integrity of distros, which
+often have package-management tools that are themselves written in
+Python. For example, it's possible to unintentionally break Fedora's
+``dnf`` command with a ``pip install`` command, making it hard to
+recover.
+
+This applies both to system-wide installs (``sudo pip install``) as
+well as user home directory installs (``pip install --user``), since
+packages in either location show up on the ``sys.path`` of
+``/usr/bin/python3``.
+
+There is a worse problem with system-wide installs: if you attempt to
+recover from this situation with ``sudo pip uninstall``, you may end
+up removing packages that are shipped by the system's package manager.
+In fact, this can even happen if you simply upgrade a package - pip
+will try to remove the old version of the package, as shipped by the
+OS. At this point it may not be possible to recover the system to a
+consistent state using just the software remaining on the system.
+
+Over the past many years, a consensus has emerged that the best way to
+install Python libraries or applications (when not using a distro's
+package) is to use a virtual environment. This approach was
+popularized by the PyPA `virtualenv`_ project, and a simple version of
+that approach is now available in the Python standard library as
+``venv``. Installing a Python package into a virtualenv prevents it
+from being visible to the unqualified ``/usr/bin/python3`` interpreter
+and prevents breaking system software.
+
+.. _virtualenv: https://virtualenv.pypa.io/en/latest/
+
+In some cases, however, it's useful and intentional to install a
+Python package from outside of the distro that influences the behavior
+of distro-shipped commands. This is common in the case of software
+like Sphinx or Ansible which have a mechanism for writing
+Python-language extensions. A user may want to use their distro's
+version of the base software (for reasons of paid support or security
+updates) but install a small extension from PyPI, and they'd want that
+extension to be importable by the software in their base system.
+
+While this continues to carry the risk of installing a newer version
+of a dependency than the operating system expects or otherwise
+negatively affecting the behavior of an application, it does not need
+to carry the risk of removing files from the operating system. A tool
+like pip should be able to install packages in some directory on the
+default ``sys.path``, if specifically requested, without deleting
+files owned by the system's package manager.
+
+Therefore, this PEP proposes two things.
+
+First, it proposes **a way for distributors of a Python interpreter to
+mark that interpreter as having its packages managed by means external
+to Python**, such that Python-specific tools like pip should not
+change the installed packages in the interpreter's global ``sys.path``
+in any way (add, upgrade/downgrade, or remove) unless specifically
+overridden. It also provides a means for the distributor to indicate
+how to use a virtual environment as an alternative.
+
+This is an opt-in mechanism: by default, the Python interpreter
+compiled from upstream sources will not be so marked, and so running
+``pip install`` with a self-compiled interpreter, or with a distro
+that has not explicitly marked its interpreter, will work as it always
+has worked.
+
+Second, it sets the rule that when installing packages to an
+interpreter's global context (either to an unmarked interpreter, or if
+overriding the marking), **Python-specific package managers should
+modify or delete files only within the directories of the sysconfig
+scheme in which they would create files**. This permits a distributor
+of a Python interpreter to set up two directories, one for its own
+managed packages, and one for unmanaged packages installed by the end
+user, and ensure that installing unmanaged packages will not delete
+(or overwrite) files owned by the external package manager.
+
+Rationale
+=========
+
+As described in detail in the next section, the first behavior change
+involves creating a marker file named ``EXTERNALLY-MANAGED``, whose
+presence indicates that non-virtual-environment package installations
+are managed by some means external to Python, such as a distro's
+package manager. This file is specified to live in the ``stdlib``
+directory in the default ``sysconfig`` scheme, which marks the
+interpreter / installation as a whole, not a particular location on
+``sys.path``. The reason for this is that, as identified above, there
+are two related problems that risk breaking an externally-managed
+Python: you can install an incompatible new version of a package
+system-wide (e.g., with ``sudo pip install``), and you can install one
+in your user account alone, but in a location that is on the standard
+Python command's ``sys.path`` (e.g., with ``pip install --user``). If
+the marker file were in the system-wide ``site-packages`` directory,
+it would not clearly apply to the second case. The `Alternatives`_
+section has further discussion of possible locations.
+
+The second behavior change takes advantage of the existing
+``sysconfig`` setup in distros that have already encountered this
+class of problem, and specifically addresses the problem of a
+Python-specific package manager deleting or overwriting files that are
+owned by an external package manager.
+
+Use cases
+---------
+
+The changed behavior in this PEP is intended to "do the right thing"
+for as many use cases as possible. In this section, we consider the
+changes specified by this PEP for several representative use cases /
+contexts. Specifically, we ask about the two behaviors that could be
+changed by this PEP:
+
+1. Will a Python-specific installer tool like ``pip install`` permit
+   installations by default, after implementation of this PEP?
+
+2. If you do run such a tool, should it be willing to delete packages
+   shipped by the external (non-Python-specific) package manager for
+   that context, such as a distro package manager?
+
+(For simplicity, this section discusses pip as the Python-specific
+installer tool, though the analysis should apply equally to any other
+Python-specific package management tool.)
+
+This table summarizes the use cases discussed in detail below:
+
+==== ================================= =========================== ===================================================
+Case Description                       ``pip install`` permitted   Deleting externally-installed packages permitted
+==== ================================= =========================== ===================================================
+1    Unpatched CPython                 Currently yes; stays yes    Currently yes; stays yes
+2    Distro ``/usr/bin/python3``       Currently yes; becomes no   Currently yes (except on Debian); becomes no
+                                       (assuming the distro
+                                       adds a marker file)
+3    Distro Python in venv             Currently yes; stays yes    There are no externally-installed packages
+4    Distro Python in venv             Currently yes; stays yes    Currently no; stays no
+     with ``--system-site-packages``
+5    Distro Python in Docker           Currently yes; becomes no    Currently yes; becomes no
+                                       (assuming the distro
+                                       adds a marker file)
+6    Conda environment                 Currently yes; stays yes    Currently yes; stays yes
+7    Dev-facing distro                 Currently yes; becomes no   Currently often yes; becomes no
+                                       (assuming they add a        (assuming they configure ``sysconfig`` as needed)
+                                       marker file)
+8    Distro building packages          Currently yes; can stay yes Currently yes; becomes no
+9    ``PYTHONHOME`` copied from        Currently yes; becomes no   Currently yes; becomes no
+     a distro Python stdlib
+10   ``PYTHONHOME`` copied from        Currently yes; stays yes    Currently yes; stays yes
+     upstream Python stdlib
+==== ================================= =========================== ===================================================
+
+In more detail, the use cases above are:
+
+1. A standard unpatched CPython, without any special configuration of
+   or patches to ``sysconfig`` and without a marker file. This PEP
+   does not change its behavior.
+
+   Such a CPython should (regardless of this PEP) not be installed in
+   a way that overlaps any distro-installed Python on the same system.
+   For instance, on an OS that ships Python in ``/usr/bin``, you
+   should not install a custom CPython built with ``./configure
+   --prefix=/usr``, or it will overwrite some files from the distro
+   and the distro will eventually overwrite some files from your
+   installation. Instead, your installation should be in a separate
+   directory (perhaps ``/usr/local``, ``/opt``, or your home
+   directory).
+
+   Therefore, we can assume that such a CPython has its own ``stdlib``
+   directory and its own ``sysconfig`` schemes that do not overlap any
+   distro-installed Python. So any OS-installed packages are not
+   visible or relevant here.
+
+   If there is a concept of "externally-installed" packages in this
+   case, it's something outside the OS and generally managed by
+   whoever built and installed this CPython. Because the installer
+   chose not to add a marker file or modify ``sysconfig`` schemes,
+   they're choosing the current behavior, and ``pip install`` can
+   remove any packages available in this CPython.
+
+2. A distro's ``/usr/bin/python3``, either when running ``pip
+   install`` as root or ``pip install --user``, following our
+   `Recommendations for distros`_.
+
+   These recommendations include shipping a marker file in the
+   ``stdlib`` directory, to prevent ``pip install`` by default, and
+   placing distro-shipped packages in a location other than the
+   default ``sysconfig`` scheme, so that ``pip`` as root does not
+   write to that location.
+
+   Many distros (including Debian, Fedora, and their derivatives) are
+   already doing the latter.
+
+   On Debian and derivatives, ``pip install`` does not currently
+   delete distro-installed packages, because Debian carries a `patch
+   to pip to prevent this`__. So, for those distros, this PEP is not a
+   behavior change; it simply standardizes that behavior in a way that
+   is no longer Debian-specific and can be included into upstream pip.
+
+   .. __: https://sources.debian.org/src/python-pip/20.3.4-2/debian/patches/hands-off-system-packages.patch/
+
+   (We have seen user reports of externally-installed packages being
+   deleted on Debian or a derivative. We suspect this is because the
+   user has previously run ``sudo pip install --upgrade pip`` and
+   therefore now has a version of ``/usr/bin/pip`` without the Debian
+   patch; standardizing this behavior in upstream package installers
+   would address this problem.)
+
+3. A distro Python when used inside a virtual environment (either from
+   ``venv`` or ``virtualenv``).
+
+   Inside a virtual environment, all packages are owned by that
+   environment. Even when ``pip``, ``setuptools``, etc. are installed
+   into the environment, they are and should be managed by tools
+   specific to that environment; they are not system-managed.
+
+4. A distro Python when used inside a virtual environment with
+   ``--system-site-packages``. This is like the previous case, but
+   worth calling out explicitly, because anything on the global
+   ``sys.path`` is visible.
+
+   Currently, the answer to "Will ``pip`` delete externally-installed
+   packages" is no, because pip has a special case for running in a
+   virtual environment and attempting to delete packages outside it.
+   After this PEP, the answer remains no, but the reasoning becomes
+   more general: system site packages will be outside any of the
+   ``sysconfig`` schemes used for package management in the
+   environment.
+
+5. A distro Python when used in a single-application container image
+   (e.g., a Docker container). In this use case, the risk of breaking
+   system software is lower, since generally only a single application
+   runs in the container, and the impact is lower, since you can
+   rebuild the container and you don't have to struggle to recover a
+   running machine. There are also a large number of existing
+   Dockerfiles with an unqualified ``RUN pip install ...`` statement,
+   etc., and it would be good not to break those. So, builders of base
+   container images may want to ensure that the marker file is not
+   present, even if the underlying OS ships one by default.
+
+   There is a small behavior change: currently, ``pip`` run as root
+   will delete externally-installed packages, but after this PEP it
+   will not. We don't propose a way to override this. However, since
+   the base image is generally minimal, there shouldn't be much of a
+   use case for simply uninstalling packages (especially without using
+   the distro's own tools). The common case is when pip wants to
+   upgrade a package, which previously would have deleted the old
+   version (except on Debian). After this change, the old version will
+   still be on disk, but pip will still *shadow* externally-installed
+   packages, and we believe this to be sufficient for this not to be a
+   breaking change in practice - a Python ``import`` statement will
+   still get you the newly-installed package.
+
+   If it becomes necessary to have a way to do this, we suggest that
+   the distro should document a way for the installer tool to access
+   the ``sysconfig`` scheme used by the distro itself. See the
+   `Recommendations for distros`_ section for more discussion.
+
+   It is the view of the authors of this PEP that it's still a good
+   idea to use virtual environments with distro-installed Python
+   interpreters, even in single-application container images. Even
+   though they run a single *application*, that application may run
+   commands from the OS that are implemented in Python, and if you've
+   installed or upgraded the distro-shipped Python packages using
+   Python-specific tools, those commands may break.
+
+6. Conda specifically supports the use of non-``conda`` tools like pip
+   to install software not available in the Conda repositories. In
+   this context, Conda acts as the external package manager / distro
+   and pip as the Python-specific one.
+
+   In some sense, this is similar to the first case, since Conda
+   provides its own installation of the Python interpreter.
+
+   We don't believe this PEP requires any changes to Conda, and
+   versions of pip that have implemented the changes in this PEP will
+   continue to behave as they currently do inside Conda environments.
+   (That said, it may be worth considering whether to use separate
+   ``sysconfig`` schemes for pip-installed and Conda-installed
+   software, for the same reasons it's a good idea for other distros.)
+
+7. By a "developer-facing distro," we mean a specific type of distro
+   where direct users of Python or other languages in the distro are
+   expected or encouraged to make changes to the distro itself if they
+   wish to add libraries. Common examples include private "monorepos"
+   at software development companies, where a single repository builds
+   both third-party and in-house software, and the direct users of the
+   distro's Python interpreter are generally software developers
+   writing said in-house software. User-level package managers like
+   Nixpkgs_ may also count, because they encourage users of Nix who
+   are Python developers to `package their software for Nix`__.
+
+   In these cases, the distro may want to respond to an attempted
+   ``pip install`` with guidance encouraging use of the distro's own
+   facilities for adding new packages, along with a link to
+   documentation.
+
+   If the distro supports/encourages creating a virtual environment
+   from the distro's Python interpreter, there may also be custom
+   instructions for how to properly set up a virtual environment (as
+   for example Nixpkgs does).
+
+   .. _Nixpkgs: https://github.com/NixOS/nixpkgs
+
+   .. __: https://nixos.wiki/wiki/Python
+
+8. When building distro Python packages for a distro Python (case 2),
+   it may be useful to have ``pip install`` be usable as part of the
+   distro's package build process. (Consider, for instance, building a
+   ``python-xyz`` RPM by using ``pip install .`` inside an sdist /
+   source tarball for ``xyz``.) The distro may also want to use a more
+   targeted but still Python-specific installation tool such as
+   installer_.
+
+   .. _installer: https://installer.rtfd.io/
+
+   For this case, the build process will need to find some way to
+   suppress the marker file to allow ``pip install`` to work, and will
+   probably need to point the Python-specific tool at the distro's
+   ``sysconfig`` scheme instead of the shipped default. See the
+   `Recommendations for distros`_ section for more discussion on how
+   to implement this.
+
+   As a result of this PEP, pip will no longer be able to remove
+   packages already on the system. However, this behavior change is
+   fine because a package build process should not (and generally
+   cannot) include instructions to delete some other files on the
+   system; it can only package up its own files.
+
+9. A distro Python used with ``PYTHONHOME`` to set up an alternative
+   Python environment (as opposed to a virtual environment), where
+   ``PYTHONHOME`` is set to some directory copied directly from the
+   distro Python (e.g., ``cp -a /usr/lib/python3.x pyhome/lib``).
+
+   Assuming there are no modifications, then the behavior is just like
+   the underlying distro Python (case 2). So there are behavior
+   changes - you can no longer ``pip install`` by default, and if you
+   override it, it will no longer delete externally-installed packages
+   (i.e., Python packages that were copied from the OS and live in the
+   OS-managed ``sys.path`` entry).
+
+   This behavior change seems to be defensible, in that if your
+   ``PYTHONHOME`` is a straight copy of the distro's Python, it should
+   behave like the distro's Python.
+
+10. A distro Python (or any Python interpreter) used with a
+    ``PYTHONHOME`` taken from a compatible unmodified upstream Python.
+
+    Because the behavior changes in this PEP are keyed off of files in
+    the standard library (the marker file in ``stdlib`` and the
+    behavior of the ``sysconfig`` module), the behavior is just like
+    an unmodified upstream CPython (case 1).
+
+Specification
+=============
+
+Marking an interpreter as using an external package manager
+-----------------------------------------------------------
+
+Before a Python-specific package installer (that is, a tool such as
+pip - not an external tool such as apt) installs a package into a
+certain Python context, it should make the following checks by
+default:
+
+1. Is it running outside of a virtual environment? It can determine
+   this by whether ``sys.prefix == sys.base_prefix`` (but see
+   `Backwards Compatibility`_).
+
+2. Is there an ``EXTERNALLY-MANAGED`` file in the directory identified
+   by ``sysconfig.get_path("stdlib",
+   sysconfig.get_default_scheme())``?
+
+If both of these conditions are true, the installer should exit with
+an error message indicating that package installation into this Python
+interpreter's directory are disabled outside of a virtual environment.
+
+The installer should have a way for the user to override these rules,
+such as a command-line flag ``--break-system-packages``. This option
+should not be enabled by default and should carry some connotation
+that its use is risky.
+
+The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended
+to be parsable by the standard library configparser_ module. If the
+file can be parsed by
+``configparser.ConfigParser(interpolation=None)`` using the UTF-8
+encoding, and it contains a section ``[externally-managed]``, then the
+installer should look for an error message specified in the file and
+output it as part of its error. If the first element of the tuple
+returned by ``locale.getlocale(locale.LC_MESSAGES)``, i.e., the
+language code, is not ``None``, it should look for the error message
+as the value of a key named ``Error-`` followed by the language code.
+If that key does not exist, and if the language code contains
+underscore or hyphen, it should look for a key named ``Error-``
+followed by the portion of the language code before the underscore or
+hyphen. If it cannot find either of those, or if the language code is
+``None``, it should look for a key simply named ``Error``.
+
+.. _configparser: https://docs.python.org/3/library/configparser.html
+
+If the installer cannot find an error message in the file (either
+because the file cannot be parsed or because no suitable error key
+exists), then the installer should just use a pre-defined error
+message of its own, which should suggest that the user create a
+virtual environment to install packages.
+
+Software distributors who have a non-Python-specific package manager
+that manages libraries in the ``sys.path`` of their Python package
+should, in general, ship a ``EXTERNALLY-MANAGED`` file in their
+standard library directory. For instance, Debian may ship a file in
+``/usr/lib/python3.9/EXTERNALLY-MANAGED`` consisting of something like
+
+::
+
+    [externally-managed]
+    Error=To install Python packages system-wide, try apt install
+     python3-xyz, where xyz is the package you are trying to
+     install.
+
+     If you wish to install a non-Debian-packaged Python package,
+     create a virtual environment using python3 -m venv path/to/venv.
+     Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
+     sure you have python3-full installed.
+
+     If you wish to install a non-Debian packaged Python application,
+     it may be easiest to use pipx install xyz, which will manage a
+     virtual environment for you. Make sure you have pipx installed.
+
+     See /usr/share/doc/python3.9/README.venv for more information.
+
+which provides useful and distro-relevant information
+to a user trying to install a package. Optionally,
+translations can be provided in the same file:
+
+::
+
+    Error-de_DE=Wenn ist das Nunstück git und Slotermeyer?
+
+     Ja! Beiherhund das Oder die Virtualenvironment gersput!
+
+In certain contexts, such as single-application container images that
+aren't updated after creation, a distributor may choose not to ship an
+``EXTERNALLY-MANAGED`` file, so that users can install whatever they
+like (as they can today) without having to manually override this
+rule.
+
+Writing to only the target ``sysconfig`` scheme
+-----------------------------------------------
+
+Usually, a Python package installer installs to directories in a
+scheme returned by the ``sysconfig`` standard library package.
+Ordinarily, this is the scheme returned by
+``sysconfig.get_default_scheme()``, but based on configuration (e.g.
+``pip install --user``), it may use a different scheme.
+
+Whenever the installer is installing to a ``sysconfig`` scheme, this
+PEP specifies that the installer should never modify or delete files
+outside of that scheme. For instance, if it's upgrading a package, and
+the package is already installed in a directory outside that scheme
+(perhaps in a directory from another scheme), it should leave the
+existing files alone.
+
+If the installer does end up shadowing an existing installation during
+an upgrade, we recommend that it produces a warning at the end of its
+run.
+
+If the installer is installing to a location outside of a
+``sysconfig`` scheme (e.g., ``pip install --target``), then this
+subsection does not apply.
+
+Recommendations for distros
+===========================
+
+This section is non-normative. It provides best practices we believe
+distros should follow unless they have a specific reason otherwise.
+
+Mark the installation as externally managed
+-------------------------------------------
+
+Distros should create an ``EXTERNALLY-MANAGED`` file in their
+``stdlib`` directory.
+
+Guide users towards virtual environments
+----------------------------------------
+
+The file should contain a useful and distro-relevant error message
+indicating both how to install system-wide packages via the distro's
+package manager and how to set up a virtual environment. If your
+distro is often used by users in a state where the ``python3`` command
+is available (and especially where ``pip`` or ``get-pip`` is
+available) but ``python3 -m venv`` does not work, the message should
+indicate clearly how to make ``python3 -m venv`` work properly.
+
+Consider packaging pipx_, a tool for installing Python-language
+applications, and suggesting it in the error. pipx automatically
+creates a virtual environment for that application alone, which is a
+much better default for end users who want to install some
+Python-language software (which isn't available in the distro) but are
+not themselves Python users. Packaging pipx in the distro avoids the
+irony of instructing users to ``pip install --user
+--break-system-packages pipx`` to *avoid* breaking system packages.
+Consider arranging things so your distro's package / environment for
+Python for end users (e.g., ``python3`` on Fedora or ``python3-full``
+on Debian) depends on pipx.
+
+.. _pipx: https://github.com/pypa/pipx
+
+Keep the marker file in container images
+----------------------------------------
+
+Distros that produce official images for single-application containers
+(e.g., Docker container images) should keep the
+``EXTERNALLY-MANAGED`` file, preferably in a way that makes it not
+go away if a user of that image installs package updates inside
+their image (think ``RUN apt-get dist-upgrade``).
+
+Create separate distro and local directories
+--------------------------------------------
+
+Distros should place two separate paths on the system interpreter's
+``sys.path``, one for distro-installed packages and one for packages
+installed by the local system administrator, and configure
+``sysconfig.get_default_scheme()`` to point at the latter path. This
+ensures that tools like pip will not modify distro-installed packages.
+The path for the local system administrator should come before the
+distro path on ``sys.path`` so that local installs take preference
+over distro packages.
+
+For example, Fedora and Debian (and their derivatives) both implement
+this split by using ``/usr/local`` for locally-installed packages and
+``/usr`` for distro-installed packages. Fedora uses
+``/usr/local/lib/python3.x/site-packages`` vs.
+``/usr/lib/python3.x/site-packages``. (Debian uses
+``/usr/local/lib/python3/dist-packages`` vs.
+``/usr/lib/python3/dist-packages`` as an additional layer of
+separation from a locally-compiled Python interpreter: if you build
+and install upstream CPython in ``/usr/local/bin``, it will look at
+``/usr/local/lib/python3/site-packages``, and Debian wishes to make
+sure that packages installed via the locally-built interpreter don't
+show up on ``sys.path`` for the distro interpreter.)
+
+Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how
+the ``PATH`` environment variable typically includes
+``/usr/local/bin:/usr/bin`` and non-distro software installs to
+``/usr/local`` by default. This split is `recommended by the
+Filesystem Hierarchy Standard`__.
+
+.. __: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s09.html
+
+There are two ways you could do this. One is, if you are building and
+packaging Python libraries directly (e.g., your packaging helpers
+unpack a :pep:`517`-built wheel or call ``setup.py install``), arrange
+for those tools to use a directory that is not in a ``sysconfig``
+scheme but is still on ``sys.path``.
+
+The other is to arrange for the default ``sysconfig`` scheme to change
+when running inside a package build versus when running on an
+installed system. The ``sysconfig`` customization hooks from
+bpo-43976_ should make this easy (once accepted and implemented):
+make your packaging tool set an
+environment variable or some other detectable configuration, and
+define a ``get_preferred_schemes`` function to return a different
+scheme when called from inside a package build. Then you can use ``pip
+install`` as part of your distro packaging.
+
+.. _bpo-43976: https://bugs.python.org/issue43976
+
+We propose adding a ``--scheme=...`` option to instruct pip to run
+against a specific scheme. (See `Implementation Notes`_ below for how
+pip currently determines schemes.) Once that's available, for local
+testing and possibly for actual packaging, you would be able to run
+something like ``pip install --scheme=posix_distro`` to explicitly
+install a package into your distro's location (bypassing
+``get_preferred_schemes``). One could also, if absolutely needed, use
+``pip uninstall --scheme=posix_distro`` to use pip to remove packages
+from the system-managed directory, which addresses the (hopefully
+theoretical) regression in use case 5 in Rationale_.
+
+To install packages with pip, you would also need to either suppress
+the ``EXTERNALLY-MANAGED`` marker file to allow pip to run or to
+override it on the command line. You may want to use the same means
+for suppressing the marker file in build chroots as you do in
+container images.
+
+The advantage of setting these up to be automatic (suppressing the
+marker file in your build environment and having
+``get_preferred_schemes`` automatically return your distro's scheme)
+is that an unadorned ``pip install`` will work inside a package build,
+which generally means that an unmodified upstream build script that
+happens to internally call ``pip install`` will do the right thing.
+You can, of course, just ensure that your packaging process always
+calls ``pip install --scheme=posix_distro --break-system-packages``,
+which would work too.
+
+The best approach here depends a lot on your distro's conventions and
+mechanisms for packaging.
+
+Similarly, the ``sysconfig`` paths that are not for importable Python
+code - that is, ``include``, ``platinclude``, ``scripts``, and
+``data`` - should also have two variants, one for use by
+distro-packaged software and one for use for locally-installed
+software, and the distro should be set up such that both are usable.
+For instance, a typical FHS-compliant distro will use
+``/usr/local/include`` for the default scheme's ``include`` and
+``/usr/include`` for distro-packaged headers and place both on the
+compiler's search path, and it will use ``/usr/local/bin`` for the
+default scheme's ``scripts`` and ``/usr/bin`` for distro-packaged
+entry points and place both on ``$PATH``.
+
+Backwards Compatibility
+=======================
+
+All of these mechanisms are proposed for new distro releases and new
+versions of tools like pip only.
+
+In particular, we strongly recommend that distros with a concept of
+major versions only add the marker file or change ``sysconfig``
+schemes in a new major version; otherwise there is a risk that, on an
+existing system, software installed via a Python-specific package
+manager now becomes unmanageable (without an override option). For a
+rolling-release distro, if possible, only add the marker file or
+change ``sysconfig`` schemes in a new Python minor version.
+
+One particular backwards-compatibility difficulty for package
+installation tools is likely to be managing environments created by
+old versions of ``virtualenv`` which have the latest version of the
+tool installed. A "virtual environment" now has a fairly precise
+definition: it uses the ``pyvenv.cfg`` mechanism, which causes
+``sys.base_prefix != sys.prefix``. It is possible, however, that a
+user may have an old virtual environment created by an older version
+of ``virtualenv``; as of this writing, pip supports Python 3.6
+onwards, which is in turn supported by ``virtualenv`` 15.1.0 onwards,
+so this scenario is possible. In older versions of ``virtualenv``, the
+mechanism is instead to set a new attribute, ``sys.real_prefix``, and
+it does not use the standard library support for virtual environments,
+so ``sys.base_prefix`` is the same as ``sys.prefix``. So the logic for
+robustly detecting a virtual environment is something like::
+
+    def is_virtual_environment():
+        return sys.base_prefix != sys.prefix or hasattr(sys, "real_prefix")
+
+Security Implications
+=====================
+
+The purpose of this feature is not to implement a security boundary;
+it is to discourage well-intended changes from unexpectedly breaking a
+user's environment. That is to say, the reason this PEP restricts
+``pip install`` outside a virtual environment is not that it's a
+security risk to be able to do so; it's that "There should be one--
+and preferably only one --obvious way to do it," and that way should
+be using a virtual environment. ``pip install`` outside a virtual
+environment is rather too obvious for what is almost always the wrong
+way to do it.
+
+If there is a case where a user should not be able to ``sudo pip
+install`` or ``pip install --user`` and add files to ``sys.path`` *for
+security reasons*, that needs to be implemented either via access
+control rules on what files the user can write to or an explicitly
+secured ``sys.path`` for the program in question. Neither of the
+mechanisms in this PEP should be interpreted as a way to address such
+a scenario.
+
+For those reasons, an attempted install with a marker file present is
+not a security incident, and there is no need to raise an auditing
+event for it. If the calling user legitimately has access to ``sudo
+pip install`` or ``pip install --user``, they can accomplish the same
+installation entirely outside of Python; if they do not legitimately
+have such access, that's a problem outside the scope of this PEP.
+
+The marker file itself is located in the standard library directory,
+which is a trusted location (i.e., anyone who can write to the marker
+file used by a particular installer could, presumably, run arbitrary
+code inside the installer). Therefore, there is generally no need to
+filter out terminal escape sequences or other potentially-malicious
+content in the error message.
+
+Alternatives
+==============
+
+There are a number of similar proposals we considered that this PEP
+rejects or defers, largely to preserve the behavior in the
+case-by-case analysis in Rationale_.
+
+Marker file
+-----------
+
+Should the marker file be in ``sys.path``, marking a particular
+directory as not to be written to by a Python-specific package
+manager? This would help with the second problem addressed by this PEP
+(not overwriting deleting distro-owned files) but not the first
+(incompatible installs). A directory-specific marker in
+``/usr/lib/python3.x/site-packages`` would not discourage
+installations into either ``/usr/local/lib/python3.x/site-packages``
+or ``~/.local/lib/python3.x/site-packages``, both of which are on
+``sys.path`` for ``/usr/bin/python3``. In other words, the marker file
+should not be interpreted as marking a single *directory* as
+externally managed (even though it happens to be in a directory on
+``sys.path``); it marks the entire *Python installation* as externally
+managed.
+
+Another variant of the above: should the marker file be in
+``sys.path``, where if it can be found in any directory in
+``sys.path``, it marks the installation as externally managed? An
+apparent advantage of this approach is that it automatically disables
+itself in virtual environments. Unfortunately, This has the wrong
+behavior with a ``--system-site-packages`` virtual environment, where
+the system-wide ``sys.path`` is visible but package installations are
+allowed. (It could work if the rule of exempting virtual environments
+is preserved, but that seems to have no advantage over the current
+scheme.)
+
+Should the marker just be a new attribute of a ``sysconfig`` scheme?
+There is some conceptual cleanliness to this, except that it's hard to
+override. We want to make it easy for container images, package build
+environments, etc. to suppress the marker file. A file that you can
+remove is easy; code in ``sysconfig`` is much harder to modify.
+
+Should the file be in ``/etc``? No, because again, it refers to a
+specific Python installation. A user who installs their own Python may
+well want to install packages within the global context of that
+interpreter.
+
+Should the configuration setting be in ``pip.conf`` or
+``distutils.cfg``? Apart from the above objections about marking an
+installation, this mechanism isn't specific to either of those tools.
+(It seems reasonable for pip to *also* implement a configuration flag
+for users to prevent themselves from performing accidental
+non-virtual-environment installs in any Python installation, but that
+is outside the scope of this PEP.)
+
+Should the file be TOML? TOML is gaining popularity for packaging (see
+e.g. :pep:`517`) but does not yet have an implementation in the standard
+library. Strictly speaking, this isn't a blocker - distros need only
+write the file, not read it, so they don't need a TOML library (the
+file will probably be written by hand, regardless of format), and
+packaging tools likely have a TOML reader already. However, the INI
+format is currently used for various other forms of packaging metadata
+(e.g., ``pydistutils.cfg`` and ``setup.cfg``), meets our needs, and is
+parsable by the standard library, and the pip maintainers expressed a
+preference to avoid using TOML for this yet.
+
+Should the file be ``email.message``-style? While this format is also
+used for packaging metadata (e.g. sdist and wheel metadata) and is
+also parsable by the standard library, it doesn't handle multi-line
+entries quite as clearly, and that is our primary use case.
+
+Should the marker file be executable Python code that evaluates
+whether installation should be allowed or not? Apart from the concerns
+above about having the file in ``sys.path``, we have a concern that
+making it executable is committing to too powerful of an API and risks
+making behavior harder to understand. (Note that the
+``get_default_scheme`` hook of bpo-43976_ is in fact executable, but
+that code needs to be supplied when the interpreter builds; it isn't
+intended to be supplied post-build.)
+
+When overriding the marker, should a Python-specific package manager
+be disallowed from shadowing a package installed by the external
+package manager (i.e., installing modules of the same name)? This
+would minimize the risk of breaking system software, but it's not
+clear it's worth the additional user experience complexity. There are
+legitimate use cases for shadowing system packages, and an additional
+command-line option to permit it would be more confusing. Meanwhile,
+not passing that option wouldn't eliminate the risk of breaking system
+software, which may be relying on a ``try: import xyz`` failing,
+finding a limited set of entry points, etc. Communicating this
+distinction seems difficult. We think it's a good idea for
+Python-specific package managers to print a warning if they shadow a
+package, but we think it's not worth disabling it by default.
+
+Why not use the ``INSTALLER`` file from :pep:`376` to determine who
+installed a package and whether it can be removed? First, it's
+specific to a particular package (it's in the package's ``dist-info``
+directory), so like some of the alternatives above, it doesn't provide
+information on an entire environment and whether package installations
+are permissible. :pep:`627` also updates :pep:`376` to prevent programmatic
+use of ``INSTALLER``, specifying that the file is "to be used for
+informational purposes only. [...] Our goal is supporting
+interoperating tools, and basing any action on which tool happened to
+install a package runs counter to that goal." Finally, as :pep:`627`
+envisions, there are legitimate use cases for one tool knowing how to
+handle packages installed by another tool; for instance, ``conda`` can
+safely remove a package installed by ``pip`` into a Conda environment.
+
+Why does the specification give no means for disabling package
+installations inside a virtual environment? We can't see a
+particularly strong use case for it (at least not one related to the
+purposes of this PEP). If you need it, it's simple enough to ``pip
+uninstall pip`` inside that environment, which should discourage at
+least unintentional changes to the environment (and this specification
+makes no provision to disable *intentional* changes, since after all
+the marker file can be easily removed).
+
+System Python
+-------------
+
+Shouldn't distro software just run with the distro ``site-packages``
+directory alone on ``sys.path`` and ignore the local system
+administrator's ``site-packages`` as well as the user-specific one?
+This is a worthwhile idea, and various versions of it have been
+circulating for a while under the name of "system Python" or "platform
+Python" (with a separate "user Python" for end users writing Python or
+installing Python software separate from the system). However, it's
+much more involved of a change. First, it would be a
+backwards-incompatible change. As mentioned in the Motivation_
+section, there are valid use cases for running distro-installed Python
+applications like Sphinx or Ansible with locally-installed Python
+libraries available on their ``sys.path``. A wholesale switch to
+ignoring local packages would break these use cases, and a distro
+would have to make a case-by-case analysis of whether an application
+ought to see locally-installed libraries or not.
+
+Furthermore, `Fedora attempted this change and reverted it`_, finding,
+ironically, that their implementation of the change `broke their
+package manager`_. Given that experience, there are clearly details to
+be worked out before distros can reliably implement that approach, and
+a PEP recommending it would be premature.
+
+.. _`Fedora attempted this change and reverted it`: https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/thread/SEFUWW4XZBTVOAQ36XOJQ72PIICMFOSN/
+.. _`broke their package manager`: https://bugzilla.redhat.com/show_bug.cgi?id=1483342
+
+This PEP is intended to be a complete and self-contained change that
+is independent of a distributor's decision for or against "system
+Python" or similar proposals. It is not incompatible with a distro
+implementing "system Python" in the future, and even though both
+proposals address the same class of problems, there are still
+arguments in favor of implementing something like "system Python" even
+after implementing this PEP. At the same time, though, this PEP
+specifically tries to make a more targeted and minimal change, such
+that it can be implemented by distributors who don't expect to adopt
+"system Python" (or don't expect to implement it immediately). The
+changes in this PEP stand on their own merits and are not an
+intermediate step for some future proposal. This PEP reduces (but does
+not eliminate) the risk of breaking system software while minimizing
+(but not completely avoiding) breaking changes, which should therefore
+be much easier to implement than the full "system Python" idea, which
+comes with the downsides mentioned above.
+
+We expect that the guidance in this PEP - that users should use
+virtual environments whenever possible and that distros should have
+separate ``sys.path`` directories for distro-managed and
+locally-managed modules - should make further experiments easier in
+the future. These may include distributing wholly separate "system"
+and "user" Python interpreters, running system software out of a
+distro-owned virtual environment or ``PYTHONHOME`` (but shipping a
+single interpreter), or modifying the entry points for certain
+software (such as the distro's package manager) to use a ``sys.path``
+that only sees distro-managed directories. Those ideas themselves,
+however, remain outside the scope of this PEP.
+
+Implementation Notes
+====================
+
+This section is non-normative and contains notes relevant to both the
+specification and potential implementations.
+
+Currently, pip does not directly expose a way to choose a target
+``sysconfig`` scheme, but it has three ways of looking up schemes when
+installing:
+
+``pip install``
+    Calls ``sysconfig.get_default_scheme()``, which is usually (in
+    upstream CPython and most current distros) the same as
+    ``get_preferred_scheme('prefix')``.
+
+``pip install --prefix=/some/path``
+    Calls ``sysconfig.get_preferred_scheme('prefix')``.
+
+``pip install --user``
+    Calls ``sysconfig.get_preferred_scheme('user')``.
+
+Finally, ``pip install --target=/some/path`` writes directly to
+``/some/path`` without looking up any schemes.
+
+Debian currently carries a `patch to change the default install
+location inside a virtual environment`__, using a few heuristics
+(including checking for the ``VIRTUAL_ENV`` environment variable),
+largely so that the directory used in a virtual environment remains
+``site-packages`` and not ``dist-packages``. This does not
+particularly affect this proposal, because the implementation of that
+patch does not actually change the default ``sysconfig`` scheme, and
+notably does not change the result of
+``sysconfig.get_path("stdlib")``.
+
+.. __: https://sources.debian.org/src/python3.7/3.7.3-2+deb10u3/debian/patches/distutils-install-layout.diff/
+
+Fedora currently carries a `patch to change the default install
+location when not running inside rpmbuild`__, which they use to
+implement the two-system-wide-directories approach. This is
+conceptually the sort of hook envisioned by bpo-43976_, except
+implemented as a code patch to ``distutils`` instead of as a changed
+``sysconfig`` scheme.
+
+.. __: https://src.fedoraproject.org/rpms/python3.9/blob/f34/f/00251-change-user-install-location.patch
+
+The implementation of ``is_virtual_environment`` above, as well as the
+logic to load the ``EXTERNALLY-MANAGED`` file and find the error
+message from it, may as well get added to the standard library
+(``sys`` and ``sysconfig``, respectively), to centralize their
+implementations, but they don't need to be added yet.
+
+References
+==========
+
+For additional background on these problems and previous attempts to
+solve them, see `Debian bug 771794`_ "pip silently removes/updates
+system provided python packages" from 2014, Fedora's 2018 article
+`Making sudo pip safe`_ about pointing ``sudo pip`` at /usr/local
+(which acknowledges that the changes still do not make ``sudo pip``
+completely safe), pip issues 5605_ ("Disable upgrades to existing
+python modules which were not installed via pip") and 5722_ ("pip
+should respect /usr/local") from 2018, and the post-PyCon US 2019
+discussion thread `Playing nice with external package managers`_.
+
+.. _`Debian bug 771794`: https://bugs.debian.org/771794
+
+.. _`Making sudo pip safe`: https://fedoraproject.org/wiki/Changes/Making_sudo_pip_safe
+
+.. _5605: https://github.com/pypa/pip/issues/5605
+
+.. _5722: https://github.com/pypa/pip/issues/5722
+
+.. _`Playing nice with external package managers`: https://discuss.python.org/t/playing-nice-with-external-package-managers/1968
+
+.. [#pip] https://pip.pypa.io/en/stable/
+
+.. [#easy-install] https://setuptools.readthedocs.io/en/latest/deprecated/easy_install.html
+   (Note that the ``easy_install`` command was removed in
+   setuptools version 52, released 23 January 2021.)
+
+.. [#Conda] https://conda.io
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.
+
+
+
 History
 =======
 - `June 2022 `_: ``EXTERNALLY-MANAGED`` marker file was originally specified in :pep:`668#marking-an-interpreter-as-using-an-external-package-manager`.

From b590452e5ee3949f043e2ecd8bba990046b97729 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 5 Nov 2023 00:18:28 +0100
Subject: [PATCH 144/733] PEP 668: Editing to fit the PUG

---
 .../externally-managed-environments.rst       | 738 ++----------------
 1 file changed, 45 insertions(+), 693 deletions(-)

diff --git a/source/specifications/externally-managed-environments.rst b/source/specifications/externally-managed-environments.rst
index 8cd3b840a..f6845e737 100644
--- a/source/specifications/externally-managed-environments.rst
+++ b/source/specifications/externally-managed-environments.rst
@@ -15,66 +15,25 @@ environments can be confusing at best and outright break the entire underlying
 operating system at worst. Documentation and interoperability guides only go
 so far in resolving such problems.
 
-:pep:`668` defined an ``EXTERNALLY-MANAGED`` marker file that allows a Python
-installation to indicate to Python-specific tools such as ``pip`` that they
+This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows a
+Python installation to indicate to Python-specific tools such as ``pip`` that they
 neither install nor remove packages into the interpreter’s default installation
 environment, and should instead guide the end user towards using
 :ref:`virtual-environments`.
 
-PEP: 668
-Title: Marking Python base environments as “externally managed”
-Author: Geoffrey Thomas ,
-        Matthias Klose ,
-        Filipe Laíns ,
-        Donald Stufft ,
-        Tzu-ping Chung ,
-        Stefano Rivera ,
-        Elana Hashman ,
-        Pradyun Gedam 
-PEP-Delegate: Paul Moore 
-Discussions-To: https://discuss.python.org/t/10302
-Status: Accepted
-Type: Standards Track
-Topic: Packaging
-Content-Type: text/x-rst
-Created: 18-May-2021
-Post-History: 28-May-2021
-Resolution: https://discuss.python.org/t/10302/44
-
-Abstract
-========
-
-A long-standing practical problem for Python users has been conflicts
-between OS package managers and Python-specific package management
-tools like pip. These conflicts include both Python-level API
-incompatibilities and conflicts over file ownership.
-
-Historically, Python-specific package management tools have defaulted
-to installing packages into an implicit global context. With the
-standardization and popularity of virtual environments, a better
-solution for most (but not all) use cases is to use Python-specific
-package management tools only within a virtual environment.
-
-This PEP proposes a mechanism for a Python installation to communicate
-to tools like pip that its global package installation context is
-managed by some means external to Python, such as an OS package
-manager. It specifies that Python-specific package management tools
-should neither install nor remove packages into the interpreter's
-global context, by default, and should instead guide the end user
-towards using a virtual environment.
-
 It also standardizes an interpretation of the ``sysconfig`` schemes so
 that, if a Python-specific package manager is about to install a
 package in an interpreter-wide context, it can do so in a manner that
 will avoid conflicting with the external package manager and reduces
 the risk of breaking software shipped by the external package manager.
 
+
 Terminology
 ===========
 
-A few terms used in this PEP have multiple meanings in the contexts
-that it spans. For clarity, this PEP uses the following terms in
-specific ways:
+A few terms used in this specification have multiple meanings in the
+contexts that it spans. For clarity, this specification uses the following
+terms in specific ways:
 
 distro
     Short for "distribution," a collection of various sorts of
@@ -104,12 +63,10 @@ distro
 package
     A unit of software that can be installed and used within Python.
     That is, this refers to what Python-specific packaging tools tend
-    to call a "`distribution package`_" or simply a "distribution";
+    to call a :term:`distribution package` or simply a "distribution";
     the colloquial abbreviation "package" is used in the sense of the
     Python Package Index.
 
-    .. _`distribution package`: https://packaging.python.org/glossary/#term-Distribution-Package
-
     This document does not use "package" in the sense of an importable
     name that contains Python modules, though in many cases, a
     distribution package consists of a single importable package of
@@ -123,26 +80,36 @@ package
     plus the Python package name.)
 Python-specific package manager
     A tool for installing, upgrading, and/or removing Python packages
-    in a manner that conforms to Python packaging standards (such as
-    :pep:`376` and :pep:`427`). The most popular Python-specific package
-    manager is pip [#pip]_; other examples include the old Easy
-    Install command [#easy-install]_ as well as direct usage of a
+    in a manner that conforms to Python packaging standards.
+    The most popular Python-specific package
+    manager is pip_; other examples include the old `Easy
+    Install command `_ as well as direct usage of a
     ``setup.py`` command.
 
-    (Conda [#conda]_ is a bit of a special case, as the ``conda``
+    .. _pip: https://pip.pypa.io/en/stable/
+    .. _easy-install: https://setuptools.readthedocs.io/en/latest/deprecated/easy_install.html
+
+    (Note that the ``easy_install`` command was removed in
+    setuptools version 52, released 23 January 2021.)
+
+
+    (Conda_ is a bit of a special case, as the ``conda``
     command can install much more than just Python packages, making it
     more like a distro package manager in some senses. Since the
     ``conda`` command generally only operates on Conda-created
     environments, most of the concerns in this document do not apply
     to ``conda`` when acting as a Python-specific package manager.)
+
+    .. _conda: https://conda.io
 distro package manager
     A tool for installing, upgrading, and/or removing a distro's
     packages in an installed instance of that distro, which is capable
     of installing Python packages as well as non-Python packages, and
     therefore generally has its own database of installed software
-    unrelated to :pep:`376`. Examples include ``apt``, ``dpkg``, ``dnf``,
-    ``rpm``, ``pacman``, and ``brew``. The salient feature is that if
-    a package was installed by a distro package manager, removing or
+    unrelated to the :ref:`database of installed distributions
+    `. Examples include ``apt``, ``dpkg``,
+    ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is
+    that if a package was installed by a distro package manager, removing or
     upgrading it in a way that would satisfy a Python-specific package
     manager will generally leave a distro package manager in an
     inconsistent state.
@@ -159,83 +126,12 @@ shadow
     a later ``sys.path`` entry, then ``import a`` returns the module
     from the former, and we say that A 2.0 shadows A 1.0.
 
-Motivation
-==========
-
-Thanks to Python's immense popularity, software distros (by which we
-mean Linux and other OS distros as well as overlay distros like
-Homebrew and MacPorts) generally ship Python for two purposes: as a
-software package to be used in its own right by end users, and as a
-language dependency for other software in the distro.
-
-For example, Fedora and Debian (and their downstream distros, as well
-as many others) ship a ``/usr/bin/python3`` binary which provides the
-``python3`` command available to end users as well as the
-``#!/usr/bin/python3`` shebang for Python-language software included
-in the distro. Because there are no official binary releases of Python
-for Linux/UNIX, almost all Python end users on these OSes use the
-Python interpreter built and shipped with their distro.
-
-The ``python3`` executable available to the users of the distro and
-the ``python3`` executable available as a dependency for other
-software in the distro are typically the same binary. This means that
-if an end user installs a Python package using a tool like ``pip``
-outside the context of a virtual environment, that package is visible
-to Python-language software shipped by the distro. If the
-newly-installed package (or one of its dependencies) is a newer,
-backwards-incompatible version of a package that was installed through
-the distro, it may break software shipped by the distro.
-
-This may pose a critical problem for the integrity of distros, which
-often have package-management tools that are themselves written in
-Python. For example, it's possible to unintentionally break Fedora's
-``dnf`` command with a ``pip install`` command, making it hard to
-recover.
-
-This applies both to system-wide installs (``sudo pip install``) as
-well as user home directory installs (``pip install --user``), since
-packages in either location show up on the ``sys.path`` of
-``/usr/bin/python3``.
-
-There is a worse problem with system-wide installs: if you attempt to
-recover from this situation with ``sudo pip uninstall``, you may end
-up removing packages that are shipped by the system's package manager.
-In fact, this can even happen if you simply upgrade a package - pip
-will try to remove the old version of the package, as shipped by the
-OS. At this point it may not be possible to recover the system to a
-consistent state using just the software remaining on the system.
-
-Over the past many years, a consensus has emerged that the best way to
-install Python libraries or applications (when not using a distro's
-package) is to use a virtual environment. This approach was
-popularized by the PyPA `virtualenv`_ project, and a simple version of
-that approach is now available in the Python standard library as
-``venv``. Installing a Python package into a virtualenv prevents it
-from being visible to the unqualified ``/usr/bin/python3`` interpreter
-and prevents breaking system software.
-
-.. _virtualenv: https://virtualenv.pypa.io/en/latest/
-
-In some cases, however, it's useful and intentional to install a
-Python package from outside of the distro that influences the behavior
-of distro-shipped commands. This is common in the case of software
-like Sphinx or Ansible which have a mechanism for writing
-Python-language extensions. A user may want to use their distro's
-version of the base software (for reasons of paid support or security
-updates) but install a small extension from PyPI, and they'd want that
-extension to be importable by the software in their base system.
-
-While this continues to carry the risk of installing a newer version
-of a dependency than the operating system expects or otherwise
-negatively affecting the behavior of an application, it does not need
-to carry the risk of removing files from the operating system. A tool
-like pip should be able to install packages in some directory on the
-default ``sys.path``, if specifically requested, without deleting
-files owned by the system's package manager.
-
-Therefore, this PEP proposes two things.
-
-First, it proposes **a way for distributors of a Python interpreter to
+Overview
+========
+
+This specification is twofold.
+
+First, it describes **a way for distributors of a Python interpreter to
 mark that interpreter as having its packages managed by means external
 to Python**, such that Python-specific tools like pip should not
 change the installed packages in the interpreter's global ``sys.path``
@@ -259,284 +155,9 @@ managed packages, and one for unmanaged packages installed by the end
 user, and ensure that installing unmanaged packages will not delete
 (or overwrite) files owned by the external package manager.
 
-Rationale
-=========
-
-As described in detail in the next section, the first behavior change
-involves creating a marker file named ``EXTERNALLY-MANAGED``, whose
-presence indicates that non-virtual-environment package installations
-are managed by some means external to Python, such as a distro's
-package manager. This file is specified to live in the ``stdlib``
-directory in the default ``sysconfig`` scheme, which marks the
-interpreter / installation as a whole, not a particular location on
-``sys.path``. The reason for this is that, as identified above, there
-are two related problems that risk breaking an externally-managed
-Python: you can install an incompatible new version of a package
-system-wide (e.g., with ``sudo pip install``), and you can install one
-in your user account alone, but in a location that is on the standard
-Python command's ``sys.path`` (e.g., with ``pip install --user``). If
-the marker file were in the system-wide ``site-packages`` directory,
-it would not clearly apply to the second case. The `Alternatives`_
-section has further discussion of possible locations.
-
-The second behavior change takes advantage of the existing
-``sysconfig`` setup in distros that have already encountered this
-class of problem, and specifically addresses the problem of a
-Python-specific package manager deleting or overwriting files that are
-owned by an external package manager.
-
-Use cases
----------
-
-The changed behavior in this PEP is intended to "do the right thing"
-for as many use cases as possible. In this section, we consider the
-changes specified by this PEP for several representative use cases /
-contexts. Specifically, we ask about the two behaviors that could be
-changed by this PEP:
-
-1. Will a Python-specific installer tool like ``pip install`` permit
-   installations by default, after implementation of this PEP?
-
-2. If you do run such a tool, should it be willing to delete packages
-   shipped by the external (non-Python-specific) package manager for
-   that context, such as a distro package manager?
-
-(For simplicity, this section discusses pip as the Python-specific
-installer tool, though the analysis should apply equally to any other
-Python-specific package management tool.)
-
-This table summarizes the use cases discussed in detail below:
-
-==== ================================= =========================== ===================================================
-Case Description                       ``pip install`` permitted   Deleting externally-installed packages permitted
-==== ================================= =========================== ===================================================
-1    Unpatched CPython                 Currently yes; stays yes    Currently yes; stays yes
-2    Distro ``/usr/bin/python3``       Currently yes; becomes no   Currently yes (except on Debian); becomes no
-                                       (assuming the distro
-                                       adds a marker file)
-3    Distro Python in venv             Currently yes; stays yes    There are no externally-installed packages
-4    Distro Python in venv             Currently yes; stays yes    Currently no; stays no
-     with ``--system-site-packages``
-5    Distro Python in Docker           Currently yes; becomes no    Currently yes; becomes no
-                                       (assuming the distro
-                                       adds a marker file)
-6    Conda environment                 Currently yes; stays yes    Currently yes; stays yes
-7    Dev-facing distro                 Currently yes; becomes no   Currently often yes; becomes no
-                                       (assuming they add a        (assuming they configure ``sysconfig`` as needed)
-                                       marker file)
-8    Distro building packages          Currently yes; can stay yes Currently yes; becomes no
-9    ``PYTHONHOME`` copied from        Currently yes; becomes no   Currently yes; becomes no
-     a distro Python stdlib
-10   ``PYTHONHOME`` copied from        Currently yes; stays yes    Currently yes; stays yes
-     upstream Python stdlib
-==== ================================= =========================== ===================================================
-
-In more detail, the use cases above are:
-
-1. A standard unpatched CPython, without any special configuration of
-   or patches to ``sysconfig`` and without a marker file. This PEP
-   does not change its behavior.
-
-   Such a CPython should (regardless of this PEP) not be installed in
-   a way that overlaps any distro-installed Python on the same system.
-   For instance, on an OS that ships Python in ``/usr/bin``, you
-   should not install a custom CPython built with ``./configure
-   --prefix=/usr``, or it will overwrite some files from the distro
-   and the distro will eventually overwrite some files from your
-   installation. Instead, your installation should be in a separate
-   directory (perhaps ``/usr/local``, ``/opt``, or your home
-   directory).
-
-   Therefore, we can assume that such a CPython has its own ``stdlib``
-   directory and its own ``sysconfig`` schemes that do not overlap any
-   distro-installed Python. So any OS-installed packages are not
-   visible or relevant here.
-
-   If there is a concept of "externally-installed" packages in this
-   case, it's something outside the OS and generally managed by
-   whoever built and installed this CPython. Because the installer
-   chose not to add a marker file or modify ``sysconfig`` schemes,
-   they're choosing the current behavior, and ``pip install`` can
-   remove any packages available in this CPython.
-
-2. A distro's ``/usr/bin/python3``, either when running ``pip
-   install`` as root or ``pip install --user``, following our
-   `Recommendations for distros`_.
-
-   These recommendations include shipping a marker file in the
-   ``stdlib`` directory, to prevent ``pip install`` by default, and
-   placing distro-shipped packages in a location other than the
-   default ``sysconfig`` scheme, so that ``pip`` as root does not
-   write to that location.
-
-   Many distros (including Debian, Fedora, and their derivatives) are
-   already doing the latter.
-
-   On Debian and derivatives, ``pip install`` does not currently
-   delete distro-installed packages, because Debian carries a `patch
-   to pip to prevent this`__. So, for those distros, this PEP is not a
-   behavior change; it simply standardizes that behavior in a way that
-   is no longer Debian-specific and can be included into upstream pip.
-
-   .. __: https://sources.debian.org/src/python-pip/20.3.4-2/debian/patches/hands-off-system-packages.patch/
-
-   (We have seen user reports of externally-installed packages being
-   deleted on Debian or a derivative. We suspect this is because the
-   user has previously run ``sudo pip install --upgrade pip`` and
-   therefore now has a version of ``/usr/bin/pip`` without the Debian
-   patch; standardizing this behavior in upstream package installers
-   would address this problem.)
-
-3. A distro Python when used inside a virtual environment (either from
-   ``venv`` or ``virtualenv``).
-
-   Inside a virtual environment, all packages are owned by that
-   environment. Even when ``pip``, ``setuptools``, etc. are installed
-   into the environment, they are and should be managed by tools
-   specific to that environment; they are not system-managed.
-
-4. A distro Python when used inside a virtual environment with
-   ``--system-site-packages``. This is like the previous case, but
-   worth calling out explicitly, because anything on the global
-   ``sys.path`` is visible.
-
-   Currently, the answer to "Will ``pip`` delete externally-installed
-   packages" is no, because pip has a special case for running in a
-   virtual environment and attempting to delete packages outside it.
-   After this PEP, the answer remains no, but the reasoning becomes
-   more general: system site packages will be outside any of the
-   ``sysconfig`` schemes used for package management in the
-   environment.
-
-5. A distro Python when used in a single-application container image
-   (e.g., a Docker container). In this use case, the risk of breaking
-   system software is lower, since generally only a single application
-   runs in the container, and the impact is lower, since you can
-   rebuild the container and you don't have to struggle to recover a
-   running machine. There are also a large number of existing
-   Dockerfiles with an unqualified ``RUN pip install ...`` statement,
-   etc., and it would be good not to break those. So, builders of base
-   container images may want to ensure that the marker file is not
-   present, even if the underlying OS ships one by default.
-
-   There is a small behavior change: currently, ``pip`` run as root
-   will delete externally-installed packages, but after this PEP it
-   will not. We don't propose a way to override this. However, since
-   the base image is generally minimal, there shouldn't be much of a
-   use case for simply uninstalling packages (especially without using
-   the distro's own tools). The common case is when pip wants to
-   upgrade a package, which previously would have deleted the old
-   version (except on Debian). After this change, the old version will
-   still be on disk, but pip will still *shadow* externally-installed
-   packages, and we believe this to be sufficient for this not to be a
-   breaking change in practice - a Python ``import`` statement will
-   still get you the newly-installed package.
-
-   If it becomes necessary to have a way to do this, we suggest that
-   the distro should document a way for the installer tool to access
-   the ``sysconfig`` scheme used by the distro itself. See the
-   `Recommendations for distros`_ section for more discussion.
-
-   It is the view of the authors of this PEP that it's still a good
-   idea to use virtual environments with distro-installed Python
-   interpreters, even in single-application container images. Even
-   though they run a single *application*, that application may run
-   commands from the OS that are implemented in Python, and if you've
-   installed or upgraded the distro-shipped Python packages using
-   Python-specific tools, those commands may break.
-
-6. Conda specifically supports the use of non-``conda`` tools like pip
-   to install software not available in the Conda repositories. In
-   this context, Conda acts as the external package manager / distro
-   and pip as the Python-specific one.
-
-   In some sense, this is similar to the first case, since Conda
-   provides its own installation of the Python interpreter.
-
-   We don't believe this PEP requires any changes to Conda, and
-   versions of pip that have implemented the changes in this PEP will
-   continue to behave as they currently do inside Conda environments.
-   (That said, it may be worth considering whether to use separate
-   ``sysconfig`` schemes for pip-installed and Conda-installed
-   software, for the same reasons it's a good idea for other distros.)
-
-7. By a "developer-facing distro," we mean a specific type of distro
-   where direct users of Python or other languages in the distro are
-   expected or encouraged to make changes to the distro itself if they
-   wish to add libraries. Common examples include private "monorepos"
-   at software development companies, where a single repository builds
-   both third-party and in-house software, and the direct users of the
-   distro's Python interpreter are generally software developers
-   writing said in-house software. User-level package managers like
-   Nixpkgs_ may also count, because they encourage users of Nix who
-   are Python developers to `package their software for Nix`__.
-
-   In these cases, the distro may want to respond to an attempted
-   ``pip install`` with guidance encouraging use of the distro's own
-   facilities for adding new packages, along with a link to
-   documentation.
-
-   If the distro supports/encourages creating a virtual environment
-   from the distro's Python interpreter, there may also be custom
-   instructions for how to properly set up a virtual environment (as
-   for example Nixpkgs does).
-
-   .. _Nixpkgs: https://github.com/NixOS/nixpkgs
-
-   .. __: https://nixos.wiki/wiki/Python
-
-8. When building distro Python packages for a distro Python (case 2),
-   it may be useful to have ``pip install`` be usable as part of the
-   distro's package build process. (Consider, for instance, building a
-   ``python-xyz`` RPM by using ``pip install .`` inside an sdist /
-   source tarball for ``xyz``.) The distro may also want to use a more
-   targeted but still Python-specific installation tool such as
-   installer_.
-
-   .. _installer: https://installer.rtfd.io/
-
-   For this case, the build process will need to find some way to
-   suppress the marker file to allow ``pip install`` to work, and will
-   probably need to point the Python-specific tool at the distro's
-   ``sysconfig`` scheme instead of the shipped default. See the
-   `Recommendations for distros`_ section for more discussion on how
-   to implement this.
-
-   As a result of this PEP, pip will no longer be able to remove
-   packages already on the system. However, this behavior change is
-   fine because a package build process should not (and generally
-   cannot) include instructions to delete some other files on the
-   system; it can only package up its own files.
-
-9. A distro Python used with ``PYTHONHOME`` to set up an alternative
-   Python environment (as opposed to a virtual environment), where
-   ``PYTHONHOME`` is set to some directory copied directly from the
-   distro Python (e.g., ``cp -a /usr/lib/python3.x pyhome/lib``).
-
-   Assuming there are no modifications, then the behavior is just like
-   the underlying distro Python (case 2). So there are behavior
-   changes - you can no longer ``pip install`` by default, and if you
-   override it, it will no longer delete externally-installed packages
-   (i.e., Python packages that were copied from the OS and live in the
-   OS-managed ``sys.path`` entry).
-
-   This behavior change seems to be defensible, in that if your
-   ``PYTHONHOME`` is a straight copy of the distro's Python, it should
-   behave like the distro's Python.
-
-10. A distro Python (or any Python interpreter) used with a
-    ``PYTHONHOME`` taken from a compatible unmodified upstream Python.
-
-    Because the behavior changes in this PEP are keyed off of files in
-    the standard library (the marker file in ``stdlib`` and the
-    behavior of the ``sysconfig`` module), the behavior is just like
-    an unmodified upstream CPython (case 1).
-
-Specification
-=============
 
 Marking an interpreter as using an external package manager
------------------------------------------------------------
+===========================================================
 
 Before a Python-specific package installer (that is, a tool such as
 pip - not an external tool such as apt) installs a package into a
@@ -544,12 +165,10 @@ certain Python context, it should make the following checks by
 default:
 
 1. Is it running outside of a virtual environment? It can determine
-   this by whether ``sys.prefix == sys.base_prefix`` (but see
-   `Backwards Compatibility`_).
+   this by whether ``sys.prefix == sys.base_prefix``.
 
 2. Is there an ``EXTERNALLY-MANAGED`` file in the directory identified
-   by ``sysconfig.get_path("stdlib",
-   sysconfig.get_default_scheme())``?
+   by ``sysconfig.get_path("stdlib", sysconfig.get_default_scheme())``?
 
 If both of these conditions are true, the installer should exit with
 an error message indicating that package installation into this Python
@@ -590,7 +209,7 @@ should, in general, ship a ``EXTERNALLY-MANAGED`` file in their
 standard library directory. For instance, Debian may ship a file in
 ``/usr/lib/python3.9/EXTERNALLY-MANAGED`` consisting of something like
 
-::
+.. code-block:: ini
 
     [externally-managed]
     Error=To install Python packages system-wide, try apt install
@@ -612,7 +231,7 @@ which provides useful and distro-relevant information
 to a user trying to install a package. Optionally,
 translations can be provided in the same file:
 
-::
+.. code-block:: ini
 
     Error-de_DE=Wenn ist das Nunstück git und Slotermeyer?
 
@@ -625,7 +244,7 @@ like (as they can today) without having to manually override this
 rule.
 
 Writing to only the target ``sysconfig`` scheme
------------------------------------------------
+===============================================
 
 Usually, a Python package installer installs to directories in a
 scheme returned by the ``sysconfig`` standard library package.
@@ -634,7 +253,7 @@ Ordinarily, this is the scheme returned by
 ``pip install --user``), it may use a different scheme.
 
 Whenever the installer is installing to a ``sysconfig`` scheme, this
-PEP specifies that the installer should never modify or delete files
+specification declares that the installer should never modify or delete files
 outside of that scheme. For instance, if it's upgrading a package, and
 the package is already installed in a directory outside that scheme
 (perhaps in a directory from another scheme), it should leave the
@@ -729,7 +348,7 @@ Filesystem Hierarchy Standard`__.
 
 There are two ways you could do this. One is, if you are building and
 packaging Python libraries directly (e.g., your packaging helpers
-unpack a :pep:`517`-built wheel or call ``setup.py install``), arrange
+unpack a wheel or call ``setup.py install``), arrange
 for those tools to use a directory that is not in a ``sysconfig``
 scheme but is still on ``sys.path``.
 
@@ -753,8 +372,7 @@ something like ``pip install --scheme=posix_distro`` to explicitly
 install a package into your distro's location (bypassing
 ``get_preferred_schemes``). One could also, if absolutely needed, use
 ``pip uninstall --scheme=posix_distro`` to use pip to remove packages
-from the system-managed directory, which addresses the (hopefully
-theoretical) regression in use case 5 in Rationale_.
+from the system-managed directory.
 
 To install packages with pip, you would also need to either suppress
 the ``EXTERNALLY-MANAGED`` marker file to allow pip to run or to
@@ -787,245 +405,6 @@ compiler's search path, and it will use ``/usr/local/bin`` for the
 default scheme's ``scripts`` and ``/usr/bin`` for distro-packaged
 entry points and place both on ``$PATH``.
 
-Backwards Compatibility
-=======================
-
-All of these mechanisms are proposed for new distro releases and new
-versions of tools like pip only.
-
-In particular, we strongly recommend that distros with a concept of
-major versions only add the marker file or change ``sysconfig``
-schemes in a new major version; otherwise there is a risk that, on an
-existing system, software installed via a Python-specific package
-manager now becomes unmanageable (without an override option). For a
-rolling-release distro, if possible, only add the marker file or
-change ``sysconfig`` schemes in a new Python minor version.
-
-One particular backwards-compatibility difficulty for package
-installation tools is likely to be managing environments created by
-old versions of ``virtualenv`` which have the latest version of the
-tool installed. A "virtual environment" now has a fairly precise
-definition: it uses the ``pyvenv.cfg`` mechanism, which causes
-``sys.base_prefix != sys.prefix``. It is possible, however, that a
-user may have an old virtual environment created by an older version
-of ``virtualenv``; as of this writing, pip supports Python 3.6
-onwards, which is in turn supported by ``virtualenv`` 15.1.0 onwards,
-so this scenario is possible. In older versions of ``virtualenv``, the
-mechanism is instead to set a new attribute, ``sys.real_prefix``, and
-it does not use the standard library support for virtual environments,
-so ``sys.base_prefix`` is the same as ``sys.prefix``. So the logic for
-robustly detecting a virtual environment is something like::
-
-    def is_virtual_environment():
-        return sys.base_prefix != sys.prefix or hasattr(sys, "real_prefix")
-
-Security Implications
-=====================
-
-The purpose of this feature is not to implement a security boundary;
-it is to discourage well-intended changes from unexpectedly breaking a
-user's environment. That is to say, the reason this PEP restricts
-``pip install`` outside a virtual environment is not that it's a
-security risk to be able to do so; it's that "There should be one--
-and preferably only one --obvious way to do it," and that way should
-be using a virtual environment. ``pip install`` outside a virtual
-environment is rather too obvious for what is almost always the wrong
-way to do it.
-
-If there is a case where a user should not be able to ``sudo pip
-install`` or ``pip install --user`` and add files to ``sys.path`` *for
-security reasons*, that needs to be implemented either via access
-control rules on what files the user can write to or an explicitly
-secured ``sys.path`` for the program in question. Neither of the
-mechanisms in this PEP should be interpreted as a way to address such
-a scenario.
-
-For those reasons, an attempted install with a marker file present is
-not a security incident, and there is no need to raise an auditing
-event for it. If the calling user legitimately has access to ``sudo
-pip install`` or ``pip install --user``, they can accomplish the same
-installation entirely outside of Python; if they do not legitimately
-have such access, that's a problem outside the scope of this PEP.
-
-The marker file itself is located in the standard library directory,
-which is a trusted location (i.e., anyone who can write to the marker
-file used by a particular installer could, presumably, run arbitrary
-code inside the installer). Therefore, there is generally no need to
-filter out terminal escape sequences or other potentially-malicious
-content in the error message.
-
-Alternatives
-==============
-
-There are a number of similar proposals we considered that this PEP
-rejects or defers, largely to preserve the behavior in the
-case-by-case analysis in Rationale_.
-
-Marker file
------------
-
-Should the marker file be in ``sys.path``, marking a particular
-directory as not to be written to by a Python-specific package
-manager? This would help with the second problem addressed by this PEP
-(not overwriting deleting distro-owned files) but not the first
-(incompatible installs). A directory-specific marker in
-``/usr/lib/python3.x/site-packages`` would not discourage
-installations into either ``/usr/local/lib/python3.x/site-packages``
-or ``~/.local/lib/python3.x/site-packages``, both of which are on
-``sys.path`` for ``/usr/bin/python3``. In other words, the marker file
-should not be interpreted as marking a single *directory* as
-externally managed (even though it happens to be in a directory on
-``sys.path``); it marks the entire *Python installation* as externally
-managed.
-
-Another variant of the above: should the marker file be in
-``sys.path``, where if it can be found in any directory in
-``sys.path``, it marks the installation as externally managed? An
-apparent advantage of this approach is that it automatically disables
-itself in virtual environments. Unfortunately, This has the wrong
-behavior with a ``--system-site-packages`` virtual environment, where
-the system-wide ``sys.path`` is visible but package installations are
-allowed. (It could work if the rule of exempting virtual environments
-is preserved, but that seems to have no advantage over the current
-scheme.)
-
-Should the marker just be a new attribute of a ``sysconfig`` scheme?
-There is some conceptual cleanliness to this, except that it's hard to
-override. We want to make it easy for container images, package build
-environments, etc. to suppress the marker file. A file that you can
-remove is easy; code in ``sysconfig`` is much harder to modify.
-
-Should the file be in ``/etc``? No, because again, it refers to a
-specific Python installation. A user who installs their own Python may
-well want to install packages within the global context of that
-interpreter.
-
-Should the configuration setting be in ``pip.conf`` or
-``distutils.cfg``? Apart from the above objections about marking an
-installation, this mechanism isn't specific to either of those tools.
-(It seems reasonable for pip to *also* implement a configuration flag
-for users to prevent themselves from performing accidental
-non-virtual-environment installs in any Python installation, but that
-is outside the scope of this PEP.)
-
-Should the file be TOML? TOML is gaining popularity for packaging (see
-e.g. :pep:`517`) but does not yet have an implementation in the standard
-library. Strictly speaking, this isn't a blocker - distros need only
-write the file, not read it, so they don't need a TOML library (the
-file will probably be written by hand, regardless of format), and
-packaging tools likely have a TOML reader already. However, the INI
-format is currently used for various other forms of packaging metadata
-(e.g., ``pydistutils.cfg`` and ``setup.cfg``), meets our needs, and is
-parsable by the standard library, and the pip maintainers expressed a
-preference to avoid using TOML for this yet.
-
-Should the file be ``email.message``-style? While this format is also
-used for packaging metadata (e.g. sdist and wheel metadata) and is
-also parsable by the standard library, it doesn't handle multi-line
-entries quite as clearly, and that is our primary use case.
-
-Should the marker file be executable Python code that evaluates
-whether installation should be allowed or not? Apart from the concerns
-above about having the file in ``sys.path``, we have a concern that
-making it executable is committing to too powerful of an API and risks
-making behavior harder to understand. (Note that the
-``get_default_scheme`` hook of bpo-43976_ is in fact executable, but
-that code needs to be supplied when the interpreter builds; it isn't
-intended to be supplied post-build.)
-
-When overriding the marker, should a Python-specific package manager
-be disallowed from shadowing a package installed by the external
-package manager (i.e., installing modules of the same name)? This
-would minimize the risk of breaking system software, but it's not
-clear it's worth the additional user experience complexity. There are
-legitimate use cases for shadowing system packages, and an additional
-command-line option to permit it would be more confusing. Meanwhile,
-not passing that option wouldn't eliminate the risk of breaking system
-software, which may be relying on a ``try: import xyz`` failing,
-finding a limited set of entry points, etc. Communicating this
-distinction seems difficult. We think it's a good idea for
-Python-specific package managers to print a warning if they shadow a
-package, but we think it's not worth disabling it by default.
-
-Why not use the ``INSTALLER`` file from :pep:`376` to determine who
-installed a package and whether it can be removed? First, it's
-specific to a particular package (it's in the package's ``dist-info``
-directory), so like some of the alternatives above, it doesn't provide
-information on an entire environment and whether package installations
-are permissible. :pep:`627` also updates :pep:`376` to prevent programmatic
-use of ``INSTALLER``, specifying that the file is "to be used for
-informational purposes only. [...] Our goal is supporting
-interoperating tools, and basing any action on which tool happened to
-install a package runs counter to that goal." Finally, as :pep:`627`
-envisions, there are legitimate use cases for one tool knowing how to
-handle packages installed by another tool; for instance, ``conda`` can
-safely remove a package installed by ``pip`` into a Conda environment.
-
-Why does the specification give no means for disabling package
-installations inside a virtual environment? We can't see a
-particularly strong use case for it (at least not one related to the
-purposes of this PEP). If you need it, it's simple enough to ``pip
-uninstall pip`` inside that environment, which should discourage at
-least unintentional changes to the environment (and this specification
-makes no provision to disable *intentional* changes, since after all
-the marker file can be easily removed).
-
-System Python
--------------
-
-Shouldn't distro software just run with the distro ``site-packages``
-directory alone on ``sys.path`` and ignore the local system
-administrator's ``site-packages`` as well as the user-specific one?
-This is a worthwhile idea, and various versions of it have been
-circulating for a while under the name of "system Python" or "platform
-Python" (with a separate "user Python" for end users writing Python or
-installing Python software separate from the system). However, it's
-much more involved of a change. First, it would be a
-backwards-incompatible change. As mentioned in the Motivation_
-section, there are valid use cases for running distro-installed Python
-applications like Sphinx or Ansible with locally-installed Python
-libraries available on their ``sys.path``. A wholesale switch to
-ignoring local packages would break these use cases, and a distro
-would have to make a case-by-case analysis of whether an application
-ought to see locally-installed libraries or not.
-
-Furthermore, `Fedora attempted this change and reverted it`_, finding,
-ironically, that their implementation of the change `broke their
-package manager`_. Given that experience, there are clearly details to
-be worked out before distros can reliably implement that approach, and
-a PEP recommending it would be premature.
-
-.. _`Fedora attempted this change and reverted it`: https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/thread/SEFUWW4XZBTVOAQ36XOJQ72PIICMFOSN/
-.. _`broke their package manager`: https://bugzilla.redhat.com/show_bug.cgi?id=1483342
-
-This PEP is intended to be a complete and self-contained change that
-is independent of a distributor's decision for or against "system
-Python" or similar proposals. It is not incompatible with a distro
-implementing "system Python" in the future, and even though both
-proposals address the same class of problems, there are still
-arguments in favor of implementing something like "system Python" even
-after implementing this PEP. At the same time, though, this PEP
-specifically tries to make a more targeted and minimal change, such
-that it can be implemented by distributors who don't expect to adopt
-"system Python" (or don't expect to implement it immediately). The
-changes in this PEP stand on their own merits and are not an
-intermediate step for some future proposal. This PEP reduces (but does
-not eliminate) the risk of breaking system software while minimizing
-(but not completely avoiding) breaking changes, which should therefore
-be much easier to implement than the full "system Python" idea, which
-comes with the downsides mentioned above.
-
-We expect that the guidance in this PEP - that users should use
-virtual environments whenever possible and that distros should have
-separate ``sys.path`` directories for distro-managed and
-locally-managed modules - should make further experiments easier in
-the future. These may include distributing wholly separate "system"
-and "user" Python interpreters, running system software out of a
-distro-owned virtual environment or ``PYTHONHOME`` (but shipping a
-single interpreter), or modifying the entry points for certain
-software (such as the distro's package manager) to use a ``sys.path``
-that only sees distro-managed directories. Those ideas themselves,
-however, remain outside the scope of this PEP.
 
 Implementation Notes
 ====================
@@ -1033,9 +412,9 @@ Implementation Notes
 This section is non-normative and contains notes relevant to both the
 specification and potential implementations.
 
-Currently, pip does not directly expose a way to choose a target
-``sysconfig`` scheme, but it has three ways of looking up schemes when
-installing:
+Currently (as of May 2021), pip does not directly expose a way to choose
+a target ``sysconfig`` scheme, but it has three ways of looking up schemes
+when installing:
 
 ``pip install``
     Calls ``sysconfig.get_default_scheme()``, which is usually (in
@@ -1078,36 +457,8 @@ message from it, may as well get added to the standard library
 (``sys`` and ``sysconfig``, respectively), to centralize their
 implementations, but they don't need to be added yet.
 
-References
-==========
-
-For additional background on these problems and previous attempts to
-solve them, see `Debian bug 771794`_ "pip silently removes/updates
-system provided python packages" from 2014, Fedora's 2018 article
-`Making sudo pip safe`_ about pointing ``sudo pip`` at /usr/local
-(which acknowledges that the changes still do not make ``sudo pip``
-completely safe), pip issues 5605_ ("Disable upgrades to existing
-python modules which were not installed via pip") and 5722_ ("pip
-should respect /usr/local") from 2018, and the post-PyCon US 2019
-discussion thread `Playing nice with external package managers`_.
-
-.. _`Debian bug 771794`: https://bugs.debian.org/771794
-
-.. _`Making sudo pip safe`: https://fedoraproject.org/wiki/Changes/Making_sudo_pip_safe
 
-.. _5605: https://github.com/pypa/pip/issues/5605
 
-.. _5722: https://github.com/pypa/pip/issues/5722
-
-.. _`Playing nice with external package managers`: https://discuss.python.org/t/playing-nice-with-external-package-managers/1968
-
-.. [#pip] https://pip.pypa.io/en/stable/
-
-.. [#easy-install] https://setuptools.readthedocs.io/en/latest/deprecated/easy_install.html
-   (Note that the ``easy_install`` command was removed in
-   setuptools version 52, released 23 January 2021.)
-
-.. [#Conda] https://conda.io
 
 Copyright
 =========
@@ -1119,4 +470,5 @@ CC0-1.0-Universal license, whichever is more permissive.
 
 History
 =======
-- `June 2022 `_: ``EXTERNALLY-MANAGED`` marker file was originally specified in :pep:`668#marking-an-interpreter-as-using-an-external-package-manager`.
+
+This specification was originally approved as :pep:`668`.

From eaf379c830380c9f8ff4b01e8b8a747b08dbf18a Mon Sep 17 00:00:00 2001
From: Laurie O 
Date: Thu, 9 Nov 2023 10:49:26 +1000
Subject: [PATCH 145/733] Better http.server links

Docs link uses intersphinx, issues link uses GitHub role

Co-authored-by: chrysle 
---
 source/key_projects.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index b386a8f2d..7a56f0b8b 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -850,8 +850,8 @@ build of the Python distribution.
 http.server
 ===========
 
-`Docs `__ |
-`Issues `__
+`Docs `__ |
+:gh:`Issues `
 
 A package and command-line interface which can host a directory as a
 website, for example as a :term:`package index ` (see

From 4c0a016ed268de9e0036e38186bc9faea64343fb Mon Sep 17 00:00:00 2001
From: Laurie O 
Date: Thu, 9 Nov 2023 10:50:18 +1000
Subject: [PATCH 146/733] Document simpleindex use of multiple directories

Co-authored-by: chrysle 
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 7a56f0b8b..414ebc28f 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -790,7 +790,7 @@ simpleindex
 
 simpleindex is a :term:`package index ` which routes URLs to
 multiple package indexes (including PyPI), serves local (or cloud-hosted,
-for example `AWS S3`_, with a custom plugin) directory of packages, and
+for example `AWS S3`_, with a custom plugin) directories of packages, and
 supports custom plugins.
 
 .. _spack:

From 646f612a84434964dd411b6be5650360a8f267c3 Mon Sep 17 00:00:00 2001
From: Laurie O 
Date: Thu, 9 Nov 2023 18:14:07 +1000
Subject: [PATCH 147/733] Fix Python std-lib doc link

---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 414ebc28f..f9f7dcbea 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -850,7 +850,7 @@ build of the Python distribution.
 http.server
 ===========
 
-`Docs `__ |
+:doc:`Docs ` |
 :gh:`Issues `
 
 A package and command-line interface which can host a directory as a

From ffff0a33d8b434f99620ef732a4a0d620c49cb1b Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade 
Date: Thu, 9 Nov 2023 16:13:31 +0200
Subject: [PATCH 148/733] Replace 'PEP' with 'specification'

---
 source/specifications/version-specifiers.rst | 28 ++++++++++----------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index 0d8b22334..acf3167c7 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -101,7 +101,7 @@ aside from always being the lowest possible value in the version ordering.
    across existing public and private Python projects.
 
    Accordingly, some of the versioning practices which are technically
-   permitted by the PEP are strongly discouraged for new projects. Where
+   permitted by the specification are strongly discouraged for new projects. Where
    this is the case, the relevant details are noted in the following
    sections.
 
@@ -631,7 +631,7 @@ are permitted and MUST be ordered as shown::
 Note that ``c`` is considered to be semantically equivalent to ``rc`` and must
 be sorted as if it were ``rc``. Tools MAY reject the case of having the same
 ``N`` for both a ``c`` and a ``rc`` in the same release segment as ambiguous
-and remain in compliance with the PEP.
+and remain in compliance with the specification.
 
 Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate
 (``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be
@@ -692,9 +692,9 @@ versions of a project.
 
 Due to the above, this specification MUST be used for all versions of metadata and
 supersedes :pep:`386` even for metadata v1.2. Tools SHOULD ignore any versions
-which cannot be parsed by the rules in this PEP, but MAY fall back to
+which cannot be parsed by the rules in this specification, but MAY fall back to
 implementation defined version parsing and ordering schemes if no versions
-complying with this PEP are available.
+complying with this specification are available.
 
 Distribution users may wish to explicitly remove non-compliant versions from
 any private package indexes they control.
@@ -705,7 +705,7 @@ Compatibility with other version schemes
 
 Some projects may choose to use a version scheme which requires
 translation in order to comply with the public version scheme defined in
-this PEP. In such cases, the project specific version can be stored in the
+this specification. In such cases, the project specific version can be stored in the
 metadata while the translated public version is published in the version field.
 
 This allows automated distribution tools to provide consistently correct
@@ -717,15 +717,15 @@ Semantic versioning
 ~~~~~~~~~~~~~~~~~~~
 
 `Semantic versioning`_ is a popular version identification scheme that is
-more prescriptive than this PEP regarding the significance of different
+more prescriptive than this specification regarding the significance of different
 elements of a release number. Even if a project chooses not to abide by
 the details of semantic versioning, the scheme is worth understanding as
 it covers many of the issues that can arise when depending on other
 distributions, and when publishing a distribution that others rely on.
 
-The "Major.Minor.Patch" (described in this PEP as "major.minor.micro")
+The "Major.Minor.Patch" (described in this specification as "major.minor.micro")
 aspects of semantic versioning (clauses 1-8 in the 2.0.0 specification)
-are fully compatible with the version scheme defined in this PEP, and abiding
+are fully compatible with the version scheme defined in this specification, and abiding
 by these aspects is encouraged.
 
 Semantic versions containing a hyphen (pre-releases - clause 10) or a
@@ -1011,10 +1011,10 @@ local versions. This operator also does not support prefix matching as the
 ``==`` operator does.
 
 The primary use case for arbitrary equality is to allow for specifying a
-version which cannot otherwise be represented by this PEP. This operator is
+version which cannot otherwise be represented by this specification. This operator is
 special and acts as an escape hatch to allow someone using a tool which
-implements this PEP to still install a legacy version which is otherwise
-incompatible with this PEP.
+implements this specification to still install a legacy version which is otherwise
+incompatible with this specification.
 
 An example would be ``===foobar`` which would match a version of ``foobar``.
 
@@ -1178,16 +1178,16 @@ Summary of differences from pkg_resources.parse_version
   the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 and
   later versions adopted the behaviour described here.
 
-* Local versions sort differently, this PEP requires that they sort as greater
+* Local versions sort differently, this specification requires that they sort as greater
   than the same version without a local version, whereas
   ``pkg_resources.parse_version`` considers it a pre-release marker.
 
-* This PEP purposely restricts the syntax which constitutes a valid version
+* This specification purposely restricts the syntax which constitutes a valid version
   while ``pkg_resources.parse_version`` attempts to provide some meaning from
   *any* arbitrary string.
 
 * ``pkg_resources.parse_version`` allows arbitrarily deeply nested version
-  signifiers like ``1.0.dev1.post1.dev5``. This PEP however allows only a
+  signifiers like ``1.0.dev1.post1.dev5``. This specification however allows only a
   single use of each type and they must exist in a certain order.
 
 

From aa0439a134a62f56f60e548e617f759f40cf9e70 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Thu, 9 Nov 2023 20:06:35 +0100
Subject: [PATCH 149/733] Address review comments

---
 source/guides/writing-pyproject-toml.rst | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 8e28e305b..c01f2b51e 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -4,12 +4,10 @@
 Writing your ``pyproject.toml``
 ===============================
 
-.. TODO: link :term:`build backends` when that's merged
-
 ``pyproject.toml`` is a configuration file used by packaging tools. Most
-build backends [#poetry-special]_ allow you to specify your project's
-basic metadata, such as the dependencies, your name, etc., in the ``[project]``
-table of your ``pyproject.toml``.
+:term:`build backends ` [#poetry-special]_ allow you to specify
+your project's basic metadata, such as the dependencies, your name, etc.,
+in the ``[project]`` table of your ``pyproject.toml``.
 
 .. note::
 
@@ -17,9 +15,9 @@ table of your ``pyproject.toml``.
    build backend. For new projects, it is recommended to use ``pyproject.toml``
    for basic metadata, and keep ``setup.py`` only if some programmatic configuration
    is needed (especially building C extensions). However, putting basic project
-   metadata in ``setup.py`` or ``setup.cfg`` is still valid.
+   metadata in ``setup.py`` or ``setup.cfg`` is still valid. See
+   :ref:`setup-py-deprecated`.
 
-.. TODO: link to "is setup.py deprecated?" page when merged
 
 Static vs. dynamic metadata
 ===========================

From cc029092cdf6639ace2efeb4346c1c0b13e74687 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Thu, 9 Nov 2023 20:06:42 +0100
Subject: [PATCH 150/733] =?UTF-8?q?Typo:=20python-requires=20=E2=86=92=20r?=
 =?UTF-8?q?equires-python?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 source/guides/writing-pyproject-toml.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index c01f2b51e..a0b6a1efc 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -115,7 +115,7 @@ could use, e.g., ``pip install your-project-name[gui]`` to install your
 project with GUI support, adding the PyQt5 dependency.
 
 
-``python-requires``
+``requires-python``
 -------------------
 
 This lets you declare the minimum version of Python that you support

From ae74041636cf75466672ecd894b64cef3cba544c Mon Sep 17 00:00:00 2001
From: sinoroc 
Date: Sat, 4 Nov 2023 18:56:59 +0100
Subject: [PATCH 151/733] Add page "How to modernize a setup.py project?"

GitHub: refs https://github.com/pypa/packaging.python.org/issues/1334
---
 source/discussions/setup-py-deprecated.rst    |   9 +-
 source/guides/modernize-setup-py-project.rst  | 249 ++++++++++++++++++
 source/guides/section-build-and-publish.rst   |   1 +
 .../declaring-project-metadata.rst            |   3 +
 4 files changed, 254 insertions(+), 8 deletions(-)
 create mode 100644 source/guides/modernize-setup-py-project.rst

diff --git a/source/discussions/setup-py-deprecated.rst b/source/discussions/setup-py-deprecated.rst
index 29eac241d..25bba70a9 100644
--- a/source/discussions/setup-py-deprecated.rst
+++ b/source/discussions/setup-py-deprecated.rst
@@ -105,10 +105,6 @@ Although the usage of :file:`setup.py` as an executable script is deprecated,
 its usage as a configuration file for setuptools is absolutely fine.
 There is likely no modification needed in :file:`setup.py`.
 
-.. todo::
-
-    Link to a "How to modernize a setup.py based project?"
-
 
 Is ``pyproject.toml`` mandatory?
 ================================
@@ -124,10 +120,7 @@ at the root of its source tree with a content like this:
     build-backend = "setuptools.build_meta"
 
 
-.. todo::
-
-    Link to "How to modernize a setup.py based project?"
-
+The guide :ref:`modernize-setup-py-project` has more details about this.
 
 The standard fallback behavior for a :term:`build frontend `
 in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` table
diff --git a/source/guides/modernize-setup-py-project.rst b/source/guides/modernize-setup-py-project.rst
new file mode 100644
index 000000000..1ecd4d6ff
--- /dev/null
+++ b/source/guides/modernize-setup-py-project.rst
@@ -0,0 +1,249 @@
+.. _modernize-setup-py-project:
+
+
+==============================================
+How to modernize a ``setup.py`` based project?
+==============================================
+
+
+Should ``pyproject.toml`` be added?
+===================================
+
+A :term:`pyproject.toml` file is strongly recommended.
+The presence of a :file:`pyproject.toml` file itself does not bring much. [#]_
+What is actually strongly recommended is the ``[build-system]`` table in :file:`pyproject.toml`.
+
+.. [#] Note that it has influence on the build isolation feature of *pip*,
+    see below.
+
+
+Should ``setup.py`` be deleted?
+===============================
+
+No, :file:`setup.py` can exist in a modern :ref:`setuptools` based project.
+The :term:`setup.py` file is a valid configuration file for setuptools
+that happens to be written in Python.
+However, the following commands are deprecated and **MUST NOT** be run anymore,
+and their recommended replacement commands can be used instead:
+
++---------------------------------+----------------------------------------+
+| Deprecated                      | Current recommendation                 |
++=================================+========================================+
+| ``python setup.py install``     | ``python -m pip install .``            |
++---------------------------------+----------------------------------------+
+| ``python setup.py develop``     | ``python -m pip install --editable .`` |
++---------------------------------+----------------------------------------+
+| ``python setup.py sdist``       | ``python -m build``                    |
++---------------------------------+                                        |
+| ``python setup.py bdist_wheel`` |                                        |
++---------------------------------+----------------------------------------+
+
+
+For more details:
+
+* :ref:`setup-py-deprecated`
+
+
+Where to start?
+===============
+
+The :term:`project` must contain a :file:`pyproject.toml` file at the root of its source tree
+that contains a ``[build-system]`` table like so:
+
+.. code:: toml
+
+    [build-system]
+    requires = ["setuptools"]
+    build-backend = "setuptools.build_meta"
+
+
+This is the standardized method of letting :term:`build frontends ` know
+that :ref:`setuptools` is the :term:`build backend ` for this project.
+
+Note that the presence of a :file:`pyproject.toml` file (even if empty)
+triggers :ref:`pip` to change its default behavior to use *build isolation*.
+
+For more details:
+
+* :ref:`distributing-packages`
+* :ref:`declaring-build-dependencies`
+* :doc:`pip:reference/build-system/pyproject-toml`
+
+
+How to handle additional build-time dependencies?
+=================================================
+
+On top of setuptools itself,
+if :file:`setup.py` depends on other third-party libraries (outside of Python's standard library),
+those must be listed in the ``requires`` list of the ``[build-system]`` table,
+so that the build frontend knows to install them
+when building the :term:`distributions `.
+
+For example, a :file:`setup.py` file such as this:
+
+.. code:: python
+
+    import setuptools
+    import some_build_toolkit  # comes from the `some-build-toolkit` library
+
+    def get_version():
+        version = some_build_toolkit.compute_version()
+        return version
+
+    setuptools.setup(
+        name="my-project",
+        version=get_version(),
+    )
+
+
+requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays unchanged):
+
+.. code:: toml
+
+    [build-system]
+    requires = [
+        "setuptools",
+        "some-build-toolkit",
+    ]
+    build-backend = "setuptools.build_meta"
+
+
+For more details:
+
+* :ref:`declaring-build-dependencies`
+
+
+What is the build isolation feature?
+====================================
+
+Build frontends typically create an ephemeral virtual environment
+where they install only the build dependencies (and their dependencies)
+that are listed under ``build-sytem.requires``
+and trigger the build in that environment.
+
+For some projects this isolation is unwanted and it can be deactivated as follows:
+
+* ``python -m build --no-isolation``
+* ``python -m install --no-build-isolation``
+
+For more details:
+
+* :doc:`pip:reference/build-system/pyproject-toml`
+
+
+How to handle packaging metadata?
+=================================
+
+All static metadata can optionally be moved to a ``[project]`` table in :file:`pyproject.toml`.
+
+For example, a :file:`setup.py` file such as this:
+
+.. code:: python
+
+    import setuptools
+
+    setuptools.setup(
+        name="my-project",
+        version="1.2.3",
+    )
+
+
+can be entirely replaced by a :file:`pyproject.toml` file like this:
+
+.. code:: toml
+
+    [build-system]
+    requires = ["setuptools"]
+    build-backend = "setuptools.build_meta"
+
+    [project]
+    name = "my-project"
+    version = "1.2.3"
+
+
+Read :ref:`declaring-project-metadata` for the full specification
+of the content allowed in the ``[project]`` table.
+
+
+How to handle dynamic metadata?
+===============================
+
+If some packaging metadata fields are not static
+they need to be listed as ``dynamic`` in this ``[project]`` table.
+
+For example, a :file:`setup.py` file such as this:
+
+.. code:: python
+
+    import setuptools
+    import some_build_toolkit
+
+    def get_version():
+        version = some_build_toolkit.compute_version()
+        return version
+
+    setuptools.setup(
+        name="my-project",
+        version=get_version(),
+    )
+
+
+can be modernized as follows:
+
+.. code:: toml
+
+    [build-system]
+    requires = [
+        "setuptools",
+        "some-build-toolkit",
+    ]
+    build-backend = "setuptools.build_meta"
+
+    [project]
+    name = "my-project"
+    dynamic = ["version"]
+
+
+.. code:: python
+
+    import setuptools
+    import some_build_toolkit
+
+    def get_version():
+        version = some_build_toolkit.compute_version()
+        return version
+
+    setuptools.setup(
+        version=get_version(),
+    )
+
+
+For more details:
+
+* :ref:`declaring-project-metadata-dynamic`
+
+
+What if something that can not be changed expects a ``setup.py`` file?
+======================================================================
+
+For example, a process exists that can not be changed easily
+and it needs to execute a command such as ``python setup.py --name``.
+
+It is perfectly fine to leave a :file:`setup.py` file in the project source tree
+even after all its content has been moved to :file:`pyproject.toml`.
+This file can be as minimalistic as this:
+
+.. code:: python
+
+    import setuptools
+
+    setuptools.setup()
+
+
+Where to read more about this?
+==============================
+
+* :ref:`declaring-build-dependencies`
+* :ref:`declaring-project-metadata`
+* :doc:`pip:reference/build-system/pyproject-toml`
+* :doc:`setuptools:build_meta`
diff --git a/source/guides/section-build-and-publish.rst b/source/guides/section-build-and-publish.rst
index 9bb5f08fe..b20c27249 100644
--- a/source/guides/section-build-and-publish.rst
+++ b/source/guides/section-build-and-publish.rst
@@ -15,3 +15,4 @@ Building and Publishing
    using-testpypi
    making-a-pypi-friendly-readme
    publishing-package-distribution-releases-using-github-actions-ci-cd-workflows
+   modernize-setup-py-project
diff --git a/source/specifications/declaring-project-metadata.rst b/source/specifications/declaring-project-metadata.rst
index df6c9ee89..c7247865b 100644
--- a/source/specifications/declaring-project-metadata.rst
+++ b/source/specifications/declaring-project-metadata.rst
@@ -379,6 +379,9 @@ metadata.
       "click",
     ]
 
+
+.. _declaring-project-metadata-dynamic:
+
 ``dynamic``
 -----------
 

From 3cadeb61326a43c4ffe0553df1c80e956e54181b Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Fri, 10 Nov 2023 23:54:40 +0100
Subject: [PATCH 152/733] Change "Bug Tracker" to Issues (closes #1183)

---
 source/guides/writing-pyproject-toml.rst | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index a0b6a1efc..03aa25612 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -274,8 +274,7 @@ A list of PyPI classifiers that apply to your project. Check the
 --------
 
 A list of URLs associated with your project, displayed on the left
-sidebar of your PyPI project page. If the key contains spaces, don't
-forget to quote it.
+sidebar of your PyPI project page.
 
 .. code-block:: toml
 
@@ -283,9 +282,14 @@ forget to quote it.
     Homepage = "https://example.com"
     Documentation = "https://readthedocs.org"
     Repository = "https://github.com/me/spam.git"
-    "Bug Tracker" = "https://github.com/me/spam/issues"
+    Issues = "https://github.com/me/spam/issues"
     Changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
 
+Note that if the key contains spaces, it needs to be quoted, e.g.,
+``Website = "https://example.com"`` but
+``"Official Website" = "https://example.com"``.
+
+
 
 Advanced plugins
 ================

From f491267f1d10fe61b5ce300f92349666432fd6fa Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sat, 11 Nov 2023 05:45:59 +0100
Subject: [PATCH 153/733] Update
 source/specifications/recording-installed-packages.rst

---
 source/specifications/recording-installed-packages.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst
index fe33df438..ffef1f93e 100644
--- a/source/specifications/recording-installed-packages.rst
+++ b/source/specifications/recording-installed-packages.rst
@@ -246,7 +246,7 @@ To achieve this, affected tools should take the following steps:
 
 Python runtime providers may also prevent inadvertent modification of platform
 provided packages by modifying the default Python package installation scheme
-to use a location other than that used by distribution packages (while also
+to use a location other than that used by platform provided packages (while also
 ensuring both locations appear on the default Python import path).
 
 In some circumstances, it may be desirable to block even installation of

From ada01ea280118a76dd879a981981370bc0fbc176 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 11 Nov 2023 20:33:10 +0100
Subject: [PATCH 154/733] Remove "Using MANIFEST.in" guide, moved to setuptools
 docs

---
 source/guides/section-build-and-publish.rst |   1 -
 source/guides/using-manifest-in.rst         | 111 --------------------
 2 files changed, 112 deletions(-)
 delete mode 100644 source/guides/using-manifest-in.rst

diff --git a/source/guides/section-build-and-publish.rst b/source/guides/section-build-and-publish.rst
index b20c27249..ccb18749e 100644
--- a/source/guides/section-build-and-publish.rst
+++ b/source/guides/section-build-and-publish.rst
@@ -6,7 +6,6 @@ Building and Publishing
    :titlesonly:
 
    distributing-packages-using-setuptools
-   using-manifest-in
    single-sourcing-package-version
    dropping-older-python-versions
    packaging-binary-extensions
diff --git a/source/guides/using-manifest-in.rst b/source/guides/using-manifest-in.rst
deleted file mode 100644
index 1eaf42c18..000000000
--- a/source/guides/using-manifest-in.rst
+++ /dev/null
@@ -1,111 +0,0 @@
-.. _`Using MANIFEST.in`:
-
-============================================================
-Including files in source distributions with ``MANIFEST.in``
-============================================================
-
-When building a :term:`source distribution `
-for your package, by default only a minimal set of files are included.  You may
-find yourself wanting to include extra files in the source distribution, such
-as an authors/contributors file, a :file:`docs/` directory, or a directory of
-data files used for testing purposes.  There may even be extra files that you
-*need* to include; for example, if your :file:`setup.py` computes your
-project's ``long_description`` by reading from both a README and a changelog
-file, you'll need to include both those files in the sdist so that people that
-build or install from the sdist get the correct results.
-
-Adding & removing files to & from the source distribution is done by writing a
-:file:`MANIFEST.in` file at the project root.
-
-
-How files are included in an sdist
-==================================
-
-The following files are included in a source distribution by default:
-
-- all Python source files implied by the ``py_modules`` and ``packages``
-  ``setup()`` arguments
-- all C source files mentioned in the ``ext_modules`` or ``libraries``
-  ``setup()`` arguments
-- scripts specified by the ``scripts`` ``setup()`` argument
-- all files specified by the ``package_data`` and ``data_files`` ``setup()``
-  arguments
-- the file specified by the ``license_file`` option in :file:`setup.cfg`
-  (setuptools 40.8.0+)
-- all files specified by the ``license_files`` option in :file:`setup.cfg`
-  (setuptools 42.0.0+)
-- all files matching the pattern :file:`test/test*.py`
-- :file:`setup.py` (or whatever you called your setup script)
-- :file:`setup.cfg`
-- :file:`README`
-- :file:`README.txt`
-- :file:`README.rst` (Python 3.7+ or setuptools 0.6.27+)
-- :file:`README.md` (setuptools 36.4.0+)
-- :file:`pyproject.toml` (setuptools 43.0.0+)
-- :file:`MANIFEST.in`
-
-After adding the above files to the sdist, the commands in :file:`MANIFEST.in`
-(if such a file exists) are executed in order to add and remove further files
-to and from the sdist.  Default files can even be removed from the sdist with the
-appropriate :file:`MANIFEST.in` command.
-
-After processing the :file:`MANIFEST.in` file, setuptools removes the
-:file:`build/` directory as well as any directories named :file:`RCS`,
-:file:`CVS`, or :file:`.svn` from the sdist, and it adds a :file:`PKG-INFO`
-file and an :file:`*.egg-info` directory.  This behavior cannot be changed with
-:file:`MANIFEST.in`.
-
-
-:file:`MANIFEST.in` commands
-============================
-
-A :file:`MANIFEST.in` file consists of commands, one per line, instructing
-setuptools to add or remove some set of files from the sdist.  The commands
-are:
-
-=========================================================  ==================================================================================================
-Command                                                    Description
-=========================================================  ==================================================================================================
-:samp:`include {pat1} {pat2} ...`                          Add all files matching any of the listed patterns
-                                                           (Files must be given as paths relative to the root of the project)
-:samp:`exclude {pat1} {pat2} ...`                          Remove all files matching any of the listed patterns
-                                                           (Files must be given as paths relative to the root of the project)
-:samp:`recursive-include {dir-pattern} {pat1} {pat2} ...`  Add all files under directories matching ``dir-pattern`` that match any of the listed patterns
-:samp:`recursive-exclude {dir-pattern} {pat1} {pat2} ...`  Remove all files under directories matching ``dir-pattern`` that match any of the listed patterns
-:samp:`global-include {pat1} {pat2} ...`                   Add all files anywhere in the source tree matching any of the listed patterns
-:samp:`global-exclude {pat1} {pat2} ...`                   Remove all files anywhere in the source tree matching any of the listed patterns
-:samp:`graft {dir-pattern}`                                Add all files under directories matching ``dir-pattern``
-:samp:`prune {dir-pattern}`                                Remove all files under directories matching ``dir-pattern``
-=========================================================  ==================================================================================================
-
-The patterns here are glob-style patterns: ``*`` matches zero or more regular
-filename characters (on Unix, everything except forward slash; on Windows,
-everything except backslash and colon); ``?`` matches a single regular filename
-character, and ``[chars]`` matches any one of the characters between the square
-brackets (which may contain character ranges, e.g., ``[a-z]`` or
-``[a-fA-F0-9]``).  Setuptools also has undocumented support for ``**`` matching
-zero or more characters including forward slash, backslash, and colon.
-
-Directory patterns are relative to the root of the project directory; e.g.,
-``graft example*`` will include a directory named :file:`examples` in the
-project root but will not include :file:`docs/examples/`.
-
-File & directory names in :file:`MANIFEST.in` should be ``/``-separated;
-setuptools will automatically convert the slashes to the local platform's
-appropriate directory separator.
-
-Commands are processed in the order they appear in the :file:`MANIFEST.in`
-file.  For example, given the commands:
-
-.. code-block:: bash
-
-    graft tests
-    global-exclude *.py[cod]
-
-the contents of the directory tree :file:`tests` will first be added to the
-sdist, and then after that all files in the sdist with a ``.pyc``, ``.pyo``, or
-``.pyd`` extension will be removed from the sdist.  If the commands were in the
-opposite order, then ``*.pyc`` files etc. would be only be removed from what
-was already in the sdist before adding :file:`tests`, and if :file:`tests`
-happened to contain any ``*.pyc`` files, they would end up included in the
-sdist because the exclusion happened before they were included.

From d79ae4ada0a2289114d2e5a3691d0aa0f6e8371e Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 11 Nov 2023 20:41:53 +0100
Subject: [PATCH 155/733] Consistent tabs in
 installing-using-pip-and-virtual-environments.rst

Fixes #1375
---
 ...ing-using-pip-and-virtual-environments.rst | 21 +++----------------
 1 file changed, 3 insertions(+), 18 deletions(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index 2544aa40a..2f6b154bc 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -155,25 +155,10 @@ Prepare pip
 It's used to install and update packages into a virtual environment.
 
 
-.. tab:: Unix
-
-    You can make sure that pip is up-to-date by running:
-
-    .. code-block:: bash
-
-        python3 -m pip install --upgrade pip
-        python3 -m pip --version
-
-    Afterwards, you should have the latest version of pip installed in your
-    user site:
-
-    .. code-block:: text
-
-        pip 23.3.1 from .../.venv/lib/python3.9/site-packages (python 3.9)
-
-.. tab:: macOS
+.. tab:: Unix/macOS
 
-    The Python installers for macOS include pip. You can make sure that pip is
+    The Python installers for macOS include pip. On Linux, you may have to install
+    an additional package such as ``python3-pip``. You can make sure that pip is
     up-to-date by running:
 
     .. code-block:: bash

From 1c2467e5223d9546008853a952292a442d4232d9 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 11 Nov 2023 23:41:02 +0100
Subject: [PATCH 156/733] =?UTF-8?q?brett@python.org=20=E2=86=92=20brett@ex?=
 =?UTF-8?q?ample.com?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 source/guides/writing-pyproject-toml.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 03aa25612..70028856c 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -180,7 +180,7 @@ an email address.
       {email = "different.person@example.com"},
     ]
     maintainers = [
-      {name = "Brett Cannon", email = "brett@python.org"}
+      {name = "Brett Cannon", email = "brett@example.com"}
     ]
 
 
@@ -329,7 +329,7 @@ A full example
      {email = "different.person@example.com"},
    ]
    maintainers = [
-     {name = "Brett Cannon", email = "brett@python.org"}
+     {name = "Brett Cannon", email = "brett@example.com"}
    ]
    description = "Lovely Spam! Wonderful Spam!"
    readme = "README.rst"

From 4397751692a895eedf7d60e4fb585fa4bad5a3b8 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 12 Nov 2023 00:04:32 +0100
Subject: [PATCH 157/733] Import PEP 723 verbatim

---
 .../specifications/inline-script-metadata.rst | 835 ++++++++++++++++++
 1 file changed, 835 insertions(+)
 create mode 100644 source/specifications/inline-script-metadata.rst

diff --git a/source/specifications/inline-script-metadata.rst b/source/specifications/inline-script-metadata.rst
new file mode 100644
index 000000000..04fb0d238
--- /dev/null
+++ b/source/specifications/inline-script-metadata.rst
@@ -0,0 +1,835 @@
+PEP: 723
+Title: Inline script metadata
+Author: Ofek Lev 
+Sponsor: Adam Turner 
+PEP-Delegate: Brett Cannon 
+Discussions-To: https://discuss.python.org/t/31151
+Status: Provisional
+Type: Standards Track
+Topic: Packaging
+Content-Type: text/x-rst
+Created: 04-Aug-2023
+Post-History: `04-Aug-2023 `__,
+              `06-Aug-2023 `__,
+              `23-Aug-2023 `__,
+Replaces: 722
+Resolution: https://discuss.python.org/t/36763
+
+
+Abstract
+========
+
+This PEP specifies a metadata format that can be embedded in single-file Python
+scripts to assist launchers, IDEs and other external tools which may need to
+interact with such scripts.
+
+
+Motivation
+==========
+
+Python is routinely used as a scripting language, with Python scripts as a
+(better) alternative to shell scripts, batch files, etc. When Python code is
+structured as a script, it is usually stored as a single file and does not
+expect the availability of any other local code that may be used for imports.
+As such, it is possible to share with others over arbitrary text-based means
+such as email, a URL to the script, or even a chat window. Code that is
+structured like this may live as a single file forever, never becoming a
+full-fledged project with its own directory and ``pyproject.toml`` file.
+
+An issue that users encounter with this approach is that there is no standard
+mechanism to define metadata for tools whose job it is to execute such scripts.
+For example, a tool that runs a script may need to know which dependencies are
+required or the supported version(s) of Python.
+
+There is currently no standard tool that addresses this issue, and this PEP
+does *not* attempt to define one. However, any tool that *does* address this
+issue will need to know what the runtime requirements of scripts are. By
+defining a standard format for storing such metadata, existing tools, as well
+as any future tools, will be able to obtain that information without requiring
+users to include tool-specific metadata in their scripts.
+
+
+Rationale
+=========
+
+This PEP defines a mechanism for embedding metadata *within the script itself*,
+and not in an external file.
+
+We choose to follow the latest developments of other modern packaging
+ecosystems (namely `Go`__ and provisionally `Rust`__) by embedding the existing
+file used to describe projects, in our case ``pyproject.toml``.
+
+__ https://github.com/erning/gorun
+__ https://rust-lang.github.io/rfcs/3424-cargo-script.html
+
+The format is intended to bridge the gap between different types of users
+of Python. Users will benefit from seamless interoperability with tools that
+already work with TOML.
+
+One of the central themes we discovered from the recent
+`packaging survey `__ is that users have
+begun getting frustrated with the lack of unification regarding both tooling
+and specs. Adding yet another metadata format (like :pep:`722` syntax for a
+list of dependencies), even for a currently unsatisfied use case, would
+further fragment the community.
+
+The following are some of the use cases that this PEP wishes to support:
+
+* A user facing CLI that is capable of executing scripts. If we take Hatch as
+  an example, the interface would be simply
+  ``hatch run /path/to/script.py [args]`` and Hatch will manage the
+  environment for that script. Such tools could be used as shebang lines on
+  non-Windows systems e.g. ``#!/usr/bin/env hatch run``.
+* A script that desires to transition to a directory-type project. A user may
+  be rapidly prototyping locally or in a remote REPL environment and then
+  decide to transition to a more formal project layout if their idea works
+  out. This intermediate script stage would be very useful to have fully
+  reproducible bug reports. By using the same format, the user can simply copy
+  and paste the metadata into a ``pyproject.toml`` file and continue working
+  without having to learn a new format. More likely, even, is that tooling will
+  eventually support this transformation with a single command.
+* Users that wish to avoid manual dependency management. For example, package
+  managers that have commands to add/remove dependencies or dependency update
+  automation in CI that triggers based on new versions or in response to
+  CVEs [1]_.
+
+
+Specification
+=============
+
+This PEP defines a metadata comment block format loosely inspired [2]_ by
+`reStructuredText Directives`__.
+
+__ https://docutils.sourceforge.io/docs/ref/rst/directives.html
+
+Any Python script may have top-level comment blocks that MUST start with the
+line ``# /// TYPE`` where ``TYPE`` determines how to process the content. That
+is: a single ``#``, followed by a single space, followed by three forward
+slashes, followed by a single space, followed by the type of metadata. Block
+MUST end with the line ``# ///``. That is: a single ``#``, followed by a single
+space, followed by three forward slashes. The ``TYPE`` MUST only consist of
+ASCII letters, numbers and hyphens.
+
+Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a
+comment starting with ``#``. If there are characters after the ``#`` then the
+first character MUST be a space. The embedded content is formed by taking away
+the first two characters of each line if the second character is a space,
+otherwise just the first character (which means the line consists of only a
+single ``#``).
+
+Precedence for an ending line ``# ///`` is given when the next line is not
+a valid embedded content line as described above. For example, the following
+is a single fully valid block:
+
+.. code:: python
+
+    # /// some-toml
+    # embedded-csharp = """
+    # /// 
+    # /// text
+    # ///
+    # /// 
+    # public class MyClass { }
+    # """
+    # ///
+
+A starting line MUST NOT be placed between another starting line and its ending
+line. In such cases tools MAY produce an error. Unclosed blocks MUST be ignored.
+
+When there are multiple comment blocks of the same ``TYPE`` defined, tools MUST
+produce an error.
+
+Tools reading embedded metadata MAY respect the standard Python encoding
+declaration. If they choose not to do so, they MUST process the file as UTF-8.
+
+This is the canonical regular expression that MAY be used to parse the
+metadata:
+
+.. code:: text
+
+    (?m)^# /// (?P[a-zA-Z0-9-]+)$\s(?P(^#(| .*)$\s)+)^# ///$
+
+In circumstances where there is a discrepancy between the text specification
+and the regular expression, the text specification takes precedence.
+
+Tools MUST NOT read from metadata blocks with types that have not been
+standardized by this PEP or future ones.
+
+pyproject type
+--------------
+
+The first type of metadata block is named ``pyproject`` which represents
+content similar to [3]_ what one would see in a ``pyproject.toml`` file.
+
+This document MAY include the ``[run]`` and ``[tool]`` tables.
+
+The :pep:`tool table <518#tool-table>` MAY be used by any tool, script runner
+or otherwise, to configure behavior.
+
+The ``[run]`` table MAY include the following optional fields:
+
+* ``dependencies``: A list of strings that specifies the runtime dependencies
+  of the script. Each entry MUST be a valid :pep:`508` dependency.
+* ``requires-python``: A string that specifies the Python version(s) with which
+  the script is compatible. The value of this field MUST be a valid
+  :pep:`version specifier <440#version-specifiers>`.
+
+Any future PEPs that define additional fields for the ``[run]`` table when used
+in a ``pyproject.toml`` file MUST include the aforementioned fields exactly as
+specified. The fields defined by this PEP are equally as applicable to
+full-fledged projects as they are to single-file scripts.
+
+Script runners MUST error if the specified ``dependencies`` cannot be provided.
+Script runners SHOULD error if no version of Python that satisfies the specified
+``requires-python`` can be provided.
+
+Example
+-------
+
+The following is an example of a script with an embedded ``pyproject.toml``:
+
+.. code:: python
+
+    # /// pyproject
+    # [run]
+    # requires-python = ">=3.11"
+    # dependencies = [
+    #   "requests<3",
+    #   "rich",
+    # ]
+    # ///
+
+    import requests
+    from rich.pretty import pprint
+
+    resp = requests.get("https://peps.python.org/api/peps.json")
+    data = resp.json()
+    pprint([(k, v["title"]) for k, v in data.items()][:10])
+
+The following [4]_ is an example of a proposed syntax for single-file Rust
+projects that embeds their equivalent of ``pyproject.toml``, which is called
+``Cargo.toml``:
+
+.. code:: rust
+
+    #!/usr/bin/env cargo
+
+    //! ```cargo
+    //! [dependencies]
+    //! regex = "1.8.0"
+    //! ```
+
+    fn main() {
+        let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
+        println!("Did our date match? {}", re.is_match("2014-01-01"));
+    }
+
+Reference Implementation
+========================
+
+The following is an example of how to read the metadata on Python 3.11 or
+higher.
+
+.. code:: python
+
+   import re
+   import tomllib
+
+   REGEX = r'(?m)^# /// (?P[a-zA-Z0-9-]+)$\s(?P(^#(| .*)$\s)+)^# ///$'
+
+   def read(script: str) -> dict | None:
+       name = 'pyproject'
+       matches = list(
+           filter(lambda m: m.group('type') == name, re.finditer(REGEX, script))
+       )
+       if len(matches) > 1:
+           raise ValueError(f'Multiple {name} blocks found')
+       elif len(matches) == 1:
+           content = ''.join(
+               line[2:] if line.startswith('# ') else line[1:]
+               for line in matches[0].group('content').splitlines(keepends=True)
+           )
+           return tomllib.loads(content)
+       else:
+           return None
+
+Often tools will edit dependencies like package managers or dependency update
+automation in CI. The following is a crude example of modifying the content
+using the ``tomlkit`` library__.
+
+__ https://tomlkit.readthedocs.io/en/latest/
+
+.. code:: python
+
+   import re
+
+   import tomlkit
+
+   REGEX = r'(?m)^# /// (?P[a-zA-Z0-9-]+)$\s(?P(^#(| .*)$\s)+)^# ///$'
+
+   def add(script: str, dependency: str) -> str:
+       match = re.search(REGEX, script)
+       content = ''.join(
+           line[2:] if line.startswith('# ') else line[1:]
+           for line in match.group('content').splitlines(keepends=True)
+       )
+
+       config = tomlkit.parse(content)
+       config['project']['dependencies'].append(dependency)
+       new_content = ''.join(
+           f'# {line}' if line.strip() else f'#{line}'
+           for line in tomlkit.dumps(config).splitlines(keepends=True)
+       )
+
+       start, end = match.span('content')
+       return script[:start] + new_content + script[end:]
+
+Note that this example used a library that preserves TOML formatting. This is
+not a requirement for editing by any means but rather is a "nice to have"
+feature.
+
+The following is an example of how to read a stream of arbitrary metadata
+blocks.
+
+.. code:: python
+
+   import re
+   from typing import Iterator
+
+   REGEX = r'(?m)^# /// (?P[a-zA-Z0-9-]+)$\s(?P(^#(| .*)$\s)+)^# ///$'
+
+   def stream(script: str) -> Iterator[tuple[str, str]]:
+       for match in re.finditer(REGEX, script):
+           yield match.group('type'), ''.join(
+               line[2:] if line.startswith('# ') else line[1:]
+               for line in match.group('content').splitlines(keepends=True)
+           )
+
+
+Backwards Compatibility
+=======================
+
+At the time of writing, the ``# /// pyproject`` block comment starter does not
+appear `on GitHub`__. Therefore, there is little risk of existing scripts being
+broken by this PEP.
+
+__ https://github.com/search?q=%22%23+%2F%2F%2F+pyproject%22&type=code
+
+
+Security Implications
+=====================
+
+If a script containing embedded metadata is ran using a tool that automatically
+installs dependencies, this could cause arbitrary code to be downloaded and
+installed in the user's environment.
+
+The risk here is part of the functionality of the tool being used to run the
+script, and as such should already be addressed by the tool itself. The only
+additional risk introduced by this PEP is if an untrusted script with a
+embedded metadata is run, when a potentially malicious dependency or transitive
+dependency might be installed.
+
+This risk is addressed by the normal good practice of reviewing code
+before running it. Additionally, tools may be able to provide
+`locking functionality <723-tool-configuration_>`__ to ameliorate this risk.
+
+
+How to Teach This
+=================
+
+To embed metadata in a script, define a comment block that starts with the
+line ``# /// pyproject`` and ends with the line ``# ///``. Every line between
+those two lines must be a comment and the full content is derived by removing
+the first two characters. The ``pyproject`` type indicates that the content
+is TOML and resembles a ``pyproject.toml`` file.
+
+.. code:: python
+
+    # /// pyproject
+    # [run]
+    # dependencies = [
+    #   "requests<3",
+    #   "rich",
+    # ]
+    # requires-python = ">=3.11"
+    # ///
+
+The two allowed tables are ``[run]`` and ``[tool]``. The ``[run]`` table may
+contain the following fields:
+
+.. list-table::
+
+   * - Field
+     - Description
+     - Tool behavior
+
+   * - ``dependencies``
+     - A list of strings that specifies the runtime dependencies of the script.
+       Each entry must be a valid :pep:`508` dependency.
+     - Tools will error if the specified dependencies cannot be provided.
+
+   * - ``requires-python``
+     - A string that specifies the Python version(s)
+       with which the script is compatible.
+       The value of this field must be a valid
+       :pep:`version specifier <440#version-specifiers>`.
+     - Tools might error if no version of Python that satisfies
+       the constraint can be executed.
+
+It is up to individual tools whether or not their behavior is altered based on
+the embedded metadata. For example, every script runner may not be able to
+provide an environment for specific Python versions as defined by the
+``requires-python`` field.
+
+The :pep:`tool table <518#tool-table>` may be used by any tool, script runner
+or otherwise, to configure behavior.
+
+
+Recommendations
+===============
+
+Tools that support managing different versions of Python should attempt to use
+the highest available version of Python that is compatible with the script's
+``requires-python`` metadata, if defined.
+
+
+Tooling buy-in
+==============
+
+The following is a list of tools that have expressed support for this PEP or
+have committed to implementing support should it be accepted:
+
+* `Pantsbuild and Pex `__:  expressed
+  support for any way to define dependencies and also features that this PEP
+  considers as valid use cases such as building packages from scripts and
+  embedding tool configuration
+* `Mypy `__ and
+  `Ruff `__: strongly expressed support
+  for embedding tool configuration as it would solve existing pain points for
+  users
+* `Hatch `__: (author of this PEP)
+  expressed support for all aspects of this PEP, and will be one of the first
+  tools to support running scripts with specifically configured Python versions
+
+
+Rejected Ideas
+==============
+
+.. _723-comment-block:
+
+Why not use a comment block resembling requirements.txt?
+--------------------------------------------------------
+
+This PEP considers there to be different types of users for whom Python code
+would live as single-file scripts:
+
+* Non-programmers who are just using Python as a scripting language to achieve
+  a specific task. These users are unlikely to be familiar with concepts of
+  operating systems like shebang lines or the ``PATH`` environment variable.
+  Some examples:
+
+  * The average person, perhaps at a workplace, who wants to write a script to
+    automate something for efficiency or to reduce tedium
+  * Someone doing data science or machine learning in industry or academia who
+    wants to write a script to analyze some data or for research purposes.
+    These users are special in that, although they have limited programming
+    knowledge, they learn from sources like StackOverflow and blogs that have a
+    programming bent and are increasingly likely to be part of communities that
+    share knowledge and code. Therefore, a non-trivial number of these users
+    will have some familiarity with things like Git(Hub), Jupyter, HuggingFace,
+    etc.
+* Non-programmers who manage operating systems e.g. a sysadmin. These users are
+  able to set up ``PATH``, for example, but are unlikely to be familiar with
+  Python concepts like virtual environments. These users often operate in
+  isolation and have limited need to gain exposure to tools intended for
+  sharing like Git.
+* Programmers who manage operating systems/infrastructure e.g. SREs. These
+  users are not very likely to be familiar with Python concepts like virtual
+  environments, but are likely to be familiar with Git and most often use it
+  to version control everything required to manage infrastructure like Python
+  scripts and Kubernetes config.
+* Programmers who write scripts primarily for themselves. These users over time
+  accumulate a great number of scripts in various languages that they use to
+  automate their workflow and often store them in a single directory, that is
+  potentially version controlled for persistence. Non-Windows users may set
+  up each Python script with a shebang line pointing to the desired Python
+  executable or script runner.
+
+This PEP argues that reusing our TOML-based metadata format is the best for
+each category of user and that the requirements-like block comment is only
+approachable for those who have familiarity with ``requirements.txt``, which
+represents a small subset of users.
+
+* For the average person automating a task or the data scientist, they are
+  already starting with zero context and are unlikely to be familiar with
+  TOML nor ``requirements.txt``. These users will very likely rely on
+  snippets found online via a search engine or utilize AI in the form
+  of a chat bot or direct code completion software. Searching for Python
+  metadata formatting will lead them to the TOML-based format that already
+  exists which they can reuse. The author tested GitHub Copilot with this
+  PEP and it already supports auto-completion of ``dependencies``. In contrast,
+  a new format may take years of being trained on the Internet for models to
+  learn.
+
+  Additionally, these users are most susceptible to formatting quirks and
+  syntax errors. TOML is a well-defined format with existing online
+  validators that features assignment that is compatible with Python
+  expressions and has no strict indenting rules. The block comment format
+  on the other hand could be easily malformed by forgetting the colon, for
+  example, and debugging why it's not working with a search engine would be
+  a difficult task for such a user.
+* For the sysadmin types, they are equally unlikely as the previously described
+  users to be familiar with TOML or ``requirements.txt``. For either format
+  they would have to read documentation. They would likely be more comfortable
+  with TOML since they are used to structured data formats and there would be
+  less perceived magic in their systems.
+
+  Additionally, for maintenance of their systems ``/// pyproject`` would be
+  much easier to search for from a shell than a block comment with potentially
+  numerous extensions over time.
+* For the SRE types, they are likely to be familiar with TOML already from
+  other projects that they might have to work with like configuring the
+  `GitLab Runner`__ or `Cloud Native Buildpacks`__.
+
+  __ https://docs.gitlab.com/runner/configuration/advanced-configuration.html
+  __ https://buildpacks.io/docs/reference/config/
+
+  These users are responsible for the security of their systems and most likely
+  have security scanners set up to automatically open PRs to update versions
+  of dependencies. Such automated tools like Dependabot would have a much
+  easier time using existing TOML libraries than writing their own custom
+  parser for a block comment format.
+* For the programmer types, they are more likely to be familiar with TOML
+  than they have ever seen a ``requirements.txt`` file, unless they are a
+  Python programmer who has had previous experience with writing applications.
+  In the case of experience with the requirements format, it necessarily means
+  that they are at least somewhat familiar with the ecosystem and therefore
+  it is safe to assume they know what TOML is.
+
+  Another benefit of this PEP to these users is that their IDEs like Visual
+  Studio Code would be able to provide TOML syntax highlighting much more
+  easily than each writing custom logic for this feature.
+
+Additionally, since the original block comment alternative format (double
+``#``) went against the recommendation of :pep:`8` and as a result linters
+and IDE auto-formatters that respected the recommendation would
+`fail by default `__, the final
+proposal uses standard comments starting with a single ``#`` character without
+any obvious start nor end sequence.
+
+The concept of regular comments that do not appear to be intended for machines
+(i.e. `encoding declarations`__) affecting behavior would not be customary to
+users of Python and goes directly against the "explicit is better than
+implicit" foundational principle.
+
+__ https://docs.python.org/3/reference/lexical_analysis.html#encoding-declarations
+
+Users typing what to them looks like prose could alter runtime behavior. This
+PEP takes the view that the possibility of that happening, even when a tool
+has been set up as such (maybe by a sysadmin), is unfriendly to users.
+
+Finally, and critically, the alternatives to this PEP like :pep:`722` do not
+satisfy the use cases enumerated herein, such as setting the supported Python
+versions, the eventual building of scripts into packages, and the ability to
+have machines edit metadata on behalf of users. It is very likely that the
+requests for such features persist and conceivable that another PEP in the
+future would allow for the embedding of such metadata. At that point there
+would be multiple ways to achieve the same thing which goes against our
+foundational principle of "there should be one - and preferably only one -
+obvious way to do it".
+
+Why not use a multi-line string?
+--------------------------------
+
+A previous version of this PEP proposed that the metadata be stored as follows:
+
+.. code:: python
+
+    __pyproject__ = """
+    ...
+    """
+
+The most significant problem with this proposal is that the embedded TOML would
+be limited in the following ways:
+
+* It would not be possible to use multi-line double-quoted strings in the TOML
+  as that would conflict with the Python string containing the document. Many
+  TOML writers do not preserve style and may potentially produce output that
+  would be malformed.
+* The way in which character escaping works in Python strings is not quite the
+  way it works in TOML strings. It would be possible to preserve a one-to-one
+  character mapping by enforcing raw strings, but this ``r`` prefix requirement
+  may be potentially confusing to users.
+
+Why not reuse core metadata fields?
+-----------------------------------
+
+A previous version of this PEP proposed to reuse the existing
+`metadata standard `_ that is used to describe projects.
+
+There are two significant problems with this proposal:
+
+* The ``name`` and ``version`` fields are required and changing that would
+  require its own PEP
+* Reusing the data is `fundamentally a misuse of it`__
+
+  __ https://snarky.ca/differentiating-between-writing-down-dependencies-to-use-packages-and-for-packages-themselves/
+
+Why not limit to specific metadata fields?
+------------------------------------------
+
+By limiting the metadata to just ``dependencies``, we would prevent the known
+use case of tools that support managing Python installations, which would
+allows users to target specific versions of Python for new syntax or standard
+library functionality.
+
+.. _723-tool-configuration:
+
+Why not limit tool configuration?
+---------------------------------
+
+By not allowing the ``[tool]`` table, we would prevent known functionality
+that would benefit users. For example:
+
+* A script runner may support injecting of dependency resolution data for an
+  embedded lock file (this is what Go's ``gorun`` can do).
+* A script runner may support configuration instructing to run scripts in
+  containers for situations in which there is no cross-platform support for a
+  dependency or if the setup is too complex for the average user like when
+  requiring Nvidia drivers. Situations like this would allow users to proceed
+  with what they want to do whereas otherwise they may stop at that point
+  altogether.
+* Tools may wish to experiment with features to ease development burden for
+  users such as the building of single-file scripts into packages. We received
+  `feedback `__ stating that there are
+  already tools that exist in the wild that build wheels and source
+  distributions from single files.
+
+  The author of the Rust RFC for embedding metadata
+  `mentioned to us `__ that they are
+  actively looking into that as well based on user feedback saying that there
+  is unnecessary friction with managing small projects.
+
+  There has been `a commitment `__ to
+  support this by at least one major build system.
+
+Why not limit tool behavior?
+----------------------------
+
+A previous version of this PEP proposed that non-script running tools SHOULD
+NOT modify their behavior when the script is not the sole input to the tool.
+For example, if a linter is invoked with the path to a directory, it SHOULD
+behave the same as if zero files had embedded metadata.
+
+This was done as a precaution to avoid tool behavior confusion and generating
+various feature requests for tools to support this PEP. However, during
+discussion we received `feedback `__
+from maintainers of tools that this would be undesirable and potentially
+confusing to users. Additionally, this may allow for a universally easier
+way to configure tools in certain circumstances and solve existing issues.
+
+Why not just set up a Python project with a ``pyproject.toml``?
+---------------------------------------------------------------
+
+Again, a key issue here is that the target audience for this proposal is people
+writing scripts which aren't intended for distribution. Sometimes scripts will
+be "shared", but this is far more informal than "distribution" - it typically
+involves sending a script via an email with some written instructions on how to
+run it, or passing someone a link to a GitHub gist.
+
+Expecting such users to learn the complexities of Python packaging is a
+significant step up in complexity, and would almost certainly give the
+impression that "Python is too hard for scripts".
+
+In addition, if the expectation here is that the ``pyproject.toml`` will
+somehow be designed for running scripts in place, that's a new feature of the
+standard that doesn't currently exist. At a minimum, this isn't a reasonable
+suggestion until the `current discussion on Discourse
+`_ about using ``pyproject.toml`` for projects that
+won't be distributed as wheels is resolved. And even then, it doesn't address
+the "sending someone a script in a gist or email" use case.
+
+Why not infer the requirements from import statements?
+------------------------------------------------------
+
+The idea would be to automatically recognize ``import`` statements in the source
+file and turn them into a list of requirements.
+
+However, this is infeasible for several reasons. First, the points above about
+the necessity to keep the syntax easily parsable, for all Python versions, also
+by tools written in other languages, apply equally here.
+
+Second, PyPI and other package repositories conforming to the Simple Repository
+API do not provide a mechanism to resolve package names from the module names
+that are imported (see also `this related discussion`__).
+
+__ https://discuss.python.org/t/record-the-top-level-names-of-a-wheel-in-metadata/29494
+
+Third, even if repositories did offer this information, the same import name may
+correspond to several packages on PyPI. One might object that disambiguating
+which package is wanted would only be needed if there are several projects
+providing the same import name. However, this would make it easy for anyone to
+unintentionally or malevolently break working scripts, by uploading a package to
+PyPI providing an import name that is the same as an existing project. The
+alternative where, among the candidates, the first package to have been
+registered on the index is chosen, would be confusing in case a popular package
+is developed with the same import name as an existing obscure package, and even
+harmful if the existing package is malware intentionally uploaded with a
+sufficiently generic import name that has a high probability of being reused.
+
+A related idea would be to attach the requirements as comments to the import
+statements instead of gathering them in a block, with a syntax such as::
+
+  import numpy as np # requires: numpy
+  import rich # requires: rich
+
+This still suffers from parsing difficulties. Also, where to place the comment
+in the case of multiline imports is ambiguous and may look ugly::
+
+   from PyQt5.QtWidgets import (
+       QCheckBox, QComboBox, QDialog, QDialogButtonBox,
+       QGridLayout, QLabel, QSpinBox, QTextEdit
+   ) # requires: PyQt5
+
+Furthermore, this syntax cannot behave as might be intuitively expected
+in all situations. Consider::
+
+  import platform
+  if platform.system() == "Windows":
+      import pywin32 # requires: pywin32
+
+Here, the user's intent is that the package is only required on Windows, but
+this cannot be understood by the script runner (the correct way to write
+it would be ``requires: pywin32 ; sys_platform == 'win32'``).
+
+(Thanks to Jean Abou-Samra for the clear discussion of this point)
+
+Why not use a requirements file for dependencies?
+-------------------------------------------------
+
+Putting your requirements in a requirements file, doesn't require a PEP. You
+can do that right now, and in fact it's quite likely that many adhoc solutions
+do this. However, without a standard, there's no way of knowing how to locate a
+script's dependency data. And furthermore, the requirements file format is
+pip-specific, so tools relying on it are depending on a pip implementation
+detail.
+
+So in order to make a standard, two things would be required:
+
+1. A standardised replacement for the requirements file format.
+2. A standard for how to locate the requirements file for a given script.
+
+The first item is a significant undertaking. It has been discussed on a number
+of occasions, but so far no-one has attempted to actually do it. The most
+likely approach would be for standards to be developed for individual use cases
+currently addressed with requirements files. One option here would be for this
+PEP to simply define a new file format which is simply a text file containing
+:pep:`508` requirements, one per line. That would just leave the question of
+how to locate that file.
+
+The "obvious" solution here would be to do something like name the file the
+same as the script, but with a ``.reqs`` extension (or something similar).
+However, this still requires *two* files, where currently only a single file is
+needed, and as such, does not match the "better batch file" model (shell
+scripts and batch files are typically self-contained). It requires the
+developer to remember to keep the two files together, and this may not always
+be possible. For example, system administration policies may require that *all*
+files in a certain directory are executable (the Linux filesystem standards
+require this of ``/usr/bin``, for example). And some methods of sharing a
+script (for example, publishing it on a text file sharing service like Github's
+gist, or a corporate intranet) may not allow for deriving the location of an
+associated requirements file from the script's location (tools like ``pipx``
+support running a script directly from a URL, so "download and unpack a zip of
+the script and its dependencies" may not be an appropriate requirement).
+
+Essentially, though, the issue here is that there is an explicitly stated
+requirement that the format supports storing dependency data *in the script
+file itself*. Solutions that don't do that are simply ignoring that
+requirement.
+
+Why not use (possibly restricted) Python syntax?
+------------------------------------------------
+
+This would typically involve storing metadata as multiple special variables,
+such as the following.
+
+.. code:: python
+
+    __requires_python__ = ">=3.11"
+    __dependencies__ = [
+        "requests",
+        "click",
+    ]
+
+The most significant problem with this proposal is that it requires all
+consumers of the dependency data to implement a Python parser. Even if the
+syntax is restricted, the *rest* of the script will use the full Python syntax,
+and trying to define a syntax which can be successfully parsed in isolation
+from the surrounding code is likely to be extremely difficult and error-prone.
+
+Furthermore, Python's syntax changes in every release. If extracting dependency
+data needs a Python parser, the parser will need to know which version of
+Python the script is written for, and the overhead for a generic tool of having
+a parser that can handle *multiple* versions of Python is unsustainable.
+
+With this approach there is the potential to clutter scripts with many
+variables as new extensions get added. Additionally, intuiting which metadata
+fields correspond to which variable names would cause confusion for users.
+
+It is worth noting, though, that the ``pip-run`` utility does implement (an
+extended form of) this approach. `Further discussion `_ of
+the ``pip-run`` design is available on the project's issue tracker.
+
+What about local dependencies?
+------------------------------
+
+These can be handled without needing special metadata and tooling, simply by
+adding the location of the dependencies to ``sys.path``. This PEP simply isn't
+needed for this case. If, on the other hand, the "local dependencies" are
+actual distributions which are published locally, they can be specified as
+usual with a :pep:`508` requirement, and the local package index specified when
+running a tool by using the tool's UI for that.
+
+Open Issues
+===========
+
+None at this point.
+
+
+References
+==========
+
+.. _pyproject metadata: https://packaging.python.org/en/latest/specifications/declaring-project-metadata/
+.. _pip-run issue: https://github.com/jaraco/pip-run/issues/44
+.. _pyproject without wheels: https://discuss.python.org/t/projects-that-arent-meant-to-generate-a-wheel-and-pyproject-toml/29684
+
+
+Footnotes
+=========
+
+.. [1] A large number of users use scripts that are version controlled. For
+   example, `the SREs that were mentioned <723-comment-block_>`_ or
+   projects that require special maintenance like the
+   `AWS CLI `__
+   or `Calibre `__.
+.. [2] The syntax is taken directly from the final resolution of the
+   `Blocks extension`__ to `Python Markdown`__.
+
+   __ https://github.com/facelessuser/pymdown-extensions/discussions/1973
+   __ https://github.com/Python-Markdown/markdown
+.. [3] A future PEP that officially introduces the ``[run]`` table to
+   ``pyproject.toml`` files will make this PEP not just similar but a strict
+   subset.
+.. [4] One important thing to note is that the metadata is embedded in a
+   `doc-comment`__ (their equivalent of docstrings). `Other syntaxes`__ are
+   under consideration within the Rust project.
+
+   __ https://doc.rust-lang.org/stable/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments
+   __ https://github.com/epage/cargo-script-mvs/blob/main/0000-cargo-script.md#embedded-manifest-format
+
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.

From ff9926fd8c6c9ad71224513bfa563719f07950a4 Mon Sep 17 00:00:00 2001
From: chrysle 
Date: Sun, 12 Nov 2023 10:24:47 +0100
Subject: [PATCH 158/733] Warn of exceeding PyPI project size limit in GHA
 guide

---
 ...tion-releases-using-github-actions-ci-cd-workflows.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
index 33cc88017..db7c88973 100644
--- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
+++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
@@ -219,6 +219,14 @@ And it'll publish any push to TestPyPI which is useful for
 providing test builds to your alpha users as well as making
 sure that your release pipeline remains healthy!
 
+.. attention::
+
+  If your repository has frequent commit activity and every push is uploaded
+  to TestPyPI as described, the project might exceed the
+  `PyPI project size limit `_.
+  The limit could be increased, but a better solution may constitute to
+  use a PyPI-compatible server like :ref:`pypiserver` in the CI for testing purposes.
+
 .. note::
 
    It is recommended to keep the integrated GitHub Actions at their latest

From 52db69f91b6d3f3e390761b428dbb5de6d59816e Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 12 Nov 2023 22:11:25 +0100
Subject: [PATCH 159/733] Add ref to version-specifiers

---
 source/guides/writing-pyproject-toml.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 70028856c..9d3634f10 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -67,6 +67,10 @@ Put the version of your project.
     [project]
     version = "2020.0.0"
 
+Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha
+release) are possible; see the :ref:`specification `
+for full details.
+
 This field is required, although it is often marked as dynamic using
 
 .. code-block:: toml

From b4ffccd73ea4466ea32010f8da67fda19c0768de Mon Sep 17 00:00:00 2001
From: chrysle 
Date: Sun, 12 Nov 2023 10:02:39 +0100
Subject: [PATCH 160/733] Improve namespace packaging guide

---
 .../guides/packaging-namespace-packages.rst   | 84 +++++++++++++------
 1 file changed, 58 insertions(+), 26 deletions(-)

diff --git a/source/guides/packaging-namespace-packages.rst b/source/guides/packaging-namespace-packages.rst
index 301b53d63..d2b05a701 100644
--- a/source/guides/packaging-namespace-packages.rst
+++ b/source/guides/packaging-namespace-packages.rst
@@ -57,24 +57,15 @@ import object short).
 Creating a namespace package
 ============================
 
-There are currently three different approaches to creating namespace packages:
+There are currently two different approaches to creating namespace packages,
+from which the latter is discouraged:
 
 #. Use `native namespace packages`_. This type of namespace package is defined
    in :pep:`420` and is available in Python 3.3 and later. This is recommended if
    packages in your namespace only ever need to support Python 3 and
    installation via ``pip``.
-#. Use `pkgutil-style namespace packages`_. This is recommended for new
-   packages that need to support Python 2 and 3 and installation via both
-   ``pip`` and ``python setup.py install``.
-#. Use `pkg_resources-style namespace packages`_. This method is recommended if
-   you need compatibility with packages already using this method or if your
-   package needs to be zip-safe.
-
-.. warning:: While native namespace packages and pkgutil-style namespace
-    packages are largely compatible, pkg_resources-style namespace packages
-    are not compatible with the other methods. It's inadvisable to use
-    different methods in different distributions that provide packages to the
-    same namespace.
+#. Use `legacy namespace packages`_. This comprises `pkgutil-style namespace packages`_
+   and `pkg_resources-style namespace packages`_.
 
 Native namespace packages
 -------------------------
@@ -86,13 +77,14 @@ structure:
 
 .. code-block:: text
 
-    setup.py
-    mynamespace/
+    mynamespace-subpackage-a/
+        setup.py # AND/OR pyproject.toml, setup.cfg
+        mynamespace/ # namespace package
         # No __init__.py here.
-        subpackage_a/
-            # Sub-packages have __init__.py.
-            __init__.py
-            module.py
+            subpackage_a/
+                # Sub-packages have an __init__.py.
+                __init__.py
+                module.py
 
 It is extremely important that every distribution that uses the namespace
 package omits the :file:`__init__.py` or uses a pkgutil-style
@@ -112,8 +104,31 @@ list all packages in your :file:`setup.py`. For example:
         name='mynamespace-subpackage-a',
         ...
         packages=find_namespace_packages(include=['mynamespace.*'])
+        # or list a single package explicitly:
+        # packages=['mynamespace.subpackage_a'],
     )
 
+The same can be accomplished by replacing the :file:`setup.py` in the
+namespace packages' parent directory with a :file:`pyproject.toml`,
+with the following contents:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["setuptools", "setuptools-scm"]
+    build-backend = "setuptools.build_meta"
+
+    [tool.setuptools.packages.find]
+    where = ["."]
+    include = ["mynamespace.*"]
+
+    [project]
+    name = "mynamespace-subpackage-a"
+    ...
+
+:ref:`setuptools` will search the directory structure for implicit namespace
+packages by default.
+
 A complete working example of two native namespace packages can be found in
 the `native namespace package example project`_.
 
@@ -125,8 +140,25 @@ the `native namespace package example project`_.
     only support Python 3 and pkgutil-style namespace packages in the
     distributions that need to support Python 2 and 3.
 
+
+Legacy namespace packages
+-------------------------
+
+These to 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 `
+has been deprecated.
+
+To migrate an existing package, all packages sharing the namespace must be migrated simultaneously.
+
+.. warning:: While native namespace packages and pkgutil-style namespace
+    packages are largely compatible, pkg_resources-style namespace packages
+    are not compatible with the other methods. It's inadvisable to use
+    different methods in different distributions that provide packages to the
+    same namespace.
+
 pkgutil-style namespace packages
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Python 2.3 introduced the :doc:`pkgutil ` module and the
 :py:func:`python:pkgutil.extend_path` function. This can be used to declare namespace
@@ -138,7 +170,7 @@ To create a pkgutil-style namespace package, you need to provide an
 
 .. code-block:: text
 
-    setup.py
+    setup.py # AND/OR pyproject.toml, setup.cfg
     mynamespace/
         __init__.py  # Namespace package __init__.py
         subpackage_a/
@@ -146,14 +178,14 @@ To create a pkgutil-style namespace package, you need to provide an
             module.py
 
 The :file:`__init__.py` file for the namespace package needs to contain
-**only** the following:
+the following:
 
 .. code-block:: python
 
     __path__ = __import__('pkgutil').extend_path(__path__, __name__)
 
-**Every** distribution that uses the namespace package must include an
-identical :file:`__init__.py`. If any distribution does not, it will cause the
+**Every** distribution that uses the namespace package must include such
+an :file:`__init__.py`. If any distribution does not, it will cause the
 namespace logic to fail and the other sub-packages will not be importable.  Any
 additional code in :file:`__init__.py` will be inaccessible.
 
@@ -167,7 +199,7 @@ in the `pkgutil namespace example project`_.
 
 
 pkg_resources-style namespace packages
---------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 :doc:`Setuptools ` provides the `pkg_resources.declare_namespace`_ function and
 the ``namespace_packages`` argument to :func:`~setuptools.setup`. Together
@@ -183,7 +215,7 @@ To create a pkg_resources-style namespace package, you need to provide an
 
 .. code-block:: text
 
-    setup.py
+    setup.py # AND/OR pyproject.toml, setup.cfg
     mynamespace/
         __init__.py  # Namespace package __init__.py
         subpackage_a/

From 5b845361c57b9c27e6f26de2308be6e03a5d9594 Mon Sep 17 00:00:00 2001
From: chrysle 
Date: Sun, 12 Nov 2023 16:07:32 +0100
Subject: [PATCH 161/733] Migrate examples to ``src-layout``

And de-emphasize ``setup.py`` in favor of ``pyproject.toml``.
---
 .../guides/packaging-namespace-packages.rst   | 126 ++++++++++--------
 1 file changed, 71 insertions(+), 55 deletions(-)

diff --git a/source/guides/packaging-namespace-packages.rst b/source/guides/packaging-namespace-packages.rst
index d2b05a701..2200c130e 100644
--- a/source/guides/packaging-namespace-packages.rst
+++ b/source/guides/packaging-namespace-packages.rst
@@ -19,7 +19,7 @@ have the following package structure:
             __init__.py
             ...
         module_b.py
-    setup.py
+    pyproject.toml
 
 And you use this package in your code like so::
 
@@ -31,17 +31,19 @@ Then you can break these sub-packages into two separate distributions:
 .. code-block:: text
 
     mynamespace-subpackage-a/
-        setup.py
-        mynamespace/
-            subpackage_a/
-                __init__.py
+        pyproject.toml
+        src/
+            mynamespace/
+                subpackage_a/
+                    __init__.py
 
     mynamespace-subpackage-b/
-        setup.py
-        mynamespace/
-            subpackage_b/
-                __init__.py
-            module_b.py
+        pyproject.toml
+        src/
+            mynamespace/
+                subpackage_b/
+                    __init__.py
+                module_b.py
 
 Each sub-package can now be separately installed, used, and versioned.
 
@@ -73,44 +75,29 @@ Native namespace packages
 Python 3.3 added **implicit** namespace packages from :pep:`420`. All that is
 required to create a native namespace package is that you just omit
 :file:`__init__.py` from the namespace package directory. An example file
-structure:
+structure (following :ref:`src-layout `):
 
 .. code-block:: text
 
     mynamespace-subpackage-a/
-        setup.py # AND/OR pyproject.toml, setup.cfg
-        mynamespace/ # namespace package
-        # No __init__.py here.
-            subpackage_a/
-                # Sub-packages have an __init__.py.
-                __init__.py
-                module.py
+        pyproject.toml # AND/OR setup.py, setup.cfg
+        src/
+            mynamespace/ # namespace package
+            # No __init__.py here.
+                subpackage_a/
+                    # Sub-packages have an __init__.py.
+                    __init__.py
+                    module.py
 
 It is extremely important that every distribution that uses the namespace
 package omits the :file:`__init__.py` or uses a pkgutil-style
 :file:`__init__.py`. If any distribution does not, it will cause the namespace
 logic to fail and the other sub-packages will not be importable.
 
-Because ``mynamespace`` doesn't contain an :file:`__init__.py`,
-:func:`setuptools.find_packages` won't find the sub-package. You must
-use :func:`setuptools.find_namespace_packages` instead or explicitly
-list all packages in your :file:`setup.py`. For example:
-
-.. code-block:: python
-
-    from setuptools import setup, find_namespace_packages
-
-    setup(
-        name='mynamespace-subpackage-a',
-        ...
-        packages=find_namespace_packages(include=['mynamespace.*'])
-        # or list a single package explicitly:
-        # packages=['mynamespace.subpackage_a'],
-    )
-
-The same can be accomplished by replacing the :file:`setup.py` in the
-namespace packages' parent directory with a :file:`pyproject.toml`,
-with the following contents:
+The ``src-layout`` directory structure allows automatic discovery of packages
+by most :term:`build backends `. If however you want to manage
+exclusions or inclusions of packages yourself, this is possible to be configured
+in the top-level :file:`pyproject.toml`:
 
 .. code-block:: toml
 
@@ -119,13 +106,38 @@ with the following contents:
     build-backend = "setuptools.build_meta"
 
     [tool.setuptools.packages.find]
-    where = ["."]
-    include = ["mynamespace.*"]
+    where = ["src/"]
+    include = ["mynamespace.subpackage_a"]
 
     [project]
     name = "mynamespace-subpackage-a"
     ...
 
+The same can be accomplished with a :file:`setup.cfg`:
+
+.. code-block:: ini
+
+   [options]
+    package_dir =
+        =src
+    packages = find_namespace:
+
+    [options.packages.find]
+    where = src
+
+Or :file:`setup.py`:
+
+.. code-block:: python
+
+    from setuptools import setup, find_namespace_packages
+
+    setup(
+        name='mynamespace-subpackage-a',
+        ...
+        packages=find_namespace_packages(where='src/', include=['mynamespace.subpackage_a']),
+        package_dir={"": "src"},
+    )
+
 :ref:`setuptools` will search the directory structure for implicit namespace
 packages by default.
 
@@ -170,12 +182,14 @@ To create a pkgutil-style namespace package, you need to provide an
 
 .. code-block:: text
 
-    setup.py # AND/OR pyproject.toml, setup.cfg
-    mynamespace/
-        __init__.py  # Namespace package __init__.py
-        subpackage_a/
-            __init__.py  # Sub-package __init__.py
-            module.py
+    mynamespace-subpackage-a/
+        src/
+            pyproject.toml # AND/OR setup.cfg, setup.py
+            mynamespace/
+                __init__.py  # Namespace package __init__.py
+                subpackage_a/
+                    __init__.py  # Sub-package __init__.py
+                    module.py
 
 The :file:`__init__.py` file for the namespace package needs to contain
 the following:
@@ -215,22 +229,24 @@ To create a pkg_resources-style namespace package, you need to provide an
 
 .. code-block:: text
 
-    setup.py # AND/OR pyproject.toml, setup.cfg
-    mynamespace/
-        __init__.py  # Namespace package __init__.py
-        subpackage_a/
-            __init__.py  # Sub-package __init__.py
-            module.py
+    mynamespace-subpackage-a/
+        src/
+            pyproject.toml # AND/OR setup.cfg, setup.py
+            mynamespace/
+                __init__.py  # Namespace package __init__.py
+                subpackage_a/
+                    __init__.py  # Sub-package __init__.py
+                    module.py
 
 The :file:`__init__.py` file for the namespace package needs to contain
-**only** the following:
+the following:
 
 .. code-block:: python
 
     __import__('pkg_resources').declare_namespace(__name__)
 
-**Every** distribution that uses the namespace package must include an
-identical :file:`__init__.py`. If any distribution does not, it will cause the
+**Every** distribution that uses the namespace package must include such an
+:file:`__init__.py`. If any distribution does not, it will cause the
 namespace logic to fail and the other sub-packages will not be importable.  Any
 additional code in :file:`__init__.py` will be inaccessible.
 

From 927d5f6fd9e6eaec7f15979013880f86bc5c4e04 Mon Sep 17 00:00:00 2001
From: chrysle 
Date: Sun, 12 Nov 2023 16:29:12 +0100
Subject: [PATCH 162/733] Fix a typo

Co-authored-by: sinoroc <5529267+sinoroc@users.noreply.github.com>
---
 source/guides/packaging-namespace-packages.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/packaging-namespace-packages.rst b/source/guides/packaging-namespace-packages.rst
index 2200c130e..653530561 100644
--- a/source/guides/packaging-namespace-packages.rst
+++ b/source/guides/packaging-namespace-packages.rst
@@ -156,7 +156,7 @@ the `native namespace package example project`_.
 Legacy namespace packages
 -------------------------
 
-These to methods, that were used to create namespace packages prior to :pep:`420`,
+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 `
 has been deprecated.

From d5e97d8fde3d7ec34ed8a646b55855e8922e4118 Mon Sep 17 00:00:00 2001
From: chrysle 
Date: Mon, 13 Nov 2023 10:15:37 +0100
Subject: [PATCH 163/733] Link to `src-layout vs flat-layout` discussion

---
 source/discussions/src-layout-vs-flat-layout.rst | 2 ++
 source/guides/packaging-namespace-packages.rst   | 6 +++---
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/source/discussions/src-layout-vs-flat-layout.rst b/source/discussions/src-layout-vs-flat-layout.rst
index 2bf9fcdb9..bfa405729 100644
--- a/source/discussions/src-layout-vs-flat-layout.rst
+++ b/source/discussions/src-layout-vs-flat-layout.rst
@@ -1,3 +1,5 @@
+.. _src-layout-vs-flat-layout:
+
 =========================
 src layout vs flat layout
 =========================
diff --git a/source/guides/packaging-namespace-packages.rst b/source/guides/packaging-namespace-packages.rst
index 653530561..7ff158888 100644
--- a/source/guides/packaging-namespace-packages.rst
+++ b/source/guides/packaging-namespace-packages.rst
@@ -95,9 +95,9 @@ package omits the :file:`__init__.py` or uses a pkgutil-style
 logic to fail and the other sub-packages will not be importable.
 
 The ``src-layout`` directory structure allows automatic discovery of packages
-by most :term:`build backends `. If however you want to manage
-exclusions or inclusions of packages yourself, this is possible to be configured
-in the top-level :file:`pyproject.toml`:
+by most :term:`build backends `. See :ref:`src-layout-vs-flat-layout`
+for more information. If however you want to manage exclusions or inclusions of packages 
+yourself, this is possible to be configured in the top-level :file:`pyproject.toml`:
 
 .. code-block:: toml
 

From ab57c779fecb731e4d20164afe8653dac240aee1 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 13 Nov 2023 09:21:10 +0000
Subject: [PATCH 164/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/guides/packaging-namespace-packages.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/packaging-namespace-packages.rst b/source/guides/packaging-namespace-packages.rst
index 7ff158888..5fa984260 100644
--- a/source/guides/packaging-namespace-packages.rst
+++ b/source/guides/packaging-namespace-packages.rst
@@ -96,7 +96,7 @@ logic to fail and the other sub-packages will not be importable.
 
 The ``src-layout`` directory structure allows automatic discovery of packages
 by most :term:`build backends `. See :ref:`src-layout-vs-flat-layout`
-for more information. If however you want to manage exclusions or inclusions of packages 
+for more information. If however you want to manage exclusions or inclusions of packages
 yourself, this is possible to be configured in the top-level :file:`pyproject.toml`:
 
 .. code-block:: toml

From f78f75f254df5a71645b928fc03d1fc67d864bb6 Mon Sep 17 00:00:00 2001
From: chrysle 
Date: Mon, 13 Nov 2023 10:23:12 +0100
Subject: [PATCH 165/733] Format code snippets

Co-authored-by: sinoroc <5529267+sinoroc@users.noreply.github.com>
---
 source/guides/packaging-namespace-packages.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/guides/packaging-namespace-packages.rst b/source/guides/packaging-namespace-packages.rst
index 5fa984260..e48ba873b 100644
--- a/source/guides/packaging-namespace-packages.rst
+++ b/source/guides/packaging-namespace-packages.rst
@@ -83,7 +83,7 @@ structure (following :ref:`src-layout `):
         pyproject.toml # AND/OR setup.py, setup.cfg
         src/
             mynamespace/ # namespace package
-            # No __init__.py here.
+                # No __init__.py here.
                 subpackage_a/
                     # Sub-packages have an __init__.py.
                     __init__.py
@@ -117,7 +117,7 @@ The same can be accomplished with a :file:`setup.cfg`:
 
 .. code-block:: ini
 
-   [options]
+    [options]
     package_dir =
         =src
     packages = find_namespace:
@@ -135,7 +135,7 @@ Or :file:`setup.py`:
         name='mynamespace-subpackage-a',
         ...
         packages=find_namespace_packages(where='src/', include=['mynamespace.subpackage_a']),
-        package_dir={"": "src"},
+        package_dir={'': 'src'},
     )
 
 :ref:`setuptools` will search the directory structure for implicit namespace

From 44e5ff02f620d14c63a5d7912ef67710ab02fa16 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 13 Nov 2023 18:39:55 +0000
Subject: [PATCH 166/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.1.4 → v0.1.5](https://github.com/astral-sh/ruff-pre-commit/compare/v0.1.4...v0.1.5)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 88494c690..7b47351d3 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -33,7 +33,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.4
+  rev: v0.1.5
   hooks:
     - id: ruff
     - id: ruff-format

From e34cf795c2c76b70baa18ba319be0b224151f9a9 Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Mon, 13 Nov 2023 19:07:55 -0500
Subject: [PATCH 167/733] add german words to codespell ignore

---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 88494c690..7337a6c21 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -15,7 +15,7 @@ repos:
   rev: v2.2.6
   hooks:
   - id: codespell
-    args: ["-L", "ned"]
+    args: ["-L", "ned,ist,oder"]
 
 - repo: local
   hooks:

From a8389a1972d48e576a97fb755cb480146723b605 Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Mon, 13 Nov 2023 19:27:05 -0500
Subject: [PATCH 168/733] Add note that News doc is not currently being updated

---
 source/news.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/source/news.rst b/source/news.rst
index 09415fddd..a8c70dc1b 100644
--- a/source/news.rst
+++ b/source/news.rst
@@ -1,6 +1,10 @@
 News
 ====
 
+.. note:: This document is not currently updated. Previously, the document
+  highlighted changes in Python packaging.
+
+
 September 2019
 --------------
 - Added a guide about publishing dists via GitHub Actions. (:pr:`647`)

From 8ea57348aef4b73fe2efe03a6063dcf3ae11aea1 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 14 Nov 2023 01:46:31 +0100
Subject: [PATCH 169/733] Change example name from spam to spam-eggs

---
 source/guides/writing-pyproject-toml.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 9d3634f10..3c3c741c9 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -54,7 +54,7 @@ only field that cannot be marked as dynamic.
 .. code-block:: toml
 
    [project]
-   name = "spam"
+   name = "spam-eggs"
 
 
 ``version``
@@ -317,7 +317,7 @@ A full example
 .. code-block:: toml
 
    [project]
-   name = "spam"
+   name = "spam-eggs"
    version = "2020.0.0"
    dependencies = [
      "httpx",

From 1e7385dd8b49d553e4fd0788653b77d140f4d72c Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 12 Nov 2023 00:16:12 +0100
Subject: [PATCH 170/733] PEP 723: Editing to fit the PUG

---
 .../declaring-build-dependencies.rst          |   2 +
 source/specifications/index.rst               |   1 +
 .../specifications/inline-script-metadata.rst | 654 +-----------------
 3 files changed, 33 insertions(+), 624 deletions(-)

diff --git a/source/specifications/declaring-build-dependencies.rst b/source/specifications/declaring-build-dependencies.rst
index 3ac94b0b3..1d8045eda 100644
--- a/source/specifications/declaring-build-dependencies.rst
+++ b/source/specifications/declaring-build-dependencies.rst
@@ -50,6 +50,8 @@ should consider it an error.
 
 .. TODO: move elsewhere
 
+.. _pyproject-tool-table:
+
 tool table
 ----------
 
diff --git a/source/specifications/index.rst b/source/specifications/index.rst
index 4f622d845..fb1a1fee2 100644
--- a/source/specifications/index.rst
+++ b/source/specifications/index.rst
@@ -21,6 +21,7 @@ Package Distribution Metadata
    dependency-specifiers
    declaring-build-dependencies
    declaring-project-metadata
+   inline-script-metadata
    platform-compatibility-tags
 
 Package Installation Environment Metadata
diff --git a/source/specifications/inline-script-metadata.rst b/source/specifications/inline-script-metadata.rst
index 04fb0d238..021c316fe 100644
--- a/source/specifications/inline-script-metadata.rst
+++ b/source/specifications/inline-script-metadata.rst
@@ -1,104 +1,24 @@
-PEP: 723
-Title: Inline script metadata
-Author: Ofek Lev 
-Sponsor: Adam Turner 
-PEP-Delegate: Brett Cannon 
-Discussions-To: https://discuss.python.org/t/31151
-Status: Provisional
-Type: Standards Track
-Topic: Packaging
-Content-Type: text/x-rst
-Created: 04-Aug-2023
-Post-History: `04-Aug-2023 `__,
-              `06-Aug-2023 `__,
-              `23-Aug-2023 `__,
-Replaces: 722
-Resolution: https://discuss.python.org/t/36763
-
-
-Abstract
-========
-
-This PEP specifies a metadata format that can be embedded in single-file Python
-scripts to assist launchers, IDEs and other external tools which may need to
-interact with such scripts.
-
-
-Motivation
-==========
-
-Python is routinely used as a scripting language, with Python scripts as a
-(better) alternative to shell scripts, batch files, etc. When Python code is
-structured as a script, it is usually stored as a single file and does not
-expect the availability of any other local code that may be used for imports.
-As such, it is possible to share with others over arbitrary text-based means
-such as email, a URL to the script, or even a chat window. Code that is
-structured like this may live as a single file forever, never becoming a
-full-fledged project with its own directory and ``pyproject.toml`` file.
-
-An issue that users encounter with this approach is that there is no standard
-mechanism to define metadata for tools whose job it is to execute such scripts.
-For example, a tool that runs a script may need to know which dependencies are
-required or the supported version(s) of Python.
-
-There is currently no standard tool that addresses this issue, and this PEP
-does *not* attempt to define one. However, any tool that *does* address this
-issue will need to know what the runtime requirements of scripts are. By
-defining a standard format for storing such metadata, existing tools, as well
-as any future tools, will be able to obtain that information without requiring
-users to include tool-specific metadata in their scripts.
-
-
-Rationale
-=========
-
-This PEP defines a mechanism for embedding metadata *within the script itself*,
-and not in an external file.
-
-We choose to follow the latest developments of other modern packaging
-ecosystems (namely `Go`__ and provisionally `Rust`__) by embedding the existing
-file used to describe projects, in our case ``pyproject.toml``.
-
-__ https://github.com/erning/gorun
-__ https://rust-lang.github.io/rfcs/3424-cargo-script.html
-
-The format is intended to bridge the gap between different types of users
-of Python. Users will benefit from seamless interoperability with tools that
-already work with TOML.
-
-One of the central themes we discovered from the recent
-`packaging survey `__ is that users have
-begun getting frustrated with the lack of unification regarding both tooling
-and specs. Adding yet another metadata format (like :pep:`722` syntax for a
-list of dependencies), even for a currently unsatisfied use case, would
-further fragment the community.
-
-The following are some of the use cases that this PEP wishes to support:
-
-* A user facing CLI that is capable of executing scripts. If we take Hatch as
-  an example, the interface would be simply
-  ``hatch run /path/to/script.py [args]`` and Hatch will manage the
-  environment for that script. Such tools could be used as shebang lines on
-  non-Windows systems e.g. ``#!/usr/bin/env hatch run``.
-* A script that desires to transition to a directory-type project. A user may
-  be rapidly prototyping locally or in a remote REPL environment and then
-  decide to transition to a more formal project layout if their idea works
-  out. This intermediate script stage would be very useful to have fully
-  reproducible bug reports. By using the same format, the user can simply copy
-  and paste the metadata into a ``pyproject.toml`` file and continue working
-  without having to learn a new format. More likely, even, is that tooling will
-  eventually support this transformation with a single command.
-* Users that wish to avoid manual dependency management. For example, package
-  managers that have commands to add/remove dependencies or dependency update
-  automation in CI that triggers based on new versions or in response to
-  CVEs [1]_.
+======================
+Inline script metadata
+======================
+
+.. warning::
+   This specification has been **provisionally accepted**. It is subject
+   to being changed or abandoned. See the
+   `PEP 723 conditional acceptance thread `_ for details.
+
+.. _pep723-thread: https://discuss.python.org/t/36763
+
+This specification defines a metadata format that can be embedded in single-file
+Python scripts to assist launchers, IDEs and other external tools which may need
+to interact with such scripts.
 
 
 Specification
 =============
 
-This PEP defines a metadata comment block format loosely inspired [2]_ by
-`reStructuredText Directives`__.
+This specification defines a metadata comment block format (loosely inspired by
+`reStructuredText Directives`__).
 
 __ https://docutils.sourceforge.io/docs/ref/rst/directives.html
 
@@ -159,25 +79,26 @@ pyproject type
 --------------
 
 The first type of metadata block is named ``pyproject`` which represents
-content similar to [3]_ what one would see in a ``pyproject.toml`` file.
+content similar to what one would see in a ``pyproject.toml`` file.
 
 This document MAY include the ``[run]`` and ``[tool]`` tables.
 
-The :pep:`tool table <518#tool-table>` MAY be used by any tool, script runner
-or otherwise, to configure behavior.
+The :ref:`tool table ` MAY be used by any tool,
+script runner or otherwise, to configure behavior.
 
 The ``[run]`` table MAY include the following optional fields:
 
 * ``dependencies``: A list of strings that specifies the runtime dependencies
-  of the script. Each entry MUST be a valid :pep:`508` dependency.
+  of the script. Each entry MUST be a valid
+  :ref:`dependency specifier `.
 * ``requires-python``: A string that specifies the Python version(s) with which
   the script is compatible. The value of this field MUST be a valid
-  :pep:`version specifier <440#version-specifiers>`.
+  :ref:`version specifier `.
 
-Any future PEPs that define additional fields for the ``[run]`` table when used
-in a ``pyproject.toml`` file MUST include the aforementioned fields exactly as
-specified. The fields defined by this PEP are equally as applicable to
-full-fledged projects as they are to single-file scripts.
+Any future specifications that define additional fields for the ``[run]`` table
+when used in a ``pyproject.toml`` file MUST include the aforementioned fields
+exactly as specified. The fields defined by this specification are equally as
+applicable to full-fledged projects as they are to single-file scripts.
 
 Script runners MUST error if the specified ``dependencies`` cannot be provided.
 Script runners SHOULD error if no version of Python that satisfies the specified
@@ -206,7 +127,7 @@ The following is an example of a script with an embedded ``pyproject.toml``:
     data = resp.json()
     pprint([(k, v["title"]) for k, v in data.items()][:10])
 
-The following [4]_ is an example of a proposed syntax for single-file Rust
+The following is an example of a proposed syntax for single-file Rust
 projects that embeds their equivalent of ``pyproject.toml``, which is called
 ``Cargo.toml``:
 
@@ -306,85 +227,6 @@ blocks.
            )
 
 
-Backwards Compatibility
-=======================
-
-At the time of writing, the ``# /// pyproject`` block comment starter does not
-appear `on GitHub`__. Therefore, there is little risk of existing scripts being
-broken by this PEP.
-
-__ https://github.com/search?q=%22%23+%2F%2F%2F+pyproject%22&type=code
-
-
-Security Implications
-=====================
-
-If a script containing embedded metadata is ran using a tool that automatically
-installs dependencies, this could cause arbitrary code to be downloaded and
-installed in the user's environment.
-
-The risk here is part of the functionality of the tool being used to run the
-script, and as such should already be addressed by the tool itself. The only
-additional risk introduced by this PEP is if an untrusted script with a
-embedded metadata is run, when a potentially malicious dependency or transitive
-dependency might be installed.
-
-This risk is addressed by the normal good practice of reviewing code
-before running it. Additionally, tools may be able to provide
-`locking functionality <723-tool-configuration_>`__ to ameliorate this risk.
-
-
-How to Teach This
-=================
-
-To embed metadata in a script, define a comment block that starts with the
-line ``# /// pyproject`` and ends with the line ``# ///``. Every line between
-those two lines must be a comment and the full content is derived by removing
-the first two characters. The ``pyproject`` type indicates that the content
-is TOML and resembles a ``pyproject.toml`` file.
-
-.. code:: python
-
-    # /// pyproject
-    # [run]
-    # dependencies = [
-    #   "requests<3",
-    #   "rich",
-    # ]
-    # requires-python = ">=3.11"
-    # ///
-
-The two allowed tables are ``[run]`` and ``[tool]``. The ``[run]`` table may
-contain the following fields:
-
-.. list-table::
-
-   * - Field
-     - Description
-     - Tool behavior
-
-   * - ``dependencies``
-     - A list of strings that specifies the runtime dependencies of the script.
-       Each entry must be a valid :pep:`508` dependency.
-     - Tools will error if the specified dependencies cannot be provided.
-
-   * - ``requires-python``
-     - A string that specifies the Python version(s)
-       with which the script is compatible.
-       The value of this field must be a valid
-       :pep:`version specifier <440#version-specifiers>`.
-     - Tools might error if no version of Python that satisfies
-       the constraint can be executed.
-
-It is up to individual tools whether or not their behavior is altered based on
-the embedded metadata. For example, every script runner may not be able to
-provide an environment for specific Python versions as defined by the
-``requires-python`` field.
-
-The :pep:`tool table <518#tool-table>` may be used by any tool, script runner
-or otherwise, to configure behavior.
-
-
 Recommendations
 ===============
 
@@ -393,443 +235,7 @@ the highest available version of Python that is compatible with the script's
 ``requires-python`` metadata, if defined.
 
 
-Tooling buy-in
-==============
-
-The following is a list of tools that have expressed support for this PEP or
-have committed to implementing support should it be accepted:
-
-* `Pantsbuild and Pex `__:  expressed
-  support for any way to define dependencies and also features that this PEP
-  considers as valid use cases such as building packages from scripts and
-  embedding tool configuration
-* `Mypy `__ and
-  `Ruff `__: strongly expressed support
-  for embedding tool configuration as it would solve existing pain points for
-  users
-* `Hatch `__: (author of this PEP)
-  expressed support for all aspects of this PEP, and will be one of the first
-  tools to support running scripts with specifically configured Python versions
-
-
-Rejected Ideas
-==============
-
-.. _723-comment-block:
-
-Why not use a comment block resembling requirements.txt?
---------------------------------------------------------
-
-This PEP considers there to be different types of users for whom Python code
-would live as single-file scripts:
-
-* Non-programmers who are just using Python as a scripting language to achieve
-  a specific task. These users are unlikely to be familiar with concepts of
-  operating systems like shebang lines or the ``PATH`` environment variable.
-  Some examples:
-
-  * The average person, perhaps at a workplace, who wants to write a script to
-    automate something for efficiency or to reduce tedium
-  * Someone doing data science or machine learning in industry or academia who
-    wants to write a script to analyze some data or for research purposes.
-    These users are special in that, although they have limited programming
-    knowledge, they learn from sources like StackOverflow and blogs that have a
-    programming bent and are increasingly likely to be part of communities that
-    share knowledge and code. Therefore, a non-trivial number of these users
-    will have some familiarity with things like Git(Hub), Jupyter, HuggingFace,
-    etc.
-* Non-programmers who manage operating systems e.g. a sysadmin. These users are
-  able to set up ``PATH``, for example, but are unlikely to be familiar with
-  Python concepts like virtual environments. These users often operate in
-  isolation and have limited need to gain exposure to tools intended for
-  sharing like Git.
-* Programmers who manage operating systems/infrastructure e.g. SREs. These
-  users are not very likely to be familiar with Python concepts like virtual
-  environments, but are likely to be familiar with Git and most often use it
-  to version control everything required to manage infrastructure like Python
-  scripts and Kubernetes config.
-* Programmers who write scripts primarily for themselves. These users over time
-  accumulate a great number of scripts in various languages that they use to
-  automate their workflow and often store them in a single directory, that is
-  potentially version controlled for persistence. Non-Windows users may set
-  up each Python script with a shebang line pointing to the desired Python
-  executable or script runner.
-
-This PEP argues that reusing our TOML-based metadata format is the best for
-each category of user and that the requirements-like block comment is only
-approachable for those who have familiarity with ``requirements.txt``, which
-represents a small subset of users.
-
-* For the average person automating a task or the data scientist, they are
-  already starting with zero context and are unlikely to be familiar with
-  TOML nor ``requirements.txt``. These users will very likely rely on
-  snippets found online via a search engine or utilize AI in the form
-  of a chat bot or direct code completion software. Searching for Python
-  metadata formatting will lead them to the TOML-based format that already
-  exists which they can reuse. The author tested GitHub Copilot with this
-  PEP and it already supports auto-completion of ``dependencies``. In contrast,
-  a new format may take years of being trained on the Internet for models to
-  learn.
-
-  Additionally, these users are most susceptible to formatting quirks and
-  syntax errors. TOML is a well-defined format with existing online
-  validators that features assignment that is compatible with Python
-  expressions and has no strict indenting rules. The block comment format
-  on the other hand could be easily malformed by forgetting the colon, for
-  example, and debugging why it's not working with a search engine would be
-  a difficult task for such a user.
-* For the sysadmin types, they are equally unlikely as the previously described
-  users to be familiar with TOML or ``requirements.txt``. For either format
-  they would have to read documentation. They would likely be more comfortable
-  with TOML since they are used to structured data formats and there would be
-  less perceived magic in their systems.
-
-  Additionally, for maintenance of their systems ``/// pyproject`` would be
-  much easier to search for from a shell than a block comment with potentially
-  numerous extensions over time.
-* For the SRE types, they are likely to be familiar with TOML already from
-  other projects that they might have to work with like configuring the
-  `GitLab Runner`__ or `Cloud Native Buildpacks`__.
-
-  __ https://docs.gitlab.com/runner/configuration/advanced-configuration.html
-  __ https://buildpacks.io/docs/reference/config/
-
-  These users are responsible for the security of their systems and most likely
-  have security scanners set up to automatically open PRs to update versions
-  of dependencies. Such automated tools like Dependabot would have a much
-  easier time using existing TOML libraries than writing their own custom
-  parser for a block comment format.
-* For the programmer types, they are more likely to be familiar with TOML
-  than they have ever seen a ``requirements.txt`` file, unless they are a
-  Python programmer who has had previous experience with writing applications.
-  In the case of experience with the requirements format, it necessarily means
-  that they are at least somewhat familiar with the ecosystem and therefore
-  it is safe to assume they know what TOML is.
-
-  Another benefit of this PEP to these users is that their IDEs like Visual
-  Studio Code would be able to provide TOML syntax highlighting much more
-  easily than each writing custom logic for this feature.
-
-Additionally, since the original block comment alternative format (double
-``#``) went against the recommendation of :pep:`8` and as a result linters
-and IDE auto-formatters that respected the recommendation would
-`fail by default `__, the final
-proposal uses standard comments starting with a single ``#`` character without
-any obvious start nor end sequence.
-
-The concept of regular comments that do not appear to be intended for machines
-(i.e. `encoding declarations`__) affecting behavior would not be customary to
-users of Python and goes directly against the "explicit is better than
-implicit" foundational principle.
-
-__ https://docs.python.org/3/reference/lexical_analysis.html#encoding-declarations
-
-Users typing what to them looks like prose could alter runtime behavior. This
-PEP takes the view that the possibility of that happening, even when a tool
-has been set up as such (maybe by a sysadmin), is unfriendly to users.
-
-Finally, and critically, the alternatives to this PEP like :pep:`722` do not
-satisfy the use cases enumerated herein, such as setting the supported Python
-versions, the eventual building of scripts into packages, and the ability to
-have machines edit metadata on behalf of users. It is very likely that the
-requests for such features persist and conceivable that another PEP in the
-future would allow for the embedding of such metadata. At that point there
-would be multiple ways to achieve the same thing which goes against our
-foundational principle of "there should be one - and preferably only one -
-obvious way to do it".
-
-Why not use a multi-line string?
---------------------------------
-
-A previous version of this PEP proposed that the metadata be stored as follows:
-
-.. code:: python
-
-    __pyproject__ = """
-    ...
-    """
-
-The most significant problem with this proposal is that the embedded TOML would
-be limited in the following ways:
-
-* It would not be possible to use multi-line double-quoted strings in the TOML
-  as that would conflict with the Python string containing the document. Many
-  TOML writers do not preserve style and may potentially produce output that
-  would be malformed.
-* The way in which character escaping works in Python strings is not quite the
-  way it works in TOML strings. It would be possible to preserve a one-to-one
-  character mapping by enforcing raw strings, but this ``r`` prefix requirement
-  may be potentially confusing to users.
-
-Why not reuse core metadata fields?
------------------------------------
-
-A previous version of this PEP proposed to reuse the existing
-`metadata standard `_ that is used to describe projects.
-
-There are two significant problems with this proposal:
-
-* The ``name`` and ``version`` fields are required and changing that would
-  require its own PEP
-* Reusing the data is `fundamentally a misuse of it`__
-
-  __ https://snarky.ca/differentiating-between-writing-down-dependencies-to-use-packages-and-for-packages-themselves/
-
-Why not limit to specific metadata fields?
-------------------------------------------
-
-By limiting the metadata to just ``dependencies``, we would prevent the known
-use case of tools that support managing Python installations, which would
-allows users to target specific versions of Python for new syntax or standard
-library functionality.
-
-.. _723-tool-configuration:
-
-Why not limit tool configuration?
----------------------------------
-
-By not allowing the ``[tool]`` table, we would prevent known functionality
-that would benefit users. For example:
-
-* A script runner may support injecting of dependency resolution data for an
-  embedded lock file (this is what Go's ``gorun`` can do).
-* A script runner may support configuration instructing to run scripts in
-  containers for situations in which there is no cross-platform support for a
-  dependency or if the setup is too complex for the average user like when
-  requiring Nvidia drivers. Situations like this would allow users to proceed
-  with what they want to do whereas otherwise they may stop at that point
-  altogether.
-* Tools may wish to experiment with features to ease development burden for
-  users such as the building of single-file scripts into packages. We received
-  `feedback `__ stating that there are
-  already tools that exist in the wild that build wheels and source
-  distributions from single files.
-
-  The author of the Rust RFC for embedding metadata
-  `mentioned to us `__ that they are
-  actively looking into that as well based on user feedback saying that there
-  is unnecessary friction with managing small projects.
-
-  There has been `a commitment `__ to
-  support this by at least one major build system.
-
-Why not limit tool behavior?
-----------------------------
-
-A previous version of this PEP proposed that non-script running tools SHOULD
-NOT modify their behavior when the script is not the sole input to the tool.
-For example, if a linter is invoked with the path to a directory, it SHOULD
-behave the same as if zero files had embedded metadata.
-
-This was done as a precaution to avoid tool behavior confusion and generating
-various feature requests for tools to support this PEP. However, during
-discussion we received `feedback `__
-from maintainers of tools that this would be undesirable and potentially
-confusing to users. Additionally, this may allow for a universally easier
-way to configure tools in certain circumstances and solve existing issues.
-
-Why not just set up a Python project with a ``pyproject.toml``?
----------------------------------------------------------------
-
-Again, a key issue here is that the target audience for this proposal is people
-writing scripts which aren't intended for distribution. Sometimes scripts will
-be "shared", but this is far more informal than "distribution" - it typically
-involves sending a script via an email with some written instructions on how to
-run it, or passing someone a link to a GitHub gist.
-
-Expecting such users to learn the complexities of Python packaging is a
-significant step up in complexity, and would almost certainly give the
-impression that "Python is too hard for scripts".
-
-In addition, if the expectation here is that the ``pyproject.toml`` will
-somehow be designed for running scripts in place, that's a new feature of the
-standard that doesn't currently exist. At a minimum, this isn't a reasonable
-suggestion until the `current discussion on Discourse
-`_ about using ``pyproject.toml`` for projects that
-won't be distributed as wheels is resolved. And even then, it doesn't address
-the "sending someone a script in a gist or email" use case.
-
-Why not infer the requirements from import statements?
-------------------------------------------------------
-
-The idea would be to automatically recognize ``import`` statements in the source
-file and turn them into a list of requirements.
-
-However, this is infeasible for several reasons. First, the points above about
-the necessity to keep the syntax easily parsable, for all Python versions, also
-by tools written in other languages, apply equally here.
-
-Second, PyPI and other package repositories conforming to the Simple Repository
-API do not provide a mechanism to resolve package names from the module names
-that are imported (see also `this related discussion`__).
-
-__ https://discuss.python.org/t/record-the-top-level-names-of-a-wheel-in-metadata/29494
-
-Third, even if repositories did offer this information, the same import name may
-correspond to several packages on PyPI. One might object that disambiguating
-which package is wanted would only be needed if there are several projects
-providing the same import name. However, this would make it easy for anyone to
-unintentionally or malevolently break working scripts, by uploading a package to
-PyPI providing an import name that is the same as an existing project. The
-alternative where, among the candidates, the first package to have been
-registered on the index is chosen, would be confusing in case a popular package
-is developed with the same import name as an existing obscure package, and even
-harmful if the existing package is malware intentionally uploaded with a
-sufficiently generic import name that has a high probability of being reused.
-
-A related idea would be to attach the requirements as comments to the import
-statements instead of gathering them in a block, with a syntax such as::
-
-  import numpy as np # requires: numpy
-  import rich # requires: rich
-
-This still suffers from parsing difficulties. Also, where to place the comment
-in the case of multiline imports is ambiguous and may look ugly::
-
-   from PyQt5.QtWidgets import (
-       QCheckBox, QComboBox, QDialog, QDialogButtonBox,
-       QGridLayout, QLabel, QSpinBox, QTextEdit
-   ) # requires: PyQt5
-
-Furthermore, this syntax cannot behave as might be intuitively expected
-in all situations. Consider::
-
-  import platform
-  if platform.system() == "Windows":
-      import pywin32 # requires: pywin32
-
-Here, the user's intent is that the package is only required on Windows, but
-this cannot be understood by the script runner (the correct way to write
-it would be ``requires: pywin32 ; sys_platform == 'win32'``).
-
-(Thanks to Jean Abou-Samra for the clear discussion of this point)
-
-Why not use a requirements file for dependencies?
--------------------------------------------------
-
-Putting your requirements in a requirements file, doesn't require a PEP. You
-can do that right now, and in fact it's quite likely that many adhoc solutions
-do this. However, without a standard, there's no way of knowing how to locate a
-script's dependency data. And furthermore, the requirements file format is
-pip-specific, so tools relying on it are depending on a pip implementation
-detail.
-
-So in order to make a standard, two things would be required:
-
-1. A standardised replacement for the requirements file format.
-2. A standard for how to locate the requirements file for a given script.
-
-The first item is a significant undertaking. It has been discussed on a number
-of occasions, but so far no-one has attempted to actually do it. The most
-likely approach would be for standards to be developed for individual use cases
-currently addressed with requirements files. One option here would be for this
-PEP to simply define a new file format which is simply a text file containing
-:pep:`508` requirements, one per line. That would just leave the question of
-how to locate that file.
-
-The "obvious" solution here would be to do something like name the file the
-same as the script, but with a ``.reqs`` extension (or something similar).
-However, this still requires *two* files, where currently only a single file is
-needed, and as such, does not match the "better batch file" model (shell
-scripts and batch files are typically self-contained). It requires the
-developer to remember to keep the two files together, and this may not always
-be possible. For example, system administration policies may require that *all*
-files in a certain directory are executable (the Linux filesystem standards
-require this of ``/usr/bin``, for example). And some methods of sharing a
-script (for example, publishing it on a text file sharing service like Github's
-gist, or a corporate intranet) may not allow for deriving the location of an
-associated requirements file from the script's location (tools like ``pipx``
-support running a script directly from a URL, so "download and unpack a zip of
-the script and its dependencies" may not be an appropriate requirement).
-
-Essentially, though, the issue here is that there is an explicitly stated
-requirement that the format supports storing dependency data *in the script
-file itself*. Solutions that don't do that are simply ignoring that
-requirement.
-
-Why not use (possibly restricted) Python syntax?
-------------------------------------------------
-
-This would typically involve storing metadata as multiple special variables,
-such as the following.
-
-.. code:: python
-
-    __requires_python__ = ">=3.11"
-    __dependencies__ = [
-        "requests",
-        "click",
-    ]
-
-The most significant problem with this proposal is that it requires all
-consumers of the dependency data to implement a Python parser. Even if the
-syntax is restricted, the *rest* of the script will use the full Python syntax,
-and trying to define a syntax which can be successfully parsed in isolation
-from the surrounding code is likely to be extremely difficult and error-prone.
-
-Furthermore, Python's syntax changes in every release. If extracting dependency
-data needs a Python parser, the parser will need to know which version of
-Python the script is written for, and the overhead for a generic tool of having
-a parser that can handle *multiple* versions of Python is unsustainable.
-
-With this approach there is the potential to clutter scripts with many
-variables as new extensions get added. Additionally, intuiting which metadata
-fields correspond to which variable names would cause confusion for users.
-
-It is worth noting, though, that the ``pip-run`` utility does implement (an
-extended form of) this approach. `Further discussion `_ of
-the ``pip-run`` design is available on the project's issue tracker.
-
-What about local dependencies?
-------------------------------
-
-These can be handled without needing special metadata and tooling, simply by
-adding the location of the dependencies to ``sys.path``. This PEP simply isn't
-needed for this case. If, on the other hand, the "local dependencies" are
-actual distributions which are published locally, they can be specified as
-usual with a :pep:`508` requirement, and the local package index specified when
-running a tool by using the tool's UI for that.
-
-Open Issues
-===========
-
-None at this point.
-
-
-References
-==========
-
-.. _pyproject metadata: https://packaging.python.org/en/latest/specifications/declaring-project-metadata/
-.. _pip-run issue: https://github.com/jaraco/pip-run/issues/44
-.. _pyproject without wheels: https://discuss.python.org/t/projects-that-arent-meant-to-generate-a-wheel-and-pyproject-toml/29684
-
-
-Footnotes
-=========
-
-.. [1] A large number of users use scripts that are version controlled. For
-   example, `the SREs that were mentioned <723-comment-block_>`_ or
-   projects that require special maintenance like the
-   `AWS CLI `__
-   or `Calibre `__.
-.. [2] The syntax is taken directly from the final resolution of the
-   `Blocks extension`__ to `Python Markdown`__.
-
-   __ https://github.com/facelessuser/pymdown-extensions/discussions/1973
-   __ https://github.com/Python-Markdown/markdown
-.. [3] A future PEP that officially introduces the ``[run]`` table to
-   ``pyproject.toml`` files will make this PEP not just similar but a strict
-   subset.
-.. [4] One important thing to note is that the metadata is embedded in a
-   `doc-comment`__ (their equivalent of docstrings). `Other syntaxes`__ are
-   under consideration within the Rust project.
-
-   __ https://doc.rust-lang.org/stable/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments
-   __ https://github.com/epage/cargo-script-mvs/blob/main/0000-cargo-script.md#embedded-manifest-format
-
-
-Copyright
-=========
+History
+=======
 
-This document is placed in the public domain or under the
-CC0-1.0-Universal license, whichever is more permissive.
+This specification was originally defined as :pep:`723`.

From 766b8b9390838f78c83c1582f0d138588d5f2b46 Mon Sep 17 00:00:00 2001
From: chrysle 
Date: Tue, 14 Nov 2023 16:43:16 +0100
Subject: [PATCH 171/733] Highlight regular package as opposite to namespace
 package

And shorten `[build-system]` table.

Co-authored-by: sinoroc <5529267+sinoroc@users.noreply.github.com>
---
 source/guides/packaging-namespace-packages.rst | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/source/guides/packaging-namespace-packages.rst b/source/guides/packaging-namespace-packages.rst
index e48ba873b..548020239 100644
--- a/source/guides/packaging-namespace-packages.rst
+++ b/source/guides/packaging-namespace-packages.rst
@@ -85,7 +85,7 @@ structure (following :ref:`src-layout `):
             mynamespace/ # namespace package
                 # No __init__.py here.
                 subpackage_a/
-                    # Sub-packages have an __init__.py.
+                    # Regular import packages have an __init__.py.
                     __init__.py
                     module.py
 
@@ -102,8 +102,7 @@ yourself, this is possible to be configured in the top-level :file:`pyproject.to
 .. code-block:: toml
 
     [build-system]
-    requires = ["setuptools", "setuptools-scm"]
-    build-backend = "setuptools.build_meta"
+    ...
 
     [tool.setuptools.packages.find]
     where = ["src/"]
@@ -188,7 +187,7 @@ To create a pkgutil-style namespace package, you need to provide an
             mynamespace/
                 __init__.py  # Namespace package __init__.py
                 subpackage_a/
-                    __init__.py  # Sub-package __init__.py
+                    __init__.py  # Regular package __init__.py
                     module.py
 
 The :file:`__init__.py` file for the namespace package needs to contain
@@ -235,7 +234,7 @@ To create a pkg_resources-style namespace package, you need to provide an
             mynamespace/
                 __init__.py  # Namespace package __init__.py
                 subpackage_a/
-                    __init__.py  # Sub-package __init__.py
+                    __init__.py  # Regular package __init__.py
                     module.py
 
 The :file:`__init__.py` file for the namespace package needs to contain

From 2a71cb9a6e8db17876c69d08281ca9dee6d4d184 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 14 Nov 2023 20:34:25 +0100
Subject: [PATCH 172/733] Expand pyproject.toml guide to also cover the
 [build-system] table

---
 source/guides/writing-pyproject-toml.rst | 103 +++++++++++++++++++----
 1 file changed, 87 insertions(+), 16 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 3c3c741c9..0e1eeef55 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -4,27 +4,98 @@
 Writing your ``pyproject.toml``
 ===============================
 
-``pyproject.toml`` is a configuration file used by packaging tools. Most
-:term:`build backends ` [#poetry-special]_ allow you to specify
-your project's basic metadata, such as the dependencies, your name, etc.,
-in the ``[project]`` table of your ``pyproject.toml``.
+``pyproject.toml`` is a configuration file used by packaging tools, as
+well as other tools such as linters, type checkers, etc. There are
+three possible TOML tables in this file.
+
+- The ``[build-system]`` table is **strongly recommended**. It allows
+  you to declare which :term:`build backend` you use and which other
+  dependencies are needed to build your project.
+
+- The ``[project]`` table is the format that most build backends use to specify
+  your project's basic metadata, such as the dependencies, your name, etc.
+
+- The ``[tool]`` table has arbitrary subtables corresponding to tools, whether
+  packaging-related or not, e.g., ``[tool.hatch]``, ``[tool.black]``,
+  ``[tool.mypy]``. We only touch upon this table here because its contents are
+  entirely tool-specific. Consult each tool's documentation to know what it can
+  contain.
 
 .. note::
 
-   You may have heard of ``setup.py`` and ``setup.cfg`` for the setuptools_
-   build backend. For new projects, it is recommended to use ``pyproject.toml``
-   for basic metadata, and keep ``setup.py`` only if some programmatic configuration
-   is needed (especially building C extensions). However, putting basic project
-   metadata in ``setup.py`` or ``setup.cfg`` is still valid. See
+   There is a significant difference between the ``[build-system]`` and
+   ``[project]`` tables. The former should always be present, regardless of
+   which build backend you use (since it *defines* the tool you use). The latter
+   is understood by *most* build backends, but some build backends use a
+   different format.
+
+   At the time of this writing (November 2023), Poetry_ is a notable build
+   backend that does not use the ``[project]`` table (it uses the
+   ``[tool.poetry]`` table instead).
+
+   Also, the setuptools_ build backend supports both the ``[project]`` table,
+   and the older format in ``setup.cfg`` or ``setup.py``. For new projects, it
+   is recommended to use the ``[project]`` table, and keep ``setup.py`` only if
+   some programmatic configuration is needed (especially building C extensions),
+   but the ``setup.cfg`` and ``setup.py`` formats are still valid. See
    :ref:`setup-py-deprecated`.
 
 
+
+Declaring the build backend
+===========================
+
+The ``[build-system]`` table contains a ``build-backend`` key, which specifies
+the build backend to be used. It also contains a ``requires`` key, which is a
+list of dependencies needed to build the project -- this is typically just the
+build backend package, but it may also contain additional dependencies. You can
+also constrain the versions, e.g., ``requires = ["setuptools >= 61.0"]``.
+
+Usually, you'll just copy what your build backend's documentation suggests. Here
+are the values for some common build backends:
+
+.. tab:: Hatchling
+
+    .. code-block:: toml
+
+        [build-system]
+        requires = ["hatchling"]
+        build-backend = "hatchling.build"
+
+.. tab:: setuptools
+
+    .. code-block:: toml
+
+        [build-system]
+        requires = ["setuptools>=61.0"]
+        build-backend = "setuptools.build_meta"
+
+.. tab:: Flit
+
+    .. code-block:: toml
+
+        [build-system]
+        requires = ["flit_core>=3.4"]
+        build-backend = "flit_core.buildapi"
+
+.. tab:: PDM
+
+    .. code-block:: toml
+
+        [build-system]
+        requires = ["pdm-backend"]
+        build-backend = "pdm.backend"
+
+
+The rest of this guide is devoted to the ``[project]`` table.
+
+
 Static vs. dynamic metadata
 ===========================
 
-Most of the time, you will directly write the value of a field in
-``pyproject.toml``.  For example: ``requires-python = ">= 3.8"``, or
-``version = "1.0"``.
+Most of the time, you will directly write the value of a ``[project]``
+field. For example: ``requires-python = ">= 3.8"``, or ``version =
+"1.0"``.
 
 However, in some cases, it is useful to let your build backend compute
 the metadata for you. For example: many build backends can read the
@@ -316,6 +387,10 @@ A full example
 
 .. code-block:: toml
 
+   [build-system]
+   requires = ["hatchling"]
+   build-backend = "hatchling.build"
+
    [project]
    name = "spam-eggs"
    version = "2020.0.0"
@@ -370,10 +445,6 @@ A full example
 
 ------------------
 
-.. [#poetry-special] At the time of this writing (November 2023), Poetry_
-   is a notable exception.  It uses its own format for this metadata, in
-   the ``[tool.poetry]`` table.
-
 .. [#requires-python-upper-bounds] Think twice before applying an upper bound
    like ``requires-python = "<= 3.10"`` here. `This blog post `_
    contains some information regarding possible problems.

From 77c643c4d2be6ec26d4a88f260524ac67e64100b Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 14 Nov 2023 20:07:12 +0100
Subject: [PATCH 173/733] Link to pyproject.toml guide in "Packaging Python
 projects" tutorial

Replace links to the "Declaring project metadata" specification with
links to the "Writing pyproject.toml guide" since this is more likely
what the user wants after a tutorial. Also harmonize with the guide
slightly and leave link to version specifier specification (advanced
reading) for the guide.
---
 source/guides/writing-pyproject-toml.rst |  4 ++--
 source/tutorials/packaging-projects.rst  | 22 +++++++++++-----------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 3c3c741c9..22f232eda 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -28,8 +28,8 @@ Most of the time, you will directly write the value of a field in
 
 However, in some cases, it is useful to let your build backend compute
 the metadata for you. For example: many build backends can read the
-version from a ``__version__`` attribute in your code, or similar.
-In such cases, you should mark the field as dynamic using, e.g.,
+version from a ``__version__`` attribute in your code, a Git tag, or
+similar. In such cases, you should mark the field as dynamic using, e.g.,
 
 .. code-block:: toml
 
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 2678c97b9..8f4076bf4 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -214,17 +214,16 @@ following this tutorial.
     ]
 
     [project.urls]
-    "Homepage" = "https://github.com/pypa/sampleproject"
-    "Bug Tracker" = "https://github.com/pypa/sampleproject/issues"
+    Homepage = "https://github.com/pypa/sampleproject"
+    Issues = "https://github.com/pypa/sampleproject/issues"
 
 - ``name`` is the *distribution name* of your package. This can be any name as
   long as it only contains letters, numbers, ``.``, ``_`` , and ``-``. It also
   must not already be taken on PyPI. **Be sure to update this with your
   username** for this tutorial, as this ensures you won't try to upload a
   package with the same name as one which already exists.
-- ``version`` is the package version. See the :ref:`version specifier specification `
-  for more details on versions. Some build backends allow it to be specified
-  another way, such as from a file or a git tag.
+- ``version`` is the package version. (Some build backends allow it to be
+  specified another way, such as from a file or Git tag.)
 - ``authors`` is used to identify the author of the package; you specify a name
   and an email for each author. You can also list ``maintainers`` in the same
   format.
@@ -233,9 +232,9 @@ following this tutorial.
   package. This is shown on the package detail page on PyPI.
   In this case, the description is loaded from :file:`README.md` (which is a
   common pattern). There also is a more advanced table form described in the
-  :ref:`project metadata specification `.
+  :ref:`pyproject.toml guide `.
 - ``requires-python`` gives the versions of Python supported by your
-  project. Installers like :ref:`pip` will look back through older versions of
+  project. An installer like :ref:`pip` will look back through older versions of
   packages until it finds one that has a matching Python version.
 - ``classifiers`` gives the index and :ref:`pip` some additional metadata
   about your package. In this case, the package is only compatible with Python
@@ -247,10 +246,11 @@ following this tutorial.
 - ``urls`` lets you list any number of extra links to show on PyPI.
   Generally this could be to the source, documentation, issue trackers, etc.
 
-See the :ref:`project metadata specification ` for
-details on these and other fields that can be defined in the ``[project]``
-table. Other common fields are ``keywords`` to improve discoverability and the
-``dependencies`` that are required to install your package.
+See the :ref:`pyproject.toml guide ` for details
+on these and other fields that can be defined in the ``[project]``
+table. Other common fields are ``keywords`` to improve discoverability
+and the ``dependencies`` that are required to install your package.
+
 
 Creating README.md
 ------------------

From 7607fab1a42d3027206da4eec9ec5c37beef6058 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Tue, 14 Nov 2023 21:29:28 +0100
Subject: [PATCH 174/733] Spaces around >=

Co-authored-by: chrysle 
---
 source/guides/writing-pyproject-toml.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 0e1eeef55..6ec8a9d8c 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -67,7 +67,7 @@ are the values for some common build backends:
     .. code-block:: toml
 
         [build-system]
-        requires = ["setuptools>=61.0"]
+        requires = ["setuptools >= 61.0"]
         build-backend = "setuptools.build_meta"
 
 .. tab:: Flit
@@ -75,7 +75,7 @@ are the values for some common build backends:
     .. code-block:: toml
 
         [build-system]
-        requires = ["flit_core>=3.4"]
+        requires = ["flit_core >= 3.4"]
         build-backend = "flit_core.buildapi"
 
 .. tab:: PDM

From 4bbc74ccc26f8172d9626c3556a281c338d5bc6f Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 14 Nov 2023 20:45:55 +0100
Subject: [PATCH 175/733] Improve sidebar presentation in specifications
 section

---
 source/specifications/index.rst               | 49 ++-----------------
 .../section-distribution-formats.rst          |  8 +++
 .../section-distribution-metadata.rst         | 14 ++++++
 .../section-installation-metadata.rst         | 13 +++++
 .../section-package-indices.rst               |  8 +++
 5 files changed, 47 insertions(+), 45 deletions(-)
 create mode 100644 source/specifications/section-distribution-formats.rst
 create mode 100644 source/specifications/section-distribution-metadata.rst
 create mode 100644 source/specifications/section-installation-metadata.rst
 create mode 100644 source/specifications/section-package-indices.rst

diff --git a/source/specifications/index.rst b/source/specifications/index.rst
index fb1a1fee2..8f44e69bb 100644
--- a/source/specifications/index.rst
+++ b/source/specifications/index.rst
@@ -8,50 +8,9 @@ by the Python Packaging Authority. The process for updating these standards,
 and for proposing new ones, is documented on
 `pypa.io `__.
 
-
-Package Distribution Metadata
------------------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   name-normalization
-   core-metadata
-   version-specifiers
-   dependency-specifiers
-   declaring-build-dependencies
-   declaring-project-metadata
-   inline-script-metadata
-   platform-compatibility-tags
-
-Package Installation Environment Metadata
------------------------------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   recording-installed-packages
-   entry-points
-   direct-url
-   direct-url-data-structure
-   virtual-environments
-   externally-managed-environments
-
-Package Distribution File Formats
----------------------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   source-distribution-format
-   binary-distribution-format
-
-
-Package Index Interfaces
-------------------------
-
 .. toctree::
-   :maxdepth: 1
 
-   pypirc
-   simple-repository-api
+   section-distribution-metadata
+   section-installation-metadata
+   section-distribution-formats
+   section-package-indices
diff --git a/source/specifications/section-distribution-formats.rst b/source/specifications/section-distribution-formats.rst
new file mode 100644
index 000000000..94256945d
--- /dev/null
+++ b/source/specifications/section-distribution-formats.rst
@@ -0,0 +1,8 @@
+=================================
+Package Distribution File Formats
+=================================
+
+.. toctree::
+
+   source-distribution-format
+   binary-distribution-format
diff --git a/source/specifications/section-distribution-metadata.rst b/source/specifications/section-distribution-metadata.rst
new file mode 100644
index 000000000..fe1e207f2
--- /dev/null
+++ b/source/specifications/section-distribution-metadata.rst
@@ -0,0 +1,14 @@
+=============================
+Package Distribution Metadata
+=============================
+
+.. toctree::
+
+   name-normalization
+   core-metadata
+   version-specifiers
+   dependency-specifiers
+   declaring-build-dependencies
+   declaring-project-metadata
+   inline-script-metadata
+   platform-compatibility-tags
diff --git a/source/specifications/section-installation-metadata.rst b/source/specifications/section-installation-metadata.rst
new file mode 100644
index 000000000..685a5aac4
--- /dev/null
+++ b/source/specifications/section-installation-metadata.rst
@@ -0,0 +1,13 @@
+=============================
+Package Installation Metadata
+=============================
+
+.. toctree::
+   :titlesonly:
+
+   recording-installed-packages
+   entry-points
+   direct-url
+   direct-url-data-structure
+   virtual-environments
+   externally-managed-environments
diff --git a/source/specifications/section-package-indices.rst b/source/specifications/section-package-indices.rst
new file mode 100644
index 000000000..9da3e30fe
--- /dev/null
+++ b/source/specifications/section-package-indices.rst
@@ -0,0 +1,8 @@
+========================
+Package Index Interfaces
+========================
+
+.. toctree::
+
+   pypirc
+   simple-repository-api

From 26d3fb9ed056deb62e912c720eb8b864fe0244b6 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 14 Nov 2023 21:37:24 +0100
Subject: [PATCH 176/733] Link to "Choosing a build backend"

---
 source/guides/writing-pyproject-toml.rst | 5 +++--
 source/tutorials/packaging-projects.rst  | 2 ++
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 6ec8a9d8c..ae2bdbc77 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -51,8 +51,9 @@ list of dependencies needed to build the project -- this is typically just the
 build backend package, but it may also contain additional dependencies. You can
 also constrain the versions, e.g., ``requires = ["setuptools >= 61.0"]``.
 
-Usually, you'll just copy what your build backend's documentation suggests. Here
-are the values for some common build backends:
+Usually, you'll just copy what your build backend's documentation
+suggests (after :ref:`choosing your build backend `).
+Here are the values for some common build backends:
 
 .. tab:: Hatchling
 
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 2678c97b9..1bc2f77ba 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -103,6 +103,8 @@ Creating a test directory
 :file:`tests/` is a placeholder for test files. Leave it empty for now.
 
 
+.. _choosing-build-backend:
+
 Choosing a build backend
 ------------------------
 

From d9203698145fb3f079327c2a51006d1e9f91afa5 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 8 Nov 2023 16:36:18 +0100
Subject: [PATCH 177/733] Move declaring-build-dependencies.rst verbatim into
 declaring-project-metadata.rst

---
 .../declaring-build-dependencies.rst          | 105 ------------------
 .../declaring-project-metadata.rst            | 104 +++++++++++++++++
 source/specifications/index.rst               |   1 -
 3 files changed, 104 insertions(+), 106 deletions(-)
 delete mode 100644 source/specifications/declaring-build-dependencies.rst

diff --git a/source/specifications/declaring-build-dependencies.rst b/source/specifications/declaring-build-dependencies.rst
deleted file mode 100644
index 1d8045eda..000000000
--- a/source/specifications/declaring-build-dependencies.rst
+++ /dev/null
@@ -1,105 +0,0 @@
-
-.. _declaring-build-dependencies:
-
-===================================
-Declaring build system dependencies
-===================================
-
-The ``pyproject.toml`` file is written in `TOML `_.
-Among other metadata (such as :ref:`project metadata `),
-it declares any Python level dependencies that must be installed in order to
-run the project's build system successfully.
-
-.. TODO: move this sentence elsewhere
-
-Tables not defined by PyPA specifications are reserved for future use.
-
-
-build-system table
-------------------
-
-.. TODO: merge with PEP 517
-
-The ``[build-system]`` table is used to store build-related data.
-Initially,  only one key of the table is valid and is mandatory
-for the table: ``requires``. This key must have a value of a list
-of strings representing dependencies required to execute the
-build system. The strings in this list follow the :ref:`version specifier
-specification `.
-
-An example ``build-system`` table for a project built with
-``setuptools`` is:
-
-.. code-block:: toml
-
-   [build-system]
-   # Minimum requirements for the build system to execute.
-   requires = ["setuptools"]
-
-Build tools are expected to use the example configuration file above as
-their default semantics when a ``pyproject.toml`` file is not present.
-
-Tools should not require the existence of the ``[build-system]`` table.
-A ``pyproject.toml`` file may be used to store configuration details
-other than build-related data and thus lack a ``[build-system]`` table
-legitimately. If the file exists but is lacking the ``[build-system]``
-table then the default values as specified above should be used.
-If the table is specified but is missing required fields then the tool
-should consider it an error.
-
-
-.. TODO: move elsewhere
-
-.. _pyproject-tool-table:
-
-tool table
-----------
-
-The ``[tool]`` table is where any tool related to your Python
-project, not just build tools, can have users specify configuration
-data as long as they use a sub-table within ``[tool]``, e.g. the
-`flit `_ tool would store its
-configuration in ``[tool.flit]``.
-
-A mechanism is needed to allocate names within the ``tool.*``
-namespace, to make sure that different projects do not attempt to use
-the same sub-table and collide. Our rule is that a project can use
-the subtable ``tool.$NAME`` if, and only if, they own the entry for
-``$NAME`` in the Cheeseshop/PyPI.
-
-JSON Schema
------------
-
-To provide a type-specific representation of the resulting data from
-the TOML file for illustrative purposes only, the following
-`JSON Schema `_ would match the data format:
-
-.. code-block:: json
-
-   {
-       "$schema": "http://json-schema.org/schema#",
-
-       "type": "object",
-       "additionalProperties": false,
-
-       "properties": {
-           "build-system": {
-               "type": "object",
-               "additionalProperties": false,
-
-               "properties": {
-                   "requires": {
-                       "type": "array",
-                       "items": {
-                           "type": "string"
-                       }
-                   }
-               },
-               "required": ["requires"]
-           },
-
-           "tool": {
-               "type": "object"
-           }
-       }
-   }
diff --git a/source/specifications/declaring-project-metadata.rst b/source/specifications/declaring-project-metadata.rst
index 0c1070b68..8d7186a46 100644
--- a/source/specifications/declaring-project-metadata.rst
+++ b/source/specifications/declaring-project-metadata.rst
@@ -16,6 +16,110 @@ specification as the canonical source for the format used.
    :ref:`writing-pyproject-toml`.
 
 
+.. _declaring-build-dependencies:
+
+===================================
+Declaring build system dependencies
+===================================
+
+The ``pyproject.toml`` file is written in `TOML `_.
+Among other metadata (such as :ref:`project metadata `),
+it declares any Python level dependencies that must be installed in order to
+run the project's build system successfully.
+
+.. TODO: move this sentence elsewhere
+
+Tables not defined by PyPA specifications are reserved for future use.
+
+build-system table
+------------------
+
+.. TODO: merge with PEP 517
+
+The ``[build-system]`` table is used to store build-related data.
+Initially,  only one key of the table is valid and is mandatory
+for the table: ``requires``. This key must have a value of a list
+of strings representing dependencies required to execute the
+build system. The strings in this list follow the :ref:`version specifier
+specification `.
+
+An example ``build-system`` table for a project built with
+``setuptools`` is:
+
+.. code-block:: toml
+
+   [build-system]
+   # Minimum requirements for the build system to execute.
+   requires = ["setuptools"]
+
+Build tools are expected to use the example configuration file above as
+their default semantics when a ``pyproject.toml`` file is not present.
+
+Tools should not require the existence of the ``[build-system]`` table.
+A ``pyproject.toml`` file may be used to store configuration details
+other than build-related data and thus lack a ``[build-system]`` table
+legitimately. If the file exists but is lacking the ``[build-system]``
+table then the default values as specified above should be used.
+If the table is specified but is missing required fields then the tool
+should consider it an error.
+
+
+.. TODO: move elsewhere
+
+.. _pyproject-tool-table:
+
+tool table
+----------
+
+The ``[tool]`` table is where any tool related to your Python
+project, not just build tools, can have users specify configuration
+data as long as they use a sub-table within ``[tool]``, e.g. the
+`flit `_ tool would store its
+configuration in ``[tool.flit]``.
+
+A mechanism is needed to allocate names within the ``tool.*``
+namespace, to make sure that different projects do not attempt to use
+the same sub-table and collide. Our rule is that a project can use
+the subtable ``tool.$NAME`` if, and only if, they own the entry for
+``$NAME`` in the Cheeseshop/PyPI.
+
+JSON Schema
+-----------
+
+To provide a type-specific representation of the resulting data from
+the TOML file for illustrative purposes only, the following
+`JSON Schema `_ would match the data format:
+
+.. code-block:: json
+
+   {
+       "$schema": "http://json-schema.org/schema#",
+
+       "type": "object",
+       "additionalProperties": false,
+
+       "properties": {
+           "build-system": {
+               "type": "object",
+               "additionalProperties": false,
+
+               "properties": {
+                   "requires": {
+                       "type": "array",
+                       "items": {
+                           "type": "string"
+                       }
+                   }
+               },
+               "required": ["requires"]
+           },
+
+           "tool": {
+               "type": "object"
+           }
+       }
+   }
+
 Specification
 =============
 
diff --git a/source/specifications/index.rst b/source/specifications/index.rst
index fb1a1fee2..a68dd11db 100644
--- a/source/specifications/index.rst
+++ b/source/specifications/index.rst
@@ -19,7 +19,6 @@ Package Distribution Metadata
    core-metadata
    version-specifiers
    dependency-specifiers
-   declaring-build-dependencies
    declaring-project-metadata
    inline-script-metadata
    platform-compatibility-tags

From 54cb4157d0f8d2f3d2ddf9f92b5f643caf0953c4 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 14 Nov 2023 22:06:56 +0100
Subject: [PATCH 178/733] Link to pyproject.toml guide (instead of
 specification) in packaging flow doc

---
 source/flow.rst | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/source/flow.rst b/source/flow.rst
index 974cfd6e9..947c399db 100644
--- a/source/flow.rst
+++ b/source/flow.rst
@@ -96,11 +96,13 @@ required in the :file:`pyproject.toml` file. For example, you might specify:
 
 * a ``[project]`` table containing project
   :doc:`Core Metadata `
-  (name, version, author and so forth); see
-  :doc:`Declaring project metadata `
-  for more detail
+  (name, version, author and so forth),
+
+* a ``[tool]`` table containing tool-specific configuration options.
+
+Refer to the :ref:`pyproject.toml guide ` for a
+complete guide to ``pyproject.toml`` configuration.
 
-* a ``[tool]`` table containing tool-specific configuration options
 
 Build artifacts
 ===============

From 39d6b779b58156fee3d194e41c96c2b217b46aee Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 14 Nov 2023 22:08:56 +0100
Subject: [PATCH 179/733] Rename "Declaring project metadata" to
 "pyproject.toml specification" to match new content

Adjust references accordingly.
---
 source/specifications/index.rst                           | 2 +-
 ...{declaring-project-metadata.rst => pyproject-toml.rst} | 8 ++++----
 source/specifications/source-distribution-format.rst      | 2 +-
 3 files changed, 6 insertions(+), 6 deletions(-)
 rename source/specifications/{declaring-project-metadata.rst => pyproject-toml.rst} (99%)

diff --git a/source/specifications/index.rst b/source/specifications/index.rst
index a68dd11db..6e8af699e 100644
--- a/source/specifications/index.rst
+++ b/source/specifications/index.rst
@@ -19,9 +19,9 @@ Package Distribution Metadata
    core-metadata
    version-specifiers
    dependency-specifiers
-   declaring-project-metadata
    inline-script-metadata
    platform-compatibility-tags
+   pyproject-toml
 
 Package Installation Environment Metadata
 -----------------------------------------
diff --git a/source/specifications/declaring-project-metadata.rst b/source/specifications/pyproject-toml.rst
similarity index 99%
rename from source/specifications/declaring-project-metadata.rst
rename to source/specifications/pyproject-toml.rst
index 8d7186a46..2d6200ffb 100644
--- a/source/specifications/declaring-project-metadata.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -1,8 +1,8 @@
-.. _declaring-project-metadata:
+.. _pyproject-toml-spec:
 
-==========================
-Declaring project metadata
-==========================
+================================
+``pyproject.toml`` specification
+================================
 
 :pep:`621` specifies how to write a project's
 :ref:`core metadata ` in a ``pyproject.toml`` file for
diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst
index 8ef55df96..55737dc07 100644
--- a/source/specifications/source-distribution-format.rst
+++ b/source/specifications/source-distribution-format.rst
@@ -58,7 +58,7 @@ A ``.tar.gz`` source distribution (sdist) contains a single top-level directory
 called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the source files of
 the package. The name and version MUST match the metadata stored in the file.
 This directory must also contain a :file:`pyproject.toml` in the format defined in
-:ref:`declaring-build-dependencies`, and a ``PKG-INFO`` file containing
+:ref:`pyproject-toml-spec`, and a ``PKG-INFO`` file containing
 metadata in the format described in the :ref:`core-metadata` specification. The
 metadata MUST conform to at least version 2.2 of the metadata specification.
 

From 66460e3661beb2128d7169f42e3b90b16524600c Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 14 Nov 2023 22:11:11 +0100
Subject: [PATCH 180/733] pyproject.toml spec: Update history and move to the
 end

---
 source/specifications/pyproject-toml.rst | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 2d6200ffb..7f9907a29 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -4,17 +4,14 @@
 ``pyproject.toml`` specification
 ================================
 
-:pep:`621` specifies how to write a project's
-:ref:`core metadata ` in a ``pyproject.toml`` file for
-packaging-related tools to consume. It defines the following
-specification as the canonical source for the format used.
-
 .. warning::
 
    This is a **technical, formal specification**. For a gentle,
    user-friendly guide to ``pyproject.toml``, see
    :ref:`writing-pyproject-toml`.
 
+The ``pyproject.toml`` file acts as a configuration file for packaging-related
+tools (as well as other tools).
 
 .. _declaring-build-dependencies:
 
@@ -444,4 +441,12 @@ provided via tooling later on.
 
 
 
+History
+=======
+
+This specification was originally defined in :pep:`518` (``[build-system]``
+and ``[tool]`` tables) and :pep:`621` (``[project]`` table).
+
+
+
 .. _TOML: https://toml.io

From 441d38e535a2e16e16b7b1293d5c5634e84ab27d Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 14 Nov 2023 22:16:03 +0100
Subject: [PATCH 181/733] pyproject.toml specification: Harmonize structure

Move the description of the tool table to its own section, and use
consistent titles and labels.
---
 source/specifications/pyproject-toml.rst | 59 +++++++++++-------------
 1 file changed, 28 insertions(+), 31 deletions(-)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 7f9907a29..03e617d97 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -13,11 +13,11 @@
 The ``pyproject.toml`` file acts as a configuration file for packaging-related
 tools (as well as other tools).
 
-.. _declaring-build-dependencies:
 
-===================================
-Declaring build system dependencies
-===================================
+.. _pyproject-build-system-table:
+
+Declaring build system dependencies: the ``[build-system]`` table
+=================================================================
 
 The ``pyproject.toml`` file is written in `TOML `_.
 Among other metadata (such as :ref:`project metadata `),
@@ -28,9 +28,6 @@ run the project's build system successfully.
 
 Tables not defined by PyPA specifications are reserved for future use.
 
-build-system table
-------------------
-
 .. TODO: merge with PEP 517
 
 The ``[build-system]`` table is used to store build-related data.
@@ -61,28 +58,6 @@ If the table is specified but is missing required fields then the tool
 should consider it an error.
 
 
-.. TODO: move elsewhere
-
-.. _pyproject-tool-table:
-
-tool table
-----------
-
-The ``[tool]`` table is where any tool related to your Python
-project, not just build tools, can have users specify configuration
-data as long as they use a sub-table within ``[tool]``, e.g. the
-`flit `_ tool would store its
-configuration in ``[tool.flit]``.
-
-A mechanism is needed to allocate names within the ``tool.*``
-namespace, to make sure that different projects do not attempt to use
-the same sub-table and collide. Our rule is that a project can use
-the subtable ``tool.$NAME`` if, and only if, they own the entry for
-``$NAME`` in the Cheeseshop/PyPI.
-
-JSON Schema
------------
-
 To provide a type-specific representation of the resulting data from
 the TOML file for illustrative purposes only, the following
 `JSON Schema `_ would match the data format:
@@ -117,8 +92,11 @@ the TOML file for illustrative purposes only, the following
        }
    }
 
-Specification
-=============
+
+.. _pyproject-project-table:
+
+Declaring project metadata: the ``[project]`` table
+===================================================
 
 There are two kinds of metadata: *static* and *dynamic*. Static
 metadata is specified in the ``pyproject.toml`` file directly and
@@ -441,6 +419,25 @@ provided via tooling later on.
 
 
 
+.. _pyproject-tool-table:
+
+Arbitrary tool configuration: the ``[tool]`` table
+==================================================
+
+The ``[tool]`` table is where any tool related to your Python
+project, not just build tools, can have users specify configuration
+data as long as they use a sub-table within ``[tool]``, e.g. the
+`flit `_ tool would store its
+configuration in ``[tool.flit]``.
+
+A mechanism is needed to allocate names within the ``tool.*``
+namespace, to make sure that different projects do not attempt to use
+the same sub-table and collide. Our rule is that a project can use
+the subtable ``tool.$NAME`` if, and only if, they own the entry for
+``$NAME`` in the Cheeseshop/PyPI.
+
+
+
 History
 =======
 

From d1a760af196df564fc943980823983ad130e8e1a Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 14 Nov 2023 22:20:16 +0100
Subject: [PATCH 182/733] pyproject.toml spec: Further harmonize

---
 source/specifications/pyproject-toml.rst | 27 +++++++++++-------------
 1 file changed, 12 insertions(+), 15 deletions(-)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 03e617d97..d484ad040 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -13,20 +13,21 @@
 The ``pyproject.toml`` file acts as a configuration file for packaging-related
 tools (as well as other tools).
 
+The ``pyproject.toml`` file is written in `TOML `_. Three
+tables are currently specified, namely
+:ref:`[build-system] `,
+:ref:`[project] ` and
+:ref:`[tool] `. Other tables are reserved for future
+use (tool-specific configuration should use the ``[tool]`` table).
 
 .. _pyproject-build-system-table:
 
 Declaring build system dependencies: the ``[build-system]`` table
 =================================================================
 
-The ``pyproject.toml`` file is written in `TOML `_.
-Among other metadata (such as :ref:`project metadata `),
-it declares any Python level dependencies that must be installed in order to
-run the project's build system successfully.
-
-.. TODO: move this sentence elsewhere
-
-Tables not defined by PyPA specifications are reserved for future use.
+The ``[build-system]`` table declares any Python level dependencies that
+must be installed in order to run the project's build system
+successfully.
 
 .. TODO: merge with PEP 517
 
@@ -37,7 +38,7 @@ of strings representing dependencies required to execute the
 build system. The strings in this list follow the :ref:`version specifier
 specification `.
 
-An example ``build-system`` table for a project built with
+An example ``[build-system]`` table for a project built with
 ``setuptools`` is:
 
 .. code-block:: toml
@@ -98,6 +99,8 @@ the TOML file for illustrative purposes only, the following
 Declaring project metadata: the ``[project]`` table
 ===================================================
 
+The ``[project]`` table specifies the project's :ref:`core metadata `.
+
 There are two kinds of metadata: *static* and *dynamic*. Static
 metadata is specified in the ``pyproject.toml`` file directly and
 cannot be specified or changed by a tool (this includes data
@@ -106,12 +109,6 @@ by the metadata). Dynamic metadata is listed via the ``dynamic`` key
 (defined later in this specification) and represents metadata that a
 tool will later provide.
 
-The keys defined in this specification MUST be in a table named
-``[project]`` in ``pyproject.toml``. No tools may add keys to this
-table which are not defined by this specification. For tools wishing
-to store their own settings in ``pyproject.toml``, they may use the
-``[tool]`` table as defined in the
-:ref:`build dependency declaration specification `.
 The lack of a ``[project]`` table implicitly means the :term:`build backend `
 will dynamically provide all keys.
 

From 6513f06d2636c96f8275884da27d650c3e7d3125 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Wed, 15 Nov 2023 11:53:41 +0100
Subject: [PATCH 183/733] Stray space

Co-authored-by: Carol Willing 
---
 source/specifications/pyproject-toml.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index d484ad040..91ad8e4ce 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -32,7 +32,7 @@ successfully.
 .. TODO: merge with PEP 517
 
 The ``[build-system]`` table is used to store build-related data.
-Initially,  only one key of the table is valid and is mandatory
+Initially, only one key of the table is valid and is mandatory
 for the table: ``requires``. This key must have a value of a list
 of strings representing dependencies required to execute the
 build system. The strings in this list follow the :ref:`version specifier

From d80aea34f16b560d12a7d1d5847a7d7fde14703d Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 15 Nov 2023 12:22:28 +0100
Subject: [PATCH 184/733] Address @willingc's review

---
 source/guides/writing-pyproject-toml.rst | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index ae2bdbc77..12fadd730 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -15,11 +15,10 @@ three possible TOML tables in this file.
 - The ``[project]`` table is the format that most build backends use to specify
   your project's basic metadata, such as the dependencies, your name, etc.
 
-- The ``[tool]`` table has arbitrary subtables corresponding to tools, whether
-  packaging-related or not, e.g., ``[tool.hatch]``, ``[tool.black]``,
-  ``[tool.mypy]``. We only touch upon this table here because its contents are
-  entirely tool-specific. Consult each tool's documentation to know what it can
-  contain.
+- The ``[tool]`` table has tool-specific subtables, e.g., ``[tool.hatch]``,
+  ``[tool.black]``, ``[tool.mypy]``. We only touch upon this table here because
+  its contents are defined by each tool. Consult the particular tool's
+  documentation to know what it can contain.
 
 .. note::
 
@@ -36,7 +35,7 @@ three possible TOML tables in this file.
    Also, the setuptools_ build backend supports both the ``[project]`` table,
    and the older format in ``setup.cfg`` or ``setup.py``. For new projects, it
    is recommended to use the ``[project]`` table, and keep ``setup.py`` only if
-   some programmatic configuration is needed (especially building C extensions),
+   some programmatic configuration is needed (such as building C extensions),
    but the ``setup.cfg`` and ``setup.py`` formats are still valid. See
    :ref:`setup-py-deprecated`.
 
@@ -88,12 +87,12 @@ Here are the values for some common build backends:
         build-backend = "pdm.backend"
 
 
-The rest of this guide is devoted to the ``[project]`` table.
-
 
 Static vs. dynamic metadata
 ===========================
 
+The rest of this guide is devoted to the ``[project]`` table.
+
 Most of the time, you will directly write the value of a ``[project]``
 field. For example: ``requires-python = ">= 3.8"``, or ``version =
 "1.0"``.

From 17eacbada0c5321fb3c3782f683b128b4e714d9c Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Thu, 16 Nov 2023 00:30:50 +0100
Subject: [PATCH 185/733] Add note about original PEPs

---
 source/specifications/pyproject-toml.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 91ad8e4ce..21cd2340d 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -13,6 +13,8 @@
 The ``pyproject.toml`` file acts as a configuration file for packaging-related
 tools (as well as other tools).
 
+.. note:: This specification was originally defined in :pep:`518` and :pep:`621`.
+
 The ``pyproject.toml`` file is written in `TOML `_. Three
 tables are currently specified, namely
 :ref:`[build-system] `,

From d475cf531d7dea0c0460d2cd4672728108900031 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Thu, 16 Nov 2023 01:04:16 +0100
Subject: [PATCH 186/733] Add :titlesonly: option throughout

Co-authored-by: Pradyun Gedam 
---
 source/specifications/index.rst                         | 1 +
 source/specifications/section-distribution-formats.rst  | 1 +
 source/specifications/section-distribution-metadata.rst | 1 +
 source/specifications/section-package-indices.rst       | 1 +
 4 files changed, 4 insertions(+)

diff --git a/source/specifications/index.rst b/source/specifications/index.rst
index 8f44e69bb..c8d2a3bed 100644
--- a/source/specifications/index.rst
+++ b/source/specifications/index.rst
@@ -9,6 +9,7 @@ and for proposing new ones, is documented on
 `pypa.io `__.
 
 .. toctree::
+   :titlesonly:
 
    section-distribution-metadata
    section-installation-metadata
diff --git a/source/specifications/section-distribution-formats.rst b/source/specifications/section-distribution-formats.rst
index 94256945d..b2c09f8db 100644
--- a/source/specifications/section-distribution-formats.rst
+++ b/source/specifications/section-distribution-formats.rst
@@ -3,6 +3,7 @@ Package Distribution File Formats
 =================================
 
 .. toctree::
+   :titlesonly:
 
    source-distribution-format
    binary-distribution-format
diff --git a/source/specifications/section-distribution-metadata.rst b/source/specifications/section-distribution-metadata.rst
index fe1e207f2..585cbc511 100644
--- a/source/specifications/section-distribution-metadata.rst
+++ b/source/specifications/section-distribution-metadata.rst
@@ -3,6 +3,7 @@ Package Distribution Metadata
 =============================
 
 .. toctree::
+   :titlesonly:
 
    name-normalization
    core-metadata
diff --git a/source/specifications/section-package-indices.rst b/source/specifications/section-package-indices.rst
index 9da3e30fe..13ba98113 100644
--- a/source/specifications/section-package-indices.rst
+++ b/source/specifications/section-package-indices.rst
@@ -3,6 +3,7 @@ Package Index Interfaces
 ========================
 
 .. toctree::
+   :titlesonly:
 
    pypirc
    simple-repository-api

From 344da81ccacd0c7d7d12eb565db90e9ef968ec71 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Thu, 16 Nov 2023 17:18:54 +0100
Subject: [PATCH 187/733] Be less formal

Co-authored-by: chrysle 
---
 source/guides/writing-pyproject-toml.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 12fadd730..e0f02ddf2 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -28,7 +28,7 @@ three possible TOML tables in this file.
    is understood by *most* build backends, but some build backends use a
    different format.
 
-   At the time of this writing (November 2023), Poetry_ is a notable build
+   At the time of writing this (November 2023), Poetry_ is a notable build
    backend that does not use the ``[project]`` table (it uses the
    ``[tool.poetry]`` table instead).
 

From a3eeeef768b94dd65632e47cde6943a18723a22a Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Thu, 16 Nov 2023 10:12:28 -0800
Subject: [PATCH 188/733] Exclude precommit codespell check for translation po
 files

---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c7c9f234a..311332c8a 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -15,7 +15,7 @@ repos:
   rev: v2.2.6
   hooks:
   - id: codespell
-    args: ["-L", "ned,ist,oder"]
+    args: ["-L", "ned,ist,oder","--skip","*.po"]
 
 - repo: local
   hooks:

From 4d2191e3b35a68765f897ba05af070955b0a6f2b Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Thu, 16 Nov 2023 11:06:15 -0800
Subject: [PATCH 189/733] Add hugovk suggestions

Co-authored-by: Hugo van Kemenade 
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 311332c8a..a181cd2c4 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -15,7 +15,7 @@ repos:
   rev: v2.2.6
   hooks:
   - id: codespell
-    args: ["-L", "ned,ist,oder","--skip","*.po"]
+    args: ["-L", "ned,ist,oder", "--skip", "*.po"]
 
 - repo: local
   hooks:

From d848d89f9ffbc11066553b2d5403545a77d0ab25 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Fri, 17 Nov 2023 20:06:47 +0100
Subject: [PATCH 190/733] Make the page an orphan stub instead of removing it

---
 source/guides/using-manifest-in.rst | 9 +++++++++
 1 file changed, 9 insertions(+)
 create mode 100644 source/guides/using-manifest-in.rst

diff --git a/source/guides/using-manifest-in.rst b/source/guides/using-manifest-in.rst
new file mode 100644
index 000000000..24bf154a1
--- /dev/null
+++ b/source/guides/using-manifest-in.rst
@@ -0,0 +1,9 @@
+:orphan:
+
+============================================================
+Including files in source distributions with ``MANIFEST.in``
+============================================================
+
+The information on this page has moved to
+:doc:`setuptools:userguide/miscellaneous` in the setuptools
+documentation.

From 381c6c435daf80230736415c078521804109d062 Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Fri, 17 Nov 2023 11:22:55 -0800
Subject: [PATCH 191/733] Ignore .po files for caps pre-commit hook

---
 .pre-commit-config.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index a181cd2c4..c4a3ab93e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -22,7 +22,7 @@ repos:
   - id: disallow-caps
     name: Disallow improper capitalization
     language: pygrep
-    entry: PyBind|Numpy|Cmake|CCache|Github|PyTest
+    entry: PyBind|Numpy|Cmake|CCache|Github|PyTest|*.po
     exclude: .pre-commit-config.yaml
 
 - repo: https://github.com/pre-commit/pygrep-hooks
@@ -33,7 +33,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.5
+  rev: v0.1.6
   hooks:
     - id: ruff
     - id: ruff-format

From 5e883f5fc4a402fab7c79f2f4b0ab87d070efe68 Mon Sep 17 00:00:00 2001
From: Karl Knechtel 
Date: Fri, 17 Nov 2023 19:05:31 -0500
Subject: [PATCH 192/733] Inline doc link

The previous version resulted in a hover tooltip on the link stating
"(in virtualenv 0.1)". This comment makes little sense; virtualenv
is now at version 20.24.6, and at any rate the documentation should
be describing current versions.
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index ea5730683..a66c4f3ff 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -333,7 +333,7 @@ it's fast and secure, it's maintained, and it reliably works.
 virtualenv
 ==========
 
-:doc:`Docs ` |
+`Docs `__ |
 `Issues `__ |
 `GitHub `__ |
 `PyPI `__

From e88199c214446afbd1aea0d6606f07169fd43fff Mon Sep 17 00:00:00 2001
From: Karl Knechtel 
Date: Fri, 17 Nov 2023 19:16:32 -0500
Subject: [PATCH 193/733] Clarify prose

This change clearly explains the role that the PATH environment variable
has in creating virtual environments using virtualenv, and contrasts
that behaviour with that of venv (which only uses the Python it was run
with).
---
 source/key_projects.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index a66c4f3ff..9d6a68cfd 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -338,9 +338,10 @@ virtualenv
 `GitHub `__ |
 `PyPI `__
 
-virtualenv is a tool which uses the command-line path environment
-variable to create isolated Python :term:`Virtual Environments
-`, much as :ref:`venv` does. virtualenv provides
+virtualenv is a tool for creating isolated Python :term:`Virtual Environments
+`, like :ref:`venv`. Unlike :ref:`venv`, virtualenv can
+create virtual environments for other versions of Python, which it locates
+using the PATH environment variable. It also provides
 additional functionality, compared to :ref:`venv`, by supporting Python
 2.7 and by providing convenient features for configuring, maintaining,
 duplicating, and troubleshooting the virtual environments. For more

From 2af6a8762064fa9fd69595006418239225dd34bd Mon Sep 17 00:00:00 2001
From: Karl Knechtel 
Date: Fri, 17 Nov 2023 19:19:07 -0500
Subject: [PATCH 194/733] Remove redundancy and outdated information

Current versions of virtualenv do not in fact support Python 2.7 and
have not since (per my investigation) version 20.16, released more than
a year ago. At any rate it seems inappropriate to advertise 2.x support
as a feature this late in the game.

This edit also cleans up a redundant description of how virtualenv
"provides additional functionality... by providing convenient features",
and eliminates an apparently extraneous "the".
---
 source/key_projects.rst | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 9d6a68cfd..4269e2da3 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -341,11 +341,9 @@ virtualenv
 virtualenv is a tool for creating isolated Python :term:`Virtual Environments
 `, like :ref:`venv`. Unlike :ref:`venv`, virtualenv can
 create virtual environments for other versions of Python, which it locates
-using the PATH environment variable. It also provides
-additional functionality, compared to :ref:`venv`, by supporting Python
-2.7 and by providing convenient features for configuring, maintaining,
-duplicating, and troubleshooting the virtual environments. For more
-information, see the section on :ref:`Creating and using Virtual
+using the PATH environment variable. It also provides convenient features for
+configuring, maintaining, duplicating, and troubleshooting virtual environments.
+For more information, see the section on :ref:`Creating and using Virtual
 Environments`.
 
 

From e15b7f489d868288f4d013e34ade99a952e1a5d2 Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sat, 18 Nov 2023 12:15:13 -0800
Subject: [PATCH 195/733] exclude po file types

---
 .pre-commit-config.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c4a3ab93e..fcc1b0d0f 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -22,8 +22,9 @@ repos:
   - id: disallow-caps
     name: Disallow improper capitalization
     language: pygrep
-    entry: PyBind|Numpy|Cmake|CCache|Github|PyTest|*.po
+    entry: PyBind|Numpy|Cmake|CCache|Github|PyTest
     exclude: .pre-commit-config.yaml
+    exclude_types: ["pofile"]
 
 - repo: https://github.com/pre-commit/pygrep-hooks
   rev: v1.10.0

From b7fb8fca1d26fcef577d24b0d72048a2dca29e72 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade 
Date: Sun, 19 Nov 2023 12:12:34 +0200
Subject: [PATCH 196/733] Remove outdated distribute fork info

---
 source/key_projects.rst | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 4269e2da3..7de8d9743 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -281,10 +281,6 @@ enhancements to the Python distutils that allow you to more easily
 build and distribute Python :term:`distributions `, especially ones that have dependencies on other packages.
 
-`distribute`_ was a fork of setuptools that was merged back into setuptools (in
-v0.7), thereby making setuptools the primary choice for Python packaging.
-
-
 .. _trove-classifiers:
 
 trove-classifiers
@@ -742,6 +738,5 @@ information, see the section on :ref:`Creating and using Virtual Environments`.
 
 ----
 
-.. _distribute: https://pypi.org/project/distribute
 .. _Sphinx: https://www.sphinx-doc.org/en/master/
 .. _pytest: https://docs.pytest.org/en/stable/

From 3843f857e5d945b4741651020b81137a35187c6e Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade 
Date: Sun, 19 Nov 2023 12:27:04 +0200
Subject: [PATCH 197/733] Setuptools capitalised at start of sentence/title

---
 source/key_projects.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 7de8d9743..a1fda4601 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -268,7 +268,7 @@ display on PyPI.
 .. _setuptools:
 .. _easy_install:
 
-setuptools
+Setuptools
 ==========
 
 `Docs `__ |
@@ -276,7 +276,7 @@ setuptools
 `GitHub `__ |
 `PyPI `__
 
-setuptools (which includes ``easy_install``) is a collection of
+Setuptools (which includes ``easy_install``) is a collection of
 enhancements to the Python distutils that allow you to more easily
 build and distribute Python :term:`distributions `, especially ones that have dependencies on other packages.

From 47b9fa541dc239ba0cbbb809bb3bfbd1e4000dc5 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade 
Date: Sun, 19 Nov 2023 12:33:19 +0200
Subject: [PATCH 198/733] Proofread 'How to modernize a setup.py based project'

---
 source/guides/modernize-setup-py-project.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/source/guides/modernize-setup-py-project.rst b/source/guides/modernize-setup-py-project.rst
index 1ecd4d6ff..98f0d78c0 100644
--- a/source/guides/modernize-setup-py-project.rst
+++ b/source/guides/modernize-setup-py-project.rst
@@ -13,7 +13,7 @@ A :term:`pyproject.toml` file is strongly recommended.
 The presence of a :file:`pyproject.toml` file itself does not bring much. [#]_
 What is actually strongly recommended is the ``[build-system]`` table in :file:`pyproject.toml`.
 
-.. [#] Note that it has influence on the build isolation feature of *pip*,
+.. [#] Note that it has influence on the build isolation feature of pip,
     see below.
 
 
@@ -24,10 +24,10 @@ No, :file:`setup.py` can exist in a modern :ref:`setuptools` based project.
 The :term:`setup.py` file is a valid configuration file for setuptools
 that happens to be written in Python.
 However, the following commands are deprecated and **MUST NOT** be run anymore,
-and their recommended replacement commands can be used instead:
+and their recommended replacement commands should be used instead:
 
 +---------------------------------+----------------------------------------+
-| Deprecated                      | Current recommendation                 |
+| Deprecated                      | Recommendation                         |
 +=================================+========================================+
 | ``python setup.py install``     | ``python -m pip install .``            |
 +---------------------------------+----------------------------------------+
@@ -118,7 +118,7 @@ What is the build isolation feature?
 
 Build frontends typically create an ephemeral virtual environment
 where they install only the build dependencies (and their dependencies)
-that are listed under ``build-sytem.requires``
+that are listed under ``build-system.requires``
 and trigger the build in that environment.
 
 For some projects this isolation is unwanted and it can be deactivated as follows:

From e5048ad200f2c5fa6ce99bfd5c19923597e92e52 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 20 Nov 2023 18:21:34 +0000
Subject: [PATCH 199/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.1.5 → v0.1.6](https://github.com/astral-sh/ruff-pre-commit/compare/v0.1.5...v0.1.6)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index a181cd2c4..41f45cdb7 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -33,7 +33,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.5
+  rev: v0.1.6
   hooks:
     - id: ruff
     - id: ruff-format

From 4e8769a87df9bb5c2b09e7d5b37f33365d6f5c72 Mon Sep 17 00:00:00 2001
From: wyattscarpenter 
Date: Mon, 20 Nov 2023 17:53:30 -0800
Subject: [PATCH 200/733] verbiage tweak in
 installing-using-pip-and-virtual-environments.rst

---
 .../installing-using-pip-and-virtual-environments.rst     | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index 2f6b154bc..4743e773a 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -104,20 +104,20 @@ Python interpreter:
 
         where python
 
-When the virtual environment is activated, the location will include
-the ``.venv`` directory:
+While the virtual environment is active, the above command will output a
+filepath that includes the ``.venv`` directory, by ending with the following:
 
 .. tab:: Unix/macOS
 
     .. code-block:: bash
 
-        .../.venv/bin/python
+        .venv/bin/python
 
 .. tab:: Windows
 
     .. code-block:: bat
 
-        ...\.venv\bin\python.exe
+        .venv\bin\python.exe
 
 
 While a virtual environment is activated, pip will install packages into that

From b200a38badc8ad478e76b646d14a21c3f8287ba6 Mon Sep 17 00:00:00 2001
From: sinoroc 
Date: Sun, 26 Nov 2023 11:45:19 +0100
Subject: [PATCH 201/733] Improve discussion "Is `setup.py` deprecated?"

Add alternative solutions for more commands.

GitHub: relates to https://github.com/pypa/packaging.python.org/pull/1415
---
 source/discussions/setup-py-deprecated.rst | 85 ++++++++++++++++++++--
 1 file changed, 78 insertions(+), 7 deletions(-)

diff --git a/source/discussions/setup-py-deprecated.rst b/source/discussions/setup-py-deprecated.rst
index 25bba70a9..01339595a 100644
--- a/source/discussions/setup-py-deprecated.rst
+++ b/source/discussions/setup-py-deprecated.rst
@@ -5,18 +5,20 @@
 Is ``setup.py`` deprecated?
 ===========================
 
-No, :term:`setup.py` is not deprecated,
-it is a valid configuration file for :ref:`setuptools`
+No, :term:`setup.py` and :ref:`setuptools` are not deprecated.
+
+Setuptools is perfectly usable as a :term:`build backend`
+for packaging Python projects.
+And :file:`setup.py` is a valid configuration file for :ref:`setuptools`
 that happens to be written in Python, instead of in *TOML* for example
 (a similar practice is used by other tools
 like *nox* and its :file:`nox.py` configuration file,
 or *pytest* and :file:`conftest.py`).
 
-And of course *setuptools* itself is not deprecated either.
-
-It is however deprecated to run ``python setup.py`` as a command line tool.
+However, ``python setup.py`` and the use of :file:`setup.py`
+as a command line tool are deprecated.
 
-This means for example that the following commands **MUST NOT** be run anymore:
+This means that commands such as the following **MUST NOT** be run anymore:
 
 * ``python setup.py install``
 * ``python setup.py develop``
@@ -28,7 +30,7 @@ What commands should be used instead?
 =====================================
 
 +---------------------------------+----------------------------------------+
-| Deprecated                      | Current recommendation                 |
+| Deprecated                      | Recommendation                         |
 +=================================+========================================+
 | ``python setup.py install``     | ``python -m pip install .``            |
 +---------------------------------+----------------------------------------+
@@ -79,6 +81,75 @@ The command ``python setup.py install`` was deprecated
 in setuptools version *58.3.0*.
 
 
+What about other commands?
+==========================
+
+What are some replacements for the other ``python setup.py`` commands?
+
+
+``python setup.py test``
+------------------------
+
+The recommendation is to use a test runner such as pytest_.
+
+.. _pytest: https://docs.pytest.org/
+
+
+``python setup.py check``, ``python setup.py register``, and ``python setup.py upload``
+---------------------------------------------------------------------------------------
+
+A trusted replacement is :ref:`twine`:
+
+* ``python -m twine check``
+* ``python -m twine register``
+* ``python -m twine upload``
+
+
+``python setup.py --version``
+-----------------------------
+
+A possible replacement solution (among others) is to rely on setuptools-scm_:
+
+* ``python -m setuptools-scm``
+
+.. _setuptools-scm: https://setuptools-scm.readthedocs.io/en/latest/usage/#as-cli-tool
+
+
+Remaining commands
+------------------
+
+This guide does not make suggestions of replacement solutions for those commands:
+
+.. hlist::
+    :columns: 4
+
+    * ``alias``
+    * ``bdist``
+    * ``bdist_dumb``
+    * ``bdist_egg``
+    * ``bdist_rpm``
+    * ``build``
+    * ``build_clib``
+    * ``build_ext``
+    * ``build_py``
+    * ``build_scripts``
+    * ``clean``
+    * ``dist_info``
+    * ``easy_install``
+    * ``editable_wheel``
+    * ``egg_info``
+    * ``install``
+    * ``install_data``
+    * ``install_egg_info``
+    * ``install_headers``
+    * ``install_lib``
+    * ``install_scripts``
+    * ``rotate``
+    * ``saveopts``
+    * ``setopt``
+    * ``upload_docs``
+
+
 What about custom commands?
 ===========================
 

From e338def2791e1092050e75552c911af6f571bbe7 Mon Sep 17 00:00:00 2001
From: Eric Larson 
Date: Thu, 30 Nov 2023 11:33:31 -0500
Subject: [PATCH 202/733] DOC: Document RECORD modification

---
 source/specifications/recording-installed-packages.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst
index 2610717d6..cbe0f0dbe 100644
--- a/source/specifications/recording-installed-packages.rst
+++ b/source/specifications/recording-installed-packages.rst
@@ -175,6 +175,14 @@ attempt to uninstall or upgrade the package.
 (This restriction does not apply to tools that rely on other sources of information,
 such as system package managers in Linux distros.)
 
+.. warning::
+
+   If your package dynamically generates files at runtime, you will need to update
+   the ``RECORD`` file to reflect the new files. If you do not, the files will be
+   retained during uninstallation (e.g., by ``pip uninstall my_package``) likely leading
+   to issues such as the package remaining importable but errantly appearing as a
+   namespace package. See :gh:`pypa/pip/issues/11835` for discussion.
+
 
 The INSTALLER file
 ==================

From 3518185b813b405a1a4d654a54bd2797092666bf Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Fri, 1 Dec 2023 11:08:57 +0100
Subject: [PATCH 203/733] Add discussion "Distribution package vs. import
 package"

Resolves #1425
---
 ...distribution-package-vs-import-package.rst | 90 +++++++++++++++++++
 source/discussions/index.rst                  |  1 +
 source/glossary.rst                           |  6 +-
 .../guides/packaging-namespace-packages.rst   |  2 +
 4 files changed, 97 insertions(+), 2 deletions(-)
 create mode 100644 source/discussions/distribution-package-vs-import-package.rst

diff --git a/source/discussions/distribution-package-vs-import-package.rst b/source/discussions/distribution-package-vs-import-package.rst
new file mode 100644
index 000000000..9ec708624
--- /dev/null
+++ b/source/discussions/distribution-package-vs-import-package.rst
@@ -0,0 +1,90 @@
+.. _distribution-package-vs-import-package:
+
+=======================================
+Distribution package vs. import package
+=======================================
+
+A number of different concepts are commonly referred to by the word
+"package". This page clarifies the differences between two distinct but
+related meanings in Python packaging, "distribution package" and "import
+package".
+
+What's a distribution package?
+==============================
+
+A distribution package is a piece of software that you can install.
+Most of the time, this is synonymous with "project". When you type ``pip
+install pkg``, or when you write ``dependencies = ["pkg"]`` in your
+``pyproject.toml``, ``pkg`` is the name of a distribution package. When
+you search or browse PyPI_, the most widely known centralized source for
+installing Python software, what you see is a list of distribution
+packages. Alternatively, the term "distribution package" can be used to
+refer to a specific file that contains a certain version of a project.
+
+Note that in the Linux world, "distribution package" refers to a package
+provided by the system package manager, which is a different meaning.
+
+
+What's an import package?
+=========================
+
+An import package is a Python module. Thus, when you write ``import
+pkg`` or ``from pkg import func`` in your Python code, ``pkg`` is the
+name of an import package. More precisely, import packages are special
+Python modules that can contain submodules. For example, the ``numpy``
+package contains modules like ``numpy.linalg`` and
+``numpy.fft``. Usually, an import package is a directory on the file
+system, containing modules as ``.py`` files and subpackages as
+subdirectories.
+
+You can use an import package as soon as you have installed a distribution
+package that provides it.
+
+
+What are the links between distribution packages and import packages?
+=====================================================================
+
+By convention, a distribution package usually provides one single import
+package (or non-package module), with a matching name. For example,
+``pip install numpy`` lets you ``import numpy``.
+
+However, this is only a convention. PyPI and other package indices do
+not enforce any relationship between the name of a distribution package
+and the import packages it provides.
+
+A distribution package could provide an import package with a different
+name. An example of this is the popular Pillow_ library for image
+processing. Its distribution package name is ``Pillow``, but it provides
+the import package ``PIL``. This is for historical reasons: Pillow
+started as a fork of the PIL library, thus it kept the import name
+``PIL`` so that existing PIL users could switch to Pillow with little
+effort. More generally, a fork of an existing library is a common reason
+for differing names between the distribution package and the import
+package.
+
+On a given package index (like PyPI), distribution package names must be
+unique. On the other hand, import packages have no such requirement.
+Import packages with the same name can be provided by several
+distribution packages. Again, forks are a common reason for this.
+
+Conversely, a distribution package can provide several import packages,
+although this is less common.
+
+
+How do distribution package names and import package names compare?
+===================================================================
+
+Import packages should have valid Python identifiers as their name.  In
+particular, they use underscores ``_`` as word separator and they are
+case-sensitive.
+
+On the other hand, distribution packages can use hyphens ``-`` or
+underscores ``.``. They can also contain dots ``.``, which is sometimes
+used for packaging a subpackage of a :ref:`namespace package
+`. For most purposes, they are insensitive
+to case and to ``-`` vs.  ``_`` differences, e.g., ``pip install
+Awesome_Package`` is the same as ``pip install awesome-package``.
+
+
+.. _PyPI: https://pypi.org
+.. _Pillow: https://pypi.org/project/Pillow
diff --git a/source/discussions/index.rst b/source/discussions/index.rst
index e5411ece3..b378ed810 100644
--- a/source/discussions/index.rst
+++ b/source/discussions/index.rst
@@ -12,5 +12,6 @@ specific topic. If you're just trying to get stuff done, see
    pip-vs-easy-install
    install-requires-vs-requirements
    wheel-vs-egg
+   distribution-package-vs-import-package
    src-layout-vs-flat-layout
    setup-py-deprecated
diff --git a/source/glossary.rst b/source/glossary.rst
index f9f2abc29..9bfcbbd3f 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -67,7 +67,8 @@ Glossary
         :term:`Import Package` (which is also commonly called a "package") or
         another kind of distribution (e.g. a Linux distribution or the Python
         language distribution), which are often referred to with the single term
-        "distribution".
+        "distribution". See :ref:`distribution-package-vs-import-package`
+        for a breakdown of the differences.
 
     Egg
 
@@ -103,7 +104,8 @@ Glossary
         An import package is more commonly referred to with the single word
         "package", but this guide will use the expanded term when more clarity
         is needed to prevent confusion with a :term:`Distribution Package` which
-        is also commonly called a "package".
+        is also commonly called a "package". See :ref:`distribution-package-vs-import-package`
+        for a breakdown of the differences.
 
     Module
 
diff --git a/source/guides/packaging-namespace-packages.rst b/source/guides/packaging-namespace-packages.rst
index 548020239..3d929d527 100644
--- a/source/guides/packaging-namespace-packages.rst
+++ b/source/guides/packaging-namespace-packages.rst
@@ -1,3 +1,5 @@
+.. _packaging-namespace-packages:
+
 ============================
 Packaging namespace packages
 ============================

From 176f95637e0a0a1d4574da25e75fe135d95da9e7 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Fri, 1 Dec 2023 16:22:02 +0100
Subject: [PATCH 204/733] Update
 source/discussions/distribution-package-vs-import-package.rst

Co-authored-by: sinoroc <5529267+sinoroc@users.noreply.github.com>
---
 source/discussions/distribution-package-vs-import-package.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/distribution-package-vs-import-package.rst b/source/discussions/distribution-package-vs-import-package.rst
index 9ec708624..c54bcb523 100644
--- a/source/discussions/distribution-package-vs-import-package.rst
+++ b/source/discussions/distribution-package-vs-import-package.rst
@@ -79,7 +79,7 @@ particular, they use underscores ``_`` as word separator and they are
 case-sensitive.
 
 On the other hand, distribution packages can use hyphens ``-`` or
-underscores ``.``. They can also contain dots ``.``, which is sometimes
+underscores ``_``. They can also contain dots ``.``, which is sometimes
 used for packaging a subpackage of a :ref:`namespace package
 `. For most purposes, they are insensitive
 to case and to ``-`` vs.  ``_`` differences, e.g., ``pip install

From 790e7cf6674c9761d204a2930673c0a1418efb8b Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Fri, 1 Dec 2023 16:26:51 +0100
Subject: [PATCH 205/733] Update
 source/discussions/distribution-package-vs-import-package.rst

---
 source/discussions/distribution-package-vs-import-package.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/source/discussions/distribution-package-vs-import-package.rst b/source/discussions/distribution-package-vs-import-package.rst
index c54bcb523..129eec926 100644
--- a/source/discussions/distribution-package-vs-import-package.rst
+++ b/source/discussions/distribution-package-vs-import-package.rst
@@ -83,7 +83,9 @@ underscores ``_``. They can also contain dots ``.``, which is sometimes
 used for packaging a subpackage of a :ref:`namespace package
 `. For most purposes, they are insensitive
 to case and to ``-`` vs.  ``_`` differences, e.g., ``pip install
-Awesome_Package`` is the same as ``pip install awesome-package``.
+Awesome_Package`` is the same as ``pip install awesome-package`` (the precise rules
+are given in the :ref:`name normalization
+specification `).
 
 
 .. _PyPI: https://pypi.org

From 6d8be6882828599d3dbc83dcec501ebbda72a40e Mon Sep 17 00:00:00 2001
From: Eric Larson 
Date: Fri, 1 Dec 2023 13:43:42 -0500
Subject: [PATCH 206/733] DOC: Discourage

---
 .../recording-installed-packages.rst              | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst
index cbe0f0dbe..53ba6b2b9 100644
--- a/source/specifications/recording-installed-packages.rst
+++ b/source/specifications/recording-installed-packages.rst
@@ -175,14 +175,15 @@ attempt to uninstall or upgrade the package.
 (This restriction does not apply to tools that rely on other sources of information,
 such as system package managers in Linux distros.)
 
-.. warning::
-
-   If your package dynamically generates files at runtime, you will need to update
-   the ``RECORD`` file to reflect the new files. If you do not, the files will be
-   retained during uninstallation (e.g., by ``pip uninstall my_package``) likely leading
-   to issues such as the package remaining importable but errantly appearing as a
-   namespace package. See :gh:`pypa/pip/issues/11835` for discussion.
+.. note::
 
+   It is *strongly discouraged* for an installed package to modify itself
+   (e.g., store cache files under its namespace in ``site-packages``).
+   Changes inside ``site-packages`` should be left to specialized installer
+   tools such as pip. If a package is nevertheless modified in this way,
+   then the ``RECORD`` must be updated, otherwise uninstalling the package
+   will leave unlisted files in place (possibly resulting in a zombie
+   namespace package).
 
 The INSTALLER file
 ==================

From e8c91cf4b8a99b6e10d1252fdc7aa8aeee45f146 Mon Sep 17 00:00:00 2001
From: Laurent Lyaudet 
Date: Sun, 3 Dec 2023 14:06:50 +0100
Subject: [PATCH 207/733] LL : correction of two code-blocks python -> pycon
 after suggestion from #1424 and command `grep -r 'code-block:: python' -A 3
 .`.

---
 source/tutorials/installing-packages.rst | 2 +-
 source/tutorials/packaging-projects.rst  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
index fc4218980..cb995103b 100644
--- a/source/tutorials/installing-packages.rst
+++ b/source/tutorials/installing-packages.rst
@@ -52,7 +52,7 @@ please install the latest 3.x version from `python.org`_ or refer to the
 
 .. Note:: If you're a newcomer and you get an error like this:
 
-    .. code-block:: python
+    .. code-block:: pycon
 
         >>> python3 --version
         Traceback (most recent call last):
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 23742c7d8..8d13d7b69 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -493,7 +493,7 @@ Make sure you're still in your virtual environment, then run Python:
 
 and import the package:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> from example_package_YOUR_USERNAME_HERE import example
     >>> example.add_one(2)

From e58cfbd9b9345de05f9ec1676571eaa2c437900c Mon Sep 17 00:00:00 2001
From: sinoroc 
Date: Sun, 3 Dec 2023 17:02:33 +0100
Subject: [PATCH 208/733] Fix bits of "Is `setup.py` deprecated?" discussion

GitHub: refs https://github.com/pypa/packaging.python.org/pull/1418
---
 source/discussions/setup-py-deprecated.rst | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/source/discussions/setup-py-deprecated.rst b/source/discussions/setup-py-deprecated.rst
index 01339595a..279e4abce 100644
--- a/source/discussions/setup-py-deprecated.rst
+++ b/source/discussions/setup-py-deprecated.rst
@@ -100,9 +100,12 @@ The recommendation is to use a test runner such as pytest_.
 
 A trusted replacement is :ref:`twine`:
 
-* ``python -m twine check``
-* ``python -m twine register``
-* ``python -m twine upload``
+* ``python -m twine check --strict dist/*``
+* ``python -m twine register dist/*.whl`` [#not-pypi]_
+* ``python -m twine upload dist/*``
+
+.. [#not-pypi] Not necessary, nor supported on :term:`PyPI `.
+    But might be necessary on other :term:`package indexes `.
 
 
 ``python setup.py --version``
@@ -110,7 +113,7 @@ A trusted replacement is :ref:`twine`:
 
 A possible replacement solution (among others) is to rely on setuptools-scm_:
 
-* ``python -m setuptools-scm``
+* ``python -m setuptools_scm``
 
 .. _setuptools-scm: https://setuptools-scm.readthedocs.io/en/latest/usage/#as-cli-tool
 

From fe9378a1935acf57149a7dd1d6c9137192939a8f Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 3 Dec 2023 17:24:59 +0100
Subject: [PATCH 209/733] Mention attrs as a distribution package which
 provides several import packages

---
 .../discussions/distribution-package-vs-import-package.rst   | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/source/discussions/distribution-package-vs-import-package.rst b/source/discussions/distribution-package-vs-import-package.rst
index 129eec926..09f61668a 100644
--- a/source/discussions/distribution-package-vs-import-package.rst
+++ b/source/discussions/distribution-package-vs-import-package.rst
@@ -68,7 +68,9 @@ Import packages with the same name can be provided by several
 distribution packages. Again, forks are a common reason for this.
 
 Conversely, a distribution package can provide several import packages,
-although this is less common.
+although this is less common. An example is the attrs_ distribution
+package, which provides both an ``attrs`` import package with a newer
+API, and an ``attr`` import package with an older but supported API.
 
 
 How do distribution package names and import package names compare?
@@ -90,3 +92,4 @@ specification `).
 
 .. _PyPI: https://pypi.org
 .. _Pillow: https://pypi.org/project/Pillow
+.. _attrs: https://pypi.org/project/attrs

From 92380eca023d5fe22f5404b022b28eb3eb224713 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 3 Dec 2023 17:25:20 +0100
Subject: [PATCH 210/733] Link to Python docs for exact rules on valid
 identifiers

---
 .../discussions/distribution-package-vs-import-package.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/source/discussions/distribution-package-vs-import-package.rst b/source/discussions/distribution-package-vs-import-package.rst
index 09f61668a..f10dced75 100644
--- a/source/discussions/distribution-package-vs-import-package.rst
+++ b/source/discussions/distribution-package-vs-import-package.rst
@@ -76,9 +76,10 @@ API, and an ``attr`` import package with an older but supported API.
 How do distribution package names and import package names compare?
 ===================================================================
 
-Import packages should have valid Python identifiers as their name.  In
-particular, they use underscores ``_`` as word separator and they are
-case-sensitive.
+Import packages should have valid Python identifiers as their name (the
+:ref:`exact rules ` are found in the Python
+documentation). In particular, they use underscores ``_`` as word
+separator and they are case-sensitive.
 
 On the other hand, distribution packages can use hyphens ``-`` or
 underscores ``_``. They can also contain dots ``.``, which is sometimes

From a7592e8aa6b4e619a80352bfbb19ba2334f74773 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 3 Dec 2023 17:37:06 +0100
Subject: [PATCH 211/733] Rewrap

---
 .../discussions/distribution-package-vs-import-package.rst  | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/discussions/distribution-package-vs-import-package.rst b/source/discussions/distribution-package-vs-import-package.rst
index f10dced75..967328620 100644
--- a/source/discussions/distribution-package-vs-import-package.rst
+++ b/source/discussions/distribution-package-vs-import-package.rst
@@ -86,9 +86,9 @@ underscores ``_``. They can also contain dots ``.``, which is sometimes
 used for packaging a subpackage of a :ref:`namespace package
 `. For most purposes, they are insensitive
 to case and to ``-`` vs.  ``_`` differences, e.g., ``pip install
-Awesome_Package`` is the same as ``pip install awesome-package`` (the precise rules
-are given in the :ref:`name normalization
-specification `).
+Awesome_Package`` is the same as ``pip install awesome-package`` (the
+precise rules are given in the :ref:`name normalization specification
+`).
 
 
 .. _PyPI: https://pypi.org

From d7fda402dc3e8b96cb679c9f7b4bf8ef32823de3 Mon Sep 17 00:00:00 2001
From: Rafael Fontenelle 
Date: Sun, 3 Dec 2023 17:16:26 -0300
Subject: [PATCH 212/733] Create test-translations.yml

---
 .github/workflows/test-translations.yml | 71 +++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 .github/workflows/test-translations.yml

diff --git a/.github/workflows/test-translations.yml b/.github/workflows/test-translations.yml
new file mode 100644
index 000000000..03df0ee70
--- /dev/null
+++ b/.github/workflows/test-translations.yml
@@ -0,0 +1,71 @@
+name: Test translations
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+    - '**.po'
+    branches:
+    - translation/source
+  push:
+    paths:
+    - '**.po'
+    branches:
+    - translation/source
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+env:
+  I18N_BRANCH: translation/source
+
+jobs:
+  matrix:
+    runs-on: ubuntu-latest
+    outputs:
+      languages: ${{ steps.languages.outputs.languages }}
+
+    steps:
+    - name: Grab the repo src
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ env.I18N_BRANCH }}
+    
+    - name: List languages
+      id: languages
+      working-directory: locales
+      run: |
+        dirs=$(find * -maxdepth 0 -type d)
+        list="$(echo $dirs | sed "s|^|['|;s|$|']|;s| |', '|g")"
+        echo "languages=$list" >> $GITHUB_OUTPUT
+
+
+  test-translation:
+    runs-on: ubuntu-latest
+    needs: matrix
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ${{fromJson(needs.matrix.outputs.languages)}}
+
+    steps:
+    - name: Grab the repo src
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ env.I18N_BRANCH }}
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: >-
+          3.10
+
+    - name: Install Python tooling
+      run: python -m pip install --upgrade nox virtualenv
+
+    - name: Build translated docs in ${{ matrix.language }}
+      run: nox -s build -- -D language=${{ matrix.language }}

From 6526d6fdd71b36353d0bf706ca5d4a0c1ed44a87 Mon Sep 17 00:00:00 2001
From: Rafael Fontenelle 
Date: Sun, 3 Dec 2023 17:20:17 -0300
Subject: [PATCH 213/733] Add sphinx-lint, make sphinx quiet

---
 .github/workflows/test-translations.yml | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/test-translations.yml b/.github/workflows/test-translations.yml
index 03df0ee70..9b1ad5c6f 100644
--- a/.github/workflows/test-translations.yml
+++ b/.github/workflows/test-translations.yml
@@ -34,7 +34,7 @@ jobs:
       uses: actions/checkout@v4
       with:
         ref: ${{ env.I18N_BRANCH }}
-    
+
     - name: List languages
       id: languages
       working-directory: locales
@@ -65,7 +65,10 @@ jobs:
           3.10
 
     - name: Install Python tooling
-      run: python -m pip install --upgrade nox virtualenv
+      run: python -m pip install --upgrade nox virtualenv sphinx-lint
 
     - name: Build translated docs in ${{ matrix.language }}
-      run: nox -s build -- -D language=${{ matrix.language }}
+      run: nox -s build -- -q -D language=${{ matrix.language }}
+
+    - name: Lint translation file
+      run: sphinx-lint locales/${{ matrix.language }}/LC_MESSAGES/message.po

From 9d1ba3147aab978e9d6834853b6d32742eec10a7 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Mon, 4 Dec 2023 08:12:02 +0100
Subject: [PATCH 214/733] Improve "further reading" at end of "packaging
 projects" tutorial

- Add links to advanced configuration for each build backend
- Replace link to "Packaging binary extensions" guide (an advanced topic,
  probably not what newcomers want to read) with links to the TOCs for
  guides and discussions
- Remove links to PEP 517 and PEP 518, which are technical standards,
  not user-facing documentation
---
 source/conf.py                          |  1 +
 source/tutorials/packaging-projects.rst | 16 +++++++++++-----
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index 75bf14be0..6c50b0ad0 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -141,6 +141,7 @@
     "dh-virtualenv": ("https://dh-virtualenv.readthedocs.io/en/latest/", None),
     "distlib": ("https://distlib.readthedocs.io/en/latest/", None),
     "flexx": ("https://flexx.readthedocs.io/en/latest/", None),
+    "flit": ("https://flit.pypa.io/en/stable/", None),
     "nox": ("https://nox.thea.codes/en/latest/", None),
     "openstack": ("https://docs.openstack.org/glance/latest/", None),
     "packaging": ("https://packaging.pypa.io/en/latest/", None),
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 23742c7d8..f1098590b 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -529,14 +529,16 @@ differences:
 At this point if you want to read more on packaging Python libraries here are
 some things you can do:
 
-.. TODO: Add links to other guides
-.. TODO: Add links to backend configuration docs
-
+* Read about advanced configuration for your chosen build backend:
+  `Hatchling `_,
+  :doc:`setuptools `,
+  :doc:`Flit `, `PDM `_.
+* Look at the :doc:`guides ` on this site for more advanced
+  practical information, or the :doc:`discussions `
+  for explanations and background on specific topics.
 * Consider packaging tools that provide a single command-line interface for
   project management and packaging, such as :ref:`hatch`, :ref:`flit`,
   :ref:`pdm`, and :ref:`poetry`.
-* Read :pep:`517` and :pep:`518` for background and details on build tool configuration.
-* Read about :doc:`/guides/packaging-binary-extensions`.
 
 
 ----
@@ -549,3 +551,7 @@ some things you can do:
    and considered an **advanced topic** (not covered in this tutorial).
    If you are only getting started with Python packaging, it is recommended to
    stick with *regular packages* and ``__init__.py`` (even if the file is empty).
+
+
+.. _hatchling-config: https://hatch.pypa.io/latest/config/metadata/
+.. _pdm-config: https://pdm-project.org/latest/reference/pep621/

From 995d2b7847c51dc7766d69df3c4a29d4c5286261 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Mon, 4 Dec 2023 20:54:48 +0100
Subject: [PATCH 215/733] Update references in modernize-setup-py-project guide

In parallel PRs, these references were added and the labels got renamed.
---
 source/guides/modernize-setup-py-project.rst | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/source/guides/modernize-setup-py-project.rst b/source/guides/modernize-setup-py-project.rst
index 98f0d78c0..bea636ca4 100644
--- a/source/guides/modernize-setup-py-project.rst
+++ b/source/guides/modernize-setup-py-project.rst
@@ -66,7 +66,7 @@ triggers :ref:`pip` to change its default behavior to use *build isolation*.
 For more details:
 
 * :ref:`distributing-packages`
-* :ref:`declaring-build-dependencies`
+* :ref:`pyproject-build-system-table`
 * :doc:`pip:reference/build-system/pyproject-toml`
 
 
@@ -110,7 +110,7 @@ requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays unchang
 
 For more details:
 
-* :ref:`declaring-build-dependencies`
+* :ref:`pyproject-build-system-table`
 
 
 What is the build isolation feature?
@@ -161,7 +161,7 @@ can be entirely replaced by a :file:`pyproject.toml` file like this:
     version = "1.2.3"
 
 
-Read :ref:`declaring-project-metadata` for the full specification
+Read :ref:`pyproject-project-table` for the full specification
 of the content allowed in the ``[project]`` table.
 
 
@@ -243,7 +243,6 @@ This file can be as minimalistic as this:
 Where to read more about this?
 ==============================
 
-* :ref:`declaring-build-dependencies`
-* :ref:`declaring-project-metadata`
+* :ref:`pyproject-toml-spec`
 * :doc:`pip:reference/build-system/pyproject-toml`
 * :doc:`setuptools:build_meta`

From ef609d0581f4cdb67d328007ce962d1a413c0a8a Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade 
Date: Mon, 4 Dec 2023 14:26:38 -0700
Subject: [PATCH 216/733] Keep old reference to unbreak intersphinx

---
 source/specifications/pyproject-toml.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 21cd2340d..92811958b 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -1,3 +1,4 @@
+.. _declaring-project-metadata:
 .. _pyproject-toml-spec:
 
 ================================

From cc61ec77d6f4c3c7981b4e75425947561dec5f7c Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Tue, 5 Dec 2023 16:13:52 +0100
Subject: [PATCH 217/733] Update pipx link

---
 source/guides/installing-stand-alone-command-line-tools.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/installing-stand-alone-command-line-tools.rst b/source/guides/installing-stand-alone-command-line-tools.rst
index f584cf996..ecc44a487 100644
--- a/source/guides/installing-stand-alone-command-line-tools.rst
+++ b/source/guides/installing-stand-alone-command-line-tools.rst
@@ -128,4 +128,4 @@ To see the full list of commands pipx offers, run:
 
   pipx --help
 
-You can learn more about pipx at https://pypa.github.io/pipx/.
+You can learn more about pipx at https://pipx.pypa.io/.

From 589d9ddb51dec3d2d4ab266ea3d4eeae788b904f Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Tue, 5 Dec 2023 16:19:39 +0100
Subject: [PATCH 218/733] Also update key_projects.rst

---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index a1fda4601..a71c219d4 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -233,7 +233,7 @@ application-centric alternative to :ref:`pip`'s lower-level
 pipx
 ====
 
-`Docs `__ |
+`Docs `__ |
 `GitHub `__ |
 `PyPI `__
 

From b53baf2057fecb077a3af765c33cc9c0542df4bc Mon Sep 17 00:00:00 2001
From: sinoroc <5529267+sinoroc@users.noreply.github.com>
Date: Tue, 5 Dec 2023 17:44:03 +0100
Subject: [PATCH 219/733] Update source/discussions/setup-py-deprecated.rst

Co-authored-by: chrysle 
---
 source/discussions/setup-py-deprecated.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/setup-py-deprecated.rst b/source/discussions/setup-py-deprecated.rst
index 279e4abce..c4d7258b4 100644
--- a/source/discussions/setup-py-deprecated.rst
+++ b/source/discussions/setup-py-deprecated.rst
@@ -105,7 +105,7 @@ A trusted replacement is :ref:`twine`:
 * ``python -m twine upload dist/*``
 
 .. [#not-pypi] Not necessary, nor supported on :term:`PyPI `.
-    But might be necessary on other :term:`package indexes `.
+    But might be necessary on other :term:`package indexes ` (for example :ref:`devpi`).
 
 
 ``python setup.py --version``

From 74554f1a104957229dc7c8d2b505fa9048a1209f Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 5 Dec 2023 21:25:36 +0100
Subject: [PATCH 220/733] Prevent workflow failures on forks

---
 .github/workflows/test.yml        | 2 +-
 .github/workflows/translation.yml | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 581b644ca..9ca602b2a 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -47,7 +47,7 @@ jobs:
     # This job does nothing and is only used for the branch protection
     # or multi-stage CI jobs, like making sure that all tests pass before
     # a publishing job is started.
-    if: always()
+    if: ${{ github.repository_owner == 'pypa' || github.event_name != 'schedule' }}
 
     needs:
     - build
diff --git a/.github/workflows/translation.yml b/.github/workflows/translation.yml
index d2ac8db35..85152af5b 100644
--- a/.github/workflows/translation.yml
+++ b/.github/workflows/translation.yml
@@ -15,6 +15,7 @@ env:
 jobs:
   build:
     runs-on: ubuntu-latest
+    if: $${ github.repository_owner == 'pypa' }}
 
     steps:
     - name: Grab the repo src

From 0bf1014cbb481e648fedd24e0d1010ba8379f212 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 5 Dec 2023 22:08:33 +0100
Subject: [PATCH 221/733] Remove the guide from its own Intersphinx mapping

Fixes #1438

Also replace a few hyperlinks inside packaging.python.org with normal
references.
---
 source/conf.py                                           | 1 -
 source/guides/distributing-packages-using-setuptools.rst | 3 +--
 source/key_projects.rst                                  | 5 ++---
 3 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index 6c50b0ad0..0e3a93d5e 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -145,7 +145,6 @@
     "nox": ("https://nox.thea.codes/en/latest/", None),
     "openstack": ("https://docs.openstack.org/glance/latest/", None),
     "packaging": ("https://packaging.pypa.io/en/latest/", None),
-    "packaging.python.org": ("https://packaging.python.org/en/latest/", None),
     "pip": ("https://pip.pypa.io/en/latest/", None),
     "pipenv": ("https://pipenv.pypa.io/en/latest/", None),
     "piwheels": ("https://piwheels.readthedocs.io/en/latest/", None),
diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
index 4b570e17b..7bc7db646 100644
--- a/source/guides/distributing-packages-using-setuptools.rst
+++ b/source/guides/distributing-packages-using-setuptools.rst
@@ -233,8 +233,7 @@ the front-page lists of trending projects and new releases, and the list of
 projects you maintain within your account profile (such as
 https://pypi.org/user/jaraco/).
 
-A `content type
-`_
+A :ref:`content type `
 can be specified with the ``long_description_content_type`` argument, which can
 be one of ``text/plain``, ``text/x-rst``, or ``text/markdown``, corresponding
 to no formatting, `reStructuredText (reST)
diff --git a/source/key_projects.rst b/source/key_projects.rst
index a71c219d4..671675641 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -244,7 +244,7 @@ causing dependency conflicts with other packages installed on the system.
 Python Packaging User Guide
 ===========================
 
-:doc:`Docs ` |
+:doc:`Docs ` |
 `Issues `__ |
 `GitHub `__
 
@@ -292,8 +292,7 @@ trove-classifiers
 
 trove-classifiers is the canonical source for `classifiers on PyPI
 `_, which project maintainers use to
-`systematically describe their projects
-`_
+:ref:`systematically describe their projects `
 so that users can better find projects that match their needs on the PyPI.
 
 The trove-classifiers package contains a list of valid classifiers and

From cd52365f8a96e9cf9840ea3f4f9cab0bb2a0a1d7 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Tue, 5 Dec 2023 22:14:27 +0100
Subject: [PATCH 222/733] Update .github/workflows/test.yml

Co-authored-by: Sviatoslav Sydorenko 
---
 .github/workflows/test.yml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 9ca602b2a..7645d7fcc 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -47,7 +47,9 @@ jobs:
     # This job does nothing and is only used for the branch protection
     # or multi-stage CI jobs, like making sure that all tests pass before
     # a publishing job is started.
-    if: ${{ github.repository_owner == 'pypa' || github.event_name != 'schedule' }}
+    if: >-
+      github.repository_owner == 'pypa'
+      || github.event_name != 'schedule'
 
     needs:
     - build

From 539d2917ad6568f6789af48f7929c599ae750e97 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Tue, 5 Dec 2023 22:14:34 +0100
Subject: [PATCH 223/733] Update .github/workflows/translation.yml

Co-authored-by: Sviatoslav Sydorenko 
---
 .github/workflows/translation.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/translation.yml b/.github/workflows/translation.yml
index 85152af5b..ffb2a9d05 100644
--- a/.github/workflows/translation.yml
+++ b/.github/workflows/translation.yml
@@ -15,7 +15,7 @@ env:
 jobs:
   build:
     runs-on: ubuntu-latest
-    if: $${ github.repository_owner == 'pypa' }}
+    if: github.repository_owner == 'pypa'
 
     steps:
     - name: Grab the repo src

From 8c00635f8489316e6f1aada153859e650f97d2c5 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 6 Dec 2023 21:38:48 +0100
Subject: [PATCH 224/733] Fix reST syntax for definition lists in
 direct-url-data-structure.rst

---
 .../direct-url-data-structure.rst             | 20 -------------------
 1 file changed, 20 deletions(-)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index e7c494111..608ed6963 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -130,24 +130,19 @@ Git
 ---
 
 Home page
-
    https://git-scm.com/
 
 vcs command
-
    git
 
 ``vcs`` field
-
    git
 
 ``requested_revision`` field
-
    A tag name, branch name, Git ref, commit hash, shortened commit hash,
    or other commit-ish.
 
 ``commit_id`` field
-
    A commit hash (40 hexadecimal characters sha1).
 
 .. note::
@@ -162,70 +157,55 @@ Mercurial
 ---------
 
 Home page
-
    https://www.mercurial-scm.org/
 
 vcs command
-
    hg
 
 ``vcs`` field
-
    hg
 
 ``requested_revision`` field
-
    A tag name, branch name, changeset ID, shortened changeset ID.
 
 ``commit_id`` field
-
    A changeset ID (40 hexadecimal characters).
 
 Bazaar
 ------
 
 Home page
-
    https://www.breezy-vcs.org/
 
 vcs command
-
    bzr
 
 ``vcs`` field
-
    bzr
 
 ``requested_revision`` field
-
    A tag name, branch name, revision id.
 
 ``commit_id`` field
-
    A revision id.
 
 Subversion
 ----------
 
 Home page
-
    https://subversion.apache.org/
 
 vcs command
-
    svn
 
 ``vcs`` field
-
    svn
 
 ``requested_revision`` field
-
    ``requested_revision`` must be compatible with ``svn checkout`` ``--revision`` option.
    In Subversion, branch or tag is part of ``url``.
 
 ``commit_id`` field
-
    Since Subversion does not support globally unique identifiers,
    this field is the Subversion revision number in the corresponding
    repository.

From 1b20810809654c18f8e67670a402b5e44809add4 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 6 Dec 2023 21:47:31 +0100
Subject: [PATCH 225/733] Wheel spec: Remove some remnants of the PEP format

---
 .../binary-distribution-format.rst            | 57 +++----------------
 1 file changed, 8 insertions(+), 49 deletions(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index 04367cc85..d0de03989 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -5,14 +5,8 @@
 Binary distribution format
 ==========================
 
-The binary distribution format (:term:`wheel `) was originally defined
-in :pep:`427`. The current version of the specification is here.
-
-
-Abstract
-========
-
-This PEP describes a built-package format for Python called "wheel".
+This page specifies the binary distribution format for Python packages,
+also called the wheel format.
 
 A wheel is a ZIP-format archive with a specially formatted file name and
 the ``.whl`` extension.  It contains a single distribution nearly as it
@@ -23,31 +17,6 @@ may be installed by simply unpacking into site-packages with the standard
 out onto their final paths at any later time.
 
 
-PEP Acceptance
-==============
-
-This PEP was accepted, and the defined wheel version updated to 1.0, by
-Nick Coghlan on 16th February, 2013 [1]_
-
-
-Rationale
-=========
-
-Python needs a package format that is easier to install than sdist.
-Python's sdist packages are defined by and require the distutils and
-setuptools build systems, running arbitrary code to build-and-install,
-and re-compile, code just so it can be installed into a new
-virtualenv.  This system of conflating build-install is slow, hard to
-maintain, and hinders innovation in both build systems and installers.
-
-Wheel attempts to remedy these problems by providing a simpler
-interface between the build system and the installer.  The wheel
-binary package format frees installers from having to know about the
-build system, saves time by amortizing compile time over many
-installations, and removes the need to install a build system in the
-target environment.
-
-
 Details
 =======
 
@@ -469,20 +438,16 @@ Is it possible to import Python code directly from a wheel file?
     aware that many projects will require a failure to be reproduced with
     a fully installed package before accepting it as a genuine bug.
 
-Changes
-=======
-
-Since :pep:`427`, this specification has changed as follows:
 
-- The rules on escaping in wheel filenames were revised, to bring them into line
-  with what popular tools actually do (February 2021).
+History
+=======
 
+This specification was originally approved as :pep:`427`.
 
-References
-==========
+The following changes were applied since the initial version:
 
-.. [1] PEP acceptance
-   (https://mail.python.org/pipermail/python-dev/2013-February/124103.html)
+- The rules on escaping in wheel filenames were revised, to bring them
+  into line with what popular tools actually do (February 2021).
 
 
 Appendix
@@ -499,9 +464,3 @@ Example urlsafe-base64-nopad implementation::
     def urlsafe_b64decode_nopad(data):
         pad = b'=' * (4 - (len(data) & 3))
         return base64.urlsafe_b64decode(data + pad)
-
-
-Copyright
-=========
-
-This document has been placed into the public domain.

From 10f40c8aae0841b795f171b5096d5916dcb3181d Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 6 Dec 2023 21:49:44 +0100
Subject: [PATCH 226/733] Wheel spec: Remove comparison to .egg

This is duplicated with source/guides/wheel-vs-egg.rst.
---
 .../binary-distribution-format.rst            | 27 -------------------
 1 file changed, 27 deletions(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index d0de03989..a66e3c2a6 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -307,33 +307,6 @@ See
 - https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01
 
 
-Comparison to .egg
-------------------
-
-#. Wheel is an installation format; egg is importable.  Wheel archives
-   do not need to include .pyc and are less tied to a specific Python
-   version or implementation. Wheel can install (pure Python) packages
-   built with previous versions of Python so you don't always have to
-   wait for the packager to catch up.
-#. Wheel uses .dist-info directories; egg uses .egg-info.  Wheel is
-   compatible with the new world of Python packaging and the new
-   concepts it brings.
-#. Wheel has a richer file naming convention for today's
-   multi-implementation world.  A single wheel archive can indicate
-   its compatibility with a number of Python language versions and
-   implementations, ABIs, and system architectures.  Historically the
-   ABI has been specific to a CPython release, wheel is ready for the
-   stable ABI.
-#. Wheel is lossless.  The first wheel implementation bdist_wheel
-   always generates egg-info, and then converts it to a .whl.  It is
-   also possible to convert existing eggs and bdist_wininst
-   distributions.
-#. Wheel is versioned.  Every wheel file contains the version of the
-   wheel specification and the implementation that packaged it.
-   Hopefully the next migration can simply be to Wheel 2.0.
-#. Wheel is a reference to the other Python.
-
-
 FAQ
 ===
 

From 26d5c49b5b34afdcd482d10623b750beaaa8a80b Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 6 Dec 2023 23:00:11 +0100
Subject: [PATCH 227/733] Fix many spurious block quotes and wrong syntax
 highlighting languages

---
 .../guides/dropping-older-python-versions.rst |  4 ++-
 .../guides/installing-using-linux-tools.rst   |  8 +++---
 .../guides/making-a-pypi-friendly-readme.rst  |  6 ++---
 ...s-using-github-actions-ci-cd-workflows.rst | 12 ++++-----
 source/guides/using-testpypi.rst              |  2 +-
 .../binary-distribution-format.rst            |  5 +++-
 source/specifications/core-metadata.rst       |  2 ++
 .../specifications/dependency-specifiers.rst  | 10 +++++--
 .../direct-url-data-structure.rst             |  5 +++-
 source/specifications/entry-points.rst        |  4 ++-
 .../recording-installed-packages.rst          |  2 ++
 source/specifications/version-specifiers.rst  | 10 +++++--
 source/tutorials/installing-packages.rst      | 26 +++++++++----------
 13 files changed, 61 insertions(+), 35 deletions(-)

diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst
index 2ac193b4c..c0c2b4434 100644
--- a/source/guides/dropping-older-python-versions.rst
+++ b/source/guides/dropping-older-python-versions.rst
@@ -78,7 +78,9 @@ Steps:
 
 You can specify version ranges and exclusion rules, such as at least Python 3. Or, Python 2.7, 3.4 and beyond.
 
-Examples::
+Examples:
+
+.. code-block:: text
 
     Requires-Python: ">=3"
     Requires-Python: ">2.7,!=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
diff --git a/source/guides/installing-using-linux-tools.rst b/source/guides/installing-using-linux-tools.rst
index b3d37675f..f0914f8dc 100644
--- a/source/guides/installing-using-linux-tools.rst
+++ b/source/guides/installing-using-linux-tools.rst
@@ -107,9 +107,9 @@ To install pip, wheel, and setuptools, in a parallel, non-system environment
 openSUSE
 ~~~~~~~~
 
-  .. code-block:: bash
+.. code-block:: bash
 
-    sudo zypper install python3-pip python3-setuptools python3-wheel
+   sudo zypper install python3-pip python3-setuptools python3-wheel
 
 
 .. _debian-ubuntu:
@@ -134,9 +134,9 @@ Firstly, update and refresh repository lists by running this command:
 Arch Linux
 ~~~~~~~~~~
 
-  .. code-block:: bash
+.. code-block:: bash
 
-    sudo pacman -S python-pip
+   sudo pacman -S python-pip
 
 ----
 
diff --git a/source/guides/making-a-pypi-friendly-readme.rst b/source/guides/making-a-pypi-friendly-readme.rst
index 4f85d5054..4a3a20670 100644
--- a/source/guides/making-a-pypi-friendly-readme.rst
+++ b/source/guides/making-a-pypi-friendly-readme.rst
@@ -59,9 +59,9 @@ such as ``text/plain``, ``text/x-rst`` (for reStructuredText), or ``text/markdow
 
    The minimum required versions of the respective tools are:
 
-    - ``setuptools >= 38.6.0``
-    - ``wheel >= 0.31.0``
-    - ``twine >= 1.11.0``
+   - ``setuptools >= 38.6.0``
+   - ``wheel >= 0.31.0``
+   - ``twine >= 1.11.0``
 
    It's recommended that you use ``twine`` to upload the project's distribution packages:
 
diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
index db7c88973..ca75d159b 100644
--- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
+++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
@@ -37,13 +37,13 @@ for your new :term:`PyPI project `.
 However it is also possible to add `trusted publishing`_ to any
 pre-existing project, if you are its owner.
 
-   .. attention::
+.. attention::
 
-      If you followed earlier versions of this guide, you
-      have created the secrets ``PYPI_API_TOKEN`` and ``TEST_PYPI_API_TOKEN``
-      for direct PyPI and TestPyPI access. These are obsolete now and
-      you should remove them from your GitHub repository and revoke
-      them in your PyPI and TestPyPI account settings in case you are replacing your old setup with the new one.
+   If you followed earlier versions of this guide, you
+   have created the secrets ``PYPI_API_TOKEN`` and ``TEST_PYPI_API_TOKEN``
+   for direct PyPI and TestPyPI access. These are obsolete now and
+   you should remove them from your GitHub repository and revoke
+   them in your PyPI and TestPyPI account settings in case you are replacing your old setup with the new one.
 
 
 Let's begin! 🚀
diff --git a/source/guides/using-testpypi.rst b/source/guides/using-testpypi.rst
index 1d466e4ea..f2c4f07c6 100644
--- a/source/guides/using-testpypi.rst
+++ b/source/guides/using-testpypi.rst
@@ -75,7 +75,7 @@ Setting up TestPyPI in :file:`.pypirc`
 If you want to avoid entering your username, you can configure TestPyPI in
 your :file:`$HOME/.pypirc`:
 
-.. code::
+.. code:: ini
 
     [testpypi]
     username = 
diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index a66e3c2a6..6637fed2e 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -1,3 +1,4 @@
+.. highlight:: text
 
 .. _binary-distribution-format:
 
@@ -285,7 +286,9 @@ or the installation will fail.
 If JSON web signatures are used, one or more JSON Web Signature JSON
 Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent
 to RECORD.  JWS is used to sign RECORD by including the SHA-256 hash of
-RECORD as the signature's JSON payload::
+RECORD as the signature's JSON payload:
+
+.. code-block:: json
 
     { "hash": "sha256=ADD-r2urObZHcxBW3Cr-vDCu5RJwT4CaRTHiFmbcIYY" }
 
diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index c8a0ca41c..b8cd5326e 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -1,3 +1,5 @@
+.. highlight:: text
+
 .. _`core-metadata`:
 
 ============================
diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index 0389ce3cb..6287f3815 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -1,3 +1,5 @@
+.. highlight:: text
+
 .. _dependency-specifiers:
 
 =====================
@@ -273,7 +275,9 @@ error like all other unknown variables.
      - ``test``
 
 The ``implementation_version`` marker variable is derived from
-``sys.implementation.version``::
+``sys.implementation.version``:
+
+.. code-block:: python
 
     def format_full_version(info):
         version = '{0.major}.{0.minor}.{0.micro}'.format(info)
@@ -400,7 +404,9 @@ The complete parsley grammar::
     sub_delims    = '!' | '$' | '&' | '\\'' | '(' | ')' | '*' | '+' | ',' | ';' | '='
     hexdig        = digit | 'a' | 'A' | 'b' | 'B' | 'c' | 'C' | 'd' | 'D' | 'e' | 'E' | 'f' | 'F'
 
-A test program - if the grammar is in a string ``grammar``::
+A test program - if the grammar is in a string ``grammar``:
+
+.. code-block:: python
 
     import os
     import sys
diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index 608ed6963..22900636c 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -1,3 +1,4 @@
+.. highlight:: json
 
 .. _direct-url-data-structure:
 
@@ -32,7 +33,9 @@ for security reasons.
 
 The user:password section of the URL MAY however
 be composed of environment variables, matching the following regular
-expression::
+expression:
+
+.. code-block:: text
 
     \$\{[A-Za-z0-9-_]+\}(:\$\{[A-Za-z0-9-_]+\})?
 
diff --git a/source/specifications/entry-points.rst b/source/specifications/entry-points.rst
index a11f3ca93..90a18a0bc 100644
--- a/source/specifications/entry-points.rst
+++ b/source/specifications/entry-points.rst
@@ -111,7 +111,9 @@ restrictions on values specified in :pep:`685`.
 For tools writing the file, it is recommended only to insert a space between the
 object reference and the left square bracket.
 
-For example::
+For example:
+
+.. code-block:: ini
 
     [console_scripts]
     foo = foomod:main
diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst
index 53ba6b2b9..ca8d5f0d5 100644
--- a/source/specifications/recording-installed-packages.rst
+++ b/source/specifications/recording-installed-packages.rst
@@ -1,3 +1,5 @@
+.. highlight:: text
+
 .. _recording-installed-packages:
 
 ============================
diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index acf3167c7..92131da0e 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -1,3 +1,5 @@
+.. highlight:: text
+
 .. _version-specifiers:
 
 ==================
@@ -1204,7 +1206,9 @@ version is already in that form, and if it's not, extract the various
 components for subsequent normalization.
 
 To test whether a version identifier is in the canonical format, you can use
-the following function::
+the following function:
+
+.. code-block:: python
 
     import re
     def is_canonical(version):
@@ -1212,7 +1216,9 @@ the following function::
 
 To extract the components of a version identifier, use the following regular
 expression (as defined by the `packaging `_
-project)::
+project):
+
+.. code-block:: python
 
     VERSION_PATTERN = r"""
         v?
diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
index fc4218980..9491f5808 100644
--- a/source/tutorials/installing-packages.rst
+++ b/source/tutorials/installing-packages.rst
@@ -69,7 +69,7 @@ please install the latest 3.x version from `python.org`_ or refer to the
    notebook, you can run system commands like those in this tutorial by
    prefacing them with a ``!`` character:
 
-    ::
+   .. code-block:: text
 
         In [1]: import sys
                 !{sys.executable} --version
@@ -133,21 +133,21 @@ standard library:
 
 If that still doesn't allow you to run ``python -m pip``:
 
- * Securely Download `get-pip.py
-   `_ [1]_
+* Securely Download `get-pip.py
+  `_ [1]_
 
- * Run ``python get-pip.py``. [2]_  This will install or upgrade pip.
-   Additionally, it will install :ref:`setuptools` and :ref:`wheel` if they're
-   not installed already.
+* Run ``python get-pip.py``. [2]_  This will install or upgrade pip.
+  Additionally, it will install :ref:`setuptools` and :ref:`wheel` if they're
+  not installed already.
 
-   .. warning::
+  .. warning::
 
-      Be cautious if you're using a Python install that's managed by your
-      operating system or another package manager. get-pip.py does not
-      coordinate with those tools, and may leave your system in an
-      inconsistent state. You can use ``python get-pip.py --prefix=/usr/local/``
-      to install in ``/usr/local`` which is designed for locally-installed
-      software.
+     Be cautious if you're using a Python install that's managed by your
+     operating system or another package manager. get-pip.py does not
+     coordinate with those tools, and may leave your system in an
+     inconsistent state. You can use ``python get-pip.py --prefix=/usr/local/``
+     to install in ``/usr/local`` which is designed for locally-installed
+     software.
 
 
 Ensure pip, setuptools, and wheel are up to date

From f9f3594e65aadff80cca4e019b7ea737cead6590 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 6 Dec 2023 23:47:39 +0100
Subject: [PATCH 228/733] Platform tags: Adjust to centralize history

Move history to a dedicated section (consistent with other specs). In
the main text, do not reference PEPs but just describe the current spec.
Also sketch out a few missing details.
---
 .../platform-compatibility-tags.rst           | 67 ++++++++++---------
 1 file changed, 37 insertions(+), 30 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index df7da59c5..4864f5bdd 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -9,13 +9,6 @@ Platform compatibility tags allow build tools to mark distributions as being
 compatible with specific platforms, and allows installers to understand which
 distributions are compatible with the system they are running on.
 
-The following PEPs contributed to this spec:
-
-1. :pep:`425`
-2. :pep:`513`
-3. :pep:`571`
-4. :pep:`599`
-5. :pep:`600`
 
 Overview
 ========
@@ -92,10 +85,14 @@ decide how to best use the ABI tag.
 Platform Tag
 ------------
 
-The platform tag is simply ``sysconfig.get_platform()`` with all
-hyphens ``-`` and periods ``.`` replaced with underscore ``_``.
+-------------------
+Basic platform tags
+-------------------
+
+In its simplest form, the platform tag is ``sysconfig.get_platform()`` with
+all hyphens ``-`` and periods ``.`` replaced with underscore ``_``.
 Until the removal of :ref:`distutils` in Python 3.12, this
-was ``distutils.util.get_platform()``.
+was ``distutils.util.get_platform()``. For example:
 
 * win32
 * linux_i386
@@ -107,32 +104,30 @@ was ``distutils.util.get_platform()``.
 -------------
 .. _manylinux:
 
-The scheme defined in :pep:`425` was insufficient for public distribution of
-wheel files (and \*nix wheel files in general) to Linux platforms, due to the
-large ecosystem of Linux platforms and subtle differences between them.
+The simple scheme above is insufficient for public distribution of wheel files
+to Linux platforms, due to the large ecosystem of Linux platforms and subtle
+differences between them.
 
-Instead, :pep:`600` defines the ``manylinux`` standard, which represents a
-common subset of Linux platforms, and allows building wheels tagged with the
+Instead, for those platforms, the ``manylinux`` standard represents a common
+subset of Linux platforms, and allows building wheels tagged with the
 ``manylinux`` platform tag which can be used across most common Linux
 distributions.
 
-There were multiple iterations of the ``manylinux`` specification, each
-representing the common subset of Linux platforms at a given point in time:
+The current standard is the future-proof ``manylinux_x_y`` standard. It defines
+tags of the form ``manylinux_x_y_arch``, where ``x`` and ``y`` are glibc major
+and minor versions supported (e.g. ``manylinux_2_24_xxx`` should work on any
+distro using glibc 2.24+), and ``arch`` is the architecture, matching the value
+of ``sysconfig.get_platform()`` on the system as in the "simple" form above.
 
-* ``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686``
-  architectures, and is based on a compatible Linux platform from 2007.
-* ``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686``
-  architectures. and updates the previous specification to be based on a
-  compatible Linux platform from 2010 instead.
-* ``manylinux2014`` (:pep:`599`) adds support for a number of
-  additional architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``,
-  and ``s390x``) and updates the base platform to a compatible Linux platform
-  from 2014.
+The following older tags are still supported for backward compatibility:
 
-``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a
-future-proof standard. It defines ``x`` and ``y`` as glibc major an minor
-versions supported (e.g. ``manylinux_2_24`` should work on any distro using
-glibc 2.24+). Previous tags are still supported for backward compatibility.
+* ``manylinux1`` is based on a compatible Linux platform from 2007,
+  and supports ``x86_64`` and ``i686`` architectures.
+* ``manylinux2010`` is based on a platform from 2010 and supports ``x86_64``
+  and ``i686``.
+* ``manylinux2014`` is based on a platform from 2014 and supports
+  ``x86_64``, ``i686``, ``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``,
+  and ``s390x``.
 
 In general, distributions built for older versions of the specification are
 forwards-compatible (meaning that ``manylinux1`` distributions should continue
@@ -302,3 +297,15 @@ Why is the ABI tag (the second tag) sometimes "none" in the reference implementa
     implementation at the time of writing guesses "none".  Ideally it
     would detect "py27(d|m|u)" analogous to newer versions of Python,
     but in the meantime "none" is a good enough way to say "don't know".
+
+
+History
+=======
+
+The following PEPs contributed to this spec:
+
+- :pep:`425`: initial definition of platform tags
+- :pep:`513`: defined ``manylinux1``
+- :pep:`571`: defined ``manylinux2010``
+- :pep:`599`: defined ``manylinux2014``
+- :pep:`600`: defined the ``manylinux_x_y`` scheme

From ecc391f25c30f540ec112b6822df3ccb838943de Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 6 Dec 2023 23:49:31 +0100
Subject: [PATCH 229/733] Remove note about manylinux_x_y being a new standard

It's been 4 years now.
---
 source/specifications/platform-compatibility-tags.rst | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 4864f5bdd..6e3f052fe 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -143,12 +143,6 @@ these images will no longer receive security updates.
 Manylinux compatibility support
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. Note::
-  * The ``manylinux2014`` specification is relatively new and is not yet widely
-    recognised by install tools.
-  * The ``manylinux_x_y`` specification is relatively new and is not yet widely
-    recognised by install tools.
-
 The following table shows the minimum versions of relevant projects to support
 the various ``manylinux`` standards:
 

From 74b071bcc1107c01118a4c4816c5375d0ded4bf6 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Thu, 7 Dec 2023 00:30:21 +0100
Subject: [PATCH 230/733] Platform tags: Flatten deeply nested headers

---
 .../platform-compatibility-tags.rst           | 22 +++++++------------
 1 file changed, 8 insertions(+), 14 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 6e3f052fe..c374c1bad 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -25,9 +25,6 @@ platform tag
 For example, the tag ``py27-none-any`` indicates compatibility with Python 2.7
 (any Python 2.7 implementation) with no abi requirement, on any platform.
 
-Use
-===
-
 The ``wheel`` built package format includes these tags in its filenames,
 of the form
 ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-{platform tag}.whl``.
@@ -35,11 +32,9 @@ Other package formats may have their own conventions.
 
 Any potential spaces in any tag should be replaced with ``_``.
 
-Details
-=======
 
 Python Tag
-----------
+==========
 
 The Python tag indicates the implementation and version required by
 a distribution.  Major implementations have abbreviated codes, initially:
@@ -66,8 +61,9 @@ intentionally released a cross-version-compatible distribution.
 A single-source Python 2/3 compatible distribution can use the compound
 tag ``py2.py3``.  See `Compressed Tag Sets`_, below.
 
+
 ABI Tag
--------
+=======
 
 The ABI tag indicates which Python ABI is required by any included
 extension modules.  For implementation-specific ABIs, the implementation
@@ -82,10 +78,10 @@ revision and compiler flags, etc, but will probably not have a great need
 to distribute binary distributions. Each implementation's community may
 decide how to best use the ABI tag.
 
+
 Platform Tag
-------------
+============
 
--------------------
 Basic platform tags
 -------------------
 
@@ -99,10 +95,10 @@ was ``distutils.util.get_platform()``. For example:
 * linux_x86_64
 
 
--------------
+.. _manylinux:
+
 ``manylinux``
 -------------
-.. _manylinux:
 
 The simple scheme above is insufficient for public distribution of wheel files
 to Linux platforms, due to the large ecosystem of Linux platforms and subtle
@@ -140,9 +136,6 @@ possible, with the caveat that the provided build environment for
 ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning that
 these images will no longer receive security updates.
 
-Manylinux compatibility support
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 The following table shows the minimum versions of relevant projects to support
 the various ``manylinux`` standards:
 
@@ -155,6 +148,7 @@ auditwheel  ``>=1.0.0``     ``>=2.0.0``        ``>=3.0.0``        ``>=3.3.0`` [#
 
 .. [#] Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0
 
+
 Use
 ===
 

From b258ce28340c4a8fb42b70de257a778247cd30dc Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Thu, 7 Dec 2023 00:23:20 +0100
Subject: [PATCH 231/733] Add musllinux platform tags from PEP 656

---
 .../platform-compatibility-tags.rst           | 51 +++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index c374c1bad..391845950 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -149,6 +149,50 @@ auditwheel  ``>=1.0.0``     ``>=2.0.0``        ``>=3.0.0``        ``>=3.3.0`` [#
 .. [#] Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0
 
 
+``musllinux``
+-------------
+
+The ``musllinux`` family of tags is similar to ``manylinux``, but for Linux
+platforms that use the musl_ libc rather than glibc (a prime example being Alpine
+Linux). The schema is ``musllinux_x_y_arch``, supporting musl ``x.y`` and higher
+on the architecture ``arch``.
+
+The musl version values can be obtained by executing the musl libc shared
+library the Python interpreter is currently running on, and parsing the output:
+
+.. code-block:: python
+
+   import re
+   import subprocess
+
+   def get_musl_major_minor(so: str) -> tuple[int, int] | None:
+       """Detect musl runtime version.
+
+       Returns a two-tuple ``(major, minor)`` that indicates musl
+       library's version, or ``None`` if the given libc .so does not
+       output expected information.
+
+       The libc library should output something like this to stderr::
+
+           musl libc (x86_64)
+           Version 1.2.2
+           Dynamic Program Loader
+       """
+       proc = subprocess.run([so], stderr=subprocess.PIPE, text=True)
+       lines = (line.strip() for line in proc.stderr.splitlines())
+       lines = [line for line in lines if line]
+       if len(lines) < 2 or lines[0][:4] != "musl":
+           return None
+       match = re.match(r"Version (\d+)\.(\d+)", lines[1])
+       if match:
+           return (int(match.group(1)), int(match.group(2)))
+       return None
+
+There are currently two possible ways to find the musl library’s location that a
+Python interpreter is running on, either with the system ldd_ command, or by
+parsing the ``PT_INTERP`` section’s value from the executable’s ELF_ header.
+
+
 Use
 ===
 
@@ -297,3 +341,10 @@ The following PEPs contributed to this spec:
 - :pep:`571`: defined ``manylinux2010``
 - :pep:`599`: defined ``manylinux2014``
 - :pep:`600`: defined the ``manylinux_x_y`` scheme
+- :pep:`656`: defined ``musllinux_x_y``
+
+
+
+.. _musl: https://musl.libc.org
+.. _ldd: https://www.unix.com/man-page/posix/1/ldd/
+.. _elf: https://refspecs.linuxfoundation.org/elf/elf.pdf

From b978b7da7b92e861ebb64262ac36541b80e45b10 Mon Sep 17 00:00:00 2001
From: Rafael Fontenelle 
Date: Tue, 5 Dec 2023 07:50:50 -0300
Subject: [PATCH 232/733] Do not fail when there's nothing to commit

---
 .github/workflows/translation.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/translation.yml b/.github/workflows/translation.yml
index d2ac8db35..c2ac3272c 100644
--- a/.github/workflows/translation.yml
+++ b/.github/workflows/translation.yml
@@ -65,6 +65,7 @@ jobs:
       run: |
         git_hash=$(git rev-parse --short "${GITHUB_SHA}")
         git add --force locales/messages.pot
+        git diff-index --quiet HEAD || \
         git commit \
           -m "Update messages.pot as of version ${git_hash}" \
           locales/messages.pot

From 7ca45200b064e1f95f1532466f3e5d254b015af0 Mon Sep 17 00:00:00 2001
From: Michael Deutsch 
Date: Sun, 10 Dec 2023 07:48:38 +0200
Subject: [PATCH 233/733] Update analyzing-pypi-package-downloads.rst

Fixing very minor typo: `it's` should be `its`
---
 source/guides/analyzing-pypi-package-downloads.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/analyzing-pypi-package-downloads.rst b/source/guides/analyzing-pypi-package-downloads.rst
index 4d2993479..62efea7ab 100644
--- a/source/guides/analyzing-pypi-package-downloads.rst
+++ b/source/guides/analyzing-pypi-package-downloads.rst
@@ -32,7 +32,7 @@ PyPI does not display download statistics for a number of reasons: [#]_
   doesn't mean it's good; Similarly just because a project hasn't been
   downloaded a lot doesn't mean it's bad!
 
-In short, because it's value is low for various reasons, and the tradeoffs
+In short, because its value is low for various reasons, and the tradeoffs
 required to make it work are high, it has been not an effective use of
 limited resources.
 

From 9f11a8a94ce8643aae74c47c2f9f0c2e05033a1b Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 11 Dec 2023 18:37:50 +0000
Subject: [PATCH 234/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.1.6 → v0.1.7](https://github.com/astral-sh/ruff-pre-commit/compare/v0.1.6...v0.1.7)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index fcc1b0d0f..ee15601ec 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.6
+  rev: v0.1.7
   hooks:
     - id: ruff
     - id: ruff-format

From 9368064ae5897ddfae0876b094e8e8c646cbb55f Mon Sep 17 00:00:00 2001
From: Graham Ashton 
Date: Tue, 12 Dec 2023 10:59:03 +0000
Subject: [PATCH 235/733] Clarify docs for creating virtual environment

I just watched a streamer on Twitch get stuck on this paragraph.

The docs said you should run `venv`, as if it's a command.

Which it isn't.
---
 .../guides/installing-using-pip-and-virtual-environments.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index 4743e773a..e6aa88471 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -45,8 +45,9 @@ another project's environment.
    It is recommended to use a virtual environment when working with third
    party packages.
 
-To create a virtual environment, go to your project's directory and run
-``venv``. This will create a new virtual environment in a local folder ``.venv``:
+To create a virtual environment, go to your project's directory and run the
+following command. This will create a new virtual environment in a local folder
+named ``.venv``:
 
 .. tab:: Unix/macOS
 

From 10006824edc01a9546c7ed2ae7bcff192805fc8c Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Mon, 11 Dec 2023 20:16:33 +0100
Subject: [PATCH 236/733] Start updating distributing-packages-using-setuptools
 guide

---
 ...distributing-packages-using-setuptools.rst | 277 +-----------------
 .../single-sourcing-package-version.rst       |   1 +
 source/guides/writing-pyproject-toml.rst      |  81 ++++-
 3 files changed, 79 insertions(+), 280 deletions(-)

diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
index 7bc7db646..e0ab11cc0 100644
--- a/source/guides/distributing-packages-using-setuptools.rst
+++ b/source/guides/distributing-packages-using-setuptools.rst
@@ -4,6 +4,10 @@
 Packaging and distributing projects
 ===================================
 
+.. warning::
+   As of December 2023, this page is largely outdated
+   and currently being revised.
+
 This section covers some additional details on configuring, packaging and
 distributing Python projects with ``setuptools`` that aren't covered by the
 introductory tutorial in :doc:`/tutorials/packaging-projects`.  It still assumes
@@ -153,206 +157,21 @@ As mentioned above, the primary feature of :file:`setup.py` is that it contains
 a global ``setup()`` function.  The keyword arguments to this function are how
 specific details of your project are defined.
 
-The most relevant arguments are explained below. Most of the snippets given are
+Some are temporarily explained below until their information is moved elsewhere.
+The full list can be found :doc:`in the setuptools documentation
+`.
+
+Most of the snippets given are
 taken from the `setup.py
 `_ contained in the
 `PyPA sample project `_.
 
 
-.. _`setup() name`:
-
-``name``
-~~~~~~~~
-
-::
-
-  name='sample',
-
-This is the name of your project, determining how your project is listed on
-:term:`PyPI `.  Per :pep:`508`, valid project
-names must:
-
-- Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``),
-  and/or periods (``.``), and
-- Start & end with an ASCII letter or digit.
-
-Comparison of project names is case insensitive and treats arbitrarily-long
-runs of underscores, hyphens, and/or periods as equal.  For example, if you
-register a project named ``cool-stuff``, users will be able to download it or
-declare a dependency on it using any of the following spellings::
-
-    Cool-Stuff
-    cool.stuff
-    COOL_STUFF
-    CoOl__-.-__sTuFF
-
-
-``version``
-~~~~~~~~~~~
-
-::
-
-  version='1.2.0',
-
-This is the current version of your project, allowing your users to determine whether or not
-they have the latest version, and to indicate which specific versions they've tested their own
-software against.
-
-Versions are displayed on :term:`PyPI ` for each release if you
-publish your project.
 
 See :ref:`Choosing a versioning scheme` for more information on ways to use versions to convey
 compatibility information to your users.
 
-If the project code itself needs run-time access to the version, the simplest
-way is to keep the version in both :file:`setup.py` and your code. If you'd
-rather not duplicate the value, there are a few ways to manage this. See the
-":ref:`Single sourcing the version`" Advanced Topics section.
-
-.. _`description`:
-
-``description``
-~~~~~~~~~~~~~~~
-
-::
-
-  description='A sample Python project',
-  long_description=long_description,
-  long_description_content_type='text/x-rst',
-
-Give a short and long description for your project.
-
-These values will be displayed on :term:`PyPI `
-if you publish your project. On ``pypi.org``, the user interface displays
-``description`` in the grey banner and ``long_description`` in the section
-named "Project Description".
-
-``description`` is also displayed in lists of projects. For example, it's
-visible in the search results pages such as https://pypi.org/search/?q=jupyter,
-the front-page lists of trending projects and new releases, and the list of
-projects you maintain within your account profile (such as
-https://pypi.org/user/jaraco/).
-
-A :ref:`content type `
-can be specified with the ``long_description_content_type`` argument, which can
-be one of ``text/plain``, ``text/x-rst``, or ``text/markdown``, corresponding
-to no formatting, `reStructuredText (reST)
-`_,
-and the GitHub-flavored Markdown dialect of `Markdown
-`_ respectively.
-
-``url``
-~~~~~~~
-
-::
-
-  url='https://github.com/pypa/sampleproject',
-
-
-Give a homepage URL for your project.
-
-
-``author``
-~~~~~~~~~~
-
-::
-
-  author='A. Random Developer',
-  author_email='author@example.com',
-
-Provide details about the author.
-
-
-``license``
-~~~~~~~~~~~
-
-::
-
-  license='MIT',
-
-The ``license`` argument doesn't have to indicate the license under
-which your package is being released, although you may optionally do
-so if you want.  If you're using a standard, well-known license, then
-your main indication can and should be via the ``classifiers``
-argument. Classifiers exist for all major open-source licenses.
-
-The ``license`` argument is more typically used to indicate differences
-from well-known licenses, or to include your own, unique license. As a
-general rule, it's a good idea to use a standard, well-known license,
-both to avoid confusion and because some organizations avoid software
-whose license is unapproved.
-
-
-``classifiers``
-~~~~~~~~~~~~~~~
-
-::
-
-  classifiers=[
-      # How mature is this project? Common values are
-      #   3 - Alpha
-      #   4 - Beta
-      #   5 - Production/Stable
-      'Development Status :: 3 - Alpha',
-
-      # Indicate who your project is intended for
-      'Intended Audience :: Developers',
-      'Topic :: Software Development :: Build Tools',
-
-      # Pick your license as you wish (should match "license" above)
-      'License :: OSI Approved :: MIT License',
-
-      # Specify the Python versions you support here. In particular, ensure
-      # that you indicate whether you support Python 2, Python 3 or both.
-      'Programming Language :: Python :: 2',
-      'Programming Language :: Python :: 2.7',
-      'Programming Language :: Python :: 3',
-      'Programming Language :: Python :: 3.6',
-      'Programming Language :: Python :: 3.7',
-      'Programming Language :: Python :: 3.8',
-      'Programming Language :: Python :: 3.9',
-  ],
-
-Provide a list of classifiers that categorize your project. For a full listing,
-see https://pypi.org/classifiers/.
-
-Although the list of classifiers is often used to declare what Python versions
-a project supports, this information is only used for searching & browsing
-projects on PyPI, not for installing projects.  To actually restrict what
-Python versions a project can be installed on, use the :ref:`python_requires`
-argument.
-
-To prevent a package from being uploaded to PyPI, use the special
-``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages with
-classifiers beginning with ``"Private ::'``.
-
-
-``keywords``
-~~~~~~~~~~~~
-
-::
 
-  keywords='sample setuptools development',
-
-List keywords that describe your project.
-
-
-``project_urls``
-~~~~~~~~~~~~~~~~
-
-::
-
-  project_urls={
-      'Documentation': 'https://packaging.python.org/tutorials/distributing-packages/',
-      'Funding': 'https://donate.pypi.org',
-      'Say Thanks!': 'http://saythanks.io/to/example',
-      'Source': 'https://github.com/pypa/sampleproject/',
-      'Tracker': 'https://github.com/pypa/sampleproject/issues',
-  },
-
-List additional relevant URLs about your project. This is the place to link to
-bug trackers, source repositories, or where to support package development.
-The string of the key is the exact text that will be displayed on PyPI.
 
 
 ``packages``
@@ -396,38 +215,6 @@ specification that is used to install its dependencies.
 For more on using "install_requires" see :ref:`install_requires vs Requirements files`.
 
 
-.. _python_requires:
-
-``python_requires``
-~~~~~~~~~~~~~~~~~~~
-
-If your project only runs on certain Python versions, setting the
-``python_requires`` argument to the appropriate :pep:`440` version specifier
-string will prevent :ref:`pip` from installing the project on other Python
-versions.  For example, if your package is for Python 3+ only, write::
-
-    python_requires='>=3',
-
-If your package is for Python 2.6, 2.7, and all versions of Python 3 starting
-with 3.3, write::
-
-    python_requires='>=2.6, !=3.0.*, !=3.1.*, !=3.2.*',
-
-And so on.
-
-.. note::
-
-    Support for this feature is relatively recent.  Your project's source
-    distributions and wheels (see :ref:`Packaging Your Project`) must be built
-    using at least version 24.2.0 of :ref:`setuptools` in order for the
-    ``python_requires`` argument to be recognized and the appropriate metadata
-    generated.
-
-    In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the
-    ``python_requires`` metadata.  Users with earlier versions of pip will be
-    able to download & install projects on any Python version regardless of the
-    projects' ``python_requires`` values.
-
 
 .. _`Package Data`:
 
@@ -500,47 +287,8 @@ keyword for pointing to pre-made scripts to install, the recommended approach to
 achieve cross-platform compatibility is to use :ref:`console_scripts` entry
 points (see below).
 
-``entry_points``
-~~~~~~~~~~~~~~~~
-
-::
-
-  entry_points={
-    ...
-  },
 
 
-Use this keyword to specify any plugins that your project provides for any named
-entry points that may be defined by your project or others that you depend on.
-
-For more information, see the section on
-:ref:`Advertising Behavior `
-from the :ref:`setuptools` docs.
-
-The most commonly used entry point is "console_scripts" (see below).
-
-.. _`console_scripts`:
-
-``console_scripts``
-*******************
-
-::
-
-  entry_points={
-      'console_scripts': [
-          'sample=sample:main',
-      ],
-  },
-
-Use ``console_script``
-:ref:`entry points `
-to register your script interfaces. You can then let the toolchain handle the
-work of turning these interfaces into actual scripts [2]_.  The scripts will be
-generated during the install of your :term:`distribution `.
-
-For more information, see :doc:`Entry Points `
-from the :doc:`setuptools docs `.
 
 .. _`Choosing a versioning scheme`:
 
@@ -956,10 +704,3 @@ your project to appear on the site.
        access. :ref:`pip` is currently considering changing this by `making user
        installs the default behavior
        `_.
-
-
-.. [2] Specifically, the "console_script" approach generates ``.exe`` files on
-       Windows, which are necessary because the OS special-cases ``.exe`` files.
-       Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for
-       Windows <397>` allow scripts to
-       be used in many cases, but not all.
diff --git a/source/guides/single-sourcing-package-version.rst b/source/guides/single-sourcing-package-version.rst
index 97a9cb026..e487e41e1 100644
--- a/source/guides/single-sourcing-package-version.rst
+++ b/source/guides/single-sourcing-package-version.rst
@@ -4,6 +4,7 @@
 Single-sourcing the package version
 ===================================
 
+.. todo:: Update this page for build backends other than setuptools.
 
 There are many techniques to maintain a single source of truth for the version
 number of your project:
diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 41456da08..187a44d50 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -116,6 +116,8 @@ does it.
 Basic information
 =================
 
+.. _`setup() name`:
+
 ``name``
 --------
 
@@ -127,6 +129,16 @@ only field that cannot be marked as dynamic.
    [project]
    name = "spam-eggs"
 
+The project name must consists of ASCII letters, digits, underscores "``_``",
+hyphens "``-``" and periods "``.``". It must not start or end with an
+underscore, hyphen or period.
+
+Comparison of project names is case insensitive and treats arbitrarily long runs
+of underscores, hyphens, and/or periods as equal.  For example, if you register
+a project named ``cool-stuff``, users will be able to download it or declare a
+dependency on it using any of the following spellings: ``Cool-Stuff``,
+``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``.
+
 
 ``version``
 -----------
@@ -149,6 +161,9 @@ This field is required, although it is often marked as dynamic using
    [project]
    dynamic = ["version"]
 
+This allows use cases such as filling the version from a ``__version__``
+attribute or a Git tag. Consult :ref:`Single sourcing the version` for more
+details.
 
 
 Dependencies and requirements
@@ -190,6 +205,9 @@ could use, e.g., ``pip install your-project-name[gui]`` to install your
 project with GUI support, adding the PyQt5 dependency.
 
 
+.. _requires-python:
+.. _python_requires:
+
 ``requires-python``
 -------------------
 
@@ -202,6 +220,7 @@ This lets you declare the minimum version of Python that you support
    requires-python = ">= 3.8"
 
 
+.. _`console_scripts`:
 
 Creating executable scripts
 ===========================
@@ -259,11 +278,14 @@ an email address.
     ]
 
 
+.. _description:
+
 ``description``
 ---------------
 
-This should be a one-line description of your project, to show as the
-"headline" of your project page on PyPI (`example `_).
+This should be a one-line description of your project, to show as the "headline"
+of your project page on PyPI (`example `_), and other places such as
+lists of search results (`example `_).
 
 .. code-block:: toml
 
@@ -285,8 +307,8 @@ page on PyPI. Typically, your project will have a ``README.md`` or
 
 The README's format is auto-detected from the extension:
 
-- ``README.md`` → Markdown,
-- ``README.rst`` → reStructuredText (without Sphinx extensions).
+- ``README.md`` → `GitHub-flavored Markdown `_,
+- ``README.rst`` → `reStructuredText `_ (without Sphinx extensions).
 
 You can also specify the format explicitly, like this:
 
@@ -311,12 +333,16 @@ This can take two forms. You can put your license in a file, typically
 
 or you can write the name of the license:
 
-
 .. code-block:: toml
 
     [project]
     license = {text = "MIT License"}
 
+If you are using a standard, well-known license, it is not necessary to use this
+field. Instead, you should one of the :ref:`classifiers` starting with ``License
+::``. (As a general rule, it is a good idea to use a standard, well-known
+license, both to avoid confusion and because some organizations avoid software
+whose license is unapproved.)
 
 
 ``keywords``
@@ -331,6 +357,8 @@ search for these keywords.
     keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
 
 
+.. _classifiers:
+
 ``classifiers``
 ---------------
 
@@ -340,10 +368,36 @@ A list of PyPI classifiers that apply to your project. Check the
 .. code-block:: toml
 
     classifiers = [
+      # How mature is this project? Common values are
+      #   3 - Alpha
+      #   4 - Beta
+      #   5 - Production/Stable
       "Development Status :: 4 - Beta",
-      "Programming Language :: Python"
+
+      # Indicate who your project is intended for
+      "Intended Audience :: Developers",
+      "Topic :: Software Development :: Build Tools",
+
+      # Pick your license as you wish (see also "license" above)
+      "License :: OSI Approved :: MIT License",
+
+      # Specify the Python versions you support here.
+      "Programming Language :: Python :: 3",
+      "Programming Language :: Python :: 3.6",
+      "Programming Language :: Python :: 3.7",
+      "Programming Language :: Python :: 3.8",
+      "Programming Language :: Python :: 3.9",
     ]
 
+Although the list of classifiers is often used to declare what Python versions a
+project supports, this information is only used for searching and browsing
+projects on PyPI, not for installing projects. To actually restrict what Python
+versions a project can be installed on, use the :ref:`requires-python` argument.
+
+To prevent a package from being uploaded to PyPI, use the special ``Private ::
+Do Not Upload`` classifier. PyPI will always reject packages with classifiers
+beginning with ``Private ::``.
+
 
 ``urls``
 --------
@@ -353,12 +407,12 @@ sidebar of your PyPI project page.
 
 .. code-block:: toml
 
-    [project.urls]
-    Homepage = "https://example.com"
-    Documentation = "https://readthedocs.org"
-    Repository = "https://github.com/me/spam.git"
-    Issues = "https://github.com/me/spam/issues"
-    Changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
+   [project.urls]
+   Homepage = "https://example.com"
+   Documentation = "https://readthedocs.org"
+   Repository = "https://github.com/me/spam.git"
+   Issues = "https://github.com/me/spam/issues"
+   Changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
 
 Note that if the key contains spaces, it needs to be quoted, e.g.,
 ``Website = "https://example.com"`` but
@@ -449,10 +503,13 @@ A full example
    like ``requires-python = "<= 3.10"`` here. `This blog post `_
    contains some information regarding possible problems.
 
+.. _gfm: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
 .. _setuptools: https://setuptools.pypa.io
 .. _poetry: https://python-poetry.org
 .. _pypi-pip: https://pypi.org/project/pip
+.. _pypi-search-pip: https://pypi.org/search?q=pip
 .. _classifier-list: https://pypi.org/classifiers
 .. _requires-python-blog-post: https://iscinumpy.dev/post/bound-version-constraints/#pinning-the-python-version-is-special
 .. _pytest: https://pytest.org
 .. _pygments: https://pygments.org
+.. _rest: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

From 7ce88369411e819ee141692e7d1ba190e1d3873a Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Thu, 14 Dec 2023 13:48:47 +0100
Subject: [PATCH 237/733] Typo fix (closes #1416)

---
 source/specifications/version-specifiers.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index acf3167c7..91b6fa60b 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -883,7 +883,7 @@ Prefix matching may be requested instead of strict comparison, by appending
 a trailing ``.*`` to the version identifier in the version matching clause.
 This means that additional trailing segments will be ignored when
 determining whether or not a version identifier matches the clause. If the
-specified version includes only a release segment, than trailing components
+specified version includes only a release segment, then trailing components
 (or the lack thereof) in the release segment are also ignored.
 
 For example, given the version ``1.1.post1``, the following clauses would

From 034a9f2ff988b9a614398cf7cd4661ae9be97034 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Thu, 14 Dec 2023 18:53:19 +0100
Subject: [PATCH 238/733] Use reST document metadata

Co-authored-by: chrysle 
---
 source/guides/distributing-packages-using-setuptools.rst | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
index e0ab11cc0..2c1a0a7c0 100644
--- a/source/guides/distributing-packages-using-setuptools.rst
+++ b/source/guides/distributing-packages-using-setuptools.rst
@@ -4,10 +4,8 @@
 Packaging and distributing projects
 ===================================
 
-.. warning::
-   As of December 2023, this page is largely outdated
-   and currently being revised.
-
+:Page Status: Outdated
+:Last Reviewed: 2023-12-14
 This section covers some additional details on configuring, packaging and
 distributing Python projects with ``setuptools`` that aren't covered by the
 introductory tutorial in :doc:`/tutorials/packaging-projects`.  It still assumes

From 1e6f244c580b1ff86497c8057a4b05614d89c386 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Thu, 14 Dec 2023 18:56:29 +0100
Subject: [PATCH 239/733] Add missing newline

---
 source/guides/distributing-packages-using-setuptools.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
index 2c1a0a7c0..e14048126 100644
--- a/source/guides/distributing-packages-using-setuptools.rst
+++ b/source/guides/distributing-packages-using-setuptools.rst
@@ -5,6 +5,7 @@ Packaging and distributing projects
 ===================================
 
 :Page Status: Outdated
+
 :Last Reviewed: 2023-12-14
 This section covers some additional details on configuring, packaging and
 distributing Python projects with ``setuptools`` that aren't covered by the

From 00b7bfc7796ddeb80f461878b9a3946ec82eef58 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Thu, 14 Dec 2023 19:01:29 +0100
Subject: [PATCH 240/733] Add the newline at the right place...

Co-authored-by: chrysle 
---
 source/guides/distributing-packages-using-setuptools.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
index e14048126..f6e41075d 100644
--- a/source/guides/distributing-packages-using-setuptools.rst
+++ b/source/guides/distributing-packages-using-setuptools.rst
@@ -5,8 +5,8 @@ Packaging and distributing projects
 ===================================
 
 :Page Status: Outdated
-
 :Last Reviewed: 2023-12-14
+
 This section covers some additional details on configuring, packaging and
 distributing Python projects with ``setuptools`` that aren't covered by the
 introductory tutorial in :doc:`/tutorials/packaging-projects`.  It still assumes

From 38675a15eeb7d1b03a1f1d16617d7ccef164179c Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Thu, 14 Dec 2023 22:19:00 +0100
Subject: [PATCH 241/733] Address review comments

---
 .../distribution-package-vs-import-package.rst         | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/source/discussions/distribution-package-vs-import-package.rst b/source/discussions/distribution-package-vs-import-package.rst
index 967328620..36f11d963 100644
--- a/source/discussions/distribution-package-vs-import-package.rst
+++ b/source/discussions/distribution-package-vs-import-package.rst
@@ -44,13 +44,15 @@ package that provides it.
 What are the links between distribution packages and import packages?
 =====================================================================
 
-By convention, a distribution package usually provides one single import
+Most of the time, a distribution package provides one single import
 package (or non-package module), with a matching name. For example,
 ``pip install numpy`` lets you ``import numpy``.
 
-However, this is only a convention. PyPI and other package indices do
-not enforce any relationship between the name of a distribution package
-and the import packages it provides.
+However, this is only a convention. PyPI and other package indices *do not
+enforce any relationship* between the name of a distribution package and the
+import packages it provides. (A consequence of this is that you cannot blindly
+install the PyPI package ``foo`` if you see ``import foo``; this may install an
+unintended, and potentially even malicious package.)
 
 A distribution package could provide an import package with a different
 name. An example of this is the popular Pillow_ library for image

From 071b8105da399c2382542e0648b0d594c9bc3638 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ville=20Skytt=C3=A4?= 
Date: Fri, 15 Dec 2023 16:51:37 +0200
Subject: [PATCH 242/733] Update nox config filename

`noxfile.py` since
https://github.com/wntrblm/nox/releases/tag/2018.8.23
---
 source/discussions/setup-py-deprecated.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/setup-py-deprecated.rst b/source/discussions/setup-py-deprecated.rst
index c4d7258b4..4993d8a0d 100644
--- a/source/discussions/setup-py-deprecated.rst
+++ b/source/discussions/setup-py-deprecated.rst
@@ -12,7 +12,7 @@ for packaging Python projects.
 And :file:`setup.py` is a valid configuration file for :ref:`setuptools`
 that happens to be written in Python, instead of in *TOML* for example
 (a similar practice is used by other tools
-like *nox* and its :file:`nox.py` configuration file,
+like *nox* and its :file:`noxfile.py` configuration file,
 or *pytest* and :file:`conftest.py`).
 
 However, ``python setup.py`` and the use of :file:`setup.py`

From d4164d2d1b8b2f04f2c5961af5e388ef42974c2b Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Sat, 16 Dec 2023 08:26:54 +0100
Subject: [PATCH 243/733] The PyPI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/discussions/distribution-package-vs-import-package.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/distribution-package-vs-import-package.rst b/source/discussions/distribution-package-vs-import-package.rst
index 36f11d963..005f65d14 100644
--- a/source/discussions/distribution-package-vs-import-package.rst
+++ b/source/discussions/distribution-package-vs-import-package.rst
@@ -16,7 +16,7 @@ A distribution package is a piece of software that you can install.
 Most of the time, this is synonymous with "project". When you type ``pip
 install pkg``, or when you write ``dependencies = ["pkg"]`` in your
 ``pyproject.toml``, ``pkg`` is the name of a distribution package. When
-you search or browse PyPI_, the most widely known centralized source for
+you search or browse the PyPI_, the most widely known centralized source for
 installing Python software, what you see is a list of distribution
 packages. Alternatively, the term "distribution package" can be used to
 refer to a specific file that contains a certain version of a project.

From 62273fef03a2a6e678f5bd5af3478914233191d7 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Sat, 16 Dec 2023 08:28:42 +0100
Subject: [PATCH 244/733] Python software -> Python libraries and tools

---
 source/discussions/distribution-package-vs-import-package.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/distribution-package-vs-import-package.rst b/source/discussions/distribution-package-vs-import-package.rst
index 005f65d14..8d847cca7 100644
--- a/source/discussions/distribution-package-vs-import-package.rst
+++ b/source/discussions/distribution-package-vs-import-package.rst
@@ -17,7 +17,7 @@ Most of the time, this is synonymous with "project". When you type ``pip
 install pkg``, or when you write ``dependencies = ["pkg"]`` in your
 ``pyproject.toml``, ``pkg`` is the name of a distribution package. When
 you search or browse the PyPI_, the most widely known centralized source for
-installing Python software, what you see is a list of distribution
+installing Python libraries and tools, what you see is a list of distribution
 packages. Alternatively, the term "distribution package" can be used to
 refer to a specific file that contains a certain version of a project.
 

From bbbab1a4bee5c1332ce9326015a2108429a7f8ac Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Sat, 16 Dec 2023 08:47:11 +0100
Subject: [PATCH 245/733] Clarify reference to Linux distro packages

---
 .../discussions/distribution-package-vs-import-package.rst | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/source/discussions/distribution-package-vs-import-package.rst b/source/discussions/distribution-package-vs-import-package.rst
index 8d847cca7..b00e3bde2 100644
--- a/source/discussions/distribution-package-vs-import-package.rst
+++ b/source/discussions/distribution-package-vs-import-package.rst
@@ -21,8 +21,10 @@ installing Python libraries and tools, what you see is a list of distribution
 packages. Alternatively, the term "distribution package" can be used to
 refer to a specific file that contains a certain version of a project.
 
-Note that in the Linux world, "distribution package" refers to a package
-provided by the system package manager, which is a different meaning.
+Note that in the Linux world, a "distribution package",
+most commonly abbreviated as "distro package" or just "package",
+is something provided by the system package manager of the `Linux distribution `_,
+which is a different meaning.
 
 
 What's an import package?
@@ -93,6 +95,7 @@ precise rules are given in the :ref:`name normalization specification
 `).
 
 
+.. _distro: https://en.wikipedia.org/wiki/Linux_distribution
 .. _PyPI: https://pypi.org
 .. _Pillow: https://pypi.org/project/Pillow
 .. _attrs: https://pypi.org/project/attrs

From 0335a1fbca21752135619e689ecc580dc78737d0 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Sat, 16 Dec 2023 08:55:29 +0100
Subject: [PATCH 246/733] Add importlib pointer

---
 .../distribution-package-vs-import-package.rst       | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/source/discussions/distribution-package-vs-import-package.rst b/source/discussions/distribution-package-vs-import-package.rst
index b00e3bde2..663225bcc 100644
--- a/source/discussions/distribution-package-vs-import-package.rst
+++ b/source/discussions/distribution-package-vs-import-package.rst
@@ -82,7 +82,7 @@ How do distribution package names and import package names compare?
 
 Import packages should have valid Python identifiers as their name (the
 :ref:`exact rules ` are found in the Python
-documentation). In particular, they use underscores ``_`` as word
+documentation) #[non-identifier-mod-name]_. In particular, they use underscores ``_`` as word
 separator and they are case-sensitive.
 
 On the other hand, distribution packages can use hyphens ``-`` or
@@ -95,6 +95,16 @@ precise rules are given in the :ref:`name normalization specification
 `).
 
 
+
+-
+---------------------------
+
+.. [#non-identifier-mod-name] Although is technically possible
+   to import packages/modules that do not have a valid Python identifier as
+   their name, using :doc:`importlib `,
+   this is vanishingly rare and strongly discouraged.
+
+
 .. _distro: https://en.wikipedia.org/wiki/Linux_distribution
 .. _PyPI: https://pypi.org
 .. _Pillow: https://pypi.org/project/Pillow

From 3b42e3f98a9737a2e26ddd78f0a4569539bc6a45 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Sat, 16 Dec 2023 09:02:50 +0100
Subject: [PATCH 247/733] Syntax fixes

---
 source/discussions/distribution-package-vs-import-package.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/discussions/distribution-package-vs-import-package.rst b/source/discussions/distribution-package-vs-import-package.rst
index 663225bcc..d4a754310 100644
--- a/source/discussions/distribution-package-vs-import-package.rst
+++ b/source/discussions/distribution-package-vs-import-package.rst
@@ -82,7 +82,7 @@ How do distribution package names and import package names compare?
 
 Import packages should have valid Python identifiers as their name (the
 :ref:`exact rules ` are found in the Python
-documentation) #[non-identifier-mod-name]_. In particular, they use underscores ``_`` as word
+documentation) [#non-identifier-mod-name]_. In particular, they use underscores ``_`` as word
 separator and they are case-sensitive.
 
 On the other hand, distribution packages can use hyphens ``-`` or
@@ -96,7 +96,6 @@ precise rules are given in the :ref:`name normalization specification
 
 
 
--
 ---------------------------
 
 .. [#non-identifier-mod-name] Although is technically possible

From 9b3655c495b0ca8f8634b48d5b558b8625bd8999 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Sat, 16 Dec 2023 09:08:02 +0100
Subject: [PATCH 248/733] Missing word

---
 source/discussions/distribution-package-vs-import-package.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/distribution-package-vs-import-package.rst b/source/discussions/distribution-package-vs-import-package.rst
index d4a754310..65e7019c6 100644
--- a/source/discussions/distribution-package-vs-import-package.rst
+++ b/source/discussions/distribution-package-vs-import-package.rst
@@ -98,7 +98,7 @@ precise rules are given in the :ref:`name normalization specification
 
 ---------------------------
 
-.. [#non-identifier-mod-name] Although is technically possible
+.. [#non-identifier-mod-name] Although it is technically possible
    to import packages/modules that do not have a valid Python identifier as
    their name, using :doc:`importlib `,
    this is vanishingly rare and strongly discouraged.

From 3820102558ba6b26c25f3348608a03c3b12c66d4 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 17 Dec 2023 13:10:26 +0100
Subject: [PATCH 249/733] Create a discussion on versioning

Move content on versioning schemes from
distributing-packages-using-setuptools.rst to a new discussion on
versioning, and update it.
---
 source/discussions/index.rst                  |   1 +
 source/discussions/versioning.rst             | 139 ++++++++++++++++++
 ...distributing-packages-using-setuptools.rst | 119 ---------------
 source/specifications/version-specifiers.rst  |   2 +
 4 files changed, 142 insertions(+), 119 deletions(-)
 create mode 100644 source/discussions/versioning.rst

diff --git a/source/discussions/index.rst b/source/discussions/index.rst
index b378ed810..4a14fbfba 100644
--- a/source/discussions/index.rst
+++ b/source/discussions/index.rst
@@ -8,6 +8,7 @@ specific topic. If you're just trying to get stuff done, see
 .. toctree::
    :maxdepth: 1
 
+   versioning
    deploying-python-applications
    pip-vs-easy-install
    install-requires-vs-requirements
diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst
new file mode 100644
index 000000000..c901ff345
--- /dev/null
+++ b/source/discussions/versioning.rst
@@ -0,0 +1,139 @@
+.. _versioning:
+.. _`Choosing a versioning scheme`:
+
+==========
+Versioning
+==========
+
+This discussion covers all aspects of versioning Python packages.
+
+
+Valid version numbers
+=====================
+
+Different Python projects may use different versioning schemes based on the
+needs of that particular project, but in order to be compatible with tools like
+:ref:`pip`, all of them are required to comply with a flexible format for
+version identifiers, for which the authoritative reference is the
+:ref:`specification of version specifiers `. Here are some
+examples of version numbers:
+
+.. code-block:: text
+
+  1.2.0.dev1  # Development release
+  1.2.0a1     # Alpha Release
+  1.2.0b1     # Beta Release
+  1.2.0rc1    # Release Candidate
+  1.2.0       # Final Release
+  1.2.0.post1 # Post Release
+  15.10       # Date based release
+  23          # Serial release
+
+
+Semantic versioning vs. calendar versioning
+===========================================
+
+A versioning scheme is a way to interpret version numbers of a package, and to
+decide which should be the next version number for a new release of a package.
+Two versioning schemes are commonly used for Python packages, semantic
+versioning and calendar versioning.
+
+Semantic versioning is recommended for most new projects.
+
+Semantic versioning
+-------------------
+
+The idea of *semantic versioning* is to use 3-part version numbers,
+*major.minor.maintenance*, where the project author increments:
+
+- *major* when they make incompatible API changes,
+- *minor* when they add functionality in a backwards-compatible manner, and
+- *maintenance*, when they make backwards-compatible bug fixes.
+
+Note that many projects, especially larger ones, do not use strict semantic
+versioning since many changes are technically breaking changes but affect only a
+small fraction of users. Such projects tend to increment the major number when
+the incompatibility is high, rather than for any tiny incompatibility, or to
+signal a shift in the project.
+
+For those projects that do adhere to semantic versioning strictly, this approach
+allows users to make use of :ref:`compatible release version specifiers
+`, with the ``~=`` operator.  For
+example, ``name ~= X.Y`` is roughly equivalent to ``name >= X.Y, == X.*``, i.e.,
+it requires at least release X.Y, and allows any later release with greater Y as
+long as X is the same. Likewise, ``name ~= X.Y.Z`` is roughly equivalent to
+``name >= X.Y.Z, == X.Y.*``, i.e., it requires at least X.Y.Z and allows a later
+release with same X and Y but higher Z.
+
+Python projects adopting semantic versioning should abide by clauses 1-8 of the
+`Semantic Versioning 2.0.0 specification `_.
+
+
+Calendar versioning
+-------------------
+
+Semantic versioning is not a suitable choice for all projects, such as those
+with a regular time based release cadence and a deprecation process that
+provides warnings for a number of releases prior to removal of a feature.
+
+A key advantage of date-based versioning, or `calendar versioning `_,
+is that it is straightforward to tell how old the base feature set of a
+particular release is given just the version number.
+
+Calendar version numbers typically take the form *year.month* (for example,
+23.10 for December 2023).
+
+
+Other schemes
+-------------
+
+Serial versioning refers to the simplest possible versioning scheme, which
+consists of a single number incremented every release. While serial versioning
+is very easy to manage as a developer, it is the hardest to track as an end
+user, as serial version numbers convey little or no information regarding API
+backwards compatibility.
+
+Combinations of the above schemes are possible. For example, a project may
+combine date based versioning with serial versioning to create a *year.serial*
+numbering scheme that readily conveys the approximate age of a release, but
+doesn't otherwise commit to a particular release cadence within the year.
+
+
+
+Pre-release versioning
+======================
+
+Regardless of the base versioning scheme, pre-releases for a given final release
+may be published as:
+
+* Zero or more dev releases, denoted with a ".devN" suffix,
+* Zero or more alpha releases, denoted with a ".aN" suffix,
+* Zero or more beta releases, denoted with a ".bN" suffix,
+* Zero or more release candidates, denoted with a ".rcN" suffix.
+
+Pip and other modern Python package installers ignore pre-releases by default
+when deciding which versions of dependencies to install.
+
+
+Local version identifiers
+=========================
+
+Public version identifiers are designed to support distribution via :term:`PyPI
+`. Python packaging tools also support the notion
+of a :ref:`local version identifier `, which can be
+used to identify local development builds not intended for publication, or
+modified variants of a release maintained by a redistributor.
+
+A local version identifier takes the form of a public version identifier,
+followed by "+" and a local version label. For example:
+
+.. code-block:: text
+
+   1.2.0.dev1+hg.5.b11e5e6f0b0b  # 5th VCS commit since 1.2.0.dev1 release
+   1.2.1+fedora.4                # Package with downstream Fedora patches applied
+
+
+
+
+.. _calver: https://calver.org
+.. _semver: https://semver.org
diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
index f6e41075d..8e9ed564b 100644
--- a/source/guides/distributing-packages-using-setuptools.rst
+++ b/source/guides/distributing-packages-using-setuptools.rst
@@ -288,125 +288,6 @@ points (see below).
 
 
 
-
-.. _`Choosing a versioning scheme`:
-
-Choosing a versioning scheme
-----------------------------
-
-Standards compliance for interoperability
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Different Python projects may use different versioning schemes based on the needs of that
-particular project, but all of them are required to comply with the flexible :pep:`public version
-scheme <440#public-version-identifiers>` specified
-in :pep:`440` in order to be supported in tools and libraries like ``pip``
-and ``setuptools``.
-
-Here are some examples of compliant version numbers::
-
-  1.2.0.dev1  # Development release
-  1.2.0a1     # Alpha Release
-  1.2.0b1     # Beta Release
-  1.2.0rc1    # Release Candidate
-  1.2.0       # Final Release
-  1.2.0.post1 # Post Release
-  15.10       # Date based release
-  23          # Serial release
-
-To further accommodate historical variations in approaches to version numbering,
-:pep:`440` also defines a comprehensive technique for :pep:`version
-normalisation <440#normalization>` that maps
-variant spellings of different version numbers to a standardised canonical form.
-
-Scheme choices
-~~~~~~~~~~~~~~
-
-Semantic versioning (preferred)
-*******************************
-
-For new projects, the recommended versioning scheme is based on `Semantic Versioning
-`_, but adopts a different approach to handling pre-releases and
-build metadata.
-
-The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE numbering scheme,
-where the project author increments:
-
-1. MAJOR version when they make incompatible API changes,
-2. MINOR version when they add functionality in a backwards-compatible manner, and
-3. MAINTENANCE version when they make backwards-compatible bug fixes.
-
-Adopting this approach as a project author allows users to make use of :pep:`"compatible release"
-<440#compatible-release>` specifiers, where
-``name ~= X.Y`` requires at least release X.Y, but also allows any later release with
-a matching MAJOR version.
-
-Python projects adopting semantic versioning should abide by clauses 1-8 of the
-`Semantic Versioning 2.0.0 specification `_.
-
-Date based versioning
-*********************
-
-Semantic versioning is not a suitable choice for all projects, such as those with a regular
-time based release cadence and a deprecation process that provides warnings for a number of
-releases prior to removal of a feature.
-
-A key advantage of date based versioning is that it is straightforward to tell how old the
-base feature set of a particular release is given just the version number.
-
-Version numbers for date based projects typically take the form of YEAR.MONTH (for example,
-``12.04``, ``15.10``).
-
-Serial versioning
-*****************
-
-This is the simplest possible versioning scheme, and consists of a single number which is
-incremented every release.
-
-While serial versioning is very easy to manage as a developer, it is the hardest to track
-as an end user, as serial version numbers convey little or no information regarding API
-backwards compatibility.
-
-Hybrid schemes
-**************
-
-Combinations of the above schemes are possible. For example, a project may combine date
-based versioning with serial versioning to create a YEAR.SERIAL numbering scheme that
-readily conveys the approximate age of a release, but doesn't otherwise commit to a particular
-release cadence within the year.
-
-Pre-release versioning
-~~~~~~~~~~~~~~~~~~~~~~
-
-Regardless of the base versioning scheme, pre-releases for a given final release may be
-published as:
-
-* zero or more dev releases (denoted with a ".devN" suffix)
-* zero or more alpha releases (denoted with a ".aN" suffix)
-* zero or more beta releases (denoted with a ".bN" suffix)
-* zero or more release candidates (denoted with a ".rcN" suffix)
-
-``pip`` and other modern Python package installers ignore pre-releases by default when
-deciding which versions of dependencies to install.
-
-
-Local version identifiers
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Public version identifiers are designed to support distribution via
-:term:`PyPI `. Python's software distribution tools also support
-the notion of a :pep:`local version identifier
-<440#local-version-identifiers>`, which can be used to
-identify local development builds not intended for publication, or modified variants of a release
-maintained by a redistributor.
-
-A local version identifier takes the form ``+``.
-For example::
-
-   1.2.0.dev1+hg.5.b11e5e6f0b0b  # 5th VCS commit since 1.2.0.dev1 release
-   1.2.1+fedora.4                # Package with downstream Fedora patches applied
-
-
 Working in "development mode"
 =============================
 
diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index 202031758..6fe9ffccd 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -108,6 +108,8 @@ aside from always being the lowest possible value in the version ordering.
    sections.
 
 
+.. _local-version-identifiers:
+
 Local version identifiers
 -------------------------
 

From b5d2d8d658779aa1e9587f1afc319bfeee8ad45a Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 17 Dec 2023 20:39:14 +0100
Subject: [PATCH 250/733] Address review comments

---
 source/conf.py                                |   1 +
 source/discussions/versioning.rst             | 102 ++++++++++++------
 ...distributing-packages-using-setuptools.rst |   6 ++
 3 files changed, 74 insertions(+), 35 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index 0e3a93d5e..e61a32451 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -143,6 +143,7 @@
     "flexx": ("https://flexx.readthedocs.io/en/latest/", None),
     "flit": ("https://flit.pypa.io/en/stable/", None),
     "nox": ("https://nox.thea.codes/en/latest/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
     "openstack": ("https://docs.openstack.org/glance/latest/", None),
     "packaging": ("https://packaging.pypa.io/en/latest/", None),
     "pip": ("https://pip.pypa.io/en/latest/", None),
diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst
index c901ff345..082dd1716 100644
--- a/source/discussions/versioning.rst
+++ b/source/discussions/versioning.rst
@@ -18,27 +18,47 @@ version identifiers, for which the authoritative reference is the
 :ref:`specification of version specifiers `. Here are some
 examples of version numbers:
 
-.. code-block:: text
-
-  1.2.0.dev1  # Development release
-  1.2.0a1     # Alpha Release
-  1.2.0b1     # Beta Release
-  1.2.0rc1    # Release Candidate
-  1.2.0       # Final Release
-  1.2.0.post1 # Post Release
-  15.10       # Date based release
-  23          # Serial release
+- A simple version (final release): 1.2.0
+- A development release: 1.2.0.dev1
+- An alpha release: 1.2.0a1
+- A beta release: 1.2.0b1
+- A release candidate: 1.2.0rc1
+- A post-release: 1.2.0.post1
+- A post-release of an alpha release (possible, but discouraged): 1.2.0a1.post1
+- A simple version with only two components: 23.12
+- A simple version with just one component (possible, but discouraged): 42
+- A version with an epoch: 1!1.0
+
+Projects can use a cycle of pre-releases to support testing by their users
+before a final release. In order, the steps are: alpha releases, beta releases,
+release candidates, final release.
+
+The purpose of development releases is to support releases made early during a
+development cycle, for example, a nightly build, or a build from the latest
+source in a Linux distribution.
+
+Post-releases are used to address minor errors in a final release that do not
+affect the distributed software, such as correcting an error in the release
+notes. They should not be used for bug fixes; these should be done with a new
+final release (e.g., incrementing the third component when using semantic
+versioning).
+
+Finally, epochs, a rarely used feature, serve to fix the sorting order when
+changing the versioning scheme. For example, if a project is using calendar
+versioning, with versions like 23.12, and switches to semantic versioning, with
+versions like 1.0, the comparison between 1.0 and 23.12 will go the wrong way.
+To correct this, the new version numbers should have an explicit epoch, as in
+"1!1.0", in order to be treated as more recent than the old version numbers.
 
 
 Semantic versioning vs. calendar versioning
 ===========================================
 
-A versioning scheme is a way to interpret version numbers of a package, and to
-decide which should be the next version number for a new release of a package.
-Two versioning schemes are commonly used for Python packages, semantic
-versioning and calendar versioning.
+A versioning scheme is a formalized way to interpret the segments of a version
+number, and to decide which should be the next version number for a new release
+of a package. Two versioning schemes are commonly used for Python packages,
+semantic versioning and calendar versioning.
 
-Semantic versioning is recommended for most new projects.
 
 Semantic versioning
 -------------------
@@ -50,14 +70,15 @@ The idea of *semantic versioning* is to use 3-part version numbers,
 - *minor* when they add functionality in a backwards-compatible manner, and
 - *maintenance*, when they make backwards-compatible bug fixes.
 
-Note that many projects, especially larger ones, do not use strict semantic
-versioning since many changes are technically breaking changes but affect only a
-small fraction of users. Such projects tend to increment the major number when
-the incompatibility is high, rather than for any tiny incompatibility, or to
-signal a shift in the project.
+A majority of Python projects use a scheme that resembles semantic
+versioning. However, most projects, especially larger ones, do not strictly
+adhere to semantic versioning, since many changes are technically breaking
+changes but affect only a small fraction of users. Such projects tend to
+increment the major number when the incompatibility is high, or to signal a
+shift in the project, rather than for any tiny incompatibility,
 
-For those projects that do adhere to semantic versioning strictly, this approach
-allows users to make use of :ref:`compatible release version specifiers
+For those projects that do use strict semantic versioning, this approach allows
+users to make use of :ref:`compatible release version specifiers
 `, with the ``~=`` operator.  For
 example, ``name ~= X.Y`` is roughly equivalent to ``name >= X.Y, == X.*``, i.e.,
 it requires at least release X.Y, and allows any later release with greater Y as
@@ -68,6 +89,13 @@ release with same X and Y but higher Z.
 Python projects adopting semantic versioning should abide by clauses 1-8 of the
 `Semantic Versioning 2.0.0 specification `_.
 
+The popular :doc:`Sphinx ` documentation generator is an example
+project that uses strict semantic versioning (:doc:`Sphinx versioning policy
+`). The famous :doc:`NumPy `
+scientific computing package explicitly uses "loose" semantic versioning, where
+releases incrementing the minor version can contain backwards-incompatible API
+changes (:doc:`NumPy versioning policy `).
+
 
 Calendar versioning
 -------------------
@@ -81,7 +109,10 @@ is that it is straightforward to tell how old the base feature set of a
 particular release is given just the version number.
 
 Calendar version numbers typically take the form *year.month* (for example,
-23.10 for December 2023).
+23.12 for December 2023).
+
+:doc:`Pip `, the standard Python package installer, uses calendar
+versioning.
 
 
 Other schemes
@@ -107,12 +138,13 @@ Regardless of the base versioning scheme, pre-releases for a given final release
 may be published as:
 
 * Zero or more dev releases, denoted with a ".devN" suffix,
-* Zero or more alpha releases, denoted with a ".aN" suffix,
-* Zero or more beta releases, denoted with a ".bN" suffix,
-* Zero or more release candidates, denoted with a ".rcN" suffix.
+* Zero or more alpha releases, denoted with a "aN" suffix,
+* Zero or more beta releases, denoted with a "bN" suffix,
+* Zero or more release candidates, denoted with a "rcN" suffix.
 
 Pip and other modern Python package installers ignore pre-releases by default
-when deciding which versions of dependencies to install.
+when deciding which versions of dependencies to install, unless explicitly
+requested, e.g., with ``pip install pkg==1.1a3``.
 
 
 Local version identifiers
@@ -125,15 +157,15 @@ used to identify local development builds not intended for publication, or
 modified variants of a release maintained by a redistributor.
 
 A local version identifier takes the form of a public version identifier,
-followed by "+" and a local version label. For example:
-
-.. code-block:: text
-
-   1.2.0.dev1+hg.5.b11e5e6f0b0b  # 5th VCS commit since 1.2.0.dev1 release
-   1.2.1+fedora.4                # Package with downstream Fedora patches applied
-
-
+followed by "+" and a local version label. For example, a package with
+Fedora-specific patches applied could have the version "1.2.1+fedora.4".
+Another example is versions computed by setuptools-scm_, a setuptools plugin
+that reads the version from Git data. In a Git repository with some commits
+since the latest release, setuptools-scm generates a version like
+"0.5.dev1+gd00980f", or if the repository has untracked changes, like
+"0.5.dev1+gd00980f.d20231217".
 
 
 .. _calver: https://calver.org
 .. _semver: https://semver.org
+.. _setuptools-scm: https://setuptools-scm.readthedocs.io
diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
index 8e9ed564b..bf4227aae 100644
--- a/source/guides/distributing-packages-using-setuptools.rst
+++ b/source/guides/distributing-packages-using-setuptools.rst
@@ -287,6 +287,12 @@ achieve cross-platform compatibility is to use :ref:`console_scripts` entry
 points (see below).
 
 
+Choosing a versioning scheme
+----------------------------
+
+See :ref:`versioning` for information on common version schemes and how to
+choose between them.
+
 
 Working in "development mode"
 =============================

From e99d27dfce0f6d8b93c019bb723e20a55871041e Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 17 Dec 2023 20:45:15 +0100
Subject: [PATCH 251/733] Merge "Pre-release versioning" into "Valid version
 numbers"

---
 source/discussions/versioning.rst | 22 +++++-----------------
 1 file changed, 5 insertions(+), 17 deletions(-)

diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst
index 082dd1716..a63d269bc 100644
--- a/source/discussions/versioning.rst
+++ b/source/discussions/versioning.rst
@@ -31,7 +31,10 @@ examples of version numbers:
 
 Projects can use a cycle of pre-releases to support testing by their users
 before a final release. In order, the steps are: alpha releases, beta releases,
-release candidates, final release.
+release candidates, final release. Pip and other modern Python package
+installers ignore pre-releases by default when deciding which versions of
+dependencies to install, unless explicitly requested (e.g., with
+``pip install pkg==1.1a3``).
 
 The purpose of development releases is to support releases made early during a
 development cycle, for example, a nightly build, or a build from the latest
@@ -51,6 +54,7 @@ To correct this, the new version numbers should have an explicit epoch, as in
 "1!1.0", in order to be treated as more recent than the old version numbers.
 
 
+
 Semantic versioning vs. calendar versioning
 ===========================================
 
@@ -131,22 +135,6 @@ doesn't otherwise commit to a particular release cadence within the year.
 
 
 
-Pre-release versioning
-======================
-
-Regardless of the base versioning scheme, pre-releases for a given final release
-may be published as:
-
-* Zero or more dev releases, denoted with a ".devN" suffix,
-* Zero or more alpha releases, denoted with a "aN" suffix,
-* Zero or more beta releases, denoted with a "bN" suffix,
-* Zero or more release candidates, denoted with a "rcN" suffix.
-
-Pip and other modern Python package installers ignore pre-releases by default
-when deciding which versions of dependencies to install, unless explicitly
-requested, e.g., with ``pip install pkg==1.1a3``.
-
-
 Local version identifiers
 =========================
 

From ece6b79a75f79df76c4cdffbd94d01c3f078e957 Mon Sep 17 00:00:00 2001
From: Noam Yorav-Raphael 
Date: Mon, 18 Dec 2023 11:19:47 +0200
Subject: [PATCH 252/733] Update glossary.rst: Update link to requirement
 specifier syntax to PEP 508

The current link doesn't actually give the syntax of the requirement specifier. PEP 508 is much better.
---
 source/glossary.rst | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index 9bfcbbd3f..d19c2f743 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -209,10 +209,8 @@ Glossary
     Requirement Specifier
 
        A format used by :ref:`pip` to install packages from a :term:`Package
-       Index`. For an EBNF diagram of the format, see the
-       `pkg_resources.Requirement
-       `_
-       entry in the :ref:`setuptools` docs. For example, "foo>=1.3" is a
+       Index`. For an EBNF diagram of the format, see `PEP 508
+       `_. For example, "foo>=1.3" is a
        requirement specifier, where "foo" is the project name, and the ">=1.3"
        portion is the :term:`Version Specifier`
 

From 21c754c1b978256162996cef6fe6052c8bcb5747 Mon Sep 17 00:00:00 2001
From: Noam Yorav-Raphael 
Date: Mon, 18 Dec 2023 15:09:30 +0200
Subject: [PATCH 253/733] Update glossary.rst - refer to
 `dependency-specifiers`

---
 source/glossary.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index d19c2f743..1f55871fa 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -209,8 +209,8 @@ Glossary
     Requirement Specifier
 
        A format used by :ref:`pip` to install packages from a :term:`Package
-       Index`. For an EBNF diagram of the format, see `PEP 508
-       `_. For example, "foo>=1.3" is a
+       Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`.
+       For example, "foo>=1.3" is a
        requirement specifier, where "foo" is the project name, and the ">=1.3"
        portion is the :term:`Version Specifier`
 

From d1e7ac4729662c727803291a7738c480f077807d Mon Sep 17 00:00:00 2001
From: Mike Fiedler 
Date: Mon, 18 Dec 2023 12:52:47 -0500
Subject: [PATCH 254/733] docs: update testpypi guide for api token

With the upcoming change to require 2FA for all users (already enforced
on TestPyPI), update guidance to point the user in the right direction.

Signed-off-by: Mike Fiedler 
---
 source/guides/using-testpypi.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/source/guides/using-testpypi.rst b/source/guides/using-testpypi.rst
index f2c4f07c6..1dbc82130 100644
--- a/source/guides/using-testpypi.rst
+++ b/source/guides/using-testpypi.rst
@@ -72,12 +72,13 @@ you're testing has dependencies:
 Setting up TestPyPI in :file:`.pypirc`
 --------------------------------------
 
-If you want to avoid entering your username, you can configure TestPyPI in
-your :file:`$HOME/.pypirc`:
+If you want to avoid being prompted for your username and password every time,
+you can configure TestPyPI in your :file:`$HOME/.pypirc`:
 
 .. code:: ini
 
     [testpypi]
-    username = 
+    username = __token__
+    password = 
 
 For more details, see the :ref:`specification ` for :file:`.pypirc`.

From d7f6d641e7ec677be4ad6d9fffe842912c12a302 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 18 Dec 2023 18:41:42 +0000
Subject: [PATCH 255/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.1.7 → v0.1.8](https://github.com/astral-sh/ruff-pre-commit/compare/v0.1.7...v0.1.8)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index ee15601ec..20eeadb57 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.7
+  rev: v0.1.8
   hooks:
     - id: ruff
     - id: ruff-format

From 390d4a8ce1dc1107ed3d1c803faf1e150d6afb9f Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 19 Dec 2023 12:07:48 +0100
Subject: [PATCH 256/733] Correct path to venv scripts on Windows

Fixes #1459
---
 .../guides/installing-using-pip-and-virtual-environments.rst  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index e6aa88471..e33615157 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -88,7 +88,7 @@ shell's ``PATH``.
 
     .. code-block:: bat
 
-        .venv\bin\Activate.bat
+        .venv\Scripts\Activate.bat
 
 To confirm the virtual environment is activated, check the location of your
 Python interpreter:
@@ -118,7 +118,7 @@ filepath that includes the ``.venv`` directory, by ending with the following:
 
     .. code-block:: bat
 
-        .venv\bin\python.exe
+        .venv\Scripts\python.exe
 
 
 While a virtual environment is activated, pip will install packages into that

From b3ce0245bc3f0fe8f36bffa4c48dcdaf00159f9c Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 15 Nov 2023 23:34:09 +0100
Subject: [PATCH 257/733] Add discussion of package formats, expanding "Wheel
 vs Egg" discussion

---
 source/discussions/index.rst                  |   2 +-
 source/discussions/package-formats.rst        | 193 ++++++++++++++++++
 source/discussions/wheel-vs-egg.rst           |  55 -----
 .../binary-distribution-format.rst            |   2 +
 4 files changed, 196 insertions(+), 56 deletions(-)
 create mode 100644 source/discussions/package-formats.rst
 delete mode 100644 source/discussions/wheel-vs-egg.rst

diff --git a/source/discussions/index.rst b/source/discussions/index.rst
index b378ed810..5033bf703 100644
--- a/source/discussions/index.rst
+++ b/source/discussions/index.rst
@@ -11,7 +11,7 @@ specific topic. If you're just trying to get stuff done, see
    deploying-python-applications
    pip-vs-easy-install
    install-requires-vs-requirements
-   wheel-vs-egg
    distribution-package-vs-import-package
+   package-formats
    src-layout-vs-flat-layout
    setup-py-deprecated
diff --git a/source/discussions/package-formats.rst b/source/discussions/package-formats.rst
new file mode 100644
index 000000000..6d4dee35c
--- /dev/null
+++ b/source/discussions/package-formats.rst
@@ -0,0 +1,193 @@
+.. _package-formats:
+
+===============
+Package Formats
+===============
+
+This page discusses the file formats that are used to distribute Python packages
+and the differences between them.
+
+You will find files in two formats on package indices such as PyPI_: **source
+distributions**, or **sdists** for short, and **binary distributions**, commonly
+called **wheels**.  For example, the `PyPI page for pip 23.3.1 `_
+lets you download two files, ``pip-23.3.1.tar.gz`` and
+``pip-23.3.1-py3-none-any.whl``.  The former is an sdist, the latter is a
+wheel. As explained below, these serve different purposes. When publishing a
+package on PyPI (or elsewhere), you should always upload both an sdist and one
+or more wheel.
+
+
+What is a source distribution?
+==============================
+
+Conceptually, a source distribution is an archive of the source code in raw
+form. Concretely, an sdist is a ``.tar.gz`` archive containing the source code
+plus an additional special file called ``PKG-INFO``, which holds the project
+metadata. The presence of this file helps packaging tools to be more efficient
+by not needing to compute the metadata themselves. The ``PKG-INFO`` file follows
+the format specified in :ref:`core-metadata` and is not intended to be written
+by hand [#core-metadata-format]_.
+
+You can thus inspect the contents of an sdist by unpacking it using standard
+tools to work with tar archives, such as ``tar -xvf`` on UNIX platforms (like
+Linux and macOS), or :ref:`the command line interface of Python's tarfile module
+` on any platform.
+
+Sdists serve several purposes in the packaging ecosystem. When :ref:`pip`, the
+standard Python package installer, cannot find a wheel to install, it will fall
+back on downloading a source distribution, compiling a wheel from it, and
+installing the wheel. Furthermore, sdists are often used as the package source
+by downstream packagers (such as Linux distributions, Conda, Homebrew and
+MacPorts on macOS, ...), who, for various reasons, may prefer them over, e.g.,
+pulling from a Git repository.
+
+A source distribution is recognized by its file name, which has the form
+:samp:`{package_name}-{version}.tar.gz`, e.g., ``pip-23.3.1.tar.gz``.
+
+.. TODO: provide clear guidance on whether sdists should contain docs and tests.
+   Discussion: https://discuss.python.org/t/should-sdists-include-docs-and-tests/14578
+
+If you want technical details on the sdist format, read the :ref:`sdist
+specification `.
+
+
+What is a wheel?
+================
+
+Conceptually, a wheel contains exactly the files that need to be copied when
+installing the package.
+
+There is a big difference between sdists and wheels for packages with
+:term:`extension modules `, written in compiled languages like
+C, C++ and Rust, which need to be compiled into platform-dependent machine code.
+With these packages, wheels do not contain source code (like C source files) but
+compiled, executable code (like ``.so`` files on Linux or DLLs on Windows).
+
+Furthermore, while there is only one sdist per version of a project, there may
+be many wheels. Again, this is most relevant in the context of extension
+modules. The compiled code of an extension module is tied to an operating system
+and processor architecture, and often also to the version of the Python
+interpreter (unless the :ref:`Python stable ABI ` is used).
+
+For pure-Python packages, the difference between sdists and wheels is less
+marked. There is normally one single wheel, for all platforms and Python
+versions.  Python is an interpreted language, which does not need ahead-of-time
+compilation, so wheels contain ``.py`` files just like sdists.
+
+If you are wondering about ``.pyc`` bytecode files: they are not included in
+wheels, since they are cheap to generate, and including them would unnecessarily
+force a huge number of packages to distribute one wheel per Python version
+instead of one single wheel. Instead, installers like :ref:`pip` generate them
+while installing the package.
+
+With that being said, there are still important differences between sdists and
+wheels, even for pure Python projects. Wheels are meant to contain exactly what
+is to be installed, and nothing more. In particular, wheels should never include
+tests and documentation, while sdists commonly do.  Also, the wheel format is
+more complex than sdist. For example, it includes a special file -- called
+``RECORD`` -- that lists all files in the wheel along with a hash of their
+content, as a safety check of the download's integrity.
+
+At a glance, you might wonder if wheels are really needed for "plain and basic"
+pure Python projects. Keep in mind that due to the flexibility of sdists,
+installers like pip cannot install from sdists directly -- they need to first
+build a wheel, by invoking the :term:`build backend` that the sdist specifies
+(the build backend may do all sorts of transformations while building the wheel,
+such as compiling C extensions). For this reason, even for a pure Python
+project, you should always upload *both* an sdist and a wheel to PyPI or other
+package indices. This makes installation much faster for your users, since a
+wheel is directly installable. By only including files that must be installed,
+wheels also make for smaller downloads.
+
+On the technical level, a wheel is a ZIP archive (unlike sdists which are TAR
+archives). You can inspect its contents by unpacking it as a normal ZIP archive,
+e.g., using ``unzip`` on UNIX platforms like Linux and macOS, ``Expand-Archive``
+in Powershell on Windows, or :ref:`the command line interface of Python's
+zipfile module `. This can be very useful to check
+that the wheel includes all the files you need it to.
+
+Inside a wheel, you will find the package's files, plus an additional directory
+called :samp:`{package_name}-{version}.dist-info`. This directory contains
+various files, including a ``METADATA`` file which is the equivalent of
+``PKG-INFO`` in sdists, as well as ``RECORD``. This can be useful to ensure no
+files are missing from your wheels.
+
+The file name of a wheel (ignoring some rarely used features) looks like this:
+:samp:`{package_name}-{version}-{python_tag}-{abi_tag}-{platform_tag}.whl`.
+This naming convention identifies which platforms and Python versions the wheel
+is compatible with. For example, the name ``pip-23.3.1-py3-none-any.whl`` means
+that:
+
+- (``py3``) This wheel can be installed on any implementation of Python 3,
+  whether CPython, the most widely used Python implementation, or an alternative
+  implementation like PyPy_;
+- (``none``) It does not depend on the Python version;
+- (``any``) It does not depend on the platform.
+
+The pattern ``py3-none-any`` is common for pure Python projects. Packages with
+extension modules typically ship multiple wheels with more complex tags.
+
+All technical details on the wheel format can be found in the :ref:`wheel
+specification `.
+
+
+.. _egg-format:
+.. _`Wheel vs Egg`:
+
+What about eggs?
+================
+
+"Egg" is an old package format that has been replaced with the wheel format.  It
+should not be used anymore. Since August 2023, PyPI `rejects egg uploads
+`_.
+
+Here's a breakdown of the important differences between wheel and egg.
+
+* The egg format was introduced by :ref:`setuptools` in 2004, whereas the wheel
+  format was introduced by :pep:`427` in 2012.
+
+* Wheel has an :doc:`official standard specification
+  `. Egg did not.
+
+* Wheel is a :term:`distribution ` format, i.e a packaging
+  format. [#wheel-importable]_ Egg was both a distribution format and a runtime
+  installation format (if left zipped), and was designed to be importable.
+
+* Wheel archives do not include ``.pyc`` files. Therefore, when the distribution
+  only contains Python files (i.e. no compiled extensions), and is compatible
+  with Python 2 and 3, it's possible for a wheel to be "universal", similar to
+  an :term:`sdist `.
+
+* Wheel uses standard :ref:`.dist-info directories
+  `.  Egg used ``.egg-info``.
+
+* Wheel has a :ref:`richer file naming convention `. A
+  single wheel archive can indicate its compatibility with a number of Python
+  language versions and implementations, ABIs, and system architectures.
+
+* Wheel is versioned. Every wheel file contains the version of the wheel
+  specification and the implementation that packaged it.
+
+* Wheel is internally organized by `sysconfig path type
+  `_,
+  therefore making it easier to convert to other formats.
+
+--------------------------------------------------------------------------------
+
+.. [#core-metadata-format] This format is email-based. Although this would
+   be unlikely to be chosen today, backwards compatibility considerations lead to
+   it being kept as the canonical format. From the user point of view, this
+   is mostly invisible, since the metadata is specified by the user in a way
+   understood by the build backend, typically ``[project]`` in ``pyproject.toml``,
+   and translated by the build backend into ``PKG-INFO``.
+
+.. [#wheel-importable] Circumstantially, in some cases, wheels can be used
+   as an importable runtime format, although :ref:`this is not officially supported
+   at this time `.
+
+
+
+.. _pip-pypi: https://pypi.org/project/pip/23.3.1/#files
+.. _pypi: https://pypi.org
+.. _pypi-eggs-deprecation: https://blog.pypi.org/posts/2023-06-26-deprecate-egg-uploads/
+.. _pypy: https://pypy.org
diff --git a/source/discussions/wheel-vs-egg.rst b/source/discussions/wheel-vs-egg.rst
deleted file mode 100644
index d4a1114fb..000000000
--- a/source/discussions/wheel-vs-egg.rst
+++ /dev/null
@@ -1,55 +0,0 @@
-.. _`Wheel vs Egg`:
-
-============
-Wheel vs Egg
-============
-
-:term:`Wheel` and :term:`Egg` are both packaging formats that aim to support the
-use case of needing an install artifact that doesn't require building or
-compilation, which can be costly in testing and production workflows.
-
-The :term:`Egg` format was introduced by :ref:`setuptools` in 2004, whereas the
-:term:`Wheel` format was introduced by :pep:`427` in 2012.
-
-:term:`Wheel` is currently considered the standard for :term:`built ` and :term:`binary ` packaging for Python.
-
-Here's a breakdown of the important differences between :term:`Wheel` and :term:`Egg`.
-
-
-* :term:`Wheel` has an :doc:`official standard specification
-  `.
-  :term:`Egg` did not.
-
-* :term:`Wheel` is a :term:`distribution ` format, i.e a packaging
-  format. [1]_ :term:`Egg` was both a distribution format and a runtime
-  installation format (if left zipped), and was designed to be importable.
-
-* :term:`Wheel` archives do not include .pyc files. Therefore, when the
-  distribution only contains Python files (i.e. no compiled extensions), and is
-  compatible with Python 2 and 3, it's possible for a wheel to be "universal",
-  similar to an :term:`sdist `.
-
-* :term:`Wheel` uses :pep:`PEP376-compliant <376>` ``.dist-info``
-  directories. Egg used ``.egg-info``.
-
-* :term:`Wheel` has a :pep:`richer file naming convention <425>`. A single
-  wheel archive can indicate its compatibility with a number of Python language
-  versions and implementations, ABIs, and system architectures.
-
-* :term:`Wheel` is versioned. Every wheel file contains the version of the wheel
-  specification and the implementation that packaged it.
-
-* :term:`Wheel` is internally organized by `sysconfig path type
-  `_,
-  therefore making it easier to convert to other formats.
-
-* :term:`Egg` uploads have been disabled for upload to PyPI, per :pep:`715`.
-  Read the `deprecation notice `_
-  for more information.
-
-----
-
-.. [1] Circumstantially, in some cases, wheels can be used as an importable
-       runtime format, although :ref:`this is not officially supported at this time
-       `.
diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index 6637fed2e..7d2c4e2a0 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -84,6 +84,8 @@ Place ``.dist-info`` at the end of the archive.
 File Format
 -----------
 
+.. _wheel-file-name-spec:
+
 File name convention
 ''''''''''''''''''''
 

From 5af20bf30596aa9e00254377c11aa408538d8a6e Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 15 Nov 2023 23:42:45 +0100
Subject: [PATCH 258/733] Update glossary with references to the new "Package
 formats" discussion

---
 source/glossary.rst | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index 1f55871fa..218c21168 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -47,11 +47,11 @@ Glossary
         A :term:`Distribution ` format containing files
         and metadata that only need to be moved to the correct location on the
         target system, to be installed. :term:`Wheel` is such a format, whereas
-        distutil's :term:`Source Distribution ` is not, in that it requires a build step before it can be
         installed.  This format does not imply that Python files have to be
         precompiled (:term:`Wheel` intentionally does not include compiled
-        Python files).
+        Python files). See :ref:`package-formats` for more information.
 
 
     Distribution Package
@@ -73,9 +73,8 @@ Glossary
     Egg
 
         A :term:`Built Distribution` format introduced by :ref:`setuptools`,
-        which is being replaced by :term:`Wheel`.  For details, see
-        :doc:`The Internal Structure of Python Eggs ` and
-        `Python Eggs `_
+        which has been replaced by :term:`Wheel`.  For details, see
+        :ref:`egg-format`.
 
     Extension Module
 
@@ -240,7 +239,8 @@ Glossary
         A :term:`distribution ` format (usually generated
         using ``python -m build --sdist``) that provides metadata and the
         essential source files needed for installing by a tool like :ref:`pip`,
-        or for generating a :term:`Built Distribution`.
+        or for generating a :term:`Built Distribution`. See :ref:`package-formats`
+        for more information.
 
 
     System Package
@@ -266,11 +266,8 @@ Glossary
 
     Wheel
 
-        A :term:`Built Distribution` format introduced by an official
-        :doc:`standard specification
-        `,
-        which is intended to replace the :term:`Egg` format.  Wheel is currently
-        supported by :ref:`pip`.
+        The standard :term:`Built Distribution` format.
+        See :ref:`package-formats` for more information.
 
     Working Set
 

From 67f169ff1f2f26ba46eee3f7609381da6334b0ee Mon Sep 17 00:00:00 2001
From: Rafael Fontenelle 
Date: Wed, 20 Dec 2023 09:43:56 -0300
Subject: [PATCH 259/733] Fix po filename in test-translations.yml

---
 .github/workflows/test-translations.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test-translations.yml b/.github/workflows/test-translations.yml
index 9b1ad5c6f..cdb40b1aa 100644
--- a/.github/workflows/test-translations.yml
+++ b/.github/workflows/test-translations.yml
@@ -71,4 +71,4 @@ jobs:
       run: nox -s build -- -q -D language=${{ matrix.language }}
 
     - name: Lint translation file
-      run: sphinx-lint locales/${{ matrix.language }}/LC_MESSAGES/message.po
+      run: sphinx-lint locales/${{ matrix.language }}/LC_MESSAGES/messages.po

From b55365166533622f9c5fd6549dcbbe6f746aca07 Mon Sep 17 00:00:00 2001
From: Rafael Fontenelle 
Date: Wed, 20 Dec 2023 09:45:23 -0300
Subject: [PATCH 260/733] Make the matrix input generation more simpler

Co-authored-by: Jean Abou-Samra 
---
 .github/workflows/test-translations.yml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/.github/workflows/test-translations.yml b/.github/workflows/test-translations.yml
index cdb40b1aa..50f2dd067 100644
--- a/.github/workflows/test-translations.yml
+++ b/.github/workflows/test-translations.yml
@@ -39,8 +39,7 @@ jobs:
       id: languages
       working-directory: locales
       run: |
-        dirs=$(find * -maxdepth 0 -type d)
-        list="$(echo $dirs | sed "s|^|['|;s|$|']|;s| |', '|g")"
+        list=$(find * -maxdepth 0 -type d | jq -nRc '[inputs]')
         echo "languages=$list" >> $GITHUB_OUTPUT
 
 

From 954a81bb8e14a09dfc3d2ed6e1d9f32b689c519c Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Wed, 20 Dec 2023 18:51:00 +0100
Subject: [PATCH 261/733] Use "universal" activate command

Co-authored-by: chrysle 
---
 source/guides/installing-using-pip-and-virtual-environments.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index e33615157..eb28f7458 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -88,7 +88,7 @@ shell's ``PATH``.
 
     .. code-block:: bat
 
-        .venv\Scripts\Activate.bat
+        .venv\Scripts\activate
 
 To confirm the virtual environment is activated, check the location of your
 Python interpreter:

From e1ed4d7ac4a027483f48b178bf5485876bfd3c32 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Wed, 20 Dec 2023 18:51:16 +0100
Subject: [PATCH 262/733] Use "universal" Python commmand

Co-authored-by: chrysle 
---
 source/guides/installing-using-pip-and-virtual-environments.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index eb28f7458..64fdf9382 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -118,7 +118,7 @@ filepath that includes the ``.venv`` directory, by ending with the following:
 
     .. code-block:: bat
 
-        .venv\Scripts\python.exe
+        .venv\Scripts\python
 
 
 While a virtual environment is activated, pip will install packages into that

From 4d0108284aedcde4a89ad4e1c829b0277f9c281a Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 20 Dec 2023 19:43:52 +0100
Subject: [PATCH 263/733] Link 0ver + blog posts on semver limitations

---
 source/discussions/versioning.rst | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst
index a63d269bc..a2d818e87 100644
--- a/source/discussions/versioning.rst
+++ b/source/discussions/versioning.rst
@@ -67,7 +67,7 @@ semantic versioning and calendar versioning.
 Semantic versioning
 -------------------
 
-The idea of *semantic versioning* is to use 3-part version numbers,
+The idea of *semantic versioning* (or SemVer) is to use 3-part version numbers,
 *major.minor.maintenance*, where the project author increments:
 
 - *major* when they make incompatible API changes,
@@ -79,7 +79,8 @@ versioning. However, most projects, especially larger ones, do not strictly
 adhere to semantic versioning, since many changes are technically breaking
 changes but affect only a small fraction of users. Such projects tend to
 increment the major number when the incompatibility is high, or to signal a
-shift in the project, rather than for any tiny incompatibility,
+shift in the project, rather than for any tiny incompatibility
+[#semver-strictness]_.
 
 For those projects that do use strict semantic versioning, this approach allows
 users to make use of :ref:`compatible release version specifiers
@@ -108,9 +109,9 @@ Semantic versioning is not a suitable choice for all projects, such as those
 with a regular time based release cadence and a deprecation process that
 provides warnings for a number of releases prior to removal of a feature.
 
-A key advantage of date-based versioning, or `calendar versioning `_,
-is that it is straightforward to tell how old the base feature set of a
-particular release is given just the version number.
+A key advantage of date-based versioning, or `calendar versioning `_
+(CalVer), is that it is straightforward to tell how old the base feature set of
+a particular release is given just the version number.
 
 Calendar version numbers typically take the form *year.month* (for example,
 23.12 for December 2023).
@@ -154,6 +155,22 @@ since the latest release, setuptools-scm generates a version like
 "0.5.dev1+gd00980f.d20231217".
 
 
+--------------------------------------------------------------------------------
+
+
+.. [#semver-strictness] For some personal viewpoints on this issue, see these
+   blog posts: `by Hynek Schlawak `_, `by Donald Stufft
+   `_, `by Bernát Gábor `_, `by
+   Brett Cannon `_. For a humoristic take, read about
+   ZeroVer_.
+
+
+
+.. _zerover: https://0ver.org
 .. _calver: https://calver.org
 .. _semver: https://semver.org
+.. _semver-bernat-gabor: https://bernat.tech/posts/version-numbers/
+.. _semver-brett-cannon: https://snarky.ca/why-i-dont-like-semver/
+.. _semver-donald-stufft: https://caremad.io/posts/2016/02/versioning-software/
+.. _semver-hynek-schlawack: https://hynek.me/articles/semver-will-not-save-you/
 .. _setuptools-scm: https://setuptools-scm.readthedocs.io

From 0288ec010b37533d53eb66a391e3ecb2c5238932 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Kr=C3=B6ner?=
 <36126706+Crown0815@users.noreply.github.com>
Date: Thu, 21 Dec 2023 12:04:06 +0100
Subject: [PATCH 264/733] Remove unnecessary word from documentation

---
 source/guides/hosting-your-own-index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/hosting-your-own-index.rst b/source/guides/hosting-your-own-index.rst
index 26ffe2b8c..bce4e0807 100644
--- a/source/guides/hosting-your-own-index.rst
+++ b/source/guides/hosting-your-own-index.rst
@@ -6,7 +6,7 @@ Hosting your own simple repository
 
 
 If you wish to host your own simple repository [1]_, you can either use a
-software package like :doc:`devpi ` or you can use simply create the proper
+software package like :doc:`devpi ` or you can simply create the proper
 directory structure and use any web server that can serve static files and
 generate an autoindex.
 

From 3a90a886056e8030cdef7f82deaffaaf8e73e9ff Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Fri, 22 Dec 2023 14:55:33 +0100
Subject: [PATCH 265/733] Deduplicate specification of valid package names

- Rename the "Package name normalization" specification into "Package
  name grammar and normalization", to make it explicitly about the
  format of valid names too.

- Link to this spec in the core metadata specification instead of
  duplicating the part about valid names.
---
 source/specifications/core-metadata.rst      |  9 ++----
 source/specifications/name-normalization.rst | 30 +++++++++++++-------
 2 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index b8cd5326e..6b5efd13a 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -73,15 +73,10 @@ Name
 
 .. versionadded:: 1.0
 .. versionchanged:: 2.1
-   Added additional restrictions on format from :pep:`508`
+   Added restrictions on format from the :ref:`name grammar `.
 
 The name of the distribution. The name field is the primary identifier for a
-distribution. A valid name consists only of ASCII letters and numbers, period,
-underscore and hyphen. It must start and end with a letter or number.
-Distribution names are limited to those which match the following
-regex (run with ``re.IGNORECASE``)::
-
-    ^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$
+distribution. It must conform to the :ref:`package name grammar `.
 
 Example::
 
diff --git a/source/specifications/name-normalization.rst b/source/specifications/name-normalization.rst
index 64be4a1d1..fb6d22a09 100644
--- a/source/specifications/name-normalization.rst
+++ b/source/specifications/name-normalization.rst
@@ -1,13 +1,16 @@
-.. _name-normalization:
+======================================
+Package name grammar and normalization
+======================================
+
+Project names obey a restricted format, and are "normalized" for use in various
+contexts. This document describes what the valid project names are, and how
+project names should be normalized.
 
-==========================
-Package name normalization
-==========================
 
-Project names are "normalized" for use in various contexts. This document describes how project names should be normalized.
+.. _name-grammar:
 
-Valid non-normalized names
---------------------------
+Name grammar
+============
 
 A valid name consists only of ASCII letters and numbers, period,
 underscore and hyphen. It must start and end with a letter or number.
@@ -16,10 +19,15 @@ following regex (run with ``re.IGNORECASE``)::
 
     ^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$
 
-Normalization
--------------
 
-The name should be lowercased with all runs of the characters ``.``, ``-``, or ``_`` replaced with a single ``-`` character. This can be implemented in Python with the re module:
+.. _name-normalization:
+
+Name normalization
+==================
+
+The name should be lowercased with all runs of the characters ``.``, ``-``, or
+``_`` replaced with a single ``-`` character. This can be implemented in Python
+with the re module:
 
 .. code-block:: python
 
@@ -30,7 +38,7 @@ The name should be lowercased with all runs of the characters ``.``, ``-``, or `
 
 This means that the following names are all equivalent:
 
-* ``friendly-bard``  (normalized form)
+* ``friendly-bard`` (normalized form)
 * ``Friendly-Bard``
 * ``FRIENDLY-BARD``
 * ``friendly.bard``

From c0f078d293ac7b30981a2f78bd6ccfe3ebad69df Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Fri, 22 Dec 2023 16:44:37 +0100
Subject: [PATCH 266/733] Consistent changelogs for all specs

Fixes #1203
---
 .../binary-distribution-format.rst            |  9 ++----
 source/specifications/core-metadata.rst       | 20 +++++++++++++
 .../specifications/dependency-specifiers.rst  | 16 +++++-----
 .../direct-url-data-structure.rst             | 13 ++++++---
 source/specifications/direct-url.rst          |  4 +--
 source/specifications/entry-points.rst        | 11 +++++++
 .../externally-managed-environments.rst       |  2 +-
 .../specifications/inline-script-metadata.rst |  2 +-
 source/specifications/name-normalization.rst  |  6 ++--
 .../platform-compatibility-tags.rst           | 19 +++++++-----
 source/specifications/pyproject-toml.rst      |  8 +++--
 .../recording-installed-packages.rst          | 29 +++++++++----------
 .../source-distribution-format.rst            | 12 ++++----
 source/specifications/version-specifiers.rst  |  5 +---
 .../specifications/virtual-environments.rst   |  6 ++++
 15 files changed, 105 insertions(+), 57 deletions(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index 6637fed2e..3ca3cc785 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -418,12 +418,9 @@ Is it possible to import Python code directly from a wheel file?
 History
 =======
 
-This specification was originally approved as :pep:`427`.
-
-The following changes were applied since the initial version:
-
-- The rules on escaping in wheel filenames were revised, to bring them
-  into line with what popular tools actually do (February 2021).
+- February 2013: This specification was approved through :pep:`427`.
+- February 2021: The rules on escaping in wheel filenames were revised, to bring
+  them into line with what popular tools actually do.
 
 
 Appendix
diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index b8cd5326e..2fb83206c 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -848,6 +848,26 @@ Example::
     Obsoletes: Gorgon
 
 
+History
+=======
+
+- March 2001: Core metadata 1.0 was approved through :pep:`241`.
+- April 2003: Core metadata 1.1 was approved through :pep:`314`:
+- February 2010: Core metadata 1.2 was approved through :pep:`345`.
+- February 2018: Core metadata 2.1 was approved through :pep:`566`.
+
+  - Added ``Description-Content-Type`` and ``Provides-Extra``.
+  - Added canonical method for transforming metadata to JSON.
+  - Restricted the grammar of the ``Name`` field.
+
+- October 2020: Core metadata 2.2 was approved through :pep:`643`.
+
+  - Added the ``Dynamic`` field.
+
+- March 2022: Core metadata 2.3 was approved through :pep:`685`.
+
+  - Restricted extra names to be normalized.
+
 ----
 
 .. [1] reStructuredText markup:
diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index 6287f3815..85216d655 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -472,14 +472,12 @@ A test program - if the grammar is in a string ``grammar``:
         print("%s -> %s" % (test, parsed))
 
 
-Summary of changes to PEP 508
-=============================
+History
+=======
 
-The following changes were made based on feedback after its initial
-implementation:
-
-- The definition of ``python_version`` was changed from
-  ``platform.python_version()[:3]`` to
+- November 2015: This specification was approved through :pep:`508`.
+- July 2019: The definition of ``python_version`` was `changed
+  `_ from ``platform.python_version()[:3]`` to
   ``'.'.join(platform.python_version_tuple()[:2])``, to accommodate potential
   future versions of Python with 2-digit major and minor versions
   (e.g. 3.10). [#future_versions]_
@@ -497,3 +495,7 @@ References
 .. [#future_versions] Future Python versions might be problematic with the
    definition of Environment Marker Variable ``python_version``
    (https://github.com/python/peps/issues/560)
+
+
+
+.. _python-version-change: https://mail.python.org/pipermail/distutils-sig/2018-January/031920.html
diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index 22900636c..f0ab2e447 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -262,10 +262,15 @@ Local directory in editable mode:
        }
    }
 
+
 History
 =======
 
-- March 2020: this data structure was originally specified as part of the
-  ``direct_url.json`` metadata file in :pep:`610` and is formally documented here.
-- January 2023: Added the ``archive_info.hashes`` key
-  ([discussion](https://discuss.python.org/t/22299)).
+- March 2020: This specification was approved through :pep:`610`, defining
+  the ``direct_url.json`` metadata file.
+- January 2023: Added the ``archive_info.hashes`` key (`discussion
+  `_).
+
+
+
+.. _archive-info-hashes: https://discuss.python.org/t/22299
diff --git a/source/specifications/direct-url.rst b/source/specifications/direct-url.rst
index 5c0bd1b21..babecd842 100644
--- a/source/specifications/direct-url.rst
+++ b/source/specifications/direct-url.rst
@@ -62,8 +62,8 @@ Commands that *do not* generate a ``direct_url.json``
 * ``pip install app``
 * ``pip install app --no-index --find-links https://example.com/``
 
+
 History
 =======
 
-- March 2020: the ``direct_url.json`` metadata file was originally specified in
-  :pep:`610` and is formally documented here.
+- March 2020: This specification was approved through :pep:`610`.
diff --git a/source/specifications/entry-points.rst b/source/specifications/entry-points.rst
index 90a18a0bc..6a601c977 100644
--- a/source/specifications/entry-points.rst
+++ b/source/specifications/entry-points.rst
@@ -158,3 +158,14 @@ which defines where command-line tools are found.
 As files are created from the names, and some filesystems are case-insensitive,
 packages should avoid using names in these groups which differ only in case.
 The behaviour of install tools when names differ only in case is undefined.
+
+
+History
+=======
+
+- October 2017: This specification was written to formalize the existing
+  entry points feature of setuptools (discussion_).
+
+
+
+.. _discussion: https://mail.python.org/pipermail/distutils-sig/2017-October/031585.html
diff --git a/source/specifications/externally-managed-environments.rst b/source/specifications/externally-managed-environments.rst
index f6845e737..2944eb3da 100644
--- a/source/specifications/externally-managed-environments.rst
+++ b/source/specifications/externally-managed-environments.rst
@@ -471,4 +471,4 @@ CC0-1.0-Universal license, whichever is more permissive.
 History
 =======
 
-This specification was originally approved as :pep:`668`.
+- June 2022: This specification was approved through :pep:`668`.
diff --git a/source/specifications/inline-script-metadata.rst b/source/specifications/inline-script-metadata.rst
index 021c316fe..f18f4f17e 100644
--- a/source/specifications/inline-script-metadata.rst
+++ b/source/specifications/inline-script-metadata.rst
@@ -238,4 +238,4 @@ the highest available version of Python that is compatible with the script's
 History
 =======
 
-This specification was originally defined as :pep:`723`.
+- October 2023: This specification was conditionally approved through :pep:`723`.
diff --git a/source/specifications/name-normalization.rst b/source/specifications/name-normalization.rst
index 64be4a1d1..18a59e1cc 100644
--- a/source/specifications/name-normalization.rst
+++ b/source/specifications/name-normalization.rst
@@ -41,5 +41,7 @@ This means that the following names are all equivalent:
 History
 =======
 
-- `September 2015 `_: normalized name was originally specified in :pep:`503#normalized-names`.
-- `November 2015 `_: valid non-normalized name was originally specified in :pep:`508#names`.
+- September 2015: The specification of name normalized was approved through
+  :pep:`503 <503#normalized-names>`.
+- November 2015: The specification of valid names was approved through
+  :pep:`508 <508#names>`.
diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index df7da59c5..52ffadfa3 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -9,13 +9,6 @@ Platform compatibility tags allow build tools to mark distributions as being
 compatible with specific platforms, and allows installers to understand which
 distributions are compatible with the system they are running on.
 
-The following PEPs contributed to this spec:
-
-1. :pep:`425`
-2. :pep:`513`
-3. :pep:`571`
-4. :pep:`599`
-5. :pep:`600`
 
 Overview
 ========
@@ -302,3 +295,15 @@ Why is the ABI tag (the second tag) sometimes "none" in the reference implementa
     implementation at the time of writing guesses "none".  Ideally it
     would detect "py27(d|m|u)" analogous to newer versions of Python,
     but in the meantime "none" is a good enough way to say "don't know".
+
+
+History
+=======
+
+- February 2013: The original version of this specification was approved through
+  :pep:`425`.
+- January 2016: The ``manylinux1`` tag was approved through :pep:`513`.
+- April 2018: The ``manylinux2010`` tag was approved through :pep:`571`.
+- July 2019: The ``manylinux2014`` tag was approved through :pep:`599`.
+- November 2019: The ``manylinux_x_y`` perennial tag was approved through
+  :pep:`600`.
diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 92811958b..1580b3772 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -441,8 +441,12 @@ the subtable ``tool.$NAME`` if, and only if, they own the entry for
 History
 =======
 
-This specification was originally defined in :pep:`518` (``[build-system]``
-and ``[tool]`` tables) and :pep:`621` (``[project]`` table).
+- May 2016: The initial specification of the ``pyproject.toml`` file, with just
+  a ``[build-system]`` containing a ``requires`` key and a ``[tool]`` table, was
+  approved through :pep:`518`.
+
+- November 2020: The specification of the ``[project]`` table was approved
+  through :pep:`621`.
 
 
 
diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst
index ca8d5f0d5..957e4f36a 100644
--- a/source/specifications/recording-installed-packages.rst
+++ b/source/specifications/recording-installed-packages.rst
@@ -19,22 +19,6 @@ files in a format specific to Python tooling, it should still record the name
 and version of the installed project.
 
 
-History and change workflow
-===========================
-
-The metadata described here was first specified in :pep:`376`, and later
-amended in :pep:`627` (and other PEPs).
-It was formerly known as *Database of Installed Python Distributions*.
-As with other PyPA specifications, editorial amendments with no functional
-impact may be made through the GitHub pull request workflow. Proposals for
-functional changes that would require amendments to package building and/or
-installation tools must be made through the PEP process (see :pep:`1`).
-
-While this document is the normative specification, the PEPs that introduce
-changes to it may include additional information such as rationales and
-backwards compatibility considerations.
-
-
 The .dist-info directory
 ========================
 
@@ -262,3 +246,16 @@ ensuring both locations appear on the default Python import path).
 In some circumstances, it may be desirable to block even installation of
 additional packages via Python-specific tools. For these cases refer to
 :ref:`externally-managed-environments`
+
+
+History
+=======
+
+- June 2009: The original version of this specification was approved through
+  :pep:`376`.  At the time, it was known as the *Database of Installed Python
+  Distributions*.
+- March 2020: The specification of the ``direct_url.json`` file was approved
+  through :pep:`610`. It is only mentioned on this page; see :ref:`direct-url`
+  for the full definition.
+- September 2020: Various amendments and clarifications were approved through
+  :pep:`627`.
diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst
index 55737dc07..bae618df1 100644
--- a/source/specifications/source-distribution-format.rst
+++ b/source/specifications/source-distribution-format.rst
@@ -143,8 +143,10 @@ verification* in ``tarfile`` documentation apply to their tool.
 History
 =======
 
-* August 2023: Standardized the source distribution archive features (:pep:`721`)
-* September 2022: Standardized the filename of a source distribution (:pep:`625`)
-* July 2021: Defined what a source tree is
-* November 2020: :pep:`643` converted to this specification
-* December 2000: Source distributions standardized in :pep:`643`
+* November 2020: The original version of this specification was approved through
+  :pep:`643`.
+* July 2021: Defined what a source tree is.
+* September 2022: The filename of a source distribution was standardized through
+  :pep:`625`.
+* August 2023: Source distribution archive features were standardized through
+  :pep:`721`.
diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index 202031758..8129fd53d 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -1261,7 +1261,4 @@ project):
 History
 =======
 
-This specification was originally approved as :pep:`440`,
-addressing several limitations of the previous attempt
-at standardized versioning, as described in :pep:`345`
-and :pep:`386`.
+- August 2014: This specification was approved through :pep:`440`.
diff --git a/source/specifications/virtual-environments.rst b/source/specifications/virtual-environments.rst
index 77c8c3627..6c8eee530 100644
--- a/source/specifications/virtual-environments.rst
+++ b/source/specifications/virtual-environments.rst
@@ -48,3 +48,9 @@ Even in the absence of a ``pyvenv.cfg`` file, any approach (e.g.
 ``sys.prefix`` and ``sys.base_prefix`` having different values, while still
 providing a matching default package installation scheme in ``sysconfig``, will
 be detected and behave as a Python virtual environment.
+
+
+History
+=======
+
+- May 2012: This specification was approved through :pep:`405`.

From ce62b3abbb6770bd4dfd4e0f4e64f79d0821a45e Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Fri, 22 Dec 2023 16:54:02 +0100
Subject: [PATCH 267/733] Increase number of linkcheck retries

We're getting frequent flaky CI failures due to the huge number of links
that have to be checked, making the check sensitive to random connection
errors.
---
 source/conf.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/source/conf.py b/source/conf.py
index 0e3a93d5e..6daeba245 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -108,6 +108,7 @@
     # https://github.com/pypa/packaging.python.org/pull/1308#issuecomment-1775347690
     "https://www.breezy-vcs.org/*",
 ]
+linkcheck_retries = 5
 
 # -- Options for extlinks ----------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html#configuration

From 74e6ac8b980c5a2f399af31bde2c22022395a373 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Fri, 22 Dec 2023 22:14:06 +0100
Subject: [PATCH 268/733] Give exact glibc versions for legacy manylinux tags

---
 source/specifications/platform-compatibility-tags.rst | 11 ++++-------
 1 file changed, 4 insertions(+), 7 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 391845950..208ecde1f 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -117,13 +117,10 @@ of ``sysconfig.get_platform()`` on the system as in the "simple" form above.
 
 The following older tags are still supported for backward compatibility:
 
-* ``manylinux1`` is based on a compatible Linux platform from 2007,
-  and supports ``x86_64`` and ``i686`` architectures.
-* ``manylinux2010`` is based on a platform from 2010 and supports ``x86_64``
-  and ``i686``.
-* ``manylinux2014`` is based on a platform from 2014 and supports
-  ``x86_64``, ``i686``, ``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``,
-  and ``s390x``.
+* ``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures.
+* ``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``.
+* ``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``,
+  ``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``.
 
 In general, distributions built for older versions of the specification are
 forwards-compatible (meaning that ``manylinux1`` distributions should continue

From 2341590e1c1475dd43ee9989c91c7f88979fb911 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 23 Dec 2023 00:02:26 +0100
Subject: [PATCH 269/733] Address @pradyunsg's review

---
 source/specifications/core-metadata.rst      |  3 ++-
 source/specifications/name-normalization.rst | 18 +++++++++---------
 2 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 6b5efd13a..5248c7122 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -76,7 +76,8 @@ Name
    Added restrictions on format from the :ref:`name grammar `.
 
 The name of the distribution. The name field is the primary identifier for a
-distribution. It must conform to the :ref:`package name grammar `.
+distribution. It must conform to the :ref:`name format specification
+`.
 
 Example::
 
diff --git a/source/specifications/name-normalization.rst b/source/specifications/name-normalization.rst
index fb6d22a09..227b9692c 100644
--- a/source/specifications/name-normalization.rst
+++ b/source/specifications/name-normalization.rst
@@ -1,16 +1,16 @@
-======================================
-Package name grammar and normalization
-======================================
+=======================
+Names and normalization
+=======================
 
-Project names obey a restricted format, and are "normalized" for use in various
-contexts. This document describes what the valid project names are, and how
-project names should be normalized.
+This specification defines the format that names for packages and extras are
+required to follow. It also describes how to normalize them, which should be
+done before lookups and comparisons.
 
 
-.. _name-grammar:
+.. _name-format:
 
-Name grammar
-============
+Name format
+===========
 
 A valid name consists only of ASCII letters and numbers, period,
 underscore and hyphen. It must start and end with a letter or number.

From 1ca542eeabe5538849a6045620e08afb6251c634 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 23 Dec 2023 00:05:07 +0100
Subject: [PATCH 270/733] Fix missing label update

---
 source/specifications/core-metadata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 5248c7122..1040c2c5d 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -73,7 +73,7 @@ Name
 
 .. versionadded:: 1.0
 .. versionchanged:: 2.1
-   Added restrictions on format from the :ref:`name grammar `.
+   Added restrictions on format from the :ref:`name format `.
 
 The name of the distribution. The name field is the primary identifier for a
 distribution. It must conform to the :ref:`name format specification

From 99beaa9b751d932df323a9144c228bf85fd10dca Mon Sep 17 00:00:00 2001
From: Rafael Fontenelle 
Date: Sat, 23 Dec 2023 00:15:49 -0300
Subject: [PATCH 271/733] Add problem matcher for test-translations.yml

---
 .github/sphinx_lint_matcher.json        | 15 +++++++++++++++
 .github/workflows/test-translations.yml |  9 +++++++--
 2 files changed, 22 insertions(+), 2 deletions(-)
 create mode 100644 .github/sphinx_lint_matcher.json

diff --git a/.github/sphinx_lint_matcher.json b/.github/sphinx_lint_matcher.json
new file mode 100644
index 000000000..41896d8f1
--- /dev/null
+++ b/.github/sphinx_lint_matcher.json
@@ -0,0 +1,15 @@
+{
+    "problemMatcher": [
+        {
+            "owner": "sphinx-lint-problem-matcher",
+            "pattern": [
+                {
+                    "regexp": "^(.*):(\\d+):\\s+(.*)$",
+                    "file": 1,
+                    "line": 2,
+                    "message": 3
+                }
+            ]
+        }
+    ]
+}
diff --git a/.github/workflows/test-translations.yml b/.github/workflows/test-translations.yml
index 50f2dd067..d6feddac0 100644
--- a/.github/workflows/test-translations.yml
+++ b/.github/workflows/test-translations.yml
@@ -58,7 +58,7 @@ jobs:
         ref: ${{ env.I18N_BRANCH }}
 
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: >-
           3.10
@@ -66,8 +66,13 @@ jobs:
     - name: Install Python tooling
       run: python -m pip install --upgrade nox virtualenv sphinx-lint
 
+    - name: Set Sphinx problem matcher
+      uses: sphinx-doc/github-problem-matcher@master
+
     - name: Build translated docs in ${{ matrix.language }}
       run: nox -s build -- -q -D language=${{ matrix.language }}
 
     - name: Lint translation file
-      run: sphinx-lint locales/${{ matrix.language }}/LC_MESSAGES/messages.po
+      run: |
+        echo '::add-matcher::.github/sphinx_lint_matcher.json'
+        sphinx-lint locales/${{ matrix.language }}/LC_MESSAGES/messages.po

From 10430a101c20725f96b2bb94ee4f78317885efbf Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 25 Dec 2023 18:33:07 +0000
Subject: [PATCH 272/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.1.8 → v0.1.9](https://github.com/astral-sh/ruff-pre-commit/compare/v0.1.8...v0.1.9)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 20eeadb57..baba00ea3 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.8
+  rev: v0.1.9
   hooks:
     - id: ruff
     - id: ruff-format

From 92759ce47302a9a6be09d157967eff7684e5021f Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko 
Date: Sun, 31 Dec 2023 18:34:42 +0100
Subject: [PATCH 273/733] Revert "Merge pull request #1436 from jeanas/gh-ci"

This partially reverts commit 9cd20c6c756b1b2c22ecab93e4cdb0c50bd15885,
reversing changes made to 45c22c2f33063c505f2f61895904b29127161a8a.
---
 .github/workflows/test.yml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 7645d7fcc..581b644ca 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -47,9 +47,7 @@ jobs:
     # This job does nothing and is only used for the branch protection
     # or multi-stage CI jobs, like making sure that all tests pass before
     # a publishing job is started.
-    if: >-
-      github.repository_owner == 'pypa'
-      || github.event_name != 'schedule'
+    if: always()
 
     needs:
     - build

From 617f04be2d66496d584349e51d1171559e8e34d8 Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko 
Date: Sun, 31 Dec 2023 18:36:43 +0100
Subject: [PATCH 274/733] =?UTF-8?q?=F0=9F=A7=AA=F0=9F=94=A7=20Move=20cron?=
 =?UTF-8?q?=20trigger=20to=20separate=20GHA=20workflow?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/cron.yml | 14 ++++++++++++++
 .github/workflows/test.yml |  3 +--
 2 files changed, 15 insertions(+), 2 deletions(-)
 create mode 100644 .github/workflows/cron.yml

diff --git a/.github/workflows/cron.yml b/.github/workflows/cron.yml
new file mode 100644
index 000000000..8870bb70b
--- /dev/null
+++ b/.github/workflows/cron.yml
@@ -0,0 +1,14 @@
+---
+
+name: Cron
+
+on:
+  schedule:
+  - cron: "0 6 * * *"  # daily at 6am
+
+jobs:
+  test:
+    if: github.repository_owner == 'pypa'  # suppress noise in forks
+    uses: ./.github/workflows/test.yml
+
+...
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 581b644ca..8503ca720 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -6,8 +6,7 @@ on:
     branches-ignore:
     - gh-readonly-queue/**  # Temporary merge queue-related GH-made branches
   pull_request:
-  schedule:
-    - cron: "0 6 * * *" # daily at 6am
+  workflow_call:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}

From 86eb51d6662362cbbf0c2dd70b26a9587977cf41 Mon Sep 17 00:00:00 2001
From: Rafael Fontenelle 
Date: Wed, 3 Jan 2024 10:11:00 -0300
Subject: [PATCH 275/733] Pin github-problem-matcher version to v1.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 .github/workflows/test-translations.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test-translations.yml b/.github/workflows/test-translations.yml
index d6feddac0..5a61b431b 100644
--- a/.github/workflows/test-translations.yml
+++ b/.github/workflows/test-translations.yml
@@ -67,7 +67,7 @@ jobs:
       run: python -m pip install --upgrade nox virtualenv sphinx-lint
 
     - name: Set Sphinx problem matcher
-      uses: sphinx-doc/github-problem-matcher@master
+      uses: sphinx-doc/github-problem-matcher@v1.0
 
     - name: Build translated docs in ${{ matrix.language }}
       run: nox -s build -- -q -D language=${{ matrix.language }}

From 0145ba51be2b610acfc1408beb97f02b53fca7f7 Mon Sep 17 00:00:00 2001
From: Rafael Fontenelle 
Date: Wed, 3 Jan 2024 10:24:54 -0300
Subject: [PATCH 276/733] Split steps for add-matcher and lint commands

---
 .github/workflows/test-translations.yml | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/test-translations.yml b/.github/workflows/test-translations.yml
index 5a61b431b..45dc60aa3 100644
--- a/.github/workflows/test-translations.yml
+++ b/.github/workflows/test-translations.yml
@@ -72,7 +72,10 @@ jobs:
     - name: Build translated docs in ${{ matrix.language }}
       run: nox -s build -- -q -D language=${{ matrix.language }}
 
+    - name: Set Sphinx Lint problem matcher
+      if: always()
+      run: echo '::add-matcher::.github/sphinx_lint_matcher.json'
+
     - name: Lint translation file
-      run: |
-        echo '::add-matcher::.github/sphinx_lint_matcher.json'
-        sphinx-lint locales/${{ matrix.language }}/LC_MESSAGES/messages.po
+      if: always()
+      run: sphinx-lint locales/${{ matrix.language }}/LC_MESSAGES/messages.po

From a3d3a813baf1c88126525e52696b3a97155c451c Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Thu, 4 Jan 2024 11:21:44 -0800
Subject: [PATCH 277/733] Remove the explicit list of PaaS platforms

It can be misconstrued as an endorsement and we can't keep up w/ all PaaS platforms which support Python to make the list comprehensive/impartial.
---
 source/overview.rst | 20 ++++++--------------
 1 file changed, 6 insertions(+), 14 deletions(-)

diff --git a/source/overview.rst b/source/overview.rst
index 3627e8122..8c68036a7 100644
--- a/source/overview.rst
+++ b/source/overview.rst
@@ -195,20 +195,12 @@ hood, you can always read the sections beyond.
 Service platforms
 *****************
 
-If you're developing for a "Platform-as-a-Service" or "PaaS" like
-Heroku or Google App Engine, you are going to want to follow their
-respective packaging guides.
-
-* `Heroku `_
-* `Google App Engine `_
-* `PythonAnywhere `_
-* `OpenShift `_
-* "Serverless" frameworks like :gh:`Zappa `
-
-In all these setups, the platform takes care of packaging and
-deployment, as long as you follow their patterns. Most software does
-not fit one of these templates, hence the existence of all the other
-options below.
+If you're developing for a
+"`Platform-as-a-Service `_"
+or "PaaS", you are going to want to follow their respective packaging
+guides. These types of platforms take care of packaging and deployment,
+as long as you follow their patterns. Most software does not fit one of
+these templates, hence the existence of all the other options below.
 
 If you're developing software that will be deployed to machines you
 own, users' personal computers, or any other arrangement, read on.

From c84d3a62d27a30c251a61e20043c105774eab55b Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 14 Jan 2024 13:36:11 +0100
Subject: [PATCH 278/733] Fix linkcheck

Apparently, GitHub now adds the README HTML on a project page
dynamically through JS, which prevents Sphinx's link checker from
finding anchors into the README.
---
 source/conf.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/source/conf.py b/source/conf.py
index 6daeba245..315aa8c52 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -109,6 +109,12 @@
     "https://www.breezy-vcs.org/*",
 ]
 linkcheck_retries = 5
+# Ignore anchors for links to GitHub project pages -- GitHub adds anchors from
+# README.md headings through JavaScript, so Sphinx's linkcheck can't find them
+# in the HTML.
+linkcheck_anchors_ignore_for_url = [
+    r"https://github\.com/",
+]
 
 # -- Options for extlinks ----------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html#configuration

From c730a82dd1df1911ed17f519c4ca934ff568cecb Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 13 Jan 2024 22:56:27 +0100
Subject: [PATCH 279/733] Update inline script metadata spec with latest PEP
 723 changes

---
 .../specifications/inline-script-metadata.rst | 56 +++++++------------
 1 file changed, 19 insertions(+), 37 deletions(-)

diff --git a/source/specifications/inline-script-metadata.rst b/source/specifications/inline-script-metadata.rst
index f18f4f17e..ad667e94a 100644
--- a/source/specifications/inline-script-metadata.rst
+++ b/source/specifications/inline-script-metadata.rst
@@ -2,13 +2,6 @@
 Inline script metadata
 ======================
 
-.. warning::
-   This specification has been **provisionally accepted**. It is subject
-   to being changed or abandoned. See the
-   `PEP 723 conditional acceptance thread `_ for details.
-
-.. _pep723-thread: https://discuss.python.org/t/36763
-
 This specification defines a metadata format that can be embedded in single-file
 Python scripts to assist launchers, IDEs and other external tools which may need
 to interact with such scripts.
@@ -73,20 +66,22 @@ In circumstances where there is a discrepancy between the text specification
 and the regular expression, the text specification takes precedence.
 
 Tools MUST NOT read from metadata blocks with types that have not been
-standardized by this PEP or future ones.
+standardized by this specification.
 
-pyproject type
---------------
+script type
+-----------
 
-The first type of metadata block is named ``pyproject`` which represents
-content similar to what one would see in a ``pyproject.toml`` file.
+The first type of metadata block is named ``script`` which contains
+script metadata (dependency data and tool configuration).
 
-This document MAY include the ``[run]`` and ``[tool]`` tables.
+This document MAY include top-level fields ``dependencies`` and ``requires-python``,
+and MAY optionally include a ``[tool]`` table.
 
-The :ref:`tool table ` MAY be used by any tool,
-script runner or otherwise, to configure behavior.
+The ``[tool]`` MAY be used by any tool, script runner or otherwise, to configure
+behavior. It has the same semantics as the :ref:`[tool] table in pyproject.toml
+`
 
-The ``[run]`` table MAY include the following optional fields:
+The top-level fields are:
 
 * ``dependencies``: A list of strings that specifies the runtime dependencies
   of the script. Each entry MUST be a valid
@@ -107,11 +102,11 @@ Script runners SHOULD error if no version of Python that satisfies the specified
 Example
 -------
 
-The following is an example of a script with an embedded ``pyproject.toml``:
+The following is an example of a script with embedded metadata:
 
 .. code:: python
 
-    # /// pyproject
+    # /// script
     # [run]
     # requires-python = ">=3.11"
     # dependencies = [
@@ -127,23 +122,6 @@ The following is an example of a script with an embedded ``pyproject.toml``:
     data = resp.json()
     pprint([(k, v["title"]) for k, v in data.items()][:10])
 
-The following is an example of a proposed syntax for single-file Rust
-projects that embeds their equivalent of ``pyproject.toml``, which is called
-``Cargo.toml``:
-
-.. code:: rust
-
-    #!/usr/bin/env cargo
-
-    //! ```cargo
-    //! [dependencies]
-    //! regex = "1.8.0"
-    //! ```
-
-    fn main() {
-        let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
-        println!("Did our date match? {}", re.is_match("2014-01-01"));
-    }
 
 Reference Implementation
 ========================
@@ -159,7 +137,7 @@ higher.
    REGEX = r'(?m)^# /// (?P[a-zA-Z0-9-]+)$\s(?P(^#(| .*)$\s)+)^# ///$'
 
    def read(script: str) -> dict | None:
-       name = 'pyproject'
+       name = 'script'
        matches = list(
            filter(lambda m: m.group('type') == name, re.finditer(REGEX, script))
        )
@@ -196,7 +174,7 @@ __ https://tomlkit.readthedocs.io/en/latest/
        )
 
        config = tomlkit.parse(content)
-       config['project']['dependencies'].append(dependency)
+       config['dependencies'].append(dependency)
        new_content = ''.join(
            f'# {line}' if line.strip() else f'#{line}'
            for line in tomlkit.dumps(config).splitlines(keepends=True)
@@ -239,3 +217,7 @@ History
 =======
 
 - October 2023: This specification was conditionally approved through :pep:`723`.
+- January 2024: Through amendments to :pep:`723`, the ``pyproject`` metadata
+  block type was renamed to ``script``, and the ``[run]`` table was dropped,
+  making the ``dependencies`` and ``requires-python`` keys
+  top-level. Additionally, the specification is no longer provisional.

From b33317c71c997f134ee31c56be6de7706f63236e Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sun, 14 Jan 2024 13:20:20 +0100
Subject: [PATCH 280/733] Fixes

---
 source/specifications/inline-script-metadata.rst | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/source/specifications/inline-script-metadata.rst b/source/specifications/inline-script-metadata.rst
index ad667e94a..dee1c2634 100644
--- a/source/specifications/inline-script-metadata.rst
+++ b/source/specifications/inline-script-metadata.rst
@@ -90,11 +90,6 @@ The top-level fields are:
   the script is compatible. The value of this field MUST be a valid
   :ref:`version specifier `.
 
-Any future specifications that define additional fields for the ``[run]`` table
-when used in a ``pyproject.toml`` file MUST include the aforementioned fields
-exactly as specified. The fields defined by this specification are equally as
-applicable to full-fledged projects as they are to single-file scripts.
-
 Script runners MUST error if the specified ``dependencies`` cannot be provided.
 Script runners SHOULD error if no version of Python that satisfies the specified
 ``requires-python`` can be provided.
@@ -107,7 +102,6 @@ The following is an example of a script with embedded metadata:
 .. code:: python
 
     # /// script
-    # [run]
     # requires-python = ">=3.11"
     # dependencies = [
     #   "requests<3",

From 4a83dbac2a8c8fe80b4d53340b0beafe9887515b Mon Sep 17 00:00:00 2001
From: Laurie O 
Date: Tue, 2 Jan 2024 11:02:01 +1000
Subject: [PATCH 281/733] Add simple repo API specs from PEPs

---
 .../specifications/simple-repository-api.rst  | 917 ++++++++++++++++++
 1 file changed, 917 insertions(+)

diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
index 70c0040d2..14644fa27 100644
--- a/source/specifications/simple-repository-api.rst
+++ b/source/specifications/simple-repository-api.rst
@@ -18,3 +18,920 @@ providing package metadata independently from a package in
 The JSON format is defined in :pep:`691`, with additional fields
 added in :pep:`700`, and revisions around providing package metadata
 independently from a package in :pep:`714`.
+
+Base HTML API
+=============
+
+A repository that implements the simple API is defined by its base URL, this is
+the top level URL that all additional URLs are below. The API is named the
+"simple" repository due to the fact that PyPI's base URL is
+``https://pypi.org/simple/``.
+
+.. note:: All subsequent URLs in this document will be relative to this base
+          URL (so given PyPI's URL, a URL of ``/foo/`` would be
+          ``https://pypi.org/simple/foo/``.
+
+
+Within a repository, the root URL (``/`` for this PEP which represents the base
+URL) **MUST** be a valid HTML5 page with a single anchor element per project in
+the repository. The text of the anchor tag **MUST** be the name of
+the project and the href attribute **MUST** link to the URL for that particular
+project. As an example::
+
+   
+   
+     
+       frob
+       spamspamspam
+     
+   
+
+Below the root URL is another URL for each individual project contained within
+a repository. The format of this URL is ``//`` where the ````
+is replaced by the normalized name for that project, so a project named
+"HolyGrail" would have a URL like ``/holygrail/``. This URL must respond with
+a valid HTML5 page with a single anchor element per file for the project. The
+href attribute **MUST** be a URL that links to the location of the file for
+download, and the text of the anchor tag **MUST** match the final path
+component (the filename) of the URL. The URL **SHOULD** include a hash in the
+form of a URL fragment with the following syntax: ``#=``,
+where ```` is the lowercase name of the hash function (such as
+``sha256``) and ```` is the hex encoded digest.
+
+In addition to the above, the following constraints are placed on the API:
+
+* All URLs which respond with an HTML5 page **MUST** end with a ``/`` and the
+  repository **SHOULD** redirect the URLs without a ``/`` to add a ``/`` to the
+  end.
+
+* URLs may be either absolute or relative as long as they point to the correct
+  location.
+
+* There are no constraints on where the files must be hosted relative to the
+  repository.
+
+* There may be any other HTML elements on the API pages as long as the required
+  anchor elements exist.
+
+* Repositories **MAY** redirect unnormalized URLs to the canonical normalized
+  URL (e.g. ``/Foobar/`` may redirect to ``/foobar/``), however clients
+  **MUST NOT** rely on this redirection and **MUST** request the normalized
+  URL.
+
+* Repositories **SHOULD** choose a hash function from one of the ones
+  guaranteed to be available via the ``hashlib`` module in the Python standard
+  library (currently ``md5``, ``sha1``, ``sha224``, ``sha256``, ``sha384``,
+  ``sha512``). The current recommendation is to use ``sha256``.
+
+* If there is a GPG signature for a particular distribution file it **MUST**
+  live alongside that file with the same name with a ``.asc`` appended to it.
+  So if the file ``/packages/HolyGrail-1.0.tar.gz`` existed and had an
+  associated signature, the signature would be located at
+  ``/packages/HolyGrail-1.0.tar.gz.asc``.
+
+* A repository **MAY** include a ``data-gpg-sig`` attribute on a file link with
+  a value of either ``true`` or ``false`` to indicate whether or not there is a
+  GPG signature. Repositories that do this **SHOULD** include it on every link.
+
+* A repository **MAY** include a ``data-requires-python`` attribute on a file
+  link. This exposes the *Requires-Python* metadata field, specified in :pep:`345`,
+  for the corresponding release. Where this is present, installer tools
+  **SHOULD** ignore the download when installing to a Python version that
+  doesn't satisfy the requirement. For example::
+
+      ...
+
+  In the attribute value, < and > have to be HTML encoded as ``<`` and
+  ``>``, respectively.
+
+Normalized Names
+----------------
+
+This PEP references the concept of a "normalized" project name. As per :pep:`426`
+the only valid characters in a name are the ASCII alphabet, ASCII numbers,
+``.``, ``-``, and ``_``. The name should be lowercased with all runs of the
+characters ``.``, ``-``, or ``_`` replaced with a single ``-`` character. This
+can be implemented in Python with the ``re`` module::
+
+   import re
+
+   def normalize(name):
+       return re.sub(r"[-_.]+", "-", name).lower()
+
+Adding "Yank" Support to the Simple API
+=======================================
+
+Links in the simple repository **MAY** have a ``data-yanked`` attribute
+which may have no value, or may have an arbitrary string as a value. The
+presence of a ``data-yanked`` attribute **SHOULD** be interpreted as
+indicating that the file pointed to by this particular link has been
+"Yanked", and should not generally be selected by an installer, except
+under specific scenarios.
+
+The value of the ``data-yanked`` attribute, if present, is an arbitrary
+string that represents the reason for why the file has been yanked. Tools
+that process the simple repository API **MAY** surface this string to
+end users.
+
+The yanked attribute is not immutable once set, and may be rescinded in
+the future (and once rescinded, may be reset as well). Thus API users
+**MUST** be able to cope with a yanked file being "unyanked" (and even
+yanked again).
+
+
+Installers
+----------
+
+The desirable experience for users is that once a file is yanked, when
+a human being is currently trying to directly install a yanked file, that
+it fails as if that file had been deleted. However, when a human did that
+awhile ago, and now a computer is just continuing to mechanically follow
+the original order to install the now yanked file, then it acts as if it
+had not been yanked.
+
+An installer **MUST** ignore yanked releases, if the selection constraints
+can be satisfied with a non-yanked version, and **MAY** refuse to use a
+yanked release even if it means that the request cannot be satisfied at all.
+An implementation **SHOULD** choose a policy that follows the spirit of the
+intention above, and that prevents "new" dependencies on yanked
+releases/files.
+
+What this means is left up to the specific installer, to decide how to best
+fit into the overall usage of their installer. However, there are two
+suggested approaches to take:
+
+1. Yanked files are always ignored, unless they are the only file that
+   matches a version specifier that "pins" to an exact version using
+   either ``==`` (without any modifiers that make it a range, such as
+   ``.*``) or ``===``. Matching this version specifier should otherwise
+   be done as per :pep:`440` for things like local versions, zero padding,
+   etc.
+2. Yanked files are always ignored, unless they are the only file that
+   matches what a lock file (such as ``Pipfile.lock`` or ``poetry.lock``)
+   specifies to be installed. In this case, a yanked file **SHOULD** not
+   be used when creating or updating a lock file from some input file or
+   command.
+
+Regardless of the specific strategy that an installer chooses for deciding
+when to install yanked files, an installer **SHOULD** emit a warning when
+it does decide to install a yanked file. That warning **MAY** utilize the
+value of the ``data-yanked`` attribute (if it has a value) to provide more
+specific feedback to the user about why that file had been yanked.
+
+
+Mirrors
+-------
+
+Mirrors can generally treat yanked files one of two ways:
+
+1. They may choose to omit them from their simple repository API completely,
+   providing a view over the repository that shows only "active", unyanked
+   files.
+2. They may choose to include yanked files, and additionally mirror the
+   ``data-yanked`` attribute as well.
+
+Mirrors **MUST NOT** mirror a yanked file without also mirroring the
+``data-yanked`` attribute for it.
+
+Versioning PyPI's Simple API
+============================
+
+This PEP proposes the inclusion of a meta tag on the responses of every
+successful request to a simple API page, which contains a name attribute
+of "pypi:repository-version", and a content that is a :pep:`440` compatible
+version number, which is further constrained to ONLY be Major.Minor, and
+none of the additional features supported by :pep:`440`.
+
+This would end up looking like::
+
+  
+
+When interpreting the repository version:
+
+* Incrementing the major version is used to signal a backwards
+  incompatible change such that existing clients would no longer be
+  expected to be able to meaningfully use the API.
+* Incrementing the minor version is used to signal a backwards
+  compatible change such that existing clients would still be
+  expected to be able to meaningfully use the API.
+
+It is left up to the discretion of any future PEPs as to what
+specifically constitutes a backwards incompatible vs compatible change
+beyond the broad suggestion that existing clients will be able to
+"meaningfully" continue to use the API, and can include adding,
+modifying, or removing existing features.
+
+It is expectation of this PEP that the major version will never be
+incremented, and any future major API evolutions would utilize a
+different mechanism for API evolution. However the major version
+is included to disambiguate with future versions (e.g. a hypothetical
+simple api v2 that lived at /v2/, but which would be confusing if the
+repository-version was set to a version >= 2).
+
+This PEP sets the current API version to "1.0", and expects that
+future PEPs that further evolve the simple API will increment the
+minor version number.
+
+
+Clients
+-------
+
+Clients interacting with the simple API **SHOULD** introspect each
+response for the repository version, and if that data does not exist
+**MUST** assume that it is version 1.0.
+
+When encountering a major version greater than expected, clients
+**MUST** hard fail with an appropriate error message for the user.
+
+When encountering a minor version greater than expected, clients
+**SHOULD** warn users with an appropriate message.
+
+Clients **MAY** still continue to use feature detection in order to
+determine what features a repository uses.
+
+Serve Distribution Metadata in the Simple Repository API
+========================================================
+
+In a simple repository's project page, each anchor tag pointing to a
+distribution **MAY** have a ``data-dist-info-metadata`` attribute. The
+presence of the attribute indicates the distribution represented by
+the anchor tag **MUST** contain a Core Metadata file that will not be
+modified when the distribution is processed and/or installed.
+
+If a ``data-dist-info-metadata`` attribute is present, the repository
+**MUST** serve the distribution's Core Metadata file alongside the
+distribution with a ``.metadata`` appended to the distribution's file
+name. For example, the Core Metadata of a distribution served at
+``/files/distribution-1.0-py3.none.any.whl`` would be located at
+``/files/distribution-1.0-py3.none.any.whl.metadata``. This is similar
+to how :pep:`503` specifies the GPG signature file's location.
+
+The repository **SHOULD** provide the hash of the Core Metadata file
+as the ``data-dist-info-metadata`` attribute's value using the syntax
+``=``, where ```` is the lower cased
+name of the hash function used, and ```` is the hex encoded
+digest. The repository **MAY** use ``true`` as the attribute's value
+if a hash is unavailable.
+
+Backwards Compatibility
+-----------------------
+
+If an anchor tag lacks the ``data-dist-info-metadata`` attribute,
+tools are expected to revert to their current behaviour of downloading
+the distribution to inspect the metadata.
+
+Older tools not supporting the new ``data-dist-info-metadata``
+attribute are expected to ignore the attribute and maintain their
+current behaviour of downloading the distribution to inspect the
+metadata. This is similar to how prior ``data-`` attribute additions
+expect existing tools to operate.
+
+JSON-based Simple API for Python Package Indexes
+================================================
+
+To enable response parsing with only the standard library, this PEP specifies that
+all responses (besides the files themselves, and the HTML responses from
+:pep:`503`) should be serialized using `JSON `_.
+
+To enable zero configuration discovery and to minimize the amount of additional HTTP
+requests, this PEP extends :pep:`503` such that all of the API endpoints (other than the
+files themselves) will utilize HTTP content negotiation to allow client and server to
+select the correct serialization format to serve, i.e. either HTML or JSON.
+
+
+Versioning
+----------
+
+Versioning will adhere to :pep:`629` format (``Major.Minor``), which has defined the
+existing HTML responses to be ``1.0``. Since this PEP does not introduce new features
+into the API, rather it describes a different serialization format for the existing
+features, this PEP does not change the existing ``1.0`` version, and instead just
+describes how to serialize that into JSON.
+
+Similar to :pep:`629`, the major version number **MUST** be incremented if any
+changes to the new format would result in no longer being able to expect existing
+clients to meaningfully understand the format.
+
+Likewise, the minor version **MUST** be incremented if features are
+added or removed from the format, but existing clients would be expected to continue
+to meaningfully understand the format.
+
+Changes that would not result in existing clients being unable to meaningfully
+understand the format and which do not represent features being added or removed
+may occur without changing the version number.
+
+This is intentionally vague, as this PEP believes it is best left up to future PEPs
+that make any changes to the API to investigate and decide whether or not that
+change should increment the major or minor version.
+
+Future versions of the API may add things that can only be represented in a subset
+of the available serializations of that version. All serializations version numbers,
+within a major version, **SHOULD** be kept in sync, but the specifics of how a
+feature serializes into each format may differ, including whether or not that feature
+is present at all.
+
+It is the intent of this PEP that the API should be thought of as URL endpoints that
+return data, whose interpretation is defined by the version of that data, and then
+serialized into the target serialization format.
+
+
+.. _json-serialization:
+
+JSON Serialization
+------------------
+
+The URL structure from :pep:`503` still applies, as this PEP only adds an additional
+serialization format for the already existing API.
+
+The following constraints apply to all JSON serialized responses described in this
+PEP:
+
+* All JSON responses will *always* be a JSON object rather than an array or other
+  type.
+
+* While JSON doesn't natively support an URL type, any value that represents an
+  URL in this API may be either absolute or relative as long as they point to
+  the correct location. If relative, they are relative to the current URL as if
+  it were HTML.
+
+* Additional keys may be added to any dictionary objects in the API responses
+  and clients **MUST** ignore keys that they don't understand.
+
+* All JSON responses will have a ``meta`` key, which contains information related to
+  the response itself, rather than the content of the response.
+
+* All JSON responses will have a ``meta.api-version`` key, which will be a string that
+  contains the :pep:`629` ``Major.Minor`` version number, with the same fail/warn
+  semantics as defined in :pep:`629`.
+
+* All requirements of :pep:`503` that are not HTML specific still apply.
+
+
+Project List
+~~~~~~~~~~~~
+
+The root URL ``/`` for this PEP (which represents the base URL) will be a JSON encoded
+dictionary which has a two keys:
+
+- ``projects``: An array where each entry is a dictionary with a single key, ``name``, which represents string of the project name.
+- ``meta``: The general response metadata as `described earlier `__.
+
+As an example:
+
+.. code-block:: json
+
+    {
+      "meta": {
+        "api-version": "1.0"
+      },
+      "projects": [
+        {"name": "Frob"},
+        {"name": "spamspamspam"}
+      ]
+    }
+
+
+.. note::
+
+  The ``name`` field is the same as the one from :pep:`503`, which does not specify
+  whether it is the non-normalized display name or the normalized name. In practice
+  different implementations of these PEPs are choosing differently here, so relying
+  on it being either non-normalized or normalized is relying on an implementation
+  detail of the repository in question.
+
+
+.. note::
+
+  While the ``projects`` key is an array, and thus is required to be in some kind
+  of an order, neither :pep:`503` nor this PEP requires any specific ordering nor
+  that the ordering is consistent from one request to the next. Mentally this is
+  best thought of as a set, but both JSON and HTML lack the functionality to have
+  sets.
+
+
+Project Detail
+~~~~~~~~~~~~~~
+
+The format of this URL is ``//`` where the ```` is replaced by the
+:pep:`503` normalized name for that project, so a project named "Silly_Walk" would
+have a URL like ``/silly-walk/``.
+
+This URL must respond with a JSON encoded dictionary that has three keys:
+
+- ``name``: The normalized name of the project.
+- ``files``: A list of dictionaries, each one representing an individual file.
+- ``meta``: The general response metadata as `described earlier `__.
+
+Each individual file dictionary has the following keys:
+
+- ``filename``: The filename that is being represented.
+- ``url``: The URL that the file can be fetched from.
+- ``hashes``: A dictionary mapping a hash name to a hex encoded digest of the file.
+  Multiple hashes can be included, and it is up to the client to decide what to do
+  with multiple hashes (it may validate all of them or a subset of them, or nothing
+  at all). These hash names **SHOULD** always be normalized to be lowercase.
+
+  The ``hashes`` dictionary **MUST** be present, even if no hashes are available
+  for the file, however it is **HIGHLY** recommended that at least one secure,
+  guaranteed-to-be-available hash is always included.
+
+  By default, any hash algorithm available via `hashlib
+  `_ (specifically any that can
+  be passed to ``hashlib.new()`` and do not require additional parameters) can
+  be used as a key for the hashes dictionary. At least one secure algorithm from
+  ``hashlib.algorithms_guaranteed`` **SHOULD** always be included. At the time
+  of this PEP, ``sha256`` specifically is recommended.
+- ``requires-python``: An **optional** key that exposes the *Requires-Python*
+  metadata field, specified in :pep:`345`. Where this is present, installer tools
+  **SHOULD** ignore the download when installing to a Python version that
+  doesn't satisfy the requirement.
+
+  Unlike ``data-requires-python`` in :pep:`503`, the ``requires-python`` key does not
+  require any special escaping other than anything JSON does naturally.
+- ``dist-info-metadata``: An **optional** key that indicates
+  that metadata for this file is available, via the same location as specified in
+  :pep:`658` (``{file_url}.metadata``). Where this is present, it **MUST** be
+  either a boolean to indicate if the file has an associated metadata file, or a
+  dictionary mapping hash names to a hex encoded digest of the metadata's hash.
+
+  When this is a dictionary of hashes instead of a boolean, then all the same
+  requirements and recommendations as the ``hashes`` key hold true for this key as
+  well.
+
+  If this key is missing then the metadata file may or may not exist. If the key
+  value is truthy, then the metadata file is present, and if it is falsey then it
+  is not.
+
+  It is recommended that servers make the hashes of the metadata file available if
+  possible.
+- ``gpg-sig``: An **optional** key that acts a boolean to indicate if the file has
+  an associated GPG signature or not. The URL for the signature file follows what
+  is specified in :pep:`503` (``{file_url}.asc``). If this key does not exist, then
+  the signature may or may not exist.
+- ``yanked``: An **optional** key which may be either a boolean to indicate if the
+  file has been yanked, or a non empty, but otherwise arbitrary, string to indicate
+  that a file has been yanked with a specific reason. If the ``yanked`` key is present
+  and is a truthy value, then it **SHOULD** be interpreted as indicating that the
+  file pointed to by the ``url`` field has been "Yanked" as per :pep:`592`.
+
+As an example:
+
+.. code-block:: json
+
+    {
+      "meta": {
+        "api-version": "1.0"
+      },
+      "name": "holygrail",
+      "files": [
+        {
+          "filename": "holygrail-1.0.tar.gz",
+          "url": "https://example.com/files/holygrail-1.0.tar.gz",
+          "hashes": {"sha256": "...", "blake2b": "..."},
+          "requires-python": ">=3.7",
+          "yanked": "Had a vulnerability"
+        },
+        {
+          "filename": "holygrail-1.0-py3-none-any.whl",
+          "url": "https://example.com/files/holygrail-1.0-py3-none-any.whl",
+          "hashes": {"sha256": "...", "blake2b": "..."},
+          "requires-python": ">=3.7",
+          "dist-info-metadata": true
+        }
+      ]
+    }
+
+
+.. note::
+
+  While the ``files`` key is an array, and thus is required to be in some kind
+  of an order, neither :pep:`503` nor this PEP requires any specific ordering nor
+  that the ordering is consistent from one request to the next. Mentally this is
+  best thought of as a set, but both JSON and HTML lack the functionality to have
+  sets.
+
+
+Content-Types
+-------------
+
+This PEP proposes that all responses from the Simple API will have a standard
+content type that describes what the response is (a Simple API response), what
+version of the API it represents, and what serialization format has been used.
+
+The structure of this content type will be:
+
+.. code-block:: text
+
+    application/vnd.pypi.simple.$version+format
+
+Since only major versions should be disruptive to clients attempting to
+understand one of these API responses, only the major version will be included
+in the content type, and will be prefixed with a ``v`` to clarify that it is a
+version number.
+
+Which means that for the existing 1.0 API, the content types would be:
+
+- **JSON:** ``application/vnd.pypi.simple.v1+json``
+- **HTML:** ``application/vnd.pypi.simple.v1+html``
+
+In addition to the above, a special "meta" version is supported named ``latest``,
+whose purpose is to allow clients to request the absolute latest version, without
+having to know ahead of time what that version is. It is recommended however,
+that clients be explicit about what versions they support.
+
+To support existing clients which expect the existing :pep:`503` API responses to
+use the ``text/html`` content type, this PEP further defines ``text/html`` as an alias
+for the ``application/vnd.pypi.simple.v1+html`` content type.
+
+
+Version + Format Selection
+--------------------------
+
+Now that there is multiple possible serializations, we need a mechanism to allow
+clients to indicate what serialization formats they're able to understand. In
+addition, it would be beneficial if any possible new major version to the API can
+be added without disrupting existing clients expecting the previous API version.
+
+To enable this, this PEP standardizes on the use of HTTP's
+`Server-Driven Content Negotiation `_.
+
+While this PEP won't fully describe the entirety of server-driven content
+negotiation, the flow is roughly:
+
+1. The client makes an HTTP request containing an ``Accept`` header listing all
+   of the version+format content types that they are able to understand.
+2. The server inspects that header, selects one of the listed content types,
+   then returns a response using that content type (treating the absence of
+   an ``Accept`` header as ``Accept: */*``).
+3. If the server does not support any of the content types in the ``Accept``
+   header then they are able to choose between 3 different options for how to
+   respond:
+
+   a. Select a default content type other than what the client has requested
+      and return a response with that.
+   b. Return a HTTP ``406 Not Acceptable`` response to indicate that none of
+      the requested content types were available, and the server was unable
+      or unwilling to select a default content type to respond with.
+   c. Return a HTTP ``300 Multiple Choices`` response that contains a list of
+      all of the possible responses that could have been chosen.
+4. The client interprets the response, handling the different types of responses
+   that the server may have responded with.
+
+This PEP does not specify which choices the server makes in regards to handling
+a content type that it isn't able to return, and clients **SHOULD** be prepared
+to handle all of the possible responses in whatever way makes the most sense for
+that client.
+
+However, as there is no standard format for how a ``300 Multiple Choices``
+response can be interpreted, this PEP highly discourages servers from utilizing
+that option, as clients will have no way to understand and select a different
+content-type to request. In addition, it's unlikely that the client *could*
+understand a different content type anyways, so at best this response would
+likely just be treated the same as a ``406 Not Acceptable`` error.
+
+This PEP **does** require that if the meta version ``latest`` is being used, the
+server **MUST** respond with the content type for the actual version that is
+contained in the response
+(i.e. A ``Accept: application/vnd.pypi.simple.latest+json`` request that returns
+a ``v1.x`` response should have a ``Content-Type`` of
+``application/vnd.pypi.simple.v1+json``).
+
+The ``Accept`` header is a comma separated list of content types that the client
+understands and is able to process. It supports three different formats for each
+content type that is being requested:
+
+- ``$type/$subtype``
+- ``$type/*``
+- ``*/*``
+
+For the use of selecting a version+format, the most useful of these is
+``$type/$subtype``, as that is the only way to actually specify the version
+and format you want.
+
+The order of the content types listed in the ``Accept`` header does not have any
+specific meaning, and the server **SHOULD** consider all of them to be equally
+valid to respond with. If a client wishes to specify that they prefer a specific
+content type over another, they may use the ``Accept`` header's
+`quality value `_
+syntax.
+
+This allows a client to specify a priority for a specific entry in their
+``Accept`` header, by appending a ``;q=`` followed by a value between ``0`` and
+``1`` inclusive, with up to 3 decimal digits. When interpreting this value,
+an entry with a higher quality has priority over an entry with a lower quality,
+and any entry without a quality present will default to a quality of ``1``.
+
+However, clients should keep in mind that a server is free to select **any** of
+the content types they've asked for, regardless of their requested priority, and
+it may even return a content type that they did **not** ask for.
+
+To aid clients in determining the content type of the response that they have
+received from an API request, this PEP requires that servers always include a
+``Content-Type`` header indicating the content type of the response. This is
+technically a backwards incompatible change, however in practice
+`pip has been enforcing this requirement `_
+so the risks for actual breakages is low.
+
+An example of how a client can operate would look like:
+
+.. code-block:: python
+
+    import email.message
+    import requests
+
+    def parse_content_type(header: str) -> str:
+        m = email.message.Message()
+        m["content-type"] = header
+        return m.get_content_type()
+
+    # Construct our list of acceptable content types, we want to prefer
+    # that we get a v1 response serialized using JSON, however we also
+    # can support a v1 response serialized using HTML. For compatibility
+    # we also request text/html, but we prefer it least of all since we
+    # don't know if it's actually a Simple API response, or just some
+    # random HTML page that we've gotten due to a misconfiguration.
+    CONTENT_TYPES = [
+        "application/vnd.pypi.simple.v1+json",
+        "application/vnd.pypi.simple.v1+html;q=0.2",
+        "text/html;q=0.01",  # For legacy compatibility
+    ]
+    ACCEPT = ", ".join(CONTENT_TYPES)
+
+
+    # Actually make our request to the API, requesting all of the content
+    # types that we find acceptable, and letting the server select one of
+    # them out of the list.
+    resp = requests.get("https://pypi.org/simple/", headers={"Accept": ACCEPT})
+
+    # If the server does not support any of the content types you requested,
+    # AND it has chosen to return a HTTP 406 error instead of a default
+    # response then this will raise an exception for the 406 error.
+    resp.raise_for_status()
+
+
+    # Determine what kind of response we've gotten to ensure that it is one
+    # that we can support, and if it is, dispatch to a function that will
+    # understand how to interpret that particular version+serialization. If
+    # we don't understand the content type we've gotten, then we'll raise
+    # an exception.
+    content_type = parse_content_type(resp.headers.get("content-type", ""))
+    match content_type:
+        case "application/vnd.pypi.simple.v1+json":
+            handle_v1_json(resp)
+        case "application/vnd.pypi.simple.v1+html" | "text/html":
+            handle_v1_html(resp)
+        case _:
+            raise Exception(f"Unknown content type: {content_type}")
+
+If a client wishes to only support HTML or only support JSON, then they would
+just remove the content types that they do not want from the ``Accept`` header,
+and turn receiving them into an error.
+
+
+Alternative Negotiation Mechanisms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While using HTTP's Content negotiation is considered the standard way for a client
+and server to coordinate to ensure that the client is getting an HTTP response that
+it is able to understand, there are situations where that mechanism may not be
+sufficient. For those cases this PEP has alternative negotiation mechanisms that
+may *optionally* be used instead.
+
+
+URL Parameter
+^^^^^^^^^^^^^
+
+Servers that implement the Simple API may choose to support an URL parameter named
+``format`` to allow the clients to request a specific version of the URL.
+
+The value of the ``format`` parameter should be **one** of the valid content types.
+Passing multiple content types, wild cards, quality values, etc... is **not**
+supported.
+
+Supporting this parameter is optional, and clients **SHOULD NOT** rely on it for
+interacting with the API. This negotiation mechanism is intended to allow for easier
+human based exploration of the API within a browser, or to allow documentation or
+notes to link to a specific version+format.
+
+Servers that do not support this parameter may choose to return an error when it is
+present, or they may simple ignore its presence.
+
+When a server does implement this parameter, it **SHOULD** take precedence over any
+values in the client's ``Accept`` header, and if the server does not support the
+requested format, it may choose to fall back to the ``Accept`` header, or choose any
+of the error conditions that standard server-driven content negotiation typically
+has (e.g. ``406 Not Available``, ``303 Multiple Choices``, or selecting a default
+type to return).
+
+
+Endpoint Configuration
+^^^^^^^^^^^^^^^^^^^^^^
+
+This option technically is not a special option at all, it is just a natural
+consequence of using content negotiation and allowing servers to select which of the
+available content types is their default.
+
+If a server is unwilling or unable to implement the server-driven content negotiation,
+and would instead rather require users to explicitly configure their client to select
+the version they want, then that is a supported configuration.
+
+To enable this, a server should make multiple endpoints (for instance,
+``/simple/v1+html/`` and/or ``/simple/v1+json/``) for each version+format that they
+wish to support. Under that endpoint, they can host a copy of their repository that
+only supports one (or a subset) of the content-types. When a client makes a request
+using the ``Accept`` header, the server can ignore it and return the content type
+that corresponds to that endpoint.
+
+For clients that wish to require specific configuration, they can keep track of
+which version+format a specific repository URL was configured for, and when making
+a request to that server, emit an ``Accept`` header that *only* includes the correct
+content type.
+
+
+TUF Support - PEP 458
+---------------------
+
+:pep:`458` requires that all API responses are hashable and that they can be uniquely
+identified by a path relative to the repository root. For a Simple API repository, the
+target path is the Root of our API (e.g. ``/simple/`` on PyPI). This creates
+challenges when accessing the API using a TUF client instead of directly using a
+standard HTTP client, as the TUF client cannot handle the fact that a target could
+have multiple different representations that all hash differently.
+
+:pep:`458` does not specify what the target path should be for the Simple API, but
+TUF requires that the target paths be "file-like", in other words, a path like
+``simple/PROJECT/`` is not acceptable, because it technically points to a
+directory.
+
+The saving grace is that the target path does not *have* to actually match the URL
+being fetched from the Simple API, and it can just be a sigil that the fetching code
+knows how to transform into the actual URL that needs to be fetched. This same thing
+can hold true for other aspects of the actual HTTP request, such as the ``Accept``
+header.
+
+Ultimately figuring out how to map a directory to a filename is out of scope for this
+PEP (but it would be in scope for :pep:`458`), and this PEP defers making a decision
+about how exactly to represent this inside of :pep:`458` metadata.
+
+However, it appears that the current WIP branch against pip that attempts to implement
+:pep:`458` is using a target path like ``simple/PROJECT/index.html``. This could be
+modified to include the API version and serialization format using something like
+``simple/PROJECT/vnd.pypi.simple.vN.FORMAT``. So the v1 HTML format would be
+``simple/PROJECT/vnd.pypi.simple.v1.html`` and the v1 JSON format would be
+``simple/PROJECT/vnd.pypi.simple.v1.json``.
+
+In this case, since ``text/html`` is an alias to ``application/vnd.pypi.simple.v1+html``
+when interacting through TUF, it likely will make the most sense to normalize to the
+more explicit name.
+
+Likewise the ``latest`` metaversion should not be included in the targets, only
+explicitly declared versions should be supported.
+
+Recommendations
+---------------
+
+This section is non-normative, and represents what the PEP authors believe to be
+the best default implementation decisions for something implementing this PEP, but
+it does **not** represent any sort of requirement to match these decisions.
+
+These decisions have been chosen to maximize the number of requests that can be
+moved onto the newest version of an API, while maintaining the greatest amount
+of compatibility. In addition, they've also tried to make using the API provide
+guardrails that attempt to push clients into making the best choices it can.
+
+It is recommended that servers:
+
+- Support all 3 content types described in this PEP, using server-driven
+  content negotiation, for as long as they reasonably can, or at least as
+  long as they're receiving non trivial traffic that uses the HTML responses.
+
+- When encountering an ``Accept`` header that does not contain any content types
+  that it knows how to work with, the server should not ever return a
+  ``300 Multiple Choice`` response, and instead return a ``406 Not Acceptable``
+  response.
+
+  - However, if choosing to use the endpoint configuration, you should prefer to
+    return a ``200 OK`` response in the expected content type for that endpoint.
+
+- When selecting an acceptable version, the server should choose the highest version
+  that the client supports, with the most expressive/featureful serialization format,
+  taking into account the specificity of the client requests as well as any
+  quality priority values they have expressed, and it should only use the
+  ``text/html`` content type as a last resort.
+
+It is recommended that clients:
+
+- Support all 3 content types described in this PEP, using server-driven
+  content negotiation, for as long as they reasonably can.
+
+- When constructing an ``Accept`` header, include all of the content types
+  that you support.
+
+  You should generally *not* include a quality priority value for your content
+  types, unless you have implementation specific reasons that you want the
+  server to take into account (for example, if you're using the standard library
+  HTML parser and you're worried that there may be some kinds of HTML responses
+  that you're unable to parse in some edge cases).
+
+  The one exception to this recommendation is that it is recommended that you
+  *should* include a ``;q=0.01`` value on the legacy ``text/html`` content type,
+  unless it is the only content type that you are requesting.
+
+- Explicitly select what versions they are looking for, rather than using the
+  ``latest`` meta version during normal operation.
+
+- Check the ``Content-Type`` of the response and ensure it matches something
+  that you were expecting.
+
+Additional Fields for the Simple API for Package Indexes
+========================================================
+
+This specification defines version 1.1 of the simple repository API. For the
+HTML version of the API, there is no change from version 1.0. For the JSON
+version of the API, the following changes are made:
+
+- The ``api-version`` must specify version 1.1 or later.
+- A new ``versions`` key is added at the top level.
+- Two new "file information" keys, ``size`` and ``upload-time``, are added to
+  the ``files`` data.
+- Keys (at any level) with a leading underscore are reserved as private for
+  index server use. No future standard will assign a meaning to any such key.
+
+The ``versions`` and ``size`` keys are mandatory. The ``upload-time`` key is
+optional.
+
+Versions
+--------
+
+An additional key, ``versions`` MUST be present at the top level, in addition to
+the keys ``name``, ``files`` and ``meta`` defined in :pep:`691`. This key MUST
+contain a list of version strings specifying all of the project versions uploaded
+for this project. The value is logically a set, and as such may not contain
+duplicates, and the order of the values is not significant.
+
+All of the files listed in the ``files`` key MUST be associated with one of the
+versions in the ``versions`` key. The ``versions`` key MAY contain versions with
+no associated files (to represent versions with no files uploaded, if the server
+has such a concept).
+
+Note that because servers may hold "legacy" data from before the adoption of
+:pep:`440`, version strings currently cannot be required to be valid :pep:`440`
+versions, and therefore cannot be assumed to be orderable using the :pep:`440`
+rules. However, servers SHOULD use normalised :pep:`440` versions where
+possible.
+
+
+Additional file information
+---------------------------
+
+Two new keys are added to the ``files`` key.
+
+- ``size``: This field is mandatory. It MUST contain an integer which is the
+  file size in bytes.
+- ``upload-time``: This field is optional. If present, it MUST contain a valid
+  ISO 8601 date/time string, in the format ``yyyy-mm-ddThh:mm:ss.ffffffZ``,
+  which represents the time the file was uploaded to the index. As indicated by
+  the ``Z`` suffix, the upload time MUST use the UTC timezone. The fractional
+  seconds part of the timestamp (the ``.ffffff`` part) is optional, and if
+  present may contain up to 6 digits of precision. If a server does not record
+  upload time information for a file, it MAY omit the ``upload-time`` key.
+
+Rename dist-info-metadata in the Simple API
+===========================================
+
+
+The keywords "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**",
+"**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**MAY**",
+and "**OPTIONAL**"" in this document are to be interpreted as described in
+:rfc:`RFC 2119 <2119>`.
+
+
+Servers
+-------
+
+The :pep:`658` metadata, when used in the HTML representation of the Simple API,
+**MUST** be emitted using the attribute name ``data-core-metadata``, with the
+supported values remaining the same.
+
+The :pep:`658` metadata, when used in the :pep:`691` JSON representation of the
+Simple API, **MUST** be emitted using the key ``core-metadata``, with the
+supported values remaining the same.
+
+To support clients that used the previous key names, the HTML representation
+**MAY** also be emitted using the ``data-dist-info-metadata``, and if it does
+so it **MUST** match the value of ``data-core-metadata``.
+
+
+
+Clients
+-------
+
+Clients consuming any of the HTML representations of the Simple API **MUST**
+read the :pep:`658` metadata from the key ``data-core-metadata`` if it is
+present. They **MAY** optionally use the legacy ``data-dist-info-metadata`` if
+it is present but ``data-core-metadata`` is not.
+
+Clients consuming the JSON representation of the Simple API **MUST** read the
+:pep:`658` metadata from the key ``core-metadata`` if it is present. They
+**MAY** optionally use the legacy ``dist-info-metadata`` key if it is present
+but ``core-metadata`` is not.

From 301b99f2ecf547628829bfd61f46f016696659b5 Mon Sep 17 00:00:00 2001
From: Laurie O 
Date: Tue, 2 Jan 2024 11:02:54 +1000
Subject: [PATCH 282/733] Convert simple repo API spec history to list

---
 .../specifications/simple-repository-api.rst  | 27 ++++++++++++-------
 1 file changed, 17 insertions(+), 10 deletions(-)

diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
index 14644fa27..e3bd344a8 100644
--- a/source/specifications/simple-repository-api.rst
+++ b/source/specifications/simple-repository-api.rst
@@ -9,16 +9,6 @@ The interface for querying available package versions and
 retrieving packages from an index server comes in two forms:
 HTML and JSON.
 
-The HTML format is defined in :pep:`503`, with the addition of "yank"
-support (allowing a kind of file deletion) in :pep:`592`, specifying
-the interface version provided by an index server in :pep:`629`, and
-providing package metadata independently from a package in
-:pep:`658` and revised in :pep:`714`.
-
-The JSON format is defined in :pep:`691`, with additional fields
-added in :pep:`700`, and revisions around providing package metadata
-independently from a package in :pep:`714`.
-
 Base HTML API
 =============
 
@@ -935,3 +925,20 @@ Clients consuming the JSON representation of the Simple API **MUST** read the
 :pep:`658` metadata from the key ``core-metadata`` if it is present. They
 **MAY** optionally use the legacy ``dist-info-metadata`` key if it is present
 but ``core-metadata`` is not.
+
+History
+=======
+
+* September 2015: initial form of the HTML format, in :pep:`503`
+* July 2016: Requires-Python metadata, in an update to :pep:`503`
+* May 2019: "yank" support, in :pep:`592`
+* July 2020: API versioning convention and metadata, and declaring the HTML
+  format as API v1, in :pep:`629`
+* May 2021: providing package metadata independently from a package, in
+  :pep:`658`
+* May 2022: initial form of the JSON format, with a mechanism for clients to
+  choose between them, and declaring both formats as API v1, in :pep:`691`
+* October 2022: project versions and file size and upload-time in the JSON
+  format, in :pep:`700`
+* June 2023: renaming the field which provides package metadata independently
+  from a package, in :pep:`714`

From 0ad7a84808640599a4ed55f031855c6abfbb3997 Mon Sep 17 00:00:00 2001
From: Laurie O 
Date: Tue, 2 Jan 2024 11:52:50 +1000
Subject: [PATCH 283/733] Replace PEP references in simple repo API spec

---
 .../specifications/simple-repository-api.rst  | 169 +++++++++++-------
 1 file changed, 107 insertions(+), 62 deletions(-)

diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
index e3bd344a8..702e587ad 100644
--- a/source/specifications/simple-repository-api.rst
+++ b/source/specifications/simple-repository-api.rst
@@ -9,6 +9,8 @@ The interface for querying available package versions and
 retrieving packages from an index server comes in two forms:
 HTML and JSON.
 
+.. _simple-repository-api-base:
+
 Base HTML API
 =============
 
@@ -22,7 +24,7 @@ the top level URL that all additional URLs are below. The API is named the
           ``https://pypi.org/simple/foo/``.
 
 
-Within a repository, the root URL (``/`` for this PEP which represents the base
+Within a repository, the root URL (``/`` for this spec which represents the base
 URL) **MUST** be a valid HTML5 page with a single anchor element per project in
 the repository. The text of the anchor tag **MUST** be the name of
 the project and the href attribute **MUST** link to the URL for that particular
@@ -84,7 +86,7 @@ In addition to the above, the following constraints are placed on the API:
   GPG signature. Repositories that do this **SHOULD** include it on every link.
 
 * A repository **MAY** include a ``data-requires-python`` attribute on a file
-  link. This exposes the *Requires-Python* metadata field, specified in :pep:`345`,
+  link. This exposes the :ref:`core-metadata-requires-python` metadata field
   for the corresponding release. Where this is present, installer tools
   **SHOULD** ignore the download when installing to a Python version that
   doesn't satisfy the requirement. For example::
@@ -97,7 +99,8 @@ In addition to the above, the following constraints are placed on the API:
 Normalized Names
 ----------------
 
-This PEP references the concept of a "normalized" project name. As per :pep:`426`
+This spec references the concept of a "normalized" project name. As per
+:ref:`the name normalization specification `
 the only valid characters in a name are the ASCII alphabet, ASCII numbers,
 ``.``, ``-``, and ``_``. The name should be lowercased with all runs of the
 characters ``.``, ``-``, or ``_`` replaced with a single ``-`` character. This
@@ -108,6 +111,8 @@ can be implemented in Python with the ``re`` module::
    def normalize(name):
        return re.sub(r"[-_.]+", "-", name).lower()
 
+.. _simple-repository-api-yank:
+
 Adding "Yank" Support to the Simple API
 =======================================
 
@@ -154,7 +159,8 @@ suggested approaches to take:
    matches a version specifier that "pins" to an exact version using
    either ``==`` (without any modifiers that make it a range, such as
    ``.*``) or ``===``. Matching this version specifier should otherwise
-   be done as per :pep:`440` for things like local versions, zero padding,
+   be done as per :ref:`the version specifiers specification
+   ` for things like local versions, zero padding,
    etc.
 2. Yanked files are always ignored, unless they are the only file that
    matches what a lock file (such as ``Pipfile.lock`` or ``poetry.lock``)
@@ -183,14 +189,18 @@ Mirrors can generally treat yanked files one of two ways:
 Mirrors **MUST NOT** mirror a yanked file without also mirroring the
 ``data-yanked`` attribute for it.
 
+.. _simple-repository-api-versioning:
+
 Versioning PyPI's Simple API
 ============================
 
-This PEP proposes the inclusion of a meta tag on the responses of every
+This spec proposes the inclusion of a meta tag on the responses of every
 successful request to a simple API page, which contains a name attribute
-of "pypi:repository-version", and a content that is a :pep:`440` compatible
+of "pypi:repository-version", and a content that is a :ref:`version specifiers
+specification ` compatible
 version number, which is further constrained to ONLY be Major.Minor, and
-none of the additional features supported by :pep:`440`.
+none of the additional features supported by :ref:`the version specifiers
+specification `.
 
 This would end up looking like::
 
@@ -205,21 +215,21 @@ When interpreting the repository version:
   compatible change such that existing clients would still be
   expected to be able to meaningfully use the API.
 
-It is left up to the discretion of any future PEPs as to what
+It is left up to the discretion of any future specs as to what
 specifically constitutes a backwards incompatible vs compatible change
 beyond the broad suggestion that existing clients will be able to
 "meaningfully" continue to use the API, and can include adding,
 modifying, or removing existing features.
 
-It is expectation of this PEP that the major version will never be
+It is expectation of this spec that the major version will never be
 incremented, and any future major API evolutions would utilize a
 different mechanism for API evolution. However the major version
 is included to disambiguate with future versions (e.g. a hypothetical
 simple api v2 that lived at /v2/, but which would be confusing if the
 repository-version was set to a version >= 2).
 
-This PEP sets the current API version to "1.0", and expects that
-future PEPs that further evolve the simple API will increment the
+This spec sets the current API version to "1.0", and expects that
+future specs that further evolve the simple API will increment the
 minor version number.
 
 
@@ -239,6 +249,8 @@ When encountering a minor version greater than expected, clients
 Clients **MAY** still continue to use feature detection in order to
 determine what features a repository uses.
 
+.. _simple-repository-api-metadata-file:
+
 Serve Distribution Metadata in the Simple Repository API
 ========================================================
 
@@ -254,7 +266,8 @@ distribution with a ``.metadata`` appended to the distribution's file
 name. For example, the Core Metadata of a distribution served at
 ``/files/distribution-1.0-py3.none.any.whl`` would be located at
 ``/files/distribution-1.0-py3.none.any.whl.metadata``. This is similar
-to how :pep:`503` specifies the GPG signature file's location.
+to how :ref:`the base HTML API specification `
+specifies the GPG signature file's location.
 
 The repository **SHOULD** provide the hash of the Core Metadata file
 as the ``data-dist-info-metadata`` attribute's value using the syntax
@@ -276,15 +289,19 @@ current behaviour of downloading the distribution to inspect the
 metadata. This is similar to how prior ``data-`` attribute additions
 expect existing tools to operate.
 
+.. _simple-repository-api-json:
+
 JSON-based Simple API for Python Package Indexes
 ================================================
 
-To enable response parsing with only the standard library, this PEP specifies that
+To enable response parsing with only the standard library, this spec specifies that
 all responses (besides the files themselves, and the HTML responses from
-:pep:`503`) should be serialized using `JSON `_.
+:ref:`the base HTML API specification `) should be
+serialized using `JSON `_.
 
 To enable zero configuration discovery and to minimize the amount of additional HTTP
-requests, this PEP extends :pep:`503` such that all of the API endpoints (other than the
+requests, this spec extends :ref:`the base HTML API specification
+` such that all of the API endpoints (other than the
 files themselves) will utilize HTTP content negotiation to allow client and server to
 select the correct serialization format to serve, i.e. either HTML or JSON.
 
@@ -292,13 +309,16 @@ select the correct serialization format to serve, i.e. either HTML or JSON.
 Versioning
 ----------
 
-Versioning will adhere to :pep:`629` format (``Major.Minor``), which has defined the
-existing HTML responses to be ``1.0``. Since this PEP does not introduce new features
+Versioning will adhere to :ref:`the API versioning specification
+` format (``Major.Minor``), which has defined the
+existing HTML responses to be ``1.0``. Since this spec does not introduce new features
 into the API, rather it describes a different serialization format for the existing
-features, this PEP does not change the existing ``1.0`` version, and instead just
+features, this spec does not change the existing ``1.0`` version, and instead just
 describes how to serialize that into JSON.
 
-Similar to :pep:`629`, the major version number **MUST** be incremented if any
+Similar to :ref:`the API versioning specification
+`, the major version number **MUST** be
+incremented if any
 changes to the new format would result in no longer being able to expect existing
 clients to meaningfully understand the format.
 
@@ -310,7 +330,7 @@ Changes that would not result in existing clients being unable to meaningfully
 understand the format and which do not represent features being added or removed
 may occur without changing the version number.
 
-This is intentionally vague, as this PEP believes it is best left up to future PEPs
+This is intentionally vague, as this spec believes it is best left up to future specs
 that make any changes to the API to investigate and decide whether or not that
 change should increment the major or minor version.
 
@@ -320,7 +340,7 @@ within a major version, **SHOULD** be kept in sync, but the specifics of how a
 feature serializes into each format may differ, including whether or not that feature
 is present at all.
 
-It is the intent of this PEP that the API should be thought of as URL endpoints that
+It is the intent of this spec that the API should be thought of as URL endpoints that
 return data, whose interpretation is defined by the version of that data, and then
 serialized into the target serialization format.
 
@@ -330,11 +350,12 @@ serialized into the target serialization format.
 JSON Serialization
 ------------------
 
-The URL structure from :pep:`503` still applies, as this PEP only adds an additional
+The URL structure from :ref:`the base HTML API specification
+` still applies, as this spec only adds an additional
 serialization format for the already existing API.
 
 The following constraints apply to all JSON serialized responses described in this
-PEP:
+spec:
 
 * All JSON responses will *always* be a JSON object rather than an array or other
   type.
@@ -351,16 +372,19 @@ PEP:
   the response itself, rather than the content of the response.
 
 * All JSON responses will have a ``meta.api-version`` key, which will be a string that
-  contains the :pep:`629` ``Major.Minor`` version number, with the same fail/warn
-  semantics as defined in :pep:`629`.
+  contains the :ref:`API versioning specification
+  ` ``Major.Minor`` version number, with the
+  same fail/warn semantics as defined in :ref:`the API versioning specification
+  `.
 
-* All requirements of :pep:`503` that are not HTML specific still apply.
+* All requirements of :ref:`the base HTML API specification
+  ` that are not HTML specific still apply.
 
 
 Project List
 ~~~~~~~~~~~~
 
-The root URL ``/`` for this PEP (which represents the base URL) will be a JSON encoded
+The root URL ``/`` for this spec (which represents the base URL) will be a JSON encoded
 dictionary which has a two keys:
 
 - ``projects``: An array where each entry is a dictionary with a single key, ``name``, which represents string of the project name.
@@ -383,9 +407,10 @@ As an example:
 
 .. note::
 
-  The ``name`` field is the same as the one from :pep:`503`, which does not specify
+  The ``name`` field is the same as the one from :ref:`the base HTML API
+  specification `, which does not specify
   whether it is the non-normalized display name or the normalized name. In practice
-  different implementations of these PEPs are choosing differently here, so relying
+  different implementations of these specs are choosing differently here, so relying
   on it being either non-normalized or normalized is relying on an implementation
   detail of the repository in question.
 
@@ -393,7 +418,8 @@ As an example:
 .. note::
 
   While the ``projects`` key is an array, and thus is required to be in some kind
-  of an order, neither :pep:`503` nor this PEP requires any specific ordering nor
+  of an order, neither :ref:`the base HTML API specification
+  ` nor this spec requires any specific ordering nor
   that the ordering is consistent from one request to the next. Mentally this is
   best thought of as a set, but both JSON and HTML lack the functionality to have
   sets.
@@ -403,7 +429,8 @@ Project Detail
 ~~~~~~~~~~~~~~
 
 The format of this URL is ``//`` where the ```` is replaced by the
-:pep:`503` normalized name for that project, so a project named "Silly_Walk" would
+:ref:`the base HTML API specification ` normalized
+name for that project, so a project named "Silly_Walk" would
 have a URL like ``/silly-walk/``.
 
 This URL must respond with a JSON encoded dictionary that has three keys:
@@ -430,17 +457,21 @@ Each individual file dictionary has the following keys:
   be passed to ``hashlib.new()`` and do not require additional parameters) can
   be used as a key for the hashes dictionary. At least one secure algorithm from
   ``hashlib.algorithms_guaranteed`` **SHOULD** always be included. At the time
-  of this PEP, ``sha256`` specifically is recommended.
-- ``requires-python``: An **optional** key that exposes the *Requires-Python*
-  metadata field, specified in :pep:`345`. Where this is present, installer tools
+  of this spec, ``sha256`` specifically is recommended.
+- ``requires-python``: An **optional** key that exposes the
+  :ref:`core-metadata-requires-python`
+  metadata field. Where this is present, installer tools
   **SHOULD** ignore the download when installing to a Python version that
   doesn't satisfy the requirement.
 
-  Unlike ``data-requires-python`` in :pep:`503`, the ``requires-python`` key does not
+  Unlike ``data-requires-python`` in :ref:`the base HTML API specification
+  `, the ``requires-python`` key does not
   require any special escaping other than anything JSON does naturally.
 - ``dist-info-metadata``: An **optional** key that indicates
   that metadata for this file is available, via the same location as specified in
-  :pep:`658` (``{file_url}.metadata``). Where this is present, it **MUST** be
+  :ref:`the API metadata file specification
+  ` (``{file_url}.metadata``). Where this
+  is present, it **MUST** be
   either a boolean to indicate if the file has an associated metadata file, or a
   dictionary mapping hash names to a hex encoded digest of the metadata's hash.
 
@@ -456,13 +487,15 @@ Each individual file dictionary has the following keys:
   possible.
 - ``gpg-sig``: An **optional** key that acts a boolean to indicate if the file has
   an associated GPG signature or not. The URL for the signature file follows what
-  is specified in :pep:`503` (``{file_url}.asc``). If this key does not exist, then
+  is specified in :ref:`the base HTML API specification
+  ` (``{file_url}.asc``). If this key does not exist, then
   the signature may or may not exist.
 - ``yanked``: An **optional** key which may be either a boolean to indicate if the
   file has been yanked, or a non empty, but otherwise arbitrary, string to indicate
   that a file has been yanked with a specific reason. If the ``yanked`` key is present
   and is a truthy value, then it **SHOULD** be interpreted as indicating that the
-  file pointed to by the ``url`` field has been "Yanked" as per :pep:`592`.
+  file pointed to by the ``url`` field has been "Yanked" as per :ref:`the API
+  yank specification `.
 
 As an example:
 
@@ -495,7 +528,8 @@ As an example:
 .. note::
 
   While the ``files`` key is an array, and thus is required to be in some kind
-  of an order, neither :pep:`503` nor this PEP requires any specific ordering nor
+  of an order, neither :ref:`the base HTML API specification
+  ` nor this spec requires any specific ordering nor
   that the ordering is consistent from one request to the next. Mentally this is
   best thought of as a set, but both JSON and HTML lack the functionality to have
   sets.
@@ -504,7 +538,7 @@ As an example:
 Content-Types
 -------------
 
-This PEP proposes that all responses from the Simple API will have a standard
+This spec proposes that all responses from the Simple API will have a standard
 content type that describes what the response is (a Simple API response), what
 version of the API it represents, and what serialization format has been used.
 
@@ -529,8 +563,9 @@ whose purpose is to allow clients to request the absolute latest version, withou
 having to know ahead of time what that version is. It is recommended however,
 that clients be explicit about what versions they support.
 
-To support existing clients which expect the existing :pep:`503` API responses to
-use the ``text/html`` content type, this PEP further defines ``text/html`` as an alias
+To support existing clients which expect the existing :ref:`the base HTML API
+specification ` API responses to
+use the ``text/html`` content type, this spec further defines ``text/html`` as an alias
 for the ``application/vnd.pypi.simple.v1+html`` content type.
 
 
@@ -542,10 +577,10 @@ clients to indicate what serialization formats they're able to understand. In
 addition, it would be beneficial if any possible new major version to the API can
 be added without disrupting existing clients expecting the previous API version.
 
-To enable this, this PEP standardizes on the use of HTTP's
+To enable this, this spec standardizes on the use of HTTP's
 `Server-Driven Content Negotiation `_.
 
-While this PEP won't fully describe the entirety of server-driven content
+While this spec won't fully describe the entirety of server-driven content
 negotiation, the flow is roughly:
 
 1. The client makes an HTTP request containing an ``Accept`` header listing all
@@ -567,19 +602,19 @@ negotiation, the flow is roughly:
 4. The client interprets the response, handling the different types of responses
    that the server may have responded with.
 
-This PEP does not specify which choices the server makes in regards to handling
+This spec does not specify which choices the server makes in regards to handling
 a content type that it isn't able to return, and clients **SHOULD** be prepared
 to handle all of the possible responses in whatever way makes the most sense for
 that client.
 
 However, as there is no standard format for how a ``300 Multiple Choices``
-response can be interpreted, this PEP highly discourages servers from utilizing
+response can be interpreted, this spec highly discourages servers from utilizing
 that option, as clients will have no way to understand and select a different
 content-type to request. In addition, it's unlikely that the client *could*
 understand a different content type anyways, so at best this response would
 likely just be treated the same as a ``406 Not Acceptable`` error.
 
-This PEP **does** require that if the meta version ``latest`` is being used, the
+This spec **does** require that if the meta version ``latest`` is being used, the
 server **MUST** respond with the content type for the actual version that is
 contained in the response
 (i.e. A ``Accept: application/vnd.pypi.simple.latest+json`` request that returns
@@ -616,7 +651,7 @@ the content types they've asked for, regardless of their requested priority, and
 it may even return a content type that they did **not** ask for.
 
 To aid clients in determining the content type of the response that they have
-received from an API request, this PEP requires that servers always include a
+received from an API request, this spec requires that servers always include a
 ``Content-Type`` header indicating the content type of the response. This is
 technically a backwards incompatible change, however in practice
 `pip has been enforcing this requirement `_
@@ -684,7 +719,7 @@ Alternative Negotiation Mechanisms
 While using HTTP's Content negotiation is considered the standard way for a client
 and server to coordinate to ensure that the client is getting an HTTP response that
 it is able to understand, there are situations where that mechanism may not be
-sufficient. For those cases this PEP has alternative negotiation mechanisms that
+sufficient. For those cases this spec has alternative negotiation mechanisms that
 may *optionally* be used instead.
 
 
@@ -760,7 +795,7 @@ can hold true for other aspects of the actual HTTP request, such as the ``Accept
 header.
 
 Ultimately figuring out how to map a directory to a filename is out of scope for this
-PEP (but it would be in scope for :pep:`458`), and this PEP defers making a decision
+spec (but it would be in scope for :pep:`458`), and this spec defers making a decision
 about how exactly to represent this inside of :pep:`458` metadata.
 
 However, it appears that the current WIP branch against pip that attempts to implement
@@ -780,8 +815,8 @@ explicitly declared versions should be supported.
 Recommendations
 ---------------
 
-This section is non-normative, and represents what the PEP authors believe to be
-the best default implementation decisions for something implementing this PEP, but
+This section is non-normative, and represents what the spec authors believe to be
+the best default implementation decisions for something implementing this spec, but
 it does **not** represent any sort of requirement to match these decisions.
 
 These decisions have been chosen to maximize the number of requests that can be
@@ -791,7 +826,7 @@ guardrails that attempt to push clients into making the best choices it can.
 
 It is recommended that servers:
 
-- Support all 3 content types described in this PEP, using server-driven
+- Support all 3 content types described in this spec, using server-driven
   content negotiation, for as long as they reasonably can, or at least as
   long as they're receiving non trivial traffic that uses the HTML responses.
 
@@ -811,7 +846,7 @@ It is recommended that servers:
 
 It is recommended that clients:
 
-- Support all 3 content types described in this PEP, using server-driven
+- Support all 3 content types described in this spec, using server-driven
   content negotiation, for as long as they reasonably can.
 
 - When constructing an ``Accept`` header, include all of the content types
@@ -854,7 +889,8 @@ Versions
 --------
 
 An additional key, ``versions`` MUST be present at the top level, in addition to
-the keys ``name``, ``files`` and ``meta`` defined in :pep:`691`. This key MUST
+the keys ``name``, ``files`` and ``meta`` defined in :ref:`the JSON API
+specification `. This key MUST
 contain a list of version strings specifying all of the project versions uploaded
 for this project. The value is logically a set, and as such may not contain
 duplicates, and the order of the values is not significant.
@@ -865,9 +901,10 @@ no associated files (to represent versions with no files uploaded, if the server
 has such a concept).
 
 Note that because servers may hold "legacy" data from before the adoption of
-:pep:`440`, version strings currently cannot be required to be valid :pep:`440`
-versions, and therefore cannot be assumed to be orderable using the :pep:`440`
-rules. However, servers SHOULD use normalised :pep:`440` versions where
+:ref:`the version specifiers specification (VSS) `, version
+strings currently cannot be required to be valid VSS versions, and therefore
+cannot be assumed to be orderable using the VSS rules. However, servers SHOULD
+use normalised VSS versions where
 possible.
 
 
@@ -899,11 +936,15 @@ and "**OPTIONAL**"" in this document are to be interpreted as described in
 Servers
 -------
 
-The :pep:`658` metadata, when used in the HTML representation of the Simple API,
+The :ref:`the API metadata file specification
+` metadata, when used in the HTML
+representation of the Simple API,
 **MUST** be emitted using the attribute name ``data-core-metadata``, with the
 supported values remaining the same.
 
-The :pep:`658` metadata, when used in the :pep:`691` JSON representation of the
+The :ref:`the API metadata file specification
+` metadata, when used in the :ref:`the
+JSON API specification ` JSON representation of the
 Simple API, **MUST** be emitted using the key ``core-metadata``, with the
 supported values remaining the same.
 
@@ -917,12 +958,16 @@ Clients
 -------
 
 Clients consuming any of the HTML representations of the Simple API **MUST**
-read the :pep:`658` metadata from the key ``data-core-metadata`` if it is
+read the :ref:`the API metadata file specification
+` metadata from the key
+``data-core-metadata`` if it is
 present. They **MAY** optionally use the legacy ``data-dist-info-metadata`` if
 it is present but ``data-core-metadata`` is not.
 
 Clients consuming the JSON representation of the Simple API **MUST** read the
-:pep:`658` metadata from the key ``core-metadata`` if it is present. They
+:ref:`the API metadata file specification
+` metadata from the key ``core-metadata``
+if it is present. They
 **MAY** optionally use the legacy ``dist-info-metadata`` key if it is present
 but ``core-metadata`` is not.
 

From 912579b177c309104563790092d1bac2ff6f38b2 Mon Sep 17 00:00:00 2001
From: John Sirois 
Date: Wed, 17 Jan 2024 14:41:07 -0800
Subject: [PATCH 284/733] Update pex entry.

Pex long ago stopped offering a programmatic API in favor of its CLI
API. I was remiss in not updating this description. Note is made of the
more expansive features Pex and PEX files have grown in the meantime,
including a nod to Pex multi-platform lock support (RIP PEP 665 - you
live on in Pex).
---
 source/key_projects.rst | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 671675641..d6a4ad7e1 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -534,11 +534,14 @@ pex
 `GitHub `__ |
 `PyPI `__
 
-pex is both a library and tool for generating :file:`.pex` (Python EXecutable)
+Pex is a tool for generating :file:`.pex` (Python EXecutable)
 files, standalone Python environments in the spirit of :ref:`virtualenv`.
-:file:`.pex` files are just carefully constructed zip files with a
-``#!/usr/bin/env python`` and special :file:`__main__.py`, and are designed to
-make deployment of Python applications as simple as ``cp``.
+PEX files are zipapps as outlined :pep:`441` that
+make deployment of Python applications as simple as ``cp``. A single PEX
+file can support multiple target platforms and can be created from standard
+:ref:`pip`-resolvable requirements, a lockfile generated with `pex3 lock ...`
+or even another PEX. PEX files can optionally have tools embedded that support
+turning the PEX file into a standard venv, graphing dependencies and more.
 
 .. _pip-tools:
 

From aefbb1359f85e4a181614c0084d0a214e6c7359f Mon Sep 17 00:00:00 2001
From: John Sirois 
Date: Wed, 17 Jan 2024 14:43:23 -0800
Subject: [PATCH 285/733] Fix code ticks for RST.

---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index d6a4ad7e1..55383c06e 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -539,7 +539,7 @@ files, standalone Python environments in the spirit of :ref:`virtualenv`.
 PEX files are zipapps as outlined :pep:`441` that
 make deployment of Python applications as simple as ``cp``. A single PEX
 file can support multiple target platforms and can be created from standard
-:ref:`pip`-resolvable requirements, a lockfile generated with `pex3 lock ...`
+:ref:`pip`-resolvable requirements, a lockfile generated with ``pex3 lock ...``
 or even another PEX. PEX files can optionally have tools embedded that support
 turning the PEX file into a standard venv, graphing dependencies and more.
 

From eed8161c9878160e0a8378111a36a4585cf61abc Mon Sep 17 00:00:00 2001
From: John Sirois 
Date: Thu, 18 Jan 2024 13:20:17 -0800
Subject: [PATCH 286/733] @sinroc's feedback.

Co-authored-by: sinoroc <5529267+sinoroc@users.noreply.github.com>
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 55383c06e..c0b6b383c 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -536,7 +536,7 @@ pex
 
 Pex is a tool for generating :file:`.pex` (Python EXecutable)
 files, standalone Python environments in the spirit of :ref:`virtualenv`.
-PEX files are zipapps as outlined :pep:`441` that
+PEX files are zipapps as outlined in :pep:`441` that
 make deployment of Python applications as simple as ``cp``. A single PEX
 file can support multiple target platforms and can be created from standard
 :ref:`pip`-resolvable requirements, a lockfile generated with ``pex3 lock ...``

From 0e0aa42ca4370dc8c9d6fb1f4a161329729e01b8 Mon Sep 17 00:00:00 2001
From: John Sirois 
Date: Fri, 19 Jan 2024 05:52:53 -0800
Subject: [PATCH 287/733] @jeanas's feedback.

Co-authored-by: Jean Abou-Samra 
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index c0b6b383c..eb24e13dd 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -536,7 +536,7 @@ pex
 
 Pex is a tool for generating :file:`.pex` (Python EXecutable)
 files, standalone Python environments in the spirit of :ref:`virtualenv`.
-PEX files are zipapps as outlined in :pep:`441` that
+PEX files are :ref:`zipapps ` that
 make deployment of Python applications as simple as ``cp``. A single PEX
 file can support multiple target platforms and can be created from standard
 :ref:`pip`-resolvable requirements, a lockfile generated with ``pex3 lock ...``

From dce257ca127ccdf966652c4f04d5ccb7f108a1a7 Mon Sep 17 00:00:00 2001
From: John Sirois 
Date: Fri, 19 Jan 2024 13:07:13 -0800
Subject: [PATCH 288/733] @chrysle's fix.

Co-authored-by: chrysle 
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index eb24e13dd..a00502cb8 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -536,7 +536,7 @@ pex
 
 Pex is a tool for generating :file:`.pex` (Python EXecutable)
 files, standalone Python environments in the spirit of :ref:`virtualenv`.
-PEX files are :ref:`zipapps ` that
+PEX files are :doc:`zipapps ` that
 make deployment of Python applications as simple as ``cp``. A single PEX
 file can support multiple target platforms and can be created from standard
 :ref:`pip`-resolvable requirements, a lockfile generated with ``pex3 lock ...``

From 61968c5f1f1a6524913a8a6e41bf72a7d6528a07 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Sat, 20 Jan 2024 21:15:23 +0100
Subject: [PATCH 289/733] Apply suggestions from code review

Co-authored-by: chrysle 
---
 source/specifications/inline-script-metadata.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/specifications/inline-script-metadata.rst b/source/specifications/inline-script-metadata.rst
index dee1c2634..352614e81 100644
--- a/source/specifications/inline-script-metadata.rst
+++ b/source/specifications/inline-script-metadata.rst
@@ -71,15 +71,15 @@ standardized by this specification.
 script type
 -----------
 
-The first type of metadata block is named ``script`` which contains
+The first type of metadata block is named ``script``, which contains
 script metadata (dependency data and tool configuration).
 
-This document MAY include top-level fields ``dependencies`` and ``requires-python``,
+This document MAY include the top-level fields ``dependencies`` and ``requires-python``,
 and MAY optionally include a ``[tool]`` table.
 
 The ``[tool]`` MAY be used by any tool, script runner or otherwise, to configure
 behavior. It has the same semantics as the :ref:`[tool] table in pyproject.toml
-`
+`.
 
 The top-level fields are:
 

From ae45509df539d51adc4a46c850ccdd2b311c0c56 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 22 Jan 2024 18:20:32 +0000
Subject: [PATCH 290/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.1.9 → v0.1.14](https://github.com/astral-sh/ruff-pre-commit/compare/v0.1.9...v0.1.14)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index baba00ea3..f46125add 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.9
+  rev: v0.1.14
   hooks:
     - id: ruff
     - id: ruff-format

From 8b02e7f478b58f8c730ba193ae827af482862a5f Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 24 Jan 2024 23:58:45 +0100
Subject: [PATCH 291/733] @sinoroc's review

---
 source/discussions/versioning.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst
index a2d818e87..b66553c19 100644
--- a/source/discussions/versioning.rst
+++ b/source/discussions/versioning.rst
@@ -34,7 +34,7 @@ before a final release. In order, the steps are: alpha releases, beta releases,
 release candidates, final release. Pip and other modern Python package
 installers ignore pre-releases by default when deciding which versions of
 dependencies to install, unless explicitly requested (e.g., with
-``pip install pkg==1.1a3``).
+``pip install pkg==1.1a3`` or ``pip install --pre pkg``).
 
 The purpose of development releases is to support releases made early during a
 development cycle, for example, a nightly build, or a build from the latest
@@ -80,7 +80,9 @@ adhere to semantic versioning, since many changes are technically breaking
 changes but affect only a small fraction of users. Such projects tend to
 increment the major number when the incompatibility is high, or to signal a
 shift in the project, rather than for any tiny incompatibility
-[#semver-strictness]_.
+[#semver-strictness]_. Conversely, a bump of the major version number
+is sometimes used to signal significant but backwards-compatible new
+features.
 
 For those projects that do use strict semantic versioning, this approach allows
 users to make use of :ref:`compatible release version specifiers

From 177b5db3a3efd016a520ac17f23fe35855e7dd80 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edgar=20Ram=C3=ADrez=20Mondrag=C3=B3n?=
 
Date: Wed, 24 Jan 2024 23:45:33 -0600
Subject: [PATCH 292/733] Use intersphinx to link to `hashlib` docs

---
 source/specifications/direct-url-data-structure.rst    | 6 +++---
 source/specifications/recording-installed-packages.rst | 2 +-
 source/specifications/simple-repository-api.rst        | 9 ++++-----
 source/specifications/version-specifiers.rst           | 2 +-
 4 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index f0ab2e447..993f40f59 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -79,10 +79,10 @@ MUST be present as a dictionary with the following keys:
 
   These hash names SHOULD always be normalized to be lowercase.
 
-  Any hash algorithm available via ``hashlib`` (specifically any that can be passed to
-  ``hashlib.new()`` and do not require additional parameters) can be used as a key for
+  Any hash algorithm available via :py:mod:`hashlib` (specifically any that can be passed to
+  :py:func:`hashlib.new()` and do not require additional parameters) can be used as a key for
   the hashes dictionary. At least one secure algorithm from
-  ``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of writing,
+  :py:data:`hashlib.algorithms_guaranteed` SHOULD always be included. At time of writing,
   ``sha256`` specifically is recommended.
 
 - A deprecated ``hash`` key (type ``string``) MAY be present for backwards compatibility
diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst
index 957e4f36a..41b8bc6ce 100644
--- a/source/specifications/recording-installed-packages.rst
+++ b/source/specifications/recording-installed-packages.rst
@@ -112,7 +112,7 @@ On Windows, directories may be separated either by forward- or backslashes
 (``/`` or ``\``).
 
 The *hash* is either an empty string or the name of a hash algorithm from
-``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` and
+:py:data:`hashlib.algorithms_guaranteed`, followed by the equals character ``=`` and
 the digest of the file's contents, encoded with the urlsafe-base64-nopad
 encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed).
 
diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
index 702e587ad..b9f87ce7b 100644
--- a/source/specifications/simple-repository-api.rst
+++ b/source/specifications/simple-repository-api.rst
@@ -71,7 +71,7 @@ In addition to the above, the following constraints are placed on the API:
   URL.
 
 * Repositories **SHOULD** choose a hash function from one of the ones
-  guaranteed to be available via the ``hashlib`` module in the Python standard
+  guaranteed to be available via the :py:mod:`hashlib` module in the Python standard
   library (currently ``md5``, ``sha1``, ``sha224``, ``sha256``, ``sha384``,
   ``sha512``). The current recommendation is to use ``sha256``.
 
@@ -452,11 +452,10 @@ Each individual file dictionary has the following keys:
   for the file, however it is **HIGHLY** recommended that at least one secure,
   guaranteed-to-be-available hash is always included.
 
-  By default, any hash algorithm available via `hashlib
-  `_ (specifically any that can
-  be passed to ``hashlib.new()`` and do not require additional parameters) can
+  By default, any hash algorithm available via :py:mod:`hashlib` (specifically any that can
+  be passed to :py:func:`hashlib.new()` and do not require additional parameters) can
   be used as a key for the hashes dictionary. At least one secure algorithm from
-  ``hashlib.algorithms_guaranteed`` **SHOULD** always be included. At the time
+  :py:data:`hashlib.algorithms_guaranteed` **SHOULD** always be included. At the time
   of this spec, ``sha256`` specifically is recommended.
 - ``requires-python``: An **optional** key that exposes the
   :ref:`core-metadata-requires-python`
diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index 8129fd53d..e5b73ce71 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -1113,7 +1113,7 @@ and MAY refuse to rely on the URL. If such a direct reference also uses an
 insecure transport, automated tools SHOULD NOT rely on the URL.
 
 It is RECOMMENDED that only hashes which are unconditionally provided by
-the latest version of the standard library's ``hashlib`` module be used
+the latest version of the standard library's :py:mod:`hashlib` module be used
 for source archive hashes. At time of writing, that list consists of
 ``'md5'``, ``'sha1'``, ``'sha224'``, ``'sha256'``, ``'sha384'``, and
 ``'sha512'``.

From 70ec8b195efc1d0a786f43dabd8c9457ddae615c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edgar=20Ram=C3=ADrez=20Mondrag=C3=B3n?=
 
Date: Thu, 25 Jan 2024 19:40:49 -0600
Subject: [PATCH 293/733] Use intersphinx to link to other Python docs

---
 .../specifications/dependency-specifiers.rst  | 20 +++++++++----------
 source/specifications/entry-points.rst        | 18 ++++++++---------
 source/specifications/name-normalization.rst  |  2 +-
 .../platform-compatibility-tags.rst           |  6 +++---
 .../recording-installed-packages.rst          |  2 +-
 .../specifications/virtual-environments.rst   | 14 ++++++-------
 6 files changed, 31 insertions(+), 31 deletions(-)

diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index 85216d655..51c0b3645 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -234,26 +234,26 @@ error like all other unknown variables.
      - Python equivalent
      - Sample values
    * - ``os_name``
-     - ``os.name``
+     - :py:data:`os.name`
      - ``posix``, ``java``
    * - ``sys_platform``
-     - ``sys.platform``
+     - :py:data:`sys.platform`
      - ``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that "linux"
        is from Python3 and "linux2" from Python2)
    * - ``platform_machine``
-     - ``platform.machine()``
+     - :py:func:`platform.machine()`
      - ``x86_64``
    * - ``platform_python_implementation``
-     - ``platform.python_implementation()``
+     - :py:func:`platform.python_implementation()`
      - ``CPython``, ``Jython``
    * - ``platform_release``
-     - ``platform.release()``
+     - :py:func:`platform.release()`
      - ``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``
    * - ``platform_system``
-     - ``platform.system()``
+     - :py:func:`platform.system()`
      - ``Linux``, ``Windows``, ``Java``
    * - ``platform_version``
-     - ``platform.version()``
+     - :py:func:`platform.version()`
      - ``#1 SMP Fri Apr 25 13:07:35 EDT 2014``
        ``Java HotSpot(TM) 64-Bit Server VM, 25.51-b03, Oracle Corporation``
        ``Darwin Kernel Version 14.5.0: Wed Jul 29 02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``
@@ -261,10 +261,10 @@ error like all other unknown variables.
      - ``'.'.join(platform.python_version_tuple()[:2])``
      - ``3.4``, ``2.7``
    * - ``python_full_version``
-     - ``platform.python_version()``
+     - :py:func:`platform.python_version()`
      - ``3.4.0``, ``3.5.0b1``
    * - ``implementation_name``
-     - ``sys.implementation.name``
+     - :py:data:`sys.implementation.name `
      - ``cpython``
    * - ``implementation_version``
      - see definition below
@@ -275,7 +275,7 @@ error like all other unknown variables.
      - ``test``
 
 The ``implementation_version`` marker variable is derived from
-``sys.implementation.version``:
+:py:data:`sys.implementation.version `:
 
 .. code-block:: python
 
diff --git a/source/specifications/entry-points.rst b/source/specifications/entry-points.rst
index 6a601c977..dea039492 100644
--- a/source/specifications/entry-points.rst
+++ b/source/specifications/entry-points.rst
@@ -18,10 +18,10 @@ example:
 
 The entry point file format was originally developed to allow packages built
 with setuptools to provide integration point metadata that would be read at
-runtime with ``importlib.metadata``. It is now defined as a PyPA interoperability
-specification in order to allow build tools other than setuptools to publish
-``importlib.metadata`` compatible entry point metadata, and runtime libraries other
-than ``importlib.metadata`` to portably read published entry point metadata
+runtime with :py:mod:`importlib.metadata`. It is now defined as a PyPA interoperability
+specification in order to allow build tools other than ``setuptools`` to publish
+:py:mod:`importlib.metadata` compatible entry point metadata, and runtime libraries other
+than :py:mod:`importlib.metadata` to portably read published entry point metadata
 (potentially with different caching and conflict resolution strategies).
 
 Data model
@@ -144,11 +144,11 @@ For instance, the entry point ``mycmd = mymod:main`` would create a command
 
 The difference between ``console_scripts`` and ``gui_scripts`` only affects
 Windows systems. ``console_scripts`` are wrapped in a console executable,
-so they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and
-``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI
-executable, so they can be started without a console, but cannot use standard
-streams unless application code redirects them. Other platforms do not have the
-same distinction.
+so they are attached to a console and can use :py:data:`sys.stdin`,
+:py:data:`sys.stdout` and :py:data:`sys.stderr` for input and output.
+``gui_scripts`` are wrapped in a GUI executable, so they can be started without
+a console, but cannot use standard streams unless application code redirects them.
+Other platforms do not have the same distinction.
 
 Install tools are expected to set up wrappers for both ``console_scripts`` and
 ``gui_scripts`` in the scripts directory of the install scheme. They are not
diff --git a/source/specifications/name-normalization.rst b/source/specifications/name-normalization.rst
index efe60e12d..ba3246b63 100644
--- a/source/specifications/name-normalization.rst
+++ b/source/specifications/name-normalization.rst
@@ -15,7 +15,7 @@ Name format
 A valid name consists only of ASCII letters and numbers, period,
 underscore and hyphen. It must start and end with a letter or number.
 This means that valid project names are limited to those which match the
-following regex (run with ``re.IGNORECASE``)::
+following regex (run with :py:data:`re.IGNORECASE`)::
 
     ^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$
 
diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 10f0c4698..381b84ca9 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -45,7 +45,7 @@ a distribution.  Major implementations have abbreviated codes, initially:
 * pp: PyPy
 * jy: Jython
 
-Other Python implementations should use ``sys.implementation.name``.
+Other Python implementations should use :py:data:`sys.implementation.name `.
 
 The version is ``py_version_nodot``.  CPython gets away with no dot,
 but if one is needed the underscore ``_`` is used instead.  PyPy should
@@ -85,7 +85,7 @@ Platform Tag
 Basic platform tags
 -------------------
 
-In its simplest form, the platform tag is ``sysconfig.get_platform()`` with
+In its simplest form, the platform tag is :py:func:`sysconfig.get_platform()` with
 all hyphens ``-`` and periods ``.`` replaced with underscore ``_``.
 Until the removal of :ref:`distutils` in Python 3.12, this
 was ``distutils.util.get_platform()``. For example:
@@ -113,7 +113,7 @@ The current standard is the future-proof ``manylinux_x_y`` standard. It defines
 tags of the form ``manylinux_x_y_arch``, where ``x`` and ``y`` are glibc major
 and minor versions supported (e.g. ``manylinux_2_24_xxx`` should work on any
 distro using glibc 2.24+), and ``arch`` is the architecture, matching the value
-of ``sysconfig.get_platform()`` on the system as in the "simple" form above.
+of :py:func:`sysconfig.get_platform()` on the system as in the "simple" form above.
 
 The following older tags are still supported for backward compatibility:
 
diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst
index 41b8bc6ce..ee8e69f79 100644
--- a/source/specifications/recording-installed-packages.rst
+++ b/source/specifications/recording-installed-packages.rst
@@ -114,7 +114,7 @@ On Windows, directories may be separated either by forward- or backslashes
 The *hash* is either an empty string or the name of a hash algorithm from
 :py:data:`hashlib.algorithms_guaranteed`, followed by the equals character ``=`` and
 the digest of the file's contents, encoded with the urlsafe-base64-nopad
-encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed).
+encoding (:py:func:`base64.urlsafe_b64encode(digest) ` with trailing ``=`` removed).
 
 The *size* is either the empty string, or file's size in bytes,
 as a base 10 integer.
diff --git a/source/specifications/virtual-environments.rst b/source/specifications/virtual-environments.rst
index 6c8eee530..c73a28c27 100644
--- a/source/specifications/virtual-environments.rst
+++ b/source/specifications/virtual-environments.rst
@@ -17,10 +17,10 @@ there was no previously standardised mechanism for declaring or discovering them
 Runtime detection of virtual environments
 =========================================
 
-At runtime, virtual environments can be identified by virtue of ``sys.prefix``
-(the filesystem location of the running interpreter) having a different value
-from ``sys.base_prefix`` (the default filesystem location of the standard library
-directories).
+At runtime, virtual environments can be identified by virtue of
+:py:data:`sys.prefix` (the filesystem location of the running interpreter)
+having a different value from :py:data:`sys.base_prefix` (the default filesystem
+location of the standard library directories).
 
 :ref:`venv-explanation` in the Python standard library documentation for the
 :py:mod:`venv` module covers this along with the concept of "activating" a
@@ -45,9 +45,9 @@ nesting is required or desired.
 
 Even in the absence of a ``pyvenv.cfg`` file, any approach (e.g.
 ``sitecustomize.py``, patching the installed Python runtime) that results in
-``sys.prefix`` and ``sys.base_prefix`` having different values, while still
-providing a matching default package installation scheme in ``sysconfig``, will
-be detected and behave as a Python virtual environment.
+:py:data:`sys.prefix` and :py:data:`sys.base_prefix` having different values,
+while still providing a matching default package installation scheme in
+:py:mod:`sysconfig`, will be detected and behave as a Python virtual environment.
 
 
 History

From 75728d629fb8b4a81def031a15b37af3c3d0999a Mon Sep 17 00:00:00 2001
From: Dos Moonen 
Date: Fri, 26 Jan 2024 14:10:42 +0100
Subject: [PATCH 294/733] Replace regex which allows dubble hyphens by one that
 does not.

The current version disallows tripple hyphens but allows dubble hyphens. (It also seems overcomplicated)

Alternatively we can make it a negative lookbehind instead of a negative lookahead, but the complexity is much higher.

See https://regex101.com/r/Xyu0bt/1 for proof the current version matches double hyphens
---
 source/specifications/core-metadata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 7ea0ccf3b..90793c791 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -631,7 +631,7 @@ of lowercase ASCII letters, ASCII numbers, and hyphen. It must start and end
 with a letter or number. Hyphens cannot be followed by another hyphen. Names are
 limited to those which match the following regex (which guarantees unambiguity)::
 
-    ^([a-z0-9]|[a-z0-9]([a-z0-9-](?!--))*[a-z0-9])$
+    ^[a-z0-9]+(-[a-z0-9]+)*$
 
 
 The specified name may be used to make a dependency conditional on whether the

From 78b83a225117fe33a4dc71494edf6387ba026d2c Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 27 Jan 2024 18:36:17 +0100
Subject: [PATCH 295/733] Address review comments from @webknjaz

---
 source/discussions/versioning.rst | 31 +++++++++++++++++--------------
 1 file changed, 17 insertions(+), 14 deletions(-)

diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst
index b66553c19..8a738f866 100644
--- a/source/discussions/versioning.rst
+++ b/source/discussions/versioning.rst
@@ -16,18 +16,18 @@ needs of that particular project, but in order to be compatible with tools like
 :ref:`pip`, all of them are required to comply with a flexible format for
 version identifiers, for which the authoritative reference is the
 :ref:`specification of version specifiers `. Here are some
-examples of version numbers:
-
-- A simple version (final release): 1.2.0
-- A development release: 1.2.0.dev1
-- An alpha release: 1.2.0a1
-- A beta release: 1.2.0b1
-- A release candidate: 1.2.0rc1
-- A post-release: 1.2.0.post1
-- A post-release of an alpha release (possible, but discouraged): 1.2.0a1.post1
-- A simple version with only two components: 23.12
-- A simple version with just one component (possible, but discouraged): 42
-- A version with an epoch: 1!1.0
+examples of version numbers [#version-examples]_:
+
+- A simple version (final release): ``1.2.0``
+- A development release: ``1.2.0.dev1``
+- An alpha release: ``1.2.0a1``
+- A beta release: ``1.2.0b1``
+- A release candidate: ``1.2.0rc1``
+- A post-release: ``1.2.0.post1``
+- A post-release of an alpha release (possible, but discouraged): ``1.2.0a1.post1``
+- A simple version with only two components: ``23.12``
+- A simple version with just one component: ``42``
+- A version with an epoch: ``1!1.0``
 
 Projects can use a cycle of pre-releases to support testing by their users
 before a final release. In order, the steps are: alpha releases, beta releases,
@@ -68,11 +68,11 @@ Semantic versioning
 -------------------
 
 The idea of *semantic versioning* (or SemVer) is to use 3-part version numbers,
-*major.minor.maintenance*, where the project author increments:
+*major.minor.patch*, where the project author increments:
 
 - *major* when they make incompatible API changes,
 - *minor* when they add functionality in a backwards-compatible manner, and
-- *maintenance*, when they make backwards-compatible bug fixes.
+- *patch*, when they make backwards-compatible bug fixes.
 
 A majority of Python projects use a scheme that resembles semantic
 versioning. However, most projects, especially larger ones, do not strictly
@@ -159,6 +159,8 @@ since the latest release, setuptools-scm generates a version like
 
 --------------------------------------------------------------------------------
 
+.. [#version-examples] Some more examples of unusual version numbers are
+   given in a `blog post `_ by Seth Larson.
 
 .. [#semver-strictness] For some personal viewpoints on this issue, see these
    blog posts: `by Hynek Schlawak `_, `by Donald Stufft
@@ -176,3 +178,4 @@ since the latest release, setuptools-scm generates a version like
 .. _semver-donald-stufft: https://caremad.io/posts/2016/02/versioning-software/
 .. _semver-hynek-schlawack: https://hynek.me/articles/semver-will-not-save-you/
 .. _setuptools-scm: https://setuptools-scm.readthedocs.io
+.. _versions-seth-larson: https://sethmlarson.dev/pep-440

From bd555c5f759c7be146a31497e8eaa701ecc35e15 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 27 Jan 2024 18:42:44 +0100
Subject: [PATCH 296/733] Fix reST syntax

---
 source/discussions/versioning.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst
index 8a738f866..c91273310 100644
--- a/source/discussions/versioning.rst
+++ b/source/discussions/versioning.rst
@@ -160,7 +160,7 @@ since the latest release, setuptools-scm generates a version like
 --------------------------------------------------------------------------------
 
 .. [#version-examples] Some more examples of unusual version numbers are
-   given in a `blog post `_ by Seth Larson.
+   given in a `blog post `_ by Seth Larson.
 
 .. [#semver-strictness] For some personal viewpoints on this issue, see these
    blog posts: `by Hynek Schlawak `_, `by Donald Stufft

From 2241c5039af75a4199b2645c8dc9f61d1d0b9017 Mon Sep 17 00:00:00 2001
From: Laurie O 
Date: Mon, 29 Jan 2024 11:36:54 +1000
Subject: [PATCH 297/733] Add 'dumb-pypi'

---
 source/guides/hosting-your-own-index.rst |  5 +++++
 source/key_projects.rst                  | 12 ++++++++++++
 2 files changed, 17 insertions(+)

diff --git a/source/guides/hosting-your-own-index.rst b/source/guides/hosting-your-own-index.rst
index 94ffb5d71..9b3c20069 100644
--- a/source/guides/hosting-your-own-index.rst
+++ b/source/guides/hosting-your-own-index.rst
@@ -105,6 +105,11 @@ Existing projects
      -
      - also mirroring; manual synchronisation
 
+   * - :ref:`dumb-pypi`
+     -
+     -
+     - not a server, but a static file site generator
+
    * - :ref:`httpserver`
      -
      -
diff --git a/source/key_projects.rst b/source/key_projects.rst
index ccd6ee883..853d4e065 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -442,6 +442,18 @@ devpi supports mirroring PyPI, multiple
 :term:`package indexes ` with inheritance, syncing between
 these indexes, index replication and fail-over, and package upload.
 
+.. _dumb-pypi:
+
+dumb-pypi
+=========
+
+`GitHub `__ |
+`PyPI `__
+
+dumb-pypi is a simple :term:`package index ` static file site
+generator, which then must be hosted by a static file webserver to become the
+package index. It supports serving the hash, core-metadata, and yank-status.
+
 .. _enscons:
 
 enscons

From b3e7b65f3f6bbc291a24b73e726684e50e300cc7 Mon Sep 17 00:00:00 2001
From: Laurie O 
Date: Wed, 31 Jan 2024 15:39:12 +1000
Subject: [PATCH 298/733] Remove duplicated-from-venv https.server description

---
 source/key_projects.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 853d4e065..531c28066 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -865,9 +865,6 @@ http.server
 A package and command-line interface which can host a directory as a
 website, for example as a :term:`package index ` (see
 :ref:`Hosting your Own Simple Repository`).
-A package in the Python Standard Library (starting with Python 3.3) for
-creating :term:`Virtual Environments `.  For more
-information, see the section on :ref:`Creating and using Virtual Environments`.
 
 .. _venv:
 

From 35c7f84c6ff6b2b530c9a781ab296786465b6e8e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sviatoslav=20Sydorenko=20=28=D0=A1=D0=B2=D1=8F=D1=82=D0=BE?=
 =?UTF-8?q?=D1=81=D0=BB=D0=B0=D0=B2=20=D0=A1=D0=B8=D0=B4=D0=BE=D1=80=D0=B5?=
 =?UTF-8?q?=D0=BD=D0=BA=D0=BE=29?= 
Date: Thu, 1 Feb 2024 03:09:57 +0100
Subject: [PATCH 299/733] Spell "fall back" as a verb with a whitespace

---
 source/guides/hosting-your-own-index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/hosting-your-own-index.rst b/source/guides/hosting-your-own-index.rst
index 9b3c20069..ebcd228ee 100644
--- a/source/guides/hosting-your-own-index.rst
+++ b/source/guides/hosting-your-own-index.rst
@@ -131,7 +131,7 @@ Existing projects
 .. [1] For complete documentation of the simple repository protocol, see
        :ref:`simple repository API `.
 
-.. [2] Can be configured to fall-back to PyPI (or another package index)
+.. [2] Can be configured to fall back to PyPI (or another package index)
        if a requested package is missing.
 
 .. _Twisted: https://twistedmatrix.com/

From e28aa45e05fdfb1d3942a6919d7d1f55a8a4c34c Mon Sep 17 00:00:00 2001
From: wim glenn 
Date: Sat, 3 Feb 2024 15:55:42 -0600
Subject: [PATCH 300/733] Update modernize-setup-py-project.rst

---
 source/guides/modernize-setup-py-project.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/modernize-setup-py-project.rst b/source/guides/modernize-setup-py-project.rst
index bea636ca4..5b6ab3c26 100644
--- a/source/guides/modernize-setup-py-project.rst
+++ b/source/guides/modernize-setup-py-project.rst
@@ -124,7 +124,7 @@ and trigger the build in that environment.
 For some projects this isolation is unwanted and it can be deactivated as follows:
 
 * ``python -m build --no-isolation``
-* ``python -m install --no-build-isolation``
+* ``python -m pip install --no-build-isolation``
 
 For more details:
 

From 1935669329cd121dbe87e84f7f311805184d8c8b Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 7 Feb 2024 17:44:55 +0100
Subject: [PATCH 301/733] Apply suggestion from @webknjaz
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/discussions/versioning.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst
index c91273310..49fbbf0de 100644
--- a/source/discussions/versioning.rst
+++ b/source/discussions/versioning.rst
@@ -63,6 +63,22 @@ number, and to decide which should be the next version number for a new release
 of a package. Two versioning schemes are commonly used for Python packages,
 semantic versioning and calendar versioning.
 
+.. caution::
+
+   The decision which version number to choose is up to a
+   project's maintainer. This effectively means that version
+   bumps reflect the maintainer's view. That view may differ
+   from the end-users' perception of what said formalized
+   versioning scheme promises them.
+
+   There are known exceptions for selecting the next version
+   number. The maintainers may consciously choose to break the
+   assumption that the last version segment only contains
+   backwards-compatible changes.
+   One such case is when security vulnerability needs to be
+   addressed. Security releases often come in patch versions
+   but contain breaking changes inevitably.
+
 
 Semantic versioning
 -------------------

From f937c9b765b2301e5931a83682fa06ac02539d4a Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 12 Feb 2024 21:47:09 +0000
Subject: [PATCH 302/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.1.14 → v0.2.1](https://github.com/astral-sh/ruff-pre-commit/compare/v0.1.14...v0.2.1)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index f46125add..3c24cfc46 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.14
+  rev: v0.2.1
   hooks:
     - id: ruff
     - id: ruff-format

From b9878e6f3c6b61cb9278d44d9dcbfb742561037d Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 30 Dec 2023 14:38:36 +0100
Subject: [PATCH 303/733] Update tool recommendations

Fixes #1468
---
 source/guides/tool-recommendations.rst   | 183 +++++++++++++----------
 source/guides/writing-pyproject-toml.rst |   1 +
 2 files changed, 107 insertions(+), 77 deletions(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index 1a59201fa..2e7c64173 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -4,111 +4,140 @@
 Tool recommendations
 ====================
 
-If you're familiar with Python packaging and installation, and just want to know
-what tools are currently recommended, then here it is.
+The Python packaging landscape consists of many different tools. For many tasks,
+the Python Packaging Authority (PyPA, the umbrella organization which
+encompasses many packaging tools and maintains this guide) purposefully does not
+make a blanket recommendation; for example, the reason there exist many build
+backends is that the landscape was opened in order to enable the development of
+new backends serving certain users' needs better than the previously unique
+backend, setuptools. This guide does point to some tools that are widely
+recognized, and also makes some recommendations of tools that you should *not*
+use because they are deprecated or insecure.
+
+
+Virtual environments
+====================
+
+The standard tools to create and use virtual environments manually are
+:ref:`virtualenv` (PyPA project) and :doc:`venv ` (part of
+the Python standard library, though missing some features of virtualenv).
+
+
+Installing packages
+===================
+
+:ref:`Pip` is a standard tool to install packages from :term:`PyPI `. It can install into the global environment or into
+virtual environments. You may want to read pip's recommendations for
+:doc:`secure installs `. Pip is available by default
+in most Python installations.
+
+Alternatively, for installing Python command line applications specifically,
+consider :ref:`pipx`, which is a wrapper around pip that installs each
+application into a dedicated virtual environment in order to avoid conflicts
+with other applications and, on Linux, conflicts with the system.
+
+For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`.
+
+.. todo:: Write a "pip vs. Conda" comparison, here or in a new discussion.
+
+Do **not** use ``easy_install`` (part of :ref:`setuptools`), which is deprecated
+in favor of pip (see :ref:`pip vs easy_install` for details). Likewise, do
+**not** use ``python setup.py install`` or ``python setup.py develop``, which
+are also deprecated (see :ref:`setup-py-deprecated` for background and
+:ref:`modernize-setup-py-project` for migration advice).
+
+
+Lock files
+==========
 
+:ref:`pip-tools` and :ref:`Pipenv` are two recognized tools to create lock
+files, which contain the exact versions of all packages installed into an
+environment, for reproducibility purposes.
 
-Application dependency management
-=================================
 
-* Use :ref:`pip` in a `secure manner`_ to install a Python application and its
-  dependencies during deployment.
+Build backends
+==============
 
-* Use :ref:`virtualenv` or :doc:`venv ` to isolate
-  application-specific dependencies from a shared Python installation. [4]_
+Popular :term:`build backends ` for pure-Python packages include:
 
-* Use `pip-tools`_, :ref:`pipenv`, or `poetry`_ to generate the fully-specified
-  application-specific dependencies, when developing Python applications.
+- Hatchling, which is part of :ref:`Hatch` (but can be used without
+  Hatch as well). Hatchling is extensible through a plugin system.
 
-.. _secure manner: https://pip.pypa.io/en/latest/topics/secure-installs/
-.. _pip-tools: https://github.com/jazzband/pip-tools
-.. _Poetry: https://python-poetry.org/
+- :ref:`setuptools`, the historical build backend. It can be configured
+  programmatically through the :file:`setup.py` file.
 
-Installation tool recommendations
-=================================
+  If you use setuptools, please be aware that it contains many deprecated
+  features which are currently kept for compatibility, but should not be used.
+  For example, do not use ``python setup.py`` invocations
+  (cf. :ref:`setup-py-deprecated`), the ``python_requires`` argument to
+  ``setup()`` (use the :ref:`[build-system] table
+  ` of :file:`pyproject.toml` instead), or
+  the ``easy_install`` command (cf. :ref:`pip vs easy_install`).
 
-* Use :ref:`pip` to install Python :term:`packages ` from
-  :term:`PyPI `. [1]_ [2]_ Depending on how :ref:`pip`
-  is installed, you may need to also install :ref:`wheel` to get the benefit
-  of wheel caching. [3]_
+- Flit-core, part of :ref:`Flit` (but usable standalone). It is meant to be a
+  minimal and opinionated build backend. It is not extensible.
 
-* Use :ref:`virtualenv` or :doc:`venv ` to isolate
-  project-specific dependencies from a shared Python installation. [4]_
+- PDM-backend_, part of :ref:`PDM` (but usable standalone). It provides build
+  hooks for extensibility.
 
-* If you're looking for management of fully integrated cross-platform software
-  stacks, consider:
+- Poetry-core, part of :ref:`Poetry` (but usable standalone). It is extensible
+  through plugins.
 
-  * :ref:`buildout`: primarily focused on the web development community
+Do **not** use distutils, which is deprecated, and has been removed from the
+standard library in Python 3.12, although it still remains available from
+setuptools.
 
-  * :ref:`spack`, :ref:`hashdist`, or :ref:`conda`: primarily focused
-    on the scientific community.
+For packages with :term:`extension modules `, you may use
+setuptools, but consider using a build system dedicated to the language the
+extension is written in, such as Meson or CMake for C/C++, or Cargo for Rust,
+and bridging this build system to Python using a dedicated build backend:
 
+- :ref:`meson-python` for Meson,
 
-Packaging tool recommendations
-==============================
+- :ref:`scikit-build-core` for CMake,
 
-* Use :ref:`setuptools` to define projects. [5]_ [6]_
+- :ref:`maturin` for Cargo.
 
-* Use :ref:`build` to create :term:`Source Distributions
-  ` and :term:`wheels `.
 
-If you have binary extensions and want to distribute wheels for multiple
-platforms, use :ref:`cibuildwheel` as part of your CI setup to build
-distributable wheels.
+Building distributions
+======================
 
-* Use `twine `_ for uploading distributions
-  to :term:`PyPI `.
+The standard tool to build :term:`source distributions ` and :term:`wheels ` for uploading to PyPI is :ref:`build`.  It
+will invoke whichever build backend you :ref:`declared
+` in :file:`pyproject.toml`.
 
+Do **not** use ``python setup.py sdist`` and ``python setup.py bdist_wheel`` for
+this task. All direct invocations of :file:`setup.py` are :ref:`deprecated
+`.
 
-Publishing platform migration
-=============================
+If you have :term:`extension modules ` and want to distribute
+wheels for multiple platforms, use :ref:`cibuildwheel` as part of your CI setup
+to build distributable wheels.
 
-The original Python Package Index implementation (previously hosted at
-`pypi.python.org `_) has been phased out in favour
-of an updated implementation hosted at `pypi.org `_.
 
-See :ref:`Migrating to PyPI.org` for more information on the status of the
-migration, and what settings to change in your clients.
+Uploading to PyPI
+=================
 
-----
+The standard tool for this task is :ref:`twine`.
 
-.. [1] There are some cases where you might choose to use ``easy_install`` (from
-       :ref:`setuptools`), e.g. if you need to install from :term:`Eggs `
-       (which pip doesn't support).  For a detailed breakdown, see :ref:`pip vs
-       easy_install`.
+**Never** use ``python setup.py upload`` for this task. In addition to being
+:ref:`deprecated `, it is insecure.
 
-.. [2] The acceptance of :pep:`453` means that :ref:`pip`
-       will be available by default in most installations of Python 3.4 or
-       later.  See the :pep:`rationale section <453#rationale>` from :pep:`453`
-       as for why pip was chosen.
 
-.. [3] `get-pip.py `_ and
-       :ref:`virtualenv` install
-       :ref:`wheel`, whereas :ref:`ensurepip` and :ref:`venv ` do not
-       currently.  Also, the common "python-pip" package that's found in various
-       linux distros, does not depend on "python-wheel" currently.
+Integrated workflow tools
+=========================
 
-.. [4] Beginning with Python 3.4, ``venv`` will create virtualenv environments
-       with ``pip`` installed, thereby making it an equal alternative to
-       :ref:`virtualenv`. However, using :ref:`virtualenv` will still be
-       recommended for users that need cross-version consistency.
+These are tools that combine many features in one command line application, such
+as automatically managing virtual environments for a project, building
+distributions, uploading to PyPI, or creating and using lock files.
 
-.. [5] Although you can use pure :ref:`distutils` for many projects, it does not
-       support defining dependencies on other projects and is missing several
-       convenience utilities for automatically populating distribution metadata
-       correctly that are provided by ``setuptools``. Being outside the
-       standard library, ``setuptools`` also offers a more consistent feature
-       set across different versions of Python, and (unlike ``distutils``),
-       recent versions of ``setuptools`` support all of the modern metadata
-       fields described in :ref:`core-metadata`.
+- :ref:`Hatch`,
+- :ref:`Flit`,
+- :ref:`PDM`,
+- :ref:`Poetry`.
 
-       Even for projects that do choose to use ``distutils``, when :ref:`pip`
-       installs such projects directly from source (rather than installing
-       from a prebuilt :term:`wheel ` file), it will actually build
-       your project using :ref:`setuptools` instead.
 
-.. [6] `distribute`_ (a fork of setuptools) was merged back into
-       :ref:`setuptools` in June 2013, thereby making setuptools the default
-       choice for packaging.
 
-.. _distribute: https://pypi.org/project/distribute
+.. _pdm-backend: https://backend.pdm-project.org
diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 187a44d50..938ebbb93 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -40,6 +40,7 @@ three possible TOML tables in this file.
    :ref:`setup-py-deprecated`.
 
 
+.. _pyproject-guide-build-system-table:
 
 Declaring the build backend
 ===========================

From dc4ff6692806bb4aa35b00eeb630b2fa6bd142ee Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Sat, 30 Dec 2023 16:20:14 +0100
Subject: [PATCH 304/733] Address @chrysle's review

---
 source/guides/tool-recommendations.rst | 34 ++++++++++++++------------
 1 file changed, 19 insertions(+), 15 deletions(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index 2e7c64173..a34df5d65 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -5,14 +5,15 @@ Tool recommendations
 ====================
 
 The Python packaging landscape consists of many different tools. For many tasks,
-the Python Packaging Authority (PyPA, the umbrella organization which
-encompasses many packaging tools and maintains this guide) purposefully does not
-make a blanket recommendation; for example, the reason there exist many build
-backends is that the landscape was opened in order to enable the development of
-new backends serving certain users' needs better than the previously unique
-backend, setuptools. This guide does point to some tools that are widely
-recognized, and also makes some recommendations of tools that you should *not*
-use because they are deprecated or insecure.
+the :term:`Python Packaging Authority `
+(PyPA, the umbrella organization which encompasses many packaging tools and
+maintains this guide) purposefully does not make a blanket recommendation; for
+example, the reason there exist many build backends is that the landscape was
+opened in order to enable the development of new backends serving certain users'
+needs better than the previously unique backend, setuptools. This guide does
+point to some tools that are widely recognized, and also makes some
+recommendations of tools that you should *not* use because they are deprecated
+or insecure.
 
 
 Virtual environments
@@ -26,7 +27,7 @@ the Python standard library, though missing some features of virtualenv).
 Installing packages
 ===================
 
-:ref:`Pip` is a standard tool to install packages from :term:`PyPI `. It can install into the global environment or into
 virtual environments. You may want to read pip's recommendations for
 :doc:`secure installs `. Pip is available by default
@@ -34,8 +35,10 @@ in most Python installations.
 
 Alternatively, for installing Python command line applications specifically,
 consider :ref:`pipx`, which is a wrapper around pip that installs each
-application into a dedicated virtual environment in order to avoid conflicts
-with other applications and, on Linux, conflicts with the system.
+application into a dedicated virtual environment. This avoids conflicts between
+the dependencies of different applications. On Linux, pipx is especially
+important because it also avoids conflicts with the system (which are the reason
+for :ref:`externally managed environments `).
 
 For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`.
 
@@ -65,11 +68,12 @@ Popular :term:`build backends ` for pure-Python packages include:
   Hatch as well). Hatchling is extensible through a plugin system.
 
 - :ref:`setuptools`, the historical build backend. It can be configured
-  programmatically through the :file:`setup.py` file.
+  programmatically through the :file:`setup.py` file (but for basic metadata,
+  :file:`pyproject.toml` is preferred).
 
   If you use setuptools, please be aware that it contains many deprecated
   features which are currently kept for compatibility, but should not be used.
-  For example, do not use ``python setup.py`` invocations
+  For example, do **not** use ``python setup.py`` invocations
   (cf. :ref:`setup-py-deprecated`), the ``python_requires`` argument to
   ``setup()`` (use the :ref:`[build-system] table
   ` of :file:`pyproject.toml` instead), or
@@ -84,8 +88,8 @@ Popular :term:`build backends ` for pure-Python packages include:
 - Poetry-core, part of :ref:`Poetry` (but usable standalone). It is extensible
   through plugins.
 
-Do **not** use distutils, which is deprecated, and has been removed from the
-standard library in Python 3.12, although it still remains available from
+Do **not** use :ref:`distutils`, which is deprecated, and has been removed from
+the standard library in Python 3.12, although it still remains available from
 setuptools.
 
 For packages with :term:`extension modules `, you may use

From f5df94159862516cad4d4d0adf379a644fa8ed61 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Sun, 31 Dec 2023 14:12:27 +0100
Subject: [PATCH 305/733] Fix brain fart

---
 source/guides/tool-recommendations.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index a34df5d65..11c57aa7d 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -74,7 +74,7 @@ Popular :term:`build backends ` for pure-Python packages include:
   If you use setuptools, please be aware that it contains many deprecated
   features which are currently kept for compatibility, but should not be used.
   For example, do **not** use ``python setup.py`` invocations
-  (cf. :ref:`setup-py-deprecated`), the ``python_requires`` argument to
+  (cf. :ref:`setup-py-deprecated`), the ``setup_requires`` argument to
   ``setup()`` (use the :ref:`[build-system] table
   ` of :file:`pyproject.toml` instead), or
   the ``easy_install`` command (cf. :ref:`pip vs easy_install`).

From 620222cb291413358d6860f33f76210e74fe3456 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 3 Jan 2024 12:38:37 +0100
Subject: [PATCH 306/733] Address review comments from @webknjaz and
 @eli-schwartz

---
 source/guides/tool-recommendations.rst | 47 +++++++++++++++-----------
 1 file changed, 27 insertions(+), 20 deletions(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index 11c57aa7d..1778851d5 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -6,10 +6,10 @@ Tool recommendations
 
 The Python packaging landscape consists of many different tools. For many tasks,
 the :term:`Python Packaging Authority `
-(PyPA, the umbrella organization which encompasses many packaging tools and
+(PyPA, the working group which encompasses many packaging tools and
 maintains this guide) purposefully does not make a blanket recommendation; for
-example, the reason there exist many build backends is that the landscape was
-opened in order to enable the development of new backends serving certain users'
+example, the reason there are many build backends is that the landscape was
+opened up in order to enable the development of new backends serving certain users'
 needs better than the previously unique backend, setuptools. This guide does
 point to some tools that are widely recognized, and also makes some
 recommendations of tools that you should *not* use because they are deprecated
@@ -31,14 +31,15 @@ Installing packages
 Package Index (PyPI)>`. It can install into the global environment or into
 virtual environments. You may want to read pip's recommendations for
 :doc:`secure installs `. Pip is available by default
-in most Python installations.
+in most Python installations through the standard library package
+:doc:`ensurepip `.
 
-Alternatively, for installing Python command line applications specifically,
-consider :ref:`pipx`, which is a wrapper around pip that installs each
+Alternatively, consider :ref:`pipx` for the specific use case of installing Python
+command line applications that are distributed through PyPI.
+Pipx is a wrapper around pip and venv that installs each
 application into a dedicated virtual environment. This avoids conflicts between
-the dependencies of different applications. On Linux, pipx is especially
-important because it also avoids conflicts with the system (which are the reason
-for :ref:`externally managed environments `).
+the dependencies of different applications, and also with the system
+(especially on Linux).
 
 For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`.
 
@@ -64,10 +65,10 @@ Build backends
 
 Popular :term:`build backends ` for pure-Python packages include:
 
-- Hatchling, which is part of :ref:`Hatch` (but can be used without
-  Hatch as well). Hatchling is extensible through a plugin system.
+- Hatchling_, which is developed along with :ref:`Hatch`, but is separate and can
+  be used without Hatch. Hatchling is extensible through a plugin system.
 
-- :ref:`setuptools`, the historical build backend. It can be configured
+- :ref:`setuptools` (which used to be the only build backend). It can be configured
   programmatically through the :file:`setup.py` file (but for basic metadata,
   :file:`pyproject.toml` is preferred).
 
@@ -79,13 +80,13 @@ Popular :term:`build backends ` for pure-Python packages include:
   ` of :file:`pyproject.toml` instead), or
   the ``easy_install`` command (cf. :ref:`pip vs easy_install`).
 
-- Flit-core, part of :ref:`Flit` (but usable standalone). It is meant to be a
+- Flit-core_ (developed with but separate from :ref:`Flit`). It is meant to be a
   minimal and opinionated build backend. It is not extensible.
 
-- PDM-backend_, part of :ref:`PDM` (but usable standalone). It provides build
+- PDM-backend_ (developed with but separate from :ref:`PDM`). It provides build
   hooks for extensibility.
 
-- Poetry-core, part of :ref:`Poetry` (but usable standalone). It is extensible
+- Poetry-core_ (developed with but separate from :ref:`Poetry`). It is extensible
   through plugins.
 
 Do **not** use :ref:`distutils`, which is deprecated, and has been removed from
@@ -93,9 +94,11 @@ the standard library in Python 3.12, although it still remains available from
 setuptools.
 
 For packages with :term:`extension modules `, you may use
-setuptools, but consider using a build system dedicated to the language the
-extension is written in, such as Meson or CMake for C/C++, or Cargo for Rust,
-and bridging this build system to Python using a dedicated build backend:
+setuptools. However, you can also use a build system with dedicated support for
+the language the extension is written in. For example, you could choose Meson or
+CMake for C, C++, Fortran and many other compiled languages; or Cargo for Rust
+specifically. You can then bridge this build system to Python using a dedicated
+build backend:
 
 - :ref:`meson-python` for Meson,
 
@@ -135,13 +138,17 @@ Integrated workflow tools
 
 These are tools that combine many features in one command line application, such
 as automatically managing virtual environments for a project, building
-distributions, uploading to PyPI, or creating and using lock files.
+distributions, uploading to PyPI, or creating and using (tool-specific) lock
+files. They often call the tools mentioned above under the hood.
 
 - :ref:`Hatch`,
 - :ref:`Flit`,
 - :ref:`PDM`,
 - :ref:`Poetry`.
+- :ref:`Pipenv`
 
 
-
+.. _flit-core: https://pypi.org/project/flit-core/
+.. _hatchling: https://pypi.org/project/hatchling/
 .. _pdm-backend: https://backend.pdm-project.org
+.. _poetry-core: https://pypi.org/project/poetry-core/

From fc6f4207a65a0d4bb7db5ae72f54f2c2bb1ce32b Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 3 Jan 2024 12:40:15 +0100
Subject: [PATCH 307/733] Sort tools alphabetically

---
 source/guides/tool-recommendations.rst | 28 ++++++++++++++------------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index 1778851d5..b883b60cc 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -63,11 +63,21 @@ environment, for reproducibility purposes.
 Build backends
 ==============
 
-Popular :term:`build backends ` for pure-Python packages include:
+Popular :term:`build backends ` for pure-Python packages include,
+in alphabetical order:
+
+- Flit-core_ (developed with but separate from :ref:`Flit`). It is meant to be a
+  minimal and opinionated build backend. It is not extensible.
 
 - Hatchling_, which is developed along with :ref:`Hatch`, but is separate and can
   be used without Hatch. Hatchling is extensible through a plugin system.
 
+- PDM-backend_ (developed with but separate from :ref:`PDM`). It provides build
+  hooks for extensibility.
+
+- Poetry-core_ (developed with but separate from :ref:`Poetry`). It is extensible
+  through plugins.
+
 - :ref:`setuptools` (which used to be the only build backend). It can be configured
   programmatically through the :file:`setup.py` file (but for basic metadata,
   :file:`pyproject.toml` is preferred).
@@ -80,15 +90,6 @@ Popular :term:`build backends ` for pure-Python packages include:
   ` of :file:`pyproject.toml` instead), or
   the ``easy_install`` command (cf. :ref:`pip vs easy_install`).
 
-- Flit-core_ (developed with but separate from :ref:`Flit`). It is meant to be a
-  minimal and opinionated build backend. It is not extensible.
-
-- PDM-backend_ (developed with but separate from :ref:`PDM`). It provides build
-  hooks for extensibility.
-
-- Poetry-core_ (developed with but separate from :ref:`Poetry`). It is extensible
-  through plugins.
-
 Do **not** use :ref:`distutils`, which is deprecated, and has been removed from
 the standard library in Python 3.12, although it still remains available from
 setuptools.
@@ -139,13 +140,14 @@ Integrated workflow tools
 These are tools that combine many features in one command line application, such
 as automatically managing virtual environments for a project, building
 distributions, uploading to PyPI, or creating and using (tool-specific) lock
-files. They often call the tools mentioned above under the hood.
+files. They often call the tools mentioned above under the hood. In alphabetical
+order:
 
-- :ref:`Hatch`,
 - :ref:`Flit`,
+- :ref:`Hatch`,
 - :ref:`PDM`,
+- :ref:`Pipenv`,
 - :ref:`Poetry`.
-- :ref:`Pipenv`
 
 
 .. _flit-core: https://pypi.org/project/flit-core/

From 52e7eac7b7bba631a505f05b7d924a0d53622d6b Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Wed, 3 Jan 2024 17:40:00 +0100
Subject: [PATCH 308/733] Suggestions from @abravalheri

Co-authored-by: Anderson Bravalheri 
---
 source/guides/tool-recommendations.rst | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index b883b60cc..3a6ec813c 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -79,6 +79,8 @@ in alphabetical order:
   through plugins.
 
 - :ref:`setuptools` (which used to be the only build backend). It can be configured
+  using modern standards like `pyproject.toml`, but can also be extended
+  and supports customisation via `setup.py`.
   programmatically through the :file:`setup.py` file (but for basic metadata,
   :file:`pyproject.toml` is preferred).
 
@@ -95,11 +97,13 @@ the standard library in Python 3.12, although it still remains available from
 setuptools.
 
 For packages with :term:`extension modules `, you may use
-setuptools. However, you can also use a build system with dedicated support for
-the language the extension is written in. For example, you could choose Meson or
-CMake for C, C++, Fortran and many other compiled languages; or Cargo for Rust
-specifically. You can then bridge this build system to Python using a dedicated
-build backend:
+a build system with dedicated support for the language the extension is written in,
+for example:
+
+- :ref:`setuptools` - natively supports C/C++ (with 3rd-party plugins for Go and Rust);
+- :ref:`meson-python` - C, C++, Fortran, and Rust and other languages supported by Meson;
+- :ref:`scikit-build-core` - C, C++, Fortran and other languages supported by CMake;
+- :ref:`maturin` - Rust, via Cargo.
 
 - :ref:`meson-python` for Meson,
 

From 874ebbc35ed3fac5c9669c379387364c59927acc Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 3 Jan 2024 17:44:02 +0100
Subject: [PATCH 309/733] Minor fixes/improvements

---
 source/guides/tool-recommendations.rst | 23 ++++++++---------------
 1 file changed, 8 insertions(+), 15 deletions(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index 3a6ec813c..de7cd9e70 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -78,11 +78,10 @@ in alphabetical order:
 - Poetry-core_ (developed with but separate from :ref:`Poetry`). It is extensible
   through plugins.
 
-- :ref:`setuptools` (which used to be the only build backend). It can be configured
-  using modern standards like `pyproject.toml`, but can also be extended
-  and supports customisation via `setup.py`.
-  programmatically through the :file:`setup.py` file (but for basic metadata,
-  :file:`pyproject.toml` is preferred).
+- :ref:`setuptools` (which used to be the only build backend). It can be
+  configured using modern standards like the :ref:`[project] table in
+  pyproject.toml `, but can also be extended and
+  customized via :file:`setup.py`.
 
   If you use setuptools, please be aware that it contains many deprecated
   features which are currently kept for compatibility, but should not be used.
@@ -100,16 +99,10 @@ For packages with :term:`extension modules `, you may use
 a build system with dedicated support for the language the extension is written in,
 for example:
 
-- :ref:`setuptools` - natively supports C/C++ (with 3rd-party plugins for Go and Rust);
-- :ref:`meson-python` - C, C++, Fortran, and Rust and other languages supported by Meson;
-- :ref:`scikit-build-core` - C, C++, Fortran and other languages supported by CMake;
-- :ref:`maturin` - Rust, via Cargo.
-
-- :ref:`meson-python` for Meson,
-
-- :ref:`scikit-build-core` for CMake,
-
-- :ref:`maturin` for Cargo.
+- :ref:`setuptools` -- natively supports C and C++ (with third-party plugins for Go and Rust),
+- :ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported by Meson,
+- :ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported by CMake,
+- :ref:`maturin` -- Rust, via Cargo.
 
 
 Building distributions

From 6d285fe3ea64f6cda14879e5b5e2d7e950adae6b Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 3 Jan 2024 17:58:31 +0100
Subject: [PATCH 310/733] Mention tox and nox

---
 source/guides/tool-recommendations.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index de7cd9e70..0c7be1f54 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -131,6 +131,15 @@ The standard tool for this task is :ref:`twine`.
 :ref:`deprecated `, it is insecure.
 
 
+Task runners
+============
+
+These tools allow you to define and invoke "tasks", such as running tests,
+compiling documentation, regenerating some files, etc. Each task can be executed
+in a dedicated virtual environment with the dependencies it requires. The most
+common tools for this are :ref:`tox` and :ref:`nox`.
+
+
 Integrated workflow tools
 =========================
 

From 8c34a17ed313c188d1ef3dee81c9962edb7270dd Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Wed, 3 Jan 2024 18:03:07 +0100
Subject: [PATCH 311/733] Fix tox/nox links

---
 source/guides/tool-recommendations.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index 0c7be1f54..80769f331 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -137,7 +137,7 @@ Task runners
 These tools allow you to define and invoke "tasks", such as running tests,
 compiling documentation, regenerating some files, etc. Each task can be executed
 in a dedicated virtual environment with the dependencies it requires. The most
-common tools for this are :ref:`tox` and :ref:`nox`.
+common tools for this are tox_ and nox_.
 
 
 Integrated workflow tools
@@ -158,5 +158,7 @@ order:
 
 .. _flit-core: https://pypi.org/project/flit-core/
 .. _hatchling: https://pypi.org/project/hatchling/
+.. _nox: https://nox.thea.codes
 .. _pdm-backend: https://backend.pdm-project.org
 .. _poetry-core: https://pypi.org/project/poetry-core/
+.. _tox: https://tox.wiki

From dc02b6d8a361809bb8ab96920f7876d678b6b4e8 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Thu, 4 Jan 2024 00:01:00 +0100
Subject: [PATCH 312/733] Rewording from @abravalheri

Co-authored-by: Anderson Bravalheri 
---
 source/guides/tool-recommendations.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index 80769f331..c9b15d164 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -83,8 +83,8 @@ in alphabetical order:
   pyproject.toml `, but can also be extended and
   customized via :file:`setup.py`.
 
-  If you use setuptools, please be aware that it contains many deprecated
-  features which are currently kept for compatibility, but should not be used.
+  If you use setuptools, please be aware that some features that predate
+  standardisation efforts are now deprecated and only *temporarily kept* for compatibility.
   For example, do **not** use ``python setup.py`` invocations
   (cf. :ref:`setup-py-deprecated`), the ``setup_requires`` argument to
   ``setup()`` (use the :ref:`[build-system] table

From 9671ddbd04576dd068d332780d516b41bfd6da3d Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 16 Jan 2024 19:09:39 +0100
Subject: [PATCH 313/733] Various minor rewordings

---
 source/guides/tool-recommendations.rst | 43 +++++++++++++++-----------
 1 file changed, 25 insertions(+), 18 deletions(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index c9b15d164..cb5bb549a 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -66,36 +66,43 @@ Build backends
 Popular :term:`build backends ` for pure-Python packages include,
 in alphabetical order:
 
-- Flit-core_ (developed with but separate from :ref:`Flit`). It is meant to be a
-  minimal and opinionated build backend. It is not extensible.
+- Flit-core_ -- developed with but separate from :ref:`Flit`. A minimal and
+  opinionated build backend. It does not support plugins.
 
-- Hatchling_, which is developed along with :ref:`Hatch`, but is separate and can
-  be used without Hatch. Hatchling is extensible through a plugin system.
+- Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports plugins.
 
-- PDM-backend_ (developed with but separate from :ref:`PDM`). It provides build
-  hooks for extensibility.
+- PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports plugins.
 
-- Poetry-core_ (developed with but separate from :ref:`Poetry`). It is extensible
-  through plugins.
+- Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports
+  plugins.
 
-- :ref:`setuptools` (which used to be the only build backend). It can be
-  configured using modern standards like the :ref:`[project] table in
-  pyproject.toml `, but can also be extended and
-  customized via :file:`setup.py`.
+  Unlike other backends on this list, Poetry-core does not support the standard
+  :ref:`[project] table ` (it uses a different format,
+  in the ``[tool.poetry]`` table).
+
+- :ref:`setuptools`, which used to be the only build backend. Supports plugins.
 
   If you use setuptools, please be aware that some features that predate
-  standardisation efforts are now deprecated and only *temporarily kept* for compatibility.
-  For example, do **not** use ``python setup.py`` invocations
-  (cf. :ref:`setup-py-deprecated`), the ``setup_requires`` argument to
-  ``setup()`` (use the :ref:`[build-system] table
-  ` of :file:`pyproject.toml` instead), or
+  standardisation efforts are now deprecated and only *temporarily kept*
+  for compatibility.
+
+  In particular, do **not** use direct ``python setup.py`` invocations. On the
+  other hand, configuring setuptools with a :file:`setup.py` file is still fully
+  supported, although it is recommended to use the modern :ref:`[project] table
+  in pyproject.toml ` whenever possible and keep
+  :file:`setup.py` only if programmatic configuration is needed. See
+  :ref:`setup-py-deprecated`.
+
+  Other examples of deprecated features you should **not** use include the
+  ``setup_requires`` argument to ``setup()`` (use the :ref:`[build-system] table
+  ` in :file:`pyproject.toml` instead), and
   the ``easy_install`` command (cf. :ref:`pip vs easy_install`).
 
 Do **not** use :ref:`distutils`, which is deprecated, and has been removed from
 the standard library in Python 3.12, although it still remains available from
 setuptools.
 
-For packages with :term:`extension modules `, you may use
+For packages with :term:`extension modules `, it is best to use
 a build system with dedicated support for the language the extension is written in,
 for example:
 

From 80a18861ec58883f54d77263727d058202ae7e78 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Thu, 25 Jan 2024 10:42:44 +0100
Subject: [PATCH 314/733] Address review comments

---
 source/guides/tool-recommendations.rst | 43 +++++++++++++-------------
 1 file changed, 21 insertions(+), 22 deletions(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index cb5bb549a..788e51b09 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -35,11 +35,11 @@ in most Python installations through the standard library package
 :doc:`ensurepip `.
 
 Alternatively, consider :ref:`pipx` for the specific use case of installing Python
-command line applications that are distributed through PyPI.
+applications that are distributed through PyPI and run from the command line.
 Pipx is a wrapper around pip and venv that installs each
 application into a dedicated virtual environment. This avoids conflicts between
-the dependencies of different applications, and also with the system
-(especially on Linux).
+the dependencies of different applications, and also with system-wide applications
+making use of the same Python interpreter (especially on Linux).
 
 For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`.
 
@@ -66,8 +66,8 @@ Build backends
 Popular :term:`build backends ` for pure-Python packages include,
 in alphabetical order:
 
-- Flit-core_ -- developed with but separate from :ref:`Flit`. A minimal and
-  opinionated build backend. It does not support plugins.
+- :doc:`Flit-core ` -- developed with but separate from :ref:`Flit`.
+  A minimal and opinionated build backend. It does not support plugins.
 
 - Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports plugins.
 
@@ -82,21 +82,23 @@ in alphabetical order:
 
 - :ref:`setuptools`, which used to be the only build backend. Supports plugins.
 
-  If you use setuptools, please be aware that some features that predate
-  standardisation efforts are now deprecated and only *temporarily kept*
-  for compatibility.
+  .. caution::
 
-  In particular, do **not** use direct ``python setup.py`` invocations. On the
-  other hand, configuring setuptools with a :file:`setup.py` file is still fully
-  supported, although it is recommended to use the modern :ref:`[project] table
-  in pyproject.toml ` whenever possible and keep
-  :file:`setup.py` only if programmatic configuration is needed. See
-  :ref:`setup-py-deprecated`.
+     If you use setuptools, please be aware that some features that predate
+     standardisation efforts are now deprecated and only *temporarily kept*
+     for compatibility.
 
-  Other examples of deprecated features you should **not** use include the
-  ``setup_requires`` argument to ``setup()`` (use the :ref:`[build-system] table
-  ` in :file:`pyproject.toml` instead), and
-  the ``easy_install`` command (cf. :ref:`pip vs easy_install`).
+     In particular, do **not** use direct ``python setup.py`` invocations. On the
+     other hand, configuring setuptools with a :file:`setup.py` file is still fully
+     supported, although it is recommended to use the modern :ref:`[project] table
+     in pyproject.toml ` whenever possible and keep
+     :file:`setup.py` only if programmatic configuration is needed. See
+     :ref:`setup-py-deprecated`.
+
+     Other examples of deprecated features you should **not** use include the
+     ``setup_requires`` argument to ``setup()`` (use the :ref:`[build-system] table
+     ` in :file:`pyproject.toml` instead), and
+     the ``easy_install`` command (cf. :ref:`pip vs easy_install`).
 
 Do **not** use :ref:`distutils`, which is deprecated, and has been removed from
 the standard library in Python 3.12, although it still remains available from
@@ -144,7 +146,7 @@ Task runners
 These tools allow you to define and invoke "tasks", such as running tests,
 compiling documentation, regenerating some files, etc. Each task can be executed
 in a dedicated virtual environment with the dependencies it requires. The most
-common tools for this are tox_ and nox_.
+common tools for this are :doc:`tox ` and :doc:`nox `.
 
 
 Integrated workflow tools
@@ -163,9 +165,6 @@ order:
 - :ref:`Poetry`.
 
 
-.. _flit-core: https://pypi.org/project/flit-core/
 .. _hatchling: https://pypi.org/project/hatchling/
-.. _nox: https://nox.thea.codes
 .. _pdm-backend: https://backend.pdm-project.org
 .. _poetry-core: https://pypi.org/project/poetry-core/
-.. _tox: https://tox.wiki

From b5cdeb9228b3b7b18e88f06b3834fe006531ac28 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Thu, 25 Jan 2024 20:46:31 +0100
Subject: [PATCH 315/733] Mention PyPI trusted publishing

---
 ...ution-releases-using-github-actions-ci-cd-workflows.rst | 2 ++
 source/guides/tool-recommendations.rst                     | 7 ++++++-
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
index ca75d159b..99ac3a9e2 100644
--- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
+++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
@@ -1,3 +1,5 @@
+.. _trusted-publishing:
+
 =============================================================================
 Publishing package distribution releases using GitHub Actions CI/CD workflows
 =============================================================================
diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index 788e51b09..594191182 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -134,7 +134,12 @@ to build distributable wheels.
 Uploading to PyPI
 =================
 
-The standard tool for this task is :ref:`twine`.
+For projects hosted on GitHub, PyPI recommends using :ref:`trusted publishing
+`, which allows the package to be securely uploaded to PyPI
+from a GitHub Actions job. (This is not yet supported on software forges other
+than GitHub.)
+
+The other available method is to upload the package manually using :ref:`twine`.
 
 **Never** use ``python setup.py upload`` for this task. In addition to being
 :ref:`deprecated `, it is insecure.

From eab0fd88be7c7a1c2e04601e81f95a4b5f629ef3 Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Thu, 25 Jan 2024 20:48:05 +0100
Subject: [PATCH 316/733] Mention setup.cfg
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/guides/tool-recommendations.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index 594191182..cfbd7d59f 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -91,7 +91,7 @@ in alphabetical order:
      In particular, do **not** use direct ``python setup.py`` invocations. On the
      other hand, configuring setuptools with a :file:`setup.py` file is still fully
      supported, although it is recommended to use the modern :ref:`[project] table
-     in pyproject.toml ` whenever possible and keep
+     in pyproject.toml ` (or :file:`setup.cfg`) whenever possible and keep
      :file:`setup.py` only if programmatic configuration is needed. See
      :ref:`setup-py-deprecated`.
 

From c08cee83b22c4b7aea99a5b3ba62a5c63ae628dc Mon Sep 17 00:00:00 2001
From: Jean Abou-Samra 
Date: Thu, 25 Jan 2024 20:56:24 +0100
Subject: [PATCH 317/733] =?UTF-8?q?PyPI=20recommends=20=E2=86=92=20it=20is?=
 =?UTF-8?q?=20recommended?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/guides/tool-recommendations.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index cfbd7d59f..88ff6884c 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -134,7 +134,7 @@ to build distributable wheels.
 Uploading to PyPI
 =================
 
-For projects hosted on GitHub, PyPI recommends using :ref:`trusted publishing
+For projects hosted on GitHub, it is recommended to use the :ref:`trusted publishing
 `, which allows the package to be securely uploaded to PyPI
 from a GitHub Actions job. (This is not yet supported on software forges other
 than GitHub.)

From 44f086f8b82694f22a7bd8f9d9b0568da92b529a Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Thu, 25 Jan 2024 22:01:24 +0100
Subject: [PATCH 318/733] Remove sentence about global/virtual environments

---
 source/guides/tool-recommendations.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index 88ff6884c..9ba538b9d 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -28,8 +28,7 @@ Installing packages
 ===================
 
 :ref:`Pip` is the standard tool to install packages from :term:`PyPI `. It can install into the global environment or into
-virtual environments. You may want to read pip's recommendations for
+Package Index (PyPI)>`. You may want to read pip's recommendations for
 :doc:`secure installs `. Pip is available by default
 in most Python installations through the standard library package
 :doc:`ensurepip `.

From 330d33ccfa7277900da6f76f1ba16d78b8196d99 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Tue, 30 Jan 2024 11:43:51 +0100
Subject: [PATCH 319/733] Present tox/nox along workflow tools

---
 source/guides/tool-recommendations.rst | 29 +++++++++++---------------
 1 file changed, 12 insertions(+), 17 deletions(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index 9ba538b9d..fb394deca 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -144,29 +144,24 @@ The other available method is to upload the package manually using :ref:`twine`.
 :ref:`deprecated `, it is insecure.
 
 
-Task runners
-============
-
-These tools allow you to define and invoke "tasks", such as running tests,
-compiling documentation, regenerating some files, etc. Each task can be executed
-in a dedicated virtual environment with the dependencies it requires. The most
-common tools for this are :doc:`tox ` and :doc:`nox `.
-
-
-Integrated workflow tools
-=========================
+Workflow tools
+==============
 
-These are tools that combine many features in one command line application, such
-as automatically managing virtual environments for a project, building
-distributions, uploading to PyPI, or creating and using (tool-specific) lock
-files. They often call the tools mentioned above under the hood. In alphabetical
-order:
+These tools are environment managers that automatically manage virtual
+environments for a project. They also act as "task runners", allowing you to
+define and invoke tasks such as running tests, compiling documentation,
+regenerating some files, etc. Some of them provide shortcuts for building
+distributions and uploading to PyPI, and some support lock files for
+applications. They often call the tools mentioned above under the hood. In
+alphabetical order:
 
 - :ref:`Flit`,
 - :ref:`Hatch`,
+- :doc:`nox `,
 - :ref:`PDM`,
 - :ref:`Pipenv`,
-- :ref:`Poetry`.
+- :ref:`Poetry`,
+- :doc:`tox `.
 
 
 .. _hatchling: https://pypi.org/project/hatchling/

From 8bd667683c54f24ac99a161db3e206ed960dfc4c Mon Sep 17 00:00:00 2001
From: Jean Abou Samra 
Date: Thu, 1 Feb 2024 12:11:33 +0100
Subject: [PATCH 320/733] Add reminder about not steering to a particular tool

---
 source/guides/tool-recommendations.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index fb394deca..3903232b9 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -62,6 +62,12 @@ environment, for reproducibility purposes.
 Build backends
 ==============
 
+.. important::
+
+   Please, remember: this document does not seek to steer the reader towards
+   a particular tool, only to enumerate common tools. Different use cases often
+   need specialized workflows.
+
 Popular :term:`build backends ` for pure-Python packages include,
 in alphabetical order:
 

From eb73c32e8b39d7661d34dae4566c4ea0e390711d Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Sun, 25 Feb 2024 19:22:28 -0800
Subject: [PATCH 321/733] Add stack overflow to linkcheck ignore list

---
 source/conf.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/source/conf.py b/source/conf.py
index 786e67dd3..12885af3b 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -107,6 +107,8 @@
     # Temporarily ignored. Ref:
     # https://github.com/pypa/packaging.python.org/pull/1308#issuecomment-1775347690
     "https://www.breezy-vcs.org/*",
+    # Blocked due to https://github.com/pypa/packaging.python.org/pull/1474
+    "https://stackoverflow.com/*",
 ]
 linkcheck_retries = 5
 # Ignore anchors for links to GitHub project pages -- GitHub adds anchors from

From 087aa93a0c6663477f5c0ce6009d290d2305730e Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Mon, 26 Feb 2024 16:40:37 -0800
Subject: [PATCH 322/733] Clarify comment per review

---
 source/conf.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/source/conf.py b/source/conf.py
index 12885af3b..831f9c9ea 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -107,7 +107,8 @@
     # Temporarily ignored. Ref:
     # https://github.com/pypa/packaging.python.org/pull/1308#issuecomment-1775347690
     "https://www.breezy-vcs.org/*",
-    # Blocked due to https://github.com/pypa/packaging.python.org/pull/1474
+    # Ignore while StackOverflow is blocking GitHub CI. Ref:
+    # https://github.com/pypa/packaging.python.org/pull/1474
     "https://stackoverflow.com/*",
 ]
 linkcheck_retries = 5

From a45329c9a2e78ab80d74716e37e01f6ef0819ec2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edgar=20Ram=C3=ADrez-Mondrag=C3=B3n?= 
Date: Tue, 27 Feb 2024 23:43:49 -0600
Subject: [PATCH 323/733] Document the JSON schema of `direct_url.json`

---
 .../direct-url-data-structure.rst             | 122 ++++++++++++++++++
 1 file changed, 122 insertions(+)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index 993f40f59..da4d959e4 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -213,6 +213,128 @@ vcs command
    this field is the Subversion revision number in the corresponding
    repository.
 
+JSON Schema
+===========
+
+The following JSON Schema can be used to validate the contents of ``direct_url.json``:
+
+.. code-block::
+
+     {
+       "$schema": "https://json-schema.org/draft/2019-09/schema",
+       "title": "Direct URL Data",
+       "description": "Data structure that can represent URLs to python projects and distribution artifacts such as VCS source trees, local source trees, source distributions and wheels.",
+       "definitions": {
+         "URL": {
+           "type": "string",
+           "format": "uri"
+         },
+         "DirInfo": {
+           "type": "object",
+           "properties": {
+             "editable": {
+               "type": ["boolean", "null"]
+             }
+           }
+         },
+         "VCSInfo": {
+           "type": "object",
+           "properties": {
+             "vcs": {
+               "type": "string",
+               "enum": [
+                 "git",
+                 "hg",
+                 "bzr",
+                 "svn"
+               ]
+             },
+             "requested_revision": {
+               "type": "string"
+             },
+             "commit_id": {
+               "type": "string"
+             },
+             "resolved_revision": {
+               "type": "string"
+             }
+           },
+           "required": [
+             "vcs",
+             "commit_id"
+           ]
+         },
+         "ArchiveInfo": {
+           "type": "object",
+           "properties": {
+             "hash": {
+               "type": "string",
+               "pattern": "^\\w+=[a-f0-9]+$",
+               "deprecated": true
+             },
+             "hashes": {
+               "type": "object",
+               "patternProperties": {
+                 "^[a-f0-9]+$": {
+                   "type": "string"
+                 }
+               }
+             }
+           }
+         }
+       },
+       "allOf": [
+         {
+           "type": "object",
+           "properties": {
+             "url": {
+               "$ref": "#/definitions/URL"
+             }
+           },
+           "required": [
+             "url"
+           ]
+         },
+         {
+           "anyOf": [
+             {
+               "type": "object",
+               "properties": {
+                 "dir_info": {
+                   "$ref": "#/definitions/DirInfo"
+                 }
+               },
+               "required": [
+                 "dir_info"
+               ]
+             },
+             {
+               "type": "object",
+               "properties": {
+                 "vcs_info": {
+                   "$ref": "#/definitions/VCSInfo"
+                 }
+               },
+               "required": [
+                 "vcs_info"
+               ]
+             },
+             {
+               "type": "object",
+               "properties": {
+                 "archive_info": {
+                   "$ref": "#/definitions/ArchiveInfo"
+                 }
+               },
+               "required": [
+                 "archive_info"
+               ]
+             }
+           ]
+         }
+       ]
+     }
+
 Examples
 ========
 

From 3e65739d8078603eec17bc2a38a1bab1a74ccb37 Mon Sep 17 00:00:00 2001
From: Carol Willing 
Date: Thu, 29 Feb 2024 10:26:30 -0800
Subject: [PATCH 324/733] Remove example for a different failing link as pip
 has removed setup.py

---
 source/guides/single-sourcing-package-version.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/guides/single-sourcing-package-version.rst b/source/guides/single-sourcing-package-version.rst
index e487e41e1..e300fa8f7 100644
--- a/source/guides/single-sourcing-package-version.rst
+++ b/source/guides/single-sourcing-package-version.rst
@@ -9,8 +9,7 @@ Single-sourcing the package version
 There are many techniques to maintain a single source of truth for the version
 number of your project:
 
-#.  Read the file in :file:`setup.py` and get the version. Example (from `pip setup.py
-    `_)::
+#.  Read the file in :file:`setup.py` and get the version. Example::
 
         import codecs
         import os.path

From 527fadf228812a4ec3780a69134b4e30d90d3e3f Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko 
Date: Thu, 29 Feb 2024 19:42:31 +0100
Subject: [PATCH 325/733] Point pip's `setup.py` link to its latest version

This file no longer exists on the `main` branch as of
https://github.com/pypa/pip/pull/12537 /
https://github.com/pypa/pip/commit/0ad4c94b.
---
 source/guides/single-sourcing-package-version.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/source/guides/single-sourcing-package-version.rst b/source/guides/single-sourcing-package-version.rst
index e300fa8f7..5c8af21e0 100644
--- a/source/guides/single-sourcing-package-version.rst
+++ b/source/guides/single-sourcing-package-version.rst
@@ -9,7 +9,8 @@ Single-sourcing the package version
 There are many techniques to maintain a single source of truth for the version
 number of your project:
 
-#.  Read the file in :file:`setup.py` and get the version. Example::
+#.  Read the file in :file:`setup.py` and get the version. Example (from `pip setup.py
+    `_)::
 
         import codecs
         import os.path

From 421bb9157a7cc3050f1e245f2465ba8eef6e617b Mon Sep 17 00:00:00 2001
From: konstin 
Date: Wed, 21 Feb 2024 10:16:16 +0100
Subject: [PATCH 326/733] RFC: Clarify that the direct_url.json url field must
 be a spec-compliant url

Clarify that the `url` field in `direct_url.json` must be a valid url.
---
 source/specifications/direct-url-data-structure.rst | 11 ++++-------
 1 file changed, 4 insertions(+), 7 deletions(-)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index da4d959e4..01687ded2 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -10,11 +10,6 @@ This document specifies a JSON-serializable abstract data structure that can rep
 URLs to python projects and distribution artifacts such as VCS source trees, local
 source trees, source distributions and wheels.
 
-The representation of the components of this data structure as a :rfc:`1738` URL
-is not formally specified at time of writing. A common representation is the pip URL
-format. Other examples are provided in the :ref:`Version specifier specification `.
-
-
 Specification
 =============
 
@@ -22,8 +17,9 @@ The Direct URL Data Structure MUST be a dictionary, serializable to JSON accordi
 :rfc:`8259`.
 
 It MUST contain at least two fields. The first one is ``url``, with
-type ``string``. Depending on what ``url`` refers to, the second field MUST be
-one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if
+type ``string``. Its content must be a valid URL according to the
+`WHATWG URL Standard `_. Depending on what ``url`` refers to,
+the second field MUST be one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if
 ``url`` is a source archives or a wheel), or ``dir_info`` (if ``url``  is a
 local directory). These info fields have a (possibly empty) subdictionary as
 value, with the possible keys defined below.
@@ -396,3 +392,4 @@ History
 
 
 .. _archive-info-hashes: https://discuss.python.org/t/22299
+.. _whatwg-url-standard: https://url.spec.whatwg.org/

From 9e976ee1e0867453dfc667df55787c3d03220536 Mon Sep 17 00:00:00 2001
From: konstin 
Date: Wed, 21 Feb 2024 10:56:12 +0100
Subject: [PATCH 327/733] Clarify merging direct_url.json into urls paragraph

---
 source/specifications/direct-url-data-structure.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index 01687ded2..26dc39eaa 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -10,6 +10,11 @@ This document specifies a JSON-serializable abstract data structure that can rep
 URLs to python projects and distribution artifacts such as VCS source trees, local
 source trees, source distributions and wheels.
 
+At time of writing, it is not formally specified how to merge the parts of this
+file into single URL that can be passed to tools. A common representation is the
+pip URL format, other examples are provided in the
+:ref:`Version specifier specification `.
+
 Specification
 =============
 

From a8d19777dbe28ce08192e30847485240f8ce6004 Mon Sep 17 00:00:00 2001
From: konstin 
Date: Wed, 21 Feb 2024 19:36:51 +0100
Subject: [PATCH 328/733] Link to pip docs

---
 source/specifications/direct-url-data-structure.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index 26dc39eaa..d9972dc37 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -12,7 +12,7 @@ source trees, source distributions and wheels.
 
 At time of writing, it is not formally specified how to merge the parts of this
 file into single URL that can be passed to tools. A common representation is the
-pip URL format, other examples are provided in the
+pip URL format (`VCS Support `_), other examples are provided in the
 :ref:`Version specifier specification `.
 
 Specification
@@ -397,4 +397,5 @@ History
 
 
 .. _archive-info-hashes: https://discuss.python.org/t/22299
+.. _pip-vcs-support: https://pip.pypa.io/en/stable/topics/vcs-support/
 .. _whatwg-url-standard: https://url.spec.whatwg.org/

From aad6bf5921e355deeb0f6bf3e8466f077581a35b Mon Sep 17 00:00:00 2001
From: konstin 
Date: Wed, 21 Feb 2024 19:36:59 +0100
Subject: [PATCH 329/733] New paragraph

---
 source/specifications/direct-url-data-structure.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index d9972dc37..a14ebba98 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -23,8 +23,10 @@ The Direct URL Data Structure MUST be a dictionary, serializable to JSON accordi
 
 It MUST contain at least two fields. The first one is ``url``, with
 type ``string``. Its content must be a valid URL according to the
-`WHATWG URL Standard `_. Depending on what ``url`` refers to,
-the second field MUST be one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if
+`WHATWG URL Standard `_.
+
+Depending on what ``url`` refers to, the second field MUST be one of ``vcs_info``
+(if ``url`` is a VCS reference), ``archive_info`` (if
 ``url`` is a source archives or a wheel), or ``dir_info`` (if ``url``  is a
 local directory). These info fields have a (possibly empty) subdictionary as
 value, with the possible keys defined below.

From bba849252c4bed9e7a615375eece739496852d02 Mon Sep 17 00:00:00 2001
From: konsti 
Date: Thu, 22 Feb 2024 10:50:50 +0100
Subject: [PATCH 330/733] Update
 source/specifications/direct-url-data-structure.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Stéphane Bidoul 
---
 source/specifications/direct-url-data-structure.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index a14ebba98..9afe5acd5 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -11,7 +11,7 @@ URLs to python projects and distribution artifacts such as VCS source trees, loc
 source trees, source distributions and wheels.
 
 At time of writing, it is not formally specified how to merge the parts of this
-file into single URL that can be passed to tools. A common representation is the
+data structure into single URL that can be passed to tools. A common representation is the
 pip URL format (`VCS Support `_), other examples are provided in the
 :ref:`Version specifier specification `.
 

From 66c29296dfe8a0276b05f733eb0bd0d2d8c3e8c4 Mon Sep 17 00:00:00 2001
From: konsti 
Date: Sat, 2 Mar 2024 16:18:34 +0100
Subject: [PATCH 331/733] Update
 source/specifications/direct-url-data-structure.rst

Co-authored-by: chrysle 
---
 source/specifications/direct-url-data-structure.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index 9afe5acd5..d73eea4ae 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -11,7 +11,7 @@ URLs to python projects and distribution artifacts such as VCS source trees, loc
 source trees, source distributions and wheels.
 
 At time of writing, it is not formally specified how to merge the parts of this
-data structure into single URL that can be passed to tools. A common representation is the
+data structure into a single URL that can be passed to tools. A common representation is the
 pip URL format (`VCS Support `_), other examples are provided in the
 :ref:`Version specifier specification `.
 

From 0f441406f49b28bd8eca6c6258ab743b75f0d342 Mon Sep 17 00:00:00 2001
From: konsti 
Date: Sat, 2 Mar 2024 16:18:41 +0100
Subject: [PATCH 332/733] typo

Co-authored-by: chrysle 
---
 source/specifications/direct-url-data-structure.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index d73eea4ae..2dbcdae91 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -27,7 +27,7 @@ type ``string``. Its content must be a valid URL according to the
 
 Depending on what ``url`` refers to, the second field MUST be one of ``vcs_info``
 (if ``url`` is a VCS reference), ``archive_info`` (if
-``url`` is a source archives or a wheel), or ``dir_info`` (if ``url``  is a
+``url`` is a source archive or a wheel), or ``dir_info`` (if ``url``  is a
 local directory). These info fields have a (possibly empty) subdictionary as
 value, with the possible keys defined below.
 

From 35dbd1efa5b46fba1971bcdf01f4ef24351acf2b Mon Sep 17 00:00:00 2001
From: Guen Prawiroatmodjo 
Date: Wed, 6 Mar 2024 12:33:08 -0800
Subject: [PATCH 333/733] Update
 publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst

---
 ...tribution-releases-using-github-actions-ci-cd-workflows.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
index 99ac3a9e2..10c45b219 100644
--- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
+++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
@@ -169,7 +169,8 @@ Firstly, it uses the `sigstore/gh-action-sigstore-python GitHub Action`_
 to sign the distribution packages. In the next step, an empty GitHub Release
 from the current tag is created using the ``gh`` CLI. Note this step can be further
 customised. See the `gh release documentation `_
-as a reference.
+as a reference. To enable writing to GitHub Release you may need to manage your ``GITHUB_TOKEN``
+permissions, see the `GitHub documentation `_.
 
 Finally, the signed distributions are uploaded to the GitHub Release.
 

From fa39abdfb542f8f19d40a35476d0b5d66c600071 Mon Sep 17 00:00:00 2001
From: Guen Prawiroatmodjo 
Date: Wed, 6 Mar 2024 15:00:51 -0800
Subject: [PATCH 334/733] Add GITHUB_TOKEN instructions to tip admonition

---
 ...ution-releases-using-github-actions-ci-cd-workflows.rst | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
index 10c45b219..1f3d66ac8 100644
--- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
+++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
@@ -169,8 +169,11 @@ Firstly, it uses the `sigstore/gh-action-sigstore-python GitHub Action`_
 to sign the distribution packages. In the next step, an empty GitHub Release
 from the current tag is created using the ``gh`` CLI. Note this step can be further
 customised. See the `gh release documentation `_
-as a reference. To enable writing to GitHub Release you may need to manage your ``GITHUB_TOKEN``
-permissions, see the `GitHub documentation `_.
+as a reference.
+
+.. tip::
+
+   You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating the GitHub Release. See the `GitHub documentation `_ for instructions. Specifically, the token needs `content.write` permissions.
 
 Finally, the signed distributions are uploaded to the GitHub Release.
 

From ac0a64aabb95135525284a5f90b62055c4a74c2b Mon Sep 17 00:00:00 2001
From: Guen Prawiroatmodjo 
Date: Wed, 6 Mar 2024 15:05:14 -0800
Subject: [PATCH 335/733] rst ``code`` is two backticks

---
 ...stribution-releases-using-github-actions-ci-cd-workflows.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
index 1f3d66ac8..6456dd182 100644
--- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
+++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
@@ -173,7 +173,7 @@ as a reference.
 
 .. tip::
 
-   You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating the GitHub Release. See the `GitHub documentation `_ for instructions. Specifically, the token needs `content.write` permissions.
+   You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating the GitHub Release. See the `GitHub documentation `_ for instructions. Specifically, the token needs ``content.write`` permissions.
 
 Finally, the signed distributions are uploaded to the GitHub Release.
 

From c766f090ee923b739fb0b29d004f90e418268f53 Mon Sep 17 00:00:00 2001
From: Guen Prawiroatmodjo 
Date: Wed, 6 Mar 2024 15:07:38 -0800
Subject: [PATCH 336/733] Fix typo: it should be ``contents: write``

---
 ...stribution-releases-using-github-actions-ci-cd-workflows.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
index 6456dd182..006b39f8b 100644
--- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
+++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
@@ -173,7 +173,7 @@ as a reference.
 
 .. tip::
 
-   You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating the GitHub Release. See the `GitHub documentation `_ for instructions. Specifically, the token needs ``content.write`` permissions.
+   You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating the GitHub Release. See the `GitHub documentation `_ for instructions. Specifically, the token needs ``contents: write`` permissions.
 
 Finally, the signed distributions are uploaded to the GitHub Release.
 

From 643b211ea2795937d208fdb055b203a8c0e1aa1e Mon Sep 17 00:00:00 2001
From: Guen Prawiroatmodjo 
Date: Wed, 6 Mar 2024 22:48:27 -0800
Subject: [PATCH 337/733] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 ...bution-releases-using-github-actions-ci-cd-workflows.rst | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
index 006b39f8b..049fba15c 100644
--- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
+++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
@@ -173,7 +173,11 @@ as a reference.
 
 .. tip::
 
-   You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating the GitHub Release. See the `GitHub documentation `_ for instructions. Specifically, the token needs ``contents: write`` permissions.
+   You may need to manage your ``GITHUB_TOKEN`` permissions to
+   enable creating the GitHub Release. See the `GitHub
+   documentation `_
+   for instructions. Specifically, the token needs the
+   ``contents: write`` permission.
 
 Finally, the signed distributions are uploaded to the GitHub Release.
 

From d68a810030f1daffad6387142f1cf01a4a5a112b Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 19 Feb 2024 19:35:39 +0000
Subject: [PATCH 338/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.2.1 → v0.2.2](https://github.com/astral-sh/ruff-pre-commit/compare/v0.2.1...v0.2.2)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 3c24cfc46..af1c55010 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.2.1
+  rev: v0.2.2
   hooks:
     - id: ruff
     - id: ruff-format

From a0bdc2f1eb5e9dd561c49714e5103947464cbb52 Mon Sep 17 00:00:00 2001
From: Brad Campbell 
Date: Tue, 12 Mar 2024 14:43:37 -0400
Subject: [PATCH 339/733] guides: stand-alone-tools: update in 2024

The `cowsay` package now requires a `-t` argument. I also noticed the output from pipx has changed a bit over time, so I updated the output to match the current format.
---
 ...talling-stand-alone-command-line-tools.rst | 23 +++++++++++--------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/source/guides/installing-stand-alone-command-line-tools.rst b/source/guides/installing-stand-alone-command-line-tools.rst
index ecc44a487..8578a3b28 100644
--- a/source/guides/installing-stand-alone-command-line-tools.rst
+++ b/source/guides/installing-stand-alone-command-line-tools.rst
@@ -54,11 +54,11 @@ For example:
 .. code-block:: console
 
   $ pipx install cowsay
-    installed package cowsay 2.0, Python 3.6.2+
-    These binaries are now globally available
+    installed package cowsay 6.1, installed using Python 3.12.2
+    These apps are now globally available
       - cowsay
   done! ✨ 🌟 ✨
-  $ cowsay moo
+  $ cowsay -t moo
     ___
   < moo >
     ===
@@ -77,18 +77,21 @@ available, use ``pipx list``:
 .. code-block:: console
 
   $ pipx list
-  venvs are in /Users/user/.local/pipx/venvs
-  symlinks to binaries are in /Users/user/.local/bin
-     package black 18.9b0, Python 3.6.2+
+  venvs are in /Users/user/Library/Application Support/pipx/venvs
+  apps are exposed on your $PATH at /Users/user/.local/bin
+  manual pages are exposed at /Users/user/.local/share/man
+     package black 24.2.0, installed using Python 3.12.2
       - black
       - blackd
-     package cowsay 2.0, Python 3.6.2+
+     package cowsay 6.1, installed using Python 3.12.2
       - cowsay
-     package mypy 0.660, Python 3.6.2+
+     package mypy 1.9.0, installed using Python 3.12.2
       - dmypy
       - mypy
+      - mypyc
       - stubgen
-     package nox 2018.10.17, Python 3.6.2+
+      - stubtest
+     package nox 2024.3.2, installed using Python 3.12.2
       - nox
       - tox-to-nox
 
@@ -120,7 +123,7 @@ in a temporary, ephemeral environment. For example:
 
 .. code-block:: bash
 
-  pipx run cowsay moooo
+  pipx run cowsay -t moooo
 
 To see the full list of commands pipx offers, run:
 

From 2572190c9841373b8763af9948262862ae1a090a Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 12 Mar 2024 22:23:06 +0000
Subject: [PATCH 340/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.2.2 → v0.3.2](https://github.com/astral-sh/ruff-pre-commit/compare/v0.2.2...v0.3.2)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index af1c55010..7e6d4359a 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.2.2
+  rev: v0.3.2
   hooks:
     - id: ruff
     - id: ruff-format

From 0b4a494425ba208a07cb2f8acfd3f0ea107d20d0 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 8 Apr 2024 19:55:56 +0000
Subject: [PATCH 341/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/pre-commit/pre-commit-hooks: v4.5.0 → v4.6.0](https://github.com/pre-commit/pre-commit-hooks/compare/v4.5.0...v4.6.0)
- [github.com/astral-sh/ruff-pre-commit: v0.3.2 → v0.3.5](https://github.com/astral-sh/ruff-pre-commit/compare/v0.3.2...v0.3.5)
---
 .pre-commit-config.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 7e6d4359a..d5b2fe281 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.5.0
+  rev: v4.6.0
   hooks:
   - id: check-added-large-files
   - id: check-case-conflict
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.3.2
+  rev: v0.3.5
   hooks:
     - id: ruff
     - id: ruff-format

From 88449eb3c36f9a834b041fd08cf0052dccaf9313 Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Thu, 11 Apr 2024 10:32:48 +0200
Subject: [PATCH 342/733] Update packages installed in venv

---
 source/tutorials/installing-packages.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
index 0e80642ae..817148d06 100644
--- a/source/tutorials/installing-packages.rst
+++ b/source/tutorials/installing-packages.rst
@@ -224,8 +224,8 @@ environments.
 Currently, there are two common tools for creating Python virtual environments:
 
 * :doc:`venv ` is available by default in Python 3.3 and later, and installs
-  :ref:`pip` and :ref:`setuptools` into created virtual environments in
-  Python 3.4 and later.
+  :ref:`pip` into created virtual environments in Python 3.4 and later
+  (Python versions prior to 3.12 also installed :ref:`setuptools`).
 * :ref:`virtualenv` needs to be installed separately, but supports Python 2.7+
   and Python 3.3+, and :ref:`pip`, :ref:`setuptools` and :ref:`wheel` are
   always installed into created virtual environments by default (regardless of

From c5a697f68873a904373353173696715b67db9e1d Mon Sep 17 00:00:00 2001
From: Ofek Lev 
Date: Fri, 12 Apr 2024 11:23:07 -0400
Subject: [PATCH 343/733] Update language for the direct URL data structure

---
 source/specifications/direct-url-data-structure.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index 2dbcdae91..231198ee8 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -59,7 +59,9 @@ as a dictionary with the following keys:
   so an installer can hand it off without transformation to a
   checkout/download command of the VCS.
 - A ``requested_revision`` key (type ``string``) MAY be present naming a
-  branch/tag/ref/commit/revision/etc (in a format compatible with the VCS).
+  branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). This field
+  MUST match the revision requested by the user and MUST NOT exist when the user did
+  not select a specific revision.
 - A ``commit_id`` key (type ``string``) MUST be present, containing the
   exact commit/revision number that was/is to be installed.
   If the VCS supports commit-hash

From 547a95ab3e34416441d414ee3cca8111737e0682 Mon Sep 17 00:00:00 2001
From: Henry Schreiner 
Date: Mon, 15 Apr 2024 23:29:19 -0400
Subject: [PATCH 344/733] pyproject.toml: specify description is one line

---
 source/specifications/pyproject-toml.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 1580b3772..efa562a73 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -180,7 +180,8 @@ Users SHOULD prefer to specify already-normalized versions.
 - Corresponding :ref:`core metadata ` field:
   :ref:`Summary `
 
-The summary description of the project.
+The summary description of the project in one line. Tools MAY error
+if this includes multiple lines.
 
 
 ``readme``

From cb6808acf09642401e5a06b3f56516b2a05d3fa2 Mon Sep 17 00:00:00 2001
From: sam rodriguez 
Date: Tue, 30 Apr 2024 12:17:34 +0200
Subject: [PATCH 345/733] Update glossary.rst

fix seeming typo and add link to the correct term
---
 source/glossary.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index 218c21168..bff0b0426 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -16,7 +16,7 @@ Glossary
 
         A library that takes a source tree or
         :term:`source distribution `
-        and builds a source distribution or :term:`wheel ` from it.
+        and builds a :term:`built distribution ` or :term:`wheel ` from it.
         The build is delegated to the backend by a
         :term:`frontend `.
         All backends offer a standardized interface.

From 05f231be5237e616cc861312c33974a318e11491 Mon Sep 17 00:00:00 2001
From: sam rodriguez 
Date: Thu, 2 May 2024 12:26:10 +0200
Subject: [PATCH 346/733] Clearer phrasing

---
 source/glossary.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index bff0b0426..297398255 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -14,9 +14,8 @@ Glossary
 
     Build Backend
 
-        A library that takes a source tree or
-        :term:`source distribution `
-        and builds a :term:`built distribution ` or :term:`wheel ` from it.
+        A library that takes a source tree
+        and builds a :term:`source distribution ` or :term:`built distribution ` from it.
         The build is delegated to the backend by a
         :term:`frontend `.
         All backends offer a standardized interface.

From d8f425f264409951ac037b2e0500624249c6f71c Mon Sep 17 00:00:00 2001
From: wyattscarpenter 
Date: Fri, 3 May 2024 00:02:42 -0400
Subject: [PATCH 347/733] Update packaging-projects.rst: rephrase first
 explanation of __init.py__

---
 source/tutorials/packaging-projects.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 761b2748f..095abd19f 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -54,8 +54,10 @@ Create the following file structure locally:
 The directory containing the Python files should match the project name. This
 simplifies the configuration and is more obvious to users who install the package.
 
-:file:`__init__.py` is recommended to import the directory as a regular package,
-even if as is our case for this tutorial that file is empty [#namespace-packages]_.
+Creating the file :file:`__init__.py` is recommended because the existence of a
+:file:`__init__.py` file allows users to import the directory as a regular package,
+even if (as is the case for this tutorial) :file:`__init__.py` is empty.
+[#namespace-packages]_
 
 :file:`example.py` is an example of a module within the package that could
 contain the logic (functions, classes, constants, etc.) of your package.

From 9808d5d06c77d0a25b0c86433212116d34d8ae8f Mon Sep 17 00:00:00 2001
From: wyattscarpenter 
Date: Fri, 3 May 2024 00:06:26 -0400
Subject: [PATCH 348/733] Update packaging-projects.rst: you know, I reckon
 people say "a*n* __init__.py file"

---
 source/tutorials/packaging-projects.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 095abd19f..4c205e28f 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -54,9 +54,9 @@ Create the following file structure locally:
 The directory containing the Python files should match the project name. This
 simplifies the configuration and is more obvious to users who install the package.
 
-Creating the file :file:`__init__.py` is recommended because the existence of a
+Creating the file :file:`__init__.py` is recommended because the existence of an
 :file:`__init__.py` file allows users to import the directory as a regular package,
-even if (as is the case for this tutorial) :file:`__init__.py` is empty.
+even if (as is the case in this tutorial) :file:`__init__.py` is empty.
 [#namespace-packages]_
 
 :file:`example.py` is an example of a module within the package that could

From 3f2c72d68e5aa4ab4785831531c590adf6d2006d Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Sun, 5 May 2024 13:43:45 -0400
Subject: [PATCH 349/733] publish-to-test-pypi: bump action versions

---
 .../github-actions-ci-cd-sample/publish-to-test-pypi.yml      | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
index 72a3eb7b2..3bd06cccc 100644
--- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
+++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
@@ -10,7 +10,7 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: "3.x"
     - name: Install pypa/build
@@ -68,7 +68,7 @@ jobs:
         name: python-package-distributions
         path: dist/
     - name: Sign the dists with Sigstore
-      uses: sigstore/gh-action-sigstore-python@v1.2.3
+      uses: sigstore/gh-action-sigstore-python@v2.1.1
       with:
         inputs: >-
           ./dist/*.tar.gz

From 167ef2d7345c420e0b48602bdc3e3d3b682b31e7 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 6 May 2024 19:42:56 +0000
Subject: [PATCH 350/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.3.5 → v0.4.3](https://github.com/astral-sh/ruff-pre-commit/compare/v0.3.5...v0.4.3)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index d5b2fe281..b1cc54c6e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.3.5
+  rev: v0.4.3
   hooks:
     - id: ruff
     - id: ruff-format

From 9ddfba16ad4954e17efdbf2e55a63f66f12c6010 Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Mon, 6 May 2024 16:20:17 +0200
Subject: [PATCH 351/733] Add glossary definitions of packaging and metadata
 terms

The definitions were originally included in PEP 639, refining and
extending the existing glossary terms.
Having the unified vocabulary in place is essential to accurately
describe the complex Python packaging landscape.

Co-Authored-By: C.A.M. Gerlach 
---
 source/glossary.rst | 109 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 107 insertions(+), 2 deletions(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index 218c21168..e2e7b6334 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -54,6 +54,39 @@ Glossary
         Python files). See :ref:`package-formats` for more information.
 
 
+    Built Metadata
+
+        The concrete form :term:`Core Metadata` takes
+        when included inside an installed :term:`Project` (``METADATA`` file)
+        or a :term:`Distribution Archive`
+        (``PKG-INFO`` in a
+        :term:`Sdist `
+        and ``METADATA`` in a :term:`Wheel`).
+
+
+    Core Metadata
+
+        The :ref:`specification `
+        and the set of :term:`Core Metadata Field`\s it defines
+        that describe key static attributes of
+        a :term:`Distribution Package` or :term:`Installed Project`.
+
+
+    Core Metadata Field
+
+        A single key-value pair
+        (or sequence of such with the same name, for multiple-use fields)
+        defined in the :term:`Core Metadata` spec
+        and stored in the :term:`Built Metadata`.
+        Notably, distinct from a :term:`Pyproject Metadata Key`.
+
+
+    Distribution Archive
+
+        The physical distribution artifact (i.e. a file on disk)
+        for a :term:`Distribution Package`.
+
+
     Distribution Package
 
         A versioned archive file that contains Python :term:`packages ` is located.
+
+
+    Project Source Tree
+
+        The on-disk format of a :term:`Project` used for development,
+        containing its raw source code before being packaged
+        into a
+        :term:`Source Distribution `
+        or :term:`Built Distribution`.
+
+
+    Project Source Metadata
+
+        Metadata defined by the package author
+        in a :term:`Project`'s :term:`source tree `,
+        to be transformed into :term:`Core Metadata field`\s
+        in the :term:`Built Metadata`
+        by the project's build backend.
+        Can be written as :term:`Pyproject Metadata`,
+        or in a tool-specific format
+        (under the ``[tool]`` table in ``pyproject.toml``,
+        or in a tool's own configuration file).
+
+
     Pure Module
 
         A :term:`Module` written in Python and contained in a single ``.py`` file (and
         possibly associated ``.pyc`` and/or ``.pyo`` files).
 
 
+    Pyproject Metadata
+
+        The :term:`Project Source Metadata` format
+        defined by the :ref:`declaring-project-metadata` specification
+        and originally introduced in :pep:`621`,
+        stored as :term:`Pyproject Metadata Key`\s
+        under the ``[project]`` table of a :term:`pyproject.toml` file.
+        Notably, *not* a tool-specific source metadata format
+        under the ``[tool]`` table in ``pyproject.toml``.
+
+
+    Pyproject Metadata Key
+
+        A top-level TOML key in the ``[project]`` table in ``pyproject.toml``;
+        part of the :term:`Pyproject Metadata`.
+        Notably, distinct from a :term:`Core Metadata Field`.
+
+
+    Pyproject Metadata Subkey
+
+        A second-level TOML key under a table-valued
+        :term:`Pyproject Metadata Key`.
+
+
     Python Packaging Authority (PyPA)
 
         PyPA is a working group that maintains many of the relevant
@@ -236,7 +329,7 @@ Glossary
 
     Source Distribution (or "sdist")
 
-        A :term:`distribution ` format (usually generated
+        A :term:`distribution ` format (usually generated
         using ``python -m build --sdist``) that provides metadata and the
         essential source files needed for installing by a tool like :ref:`pip`,
         or for generating a :term:`Built Distribution`. See :ref:`package-formats`
@@ -264,10 +357,22 @@ Glossary
         wide. For more information, see the section on :ref:`Creating and using
         Virtual Environments`.
 
+
+    Wheel Format
     Wheel
 
-        The standard :term:`Built Distribution` format.
+        The standard :term:`Built Distribution` format
+        originally introduced in :pep:`427`
+        and defined by the :ref:`binary-distribution-format` specification.
         See :ref:`package-formats` for more information.
+        Not to be confused with its reference implementation,
+        the :term:`Wheel Project`.
+
+
+    Wheel Project
+
+        The PyPA reference implementation of the :term:`Wheel Format`.
+
 
     Working Set
 

From 25426b36dd702c43e4c6f78b75cc42d3c740e6ec Mon Sep 17 00:00:00 2001
From: Karolina Surma <33810531+befeleme@users.noreply.github.com>
Date: Tue, 7 May 2024 09:57:20 +0200
Subject: [PATCH 352/733] Apply suggestions from code review

Co-authored-by: chrysle <96722107+chrysle@users.noreply.github.com>
---
 source/glossary.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index e2e7b6334..f6675fef9 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -211,7 +211,7 @@ Glossary
         in a :term:`Project`'s :term:`source tree `,
         to be transformed into :term:`Core Metadata field`\s
         in the :term:`Built Metadata`
-        by the project's build backend.
+        by the project's :term:`build backend `.
         Can be written as :term:`Pyproject Metadata`,
         or in a tool-specific format
         (under the ``[tool]`` table in ``pyproject.toml``,
@@ -371,7 +371,7 @@ Glossary
 
     Wheel Project
 
-        The PyPA reference implementation of the :term:`Wheel Format`.
+        The PyPA reference implementation of the :term:`Wheel Format`; see :ref:`wheel`.
 
 
     Working Set

From 706b0f157bab3935d53ec9a7700985e09c2563d8 Mon Sep 17 00:00:00 2001
From: Ofek Lev 
Date: Wed, 8 May 2024 09:39:04 -0400
Subject: [PATCH 353/733] Add reference for inline script metadata spec

---
 source/specifications/inline-script-metadata.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/source/specifications/inline-script-metadata.rst b/source/specifications/inline-script-metadata.rst
index 352614e81..f40b9ac4a 100644
--- a/source/specifications/inline-script-metadata.rst
+++ b/source/specifications/inline-script-metadata.rst
@@ -1,3 +1,5 @@
+.. _inline-script-metadata:
+
 ======================
 Inline script metadata
 ======================

From abf27b61cd8ccad51a9c4f04609a5573d54c1f35 Mon Sep 17 00:00:00 2001
From: sam rodriguez 
Date: Mon, 13 May 2024 04:40:41 +0200
Subject: [PATCH 354/733] Update source/glossary.rst

Co-authored-by: chrysle <96722107+chrysle@users.noreply.github.com>
---
 source/glossary.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index 297398255..9d53e40eb 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -15,7 +15,8 @@ Glossary
     Build Backend
 
         A library that takes a source tree
-        and builds a :term:`source distribution ` or :term:`built distribution ` from it.
+        and builds a :term:`source distribution ` or 
+        :term:`built distribution ` from it.
         The build is delegated to the backend by a
         :term:`frontend `.
         All backends offer a standardized interface.

From 627ed17bb001aeda664ee6e82493703b99706b7b Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 13 May 2024 02:40:46 +0000
Subject: [PATCH 355/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/glossary.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index 9d53e40eb..58b096f46 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -15,7 +15,7 @@ Glossary
     Build Backend
 
         A library that takes a source tree
-        and builds a :term:`source distribution ` or 
+        and builds a :term:`source distribution ` or
         :term:`built distribution ` from it.
         The build is delegated to the backend by a
         :term:`frontend `.

From 01a03ce0c4ddb6a503c808bf4202f763131adba7 Mon Sep 17 00:00:00 2001
From: Geoffrey Thomas 
Date: Wed, 22 May 2024 16:40:15 -0400
Subject: [PATCH 356/733] binary-distribution-format: Update a mention of
 distutils

---
 source/specifications/binary-distribution-format.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index e2f65411b..211019f85 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -43,8 +43,8 @@ Wheel installation notionally consists of two phases:
      destination path. Each subdirectory of ``distribution-1.0.data/``
      is a key into a dict of destination directories, such as
      ``distribution-1.0.data/(purelib|platlib|headers|scripts|data)``.
-     The initially supported paths are taken from
-     ``distutils.command.install``.
+     These subdirectories are `installation paths defined by sysconfig
+     `_.
   c. If applicable, update scripts starting with ``#!python`` to point
      to the correct interpreter.
   d. Update ``distribution-1.0.dist-info/RECORD`` with the installed

From 5901ab5d4489328e1be14e62b2b0f3bda17860ae Mon Sep 17 00:00:00 2001
From: Victor Blomqvist 
Date: Sun, 26 May 2024 21:16:25 +0200
Subject: [PATCH 357/733] Create considerations_for_binary_wheels.rst

---
 .../discussions/considerations_for_binary_wheels.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)
 create mode 100644 source/discussions/considerations_for_binary_wheels.rst

diff --git a/source/discussions/considerations_for_binary_wheels.rst b/source/discussions/considerations_for_binary_wheels.rst
new file mode 100644
index 000000000..f5e1e20f8
--- /dev/null
+++ b/source/discussions/considerations_for_binary_wheels.rst
@@ -0,0 +1,12 @@
+================================
+Considerations for binary wheels
+================================
+
+Python packages with native code have a set of unique challenges not present 
+in pure packages. The more complex the native code, the more complex the 
+packaging can become. Issues arrise around topics such as non-Python compiled 
+dependencies ("native dependencies"), the importance of the ABI (Application 
+Binary Interface) of native code, dependency on SIMD code and cross 
+compilation. In depth dicussion of these and many more topics and issues around
+ native packaging is available at 
+ `pypackaging-native`.

From 413893d0c1af1e33707232d9f0b48e29b421bac4 Mon Sep 17 00:00:00 2001
From: Victor Blomqvist 
Date: Sun, 26 May 2024 21:17:47 +0200
Subject: [PATCH 358/733] And binary wheel discussion to index

---
 source/discussions/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/source/discussions/index.rst b/source/discussions/index.rst
index d262bcff2..02ceba602 100644
--- a/source/discussions/index.rst
+++ b/source/discussions/index.rst
@@ -16,3 +16,4 @@ specific topic. If you're just trying to get stuff done, see
    package-formats
    src-layout-vs-flat-layout
    setup-py-deprecated
+   considerations_for_binary_wheels

From a548da992ffd394699873f9a9359dc22df61b9ab Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sun, 26 May 2024 19:19:46 +0000
Subject: [PATCH 359/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .../discussions/considerations_for_binary_wheels.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/source/discussions/considerations_for_binary_wheels.rst b/source/discussions/considerations_for_binary_wheels.rst
index f5e1e20f8..861e7794e 100644
--- a/source/discussions/considerations_for_binary_wheels.rst
+++ b/source/discussions/considerations_for_binary_wheels.rst
@@ -2,11 +2,11 @@
 Considerations for binary wheels
 ================================
 
-Python packages with native code have a set of unique challenges not present 
-in pure packages. The more complex the native code, the more complex the 
-packaging can become. Issues arrise around topics such as non-Python compiled 
-dependencies ("native dependencies"), the importance of the ABI (Application 
-Binary Interface) of native code, dependency on SIMD code and cross 
+Python packages with native code have a set of unique challenges not present
+in pure packages. The more complex the native code, the more complex the
+packaging can become. Issues arrise around topics such as non-Python compiled
+dependencies ("native dependencies"), the importance of the ABI (Application
+Binary Interface) of native code, dependency on SIMD code and cross
 compilation. In depth dicussion of these and many more topics and issues around
- native packaging is available at 
+ native packaging is available at
  `pypackaging-native`.

From 380b8d19be61104df65dac7c547d180ab056ef58 Mon Sep 17 00:00:00 2001
From: Victor Blomqvist 
Date: Sun, 26 May 2024 21:27:21 +0200
Subject: [PATCH 360/733] Fix link in considerations_for_binary_wheels.rst

---
 source/discussions/considerations_for_binary_wheels.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/considerations_for_binary_wheels.rst b/source/discussions/considerations_for_binary_wheels.rst
index 861e7794e..4158de1ea 100644
--- a/source/discussions/considerations_for_binary_wheels.rst
+++ b/source/discussions/considerations_for_binary_wheels.rst
@@ -9,4 +9,4 @@ dependencies ("native dependencies"), the importance of the ABI (Application
 Binary Interface) of native code, dependency on SIMD code and cross
 compilation. In depth dicussion of these and many more topics and issues around
  native packaging is available at
- `pypackaging-native`.
+ `pypackaging-native`_.

From 203c79d9527f66ae90cb385929f537616c845223 Mon Sep 17 00:00:00 2001
From: Victor Blomqvist 
Date: Mon, 27 May 2024 21:29:08 +0200
Subject: [PATCH 361/733] Update
 source/discussions/considerations_for_binary_wheels.rst

Co-authored-by: chrysle <96722107+chrysle@users.noreply.github.com>
---
 source/discussions/considerations_for_binary_wheels.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/considerations_for_binary_wheels.rst b/source/discussions/considerations_for_binary_wheels.rst
index 4158de1ea..49d89e394 100644
--- a/source/discussions/considerations_for_binary_wheels.rst
+++ b/source/discussions/considerations_for_binary_wheels.rst
@@ -7,6 +7,6 @@ in pure packages. The more complex the native code, the more complex the
 packaging can become. Issues arrise around topics such as non-Python compiled
 dependencies ("native dependencies"), the importance of the ABI (Application
 Binary Interface) of native code, dependency on SIMD code and cross
-compilation. In depth dicussion of these and many more topics and issues around
+compilation. In depth discussion of these and many more topics and issues around
  native packaging is available at
  `pypackaging-native`_.

From 639ef8a21f07da1bfc4010da2247a3412bf25d04 Mon Sep 17 00:00:00 2001
From: Victor Blomqvist 
Date: Mon, 27 May 2024 21:29:20 +0200
Subject: [PATCH 362/733] Update
 source/discussions/considerations_for_binary_wheels.rst

Co-authored-by: chrysle <96722107+chrysle@users.noreply.github.com>
---
 source/discussions/considerations_for_binary_wheels.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/discussions/considerations_for_binary_wheels.rst b/source/discussions/considerations_for_binary_wheels.rst
index 49d89e394..cfca706c7 100644
--- a/source/discussions/considerations_for_binary_wheels.rst
+++ b/source/discussions/considerations_for_binary_wheels.rst
@@ -8,5 +8,4 @@ packaging can become. Issues arrise around topics such as non-Python compiled
 dependencies ("native dependencies"), the importance of the ABI (Application
 Binary Interface) of native code, dependency on SIMD code and cross
 compilation. In depth discussion of these and many more topics and issues around
- native packaging is available at
- `pypackaging-native`_.
+native packaging is available at `pypackaging-native `_.

From 5a89e74e83b92cfaa455dbedf87869ed4641ada9 Mon Sep 17 00:00:00 2001
From: Victor Blomqvist 
Date: Sat, 1 Jun 2024 21:35:50 +0200
Subject: [PATCH 363/733] Added link to pypackaging-native on packaging binary
 extensions page

---
 .../discussions/considerations_for_binary_wheels.rst | 11 -----------
 source/discussions/index.rst                         |  1 -
 source/guides/packaging-binary-extensions.rst        | 12 ++++++++++++
 3 files changed, 12 insertions(+), 12 deletions(-)
 delete mode 100644 source/discussions/considerations_for_binary_wheels.rst

diff --git a/source/discussions/considerations_for_binary_wheels.rst b/source/discussions/considerations_for_binary_wheels.rst
deleted file mode 100644
index cfca706c7..000000000
--- a/source/discussions/considerations_for_binary_wheels.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-================================
-Considerations for binary wheels
-================================
-
-Python packages with native code have a set of unique challenges not present
-in pure packages. The more complex the native code, the more complex the
-packaging can become. Issues arrise around topics such as non-Python compiled
-dependencies ("native dependencies"), the importance of the ABI (Application
-Binary Interface) of native code, dependency on SIMD code and cross
-compilation. In depth discussion of these and many more topics and issues around
-native packaging is available at `pypackaging-native `_.
diff --git a/source/discussions/index.rst b/source/discussions/index.rst
index 02ceba602..d262bcff2 100644
--- a/source/discussions/index.rst
+++ b/source/discussions/index.rst
@@ -16,4 +16,3 @@ specific topic. If you're just trying to get stuff done, see
    package-formats
    src-layout-vs-flat-layout
    setup-py-deprecated
-   considerations_for_binary_wheels
diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst
index 589ed89c8..b664d68a4 100644
--- a/source/guides/packaging-binary-extensions.rst
+++ b/source/guides/packaging-binary-extensions.rst
@@ -403,3 +403,15 @@ a Debian system, see the following articles:
 * `What are (c)python extension modules? `_
 * `Releasing the gil `_
 * `Writing cpython extension modules using C++ `_
+
+Additional considerations for binary wheels
+-------------------------------------------
+
+The `pypackaging-native `_ website has 
+additional coverage of packaging Python packages with native code. It aims to 
+provide an overview of the most important packaging issues for such projects, 
+with in-depth explanations and references.
+
+Topics cover for example non-Python compiled dependencies ("native dependencies"), 
+the importance of the ABI (Application Binary Interface) of native code, 
+dependency on SIMD code and cross compilation. 

From fb2192df714ec14879ec2ef7e37050481339512b Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sat, 1 Jun 2024 19:36:03 +0000
Subject: [PATCH 364/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/guides/packaging-binary-extensions.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst
index b664d68a4..ff7298658 100644
--- a/source/guides/packaging-binary-extensions.rst
+++ b/source/guides/packaging-binary-extensions.rst
@@ -407,11 +407,11 @@ a Debian system, see the following articles:
 Additional considerations for binary wheels
 -------------------------------------------
 
-The `pypackaging-native `_ website has 
-additional coverage of packaging Python packages with native code. It aims to 
-provide an overview of the most important packaging issues for such projects, 
+The `pypackaging-native `_ website has
+additional coverage of packaging Python packages with native code. It aims to
+provide an overview of the most important packaging issues for such projects,
 with in-depth explanations and references.
 
-Topics cover for example non-Python compiled dependencies ("native dependencies"), 
-the importance of the ABI (Application Binary Interface) of native code, 
-dependency on SIMD code and cross compilation. 
+Topics cover for example non-Python compiled dependencies ("native dependencies"),
+the importance of the ABI (Application Binary Interface) of native code,
+dependency on SIMD code and cross compilation.

From bd9956a0f90865ce704bb19587ab6c1129bb4c80 Mon Sep 17 00:00:00 2001
From: Victor Blomqvist 
Date: Sat, 1 Jun 2024 21:57:05 +0200
Subject: [PATCH 365/733] Minor improvement of text

---
 source/guides/packaging-binary-extensions.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst
index b664d68a4..25a897d2e 100644
--- a/source/guides/packaging-binary-extensions.rst
+++ b/source/guides/packaging-binary-extensions.rst
@@ -412,6 +412,6 @@ additional coverage of packaging Python packages with native code. It aims to
 provide an overview of the most important packaging issues for such projects, 
 with in-depth explanations and references.
 
-Topics cover for example non-Python compiled dependencies ("native dependencies"), 
+Example of topics are non-Python compiled dependencies ("native dependencies"), 
 the importance of the ABI (Application Binary Interface) of native code, 
 dependency on SIMD code and cross compilation. 

From ce3653dc5f0f7376cc240954ecac71528ce2022e Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sat, 1 Jun 2024 19:58:24 +0000
Subject: [PATCH 366/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/guides/packaging-binary-extensions.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst
index 4a3be2cc3..de8a9d2d6 100644
--- a/source/guides/packaging-binary-extensions.rst
+++ b/source/guides/packaging-binary-extensions.rst
@@ -412,6 +412,6 @@ additional coverage of packaging Python packages with native code. It aims to
 provide an overview of the most important packaging issues for such projects,
 with in-depth explanations and references.
 
-Examples of topics covered are non-Python compiled dependencies ("native 
-dependencies"), the importance of the ABI (Application Binary Interface) of 
+Examples of topics covered are non-Python compiled dependencies ("native
+dependencies"), the importance of the ABI (Application Binary Interface) of
 native code, dependency on SIMD code and cross compilation.

From f70787f91f8e8eee48365e60b576f0ff70285ab2 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 17 Jun 2024 19:46:45 +0000
Subject: [PATCH 367/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/codespell-project/codespell: v2.2.6 → v2.3.0](https://github.com/codespell-project/codespell/compare/v2.2.6...v2.3.0)
- [github.com/astral-sh/ruff-pre-commit: v0.4.3 → v0.4.9](https://github.com/astral-sh/ruff-pre-commit/compare/v0.4.3...v0.4.9)
---
 .pre-commit-config.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index b1cc54c6e..de44b7a34 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -12,7 +12,7 @@ repos:
   - id: trailing-whitespace
 
 - repo: https://github.com/codespell-project/codespell
-  rev: v2.2.6
+  rev: v2.3.0
   hooks:
   - id: codespell
     args: ["-L", "ned,ist,oder", "--skip", "*.po"]
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.4.3
+  rev: v0.4.9
   hooks:
     - id: ruff
     - id: ruff-format

From 82280c02107fa1b3f946de89325f1575cdd8287b Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan 
Date: Wed, 19 Jun 2024 21:37:22 +1000
Subject: [PATCH 368/733] Add HTML snippet for Plausible metrics

Metrics are only collected for the main packaging.python.org
documentation deployments.

Closes #1561
---
 source/conf.py | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/source/conf.py b/source/conf.py
index 831f9c9ea..be5f7f149 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -1,6 +1,14 @@
 # -- Project information ---------------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import os
+
+# Some options are only enabled for the main packaging.python.org deployment builds
+RTD_BUILD = bool(os.getenv("READTHEDOCS"))
+RTD_PR_BUILD = RTD_BUILD and os.getenv("READTHEDOCS_VERSION_TYPE") == "external"
+RTD_URL = os.getenv("READTHEDOCS_CANONICAL_URL")
+RTD_CANONICAL_BUILD = RTD_BUILD and not RTD_PR_BUILD and "packaging.python.org" in RTD_URL
+
 project = "Python Packaging User Guide"
 
 copyright = "2013–2020, PyPA"
@@ -55,6 +63,15 @@
 html_favicon = "assets/py.png"
 html_last_updated_fmt = ""
 
+_metrics_js_files = [
+    ("https://plausible.io/js/script.js", {"data-domain": "packaging.python.org"})
+]
+html_js_files = []
+if RTD_CANONICAL_BUILD:
+    # Enable collection of the visitor metrics reported at
+    # https://plausible.io/packaging.python.org
+    html_js_files.extend(_metrics_js_files)
+
 # -- Options for HTML help output ------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-help-output
 

From 5bf53f3eba538f4e8953ca66f36ddb5d3e8963d9 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 19 Jun 2024 11:37:57 +0000
Subject: [PATCH 369/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/conf.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/source/conf.py b/source/conf.py
index be5f7f149..3817ce1d3 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -7,7 +7,9 @@
 RTD_BUILD = bool(os.getenv("READTHEDOCS"))
 RTD_PR_BUILD = RTD_BUILD and os.getenv("READTHEDOCS_VERSION_TYPE") == "external"
 RTD_URL = os.getenv("READTHEDOCS_CANONICAL_URL")
-RTD_CANONICAL_BUILD = RTD_BUILD and not RTD_PR_BUILD and "packaging.python.org" in RTD_URL
+RTD_CANONICAL_BUILD = (
+    RTD_BUILD and not RTD_PR_BUILD and "packaging.python.org" in RTD_URL
+)
 
 project = "Python Packaging User Guide"
 

From c37de0523ac61c8b2a9608a9e7b2314c88d293b0 Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan 
Date: Wed, 19 Jun 2024 23:22:36 +1000
Subject: [PATCH 370/733] Defer loading metrics JS

---
 source/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/conf.py b/source/conf.py
index 3817ce1d3..92c1290cc 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -66,7 +66,7 @@
 html_last_updated_fmt = ""
 
 _metrics_js_files = [
-    ("https://plausible.io/js/script.js", {"data-domain": "packaging.python.org"})
+    ("https://plausible.io/js/script.js", {"data-domain": "packaging.python.org", "defer": "defer"})
 ]
 html_js_files = []
 if RTD_CANONICAL_BUILD:

From db35d2764a9ad62dedf231b75bab05d1046ead4c Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 19 Jun 2024 13:22:48 +0000
Subject: [PATCH 371/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/conf.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/source/conf.py b/source/conf.py
index 92c1290cc..cd459ffb2 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -66,7 +66,10 @@
 html_last_updated_fmt = ""
 
 _metrics_js_files = [
-    ("https://plausible.io/js/script.js", {"data-domain": "packaging.python.org", "defer": "defer"})
+    (
+        "https://plausible.io/js/script.js",
+        {"data-domain": "packaging.python.org", "defer": "defer"},
+    )
 ]
 html_js_files = []
 if RTD_CANONICAL_BUILD:

From 4af7da079f97a91fdb8f53155be84258bf1f524d Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan 
Date: Thu, 20 Jun 2024 02:26:34 +1000
Subject: [PATCH 372/733] Use intersphinx reference

---
 source/specifications/binary-distribution-format.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index 211019f85..692e6f642 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -43,8 +43,8 @@ Wheel installation notionally consists of two phases:
      destination path. Each subdirectory of ``distribution-1.0.data/``
      is a key into a dict of destination directories, such as
      ``distribution-1.0.data/(purelib|platlib|headers|scripts|data)``.
-     These subdirectories are `installation paths defined by sysconfig
-     `_.
+     These subdirectories are :ref:`installation paths defined by sysconfig
+     `_.
   c. If applicable, update scripts starting with ``#!python`` to point
      to the correct interpreter.
   d. Update ``distribution-1.0.dist-info/RECORD`` with the installed

From 5c432f6a043a0988ab5814f978c6387daf28765a Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan 
Date: Thu, 20 Jun 2024 02:29:44 +1000
Subject: [PATCH 373/733] Fix ref syntax and target name

---
 source/specifications/binary-distribution-format.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index 692e6f642..8da38357a 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -44,7 +44,7 @@ Wheel installation notionally consists of two phases:
      is a key into a dict of destination directories, such as
      ``distribution-1.0.data/(purelib|platlib|headers|scripts|data)``.
      These subdirectories are :ref:`installation paths defined by sysconfig
-     `_.
+     `.
   c. If applicable, update scripts starting with ``#!python`` to point
      to the correct interpreter.
   d. Update ``distribution-1.0.dist-info/RECORD`` with the installed

From 77a87f2f6ce25f38e3672d05bd7ee378157de0b5 Mon Sep 17 00:00:00 2001
From: Daniel Schultz 
Date: Thu, 20 Jun 2024 14:27:13 -0400
Subject: [PATCH 374/733] Fix a typo

---
 source/guides/writing-pyproject-toml.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 938ebbb93..e82bd893d 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -340,7 +340,7 @@ or you can write the name of the license:
     license = {text = "MIT License"}
 
 If you are using a standard, well-known license, it is not necessary to use this
-field. Instead, you should one of the :ref:`classifiers` starting with ``License
+field. Instead, you should use one of the :ref:`classifiers` starting with ``License
 ::``. (As a general rule, it is a good idea to use a standard, well-known
 license, both to avoid confusion and because some organizations avoid software
 whose license is unapproved.)

From c0953f394e467281a77afa9c42a41ee7d8bcbdb2 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 24 Jun 2024 19:47:21 +0000
Subject: [PATCH 375/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.4.9 → v0.4.10](https://github.com/astral-sh/ruff-pre-commit/compare/v0.4.9...v0.4.10)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index de44b7a34..c6372ec30 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.4.9
+  rev: v0.4.10
   hooks:
     - id: ruff
     - id: ruff-format

From 3a4616755d742e8c7c29b88e2e686e50ce6452b4 Mon Sep 17 00:00:00 2001
From: Matthew Donoughe 
Date: Tue, 21 May 2024 09:26:36 -0400
Subject: [PATCH 376/733] allow trailing comma in version_many

---
 source/specifications/dependency-specifiers.rst | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index b6c867084..e35d22b14 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -66,7 +66,7 @@ URI is defined in :rfc:`std-66 <3986>`)::
     version_cmp   = wsp* '<' | '<=' | '!=' | '==' | '>=' | '>' | '~=' | '==='
     version       = wsp* ( letterOrDigit | '-' | '_' | '.' | '*' | '+' | '!' )+
     version_one   = version_cmp version wsp*
-    version_many  = version_one (wsp* ',' version_one)*
+    version_many  = version_one (',' version_one)* (',' wsp*)?
     versionspec   = ( '(' version_many ')' ) | version_many
     urlspec       = '@' wsp* 
 
@@ -303,7 +303,7 @@ The complete parsley grammar::
     version_cmp   = wsp* <'<=' | '<' | '!=' | '==' | '>=' | '>' | '~=' | '==='>
     version       = wsp* <( letterOrDigit | '-' | '_' | '.' | '*' | '+' | '!' )+>
     version_one   = version_cmp:op version:v wsp* -> (op, v)
-    version_many  = version_one:v1 (wsp* ',' version_one)*:v2 -> [v1] + v2
+    version_many  = version_one:v1 (',' version_one)*:v2 (',' wsp*)? -> [v1] + v2
     versionspec   = ('(' version_many:v ')' ->v) | version_many
     urlspec       = '@' wsp* 
     marker_op     = version_cmp | (wsp* 'in') | (wsp* 'not' wsp+ 'in')
@@ -424,6 +424,7 @@ A test program - if the grammar is in a string ``grammar``:
         "name",
         "name<=1",
         "name>=3",
+        "name>=3,",
         "name>=3,<2",
         "name@http://foo.com",
         "name [fred,bar] @ http://foo.com ; python_version=='2.7'",
@@ -481,6 +482,9 @@ History
   ``'.'.join(platform.python_version_tuple()[:2])``, to accommodate potential
   future versions of Python with 2-digit major and minor versions
   (e.g. 3.10). [#future_versions]_
+- May 2024: The definition of ``version_many`` was changed to allow trailing
+  commas, matching with the behavior of the Python implementation that has been
+  in use since late 2022.
 
 
 References

From e496a99cb2b89fd496b4522e4fea40aa4311bfd7 Mon Sep 17 00:00:00 2001
From: Matthew Donoughe 
Date: Wed, 26 Jun 2024 08:10:26 -0400
Subject: [PATCH 377/733] update month

---
 source/specifications/dependency-specifiers.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index e35d22b14..d6713f713 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -482,7 +482,7 @@ History
   ``'.'.join(platform.python_version_tuple()[:2])``, to accommodate potential
   future versions of Python with 2-digit major and minor versions
   (e.g. 3.10). [#future_versions]_
-- May 2024: The definition of ``version_many`` was changed to allow trailing
+- June 2024: The definition of ``version_many`` was changed to allow trailing
   commas, matching with the behavior of the Python implementation that has been
   in use since late 2022.
 

From ade43fa7f52f091994a7ec578332e4c842f8e99c Mon Sep 17 00:00:00 2001
From: Christopher Covington 
Date: Fri, 12 Jul 2024 10:51:10 +0000
Subject: [PATCH 378/733] Fix conflicting classification of install

The first paragraph says the command must not be run anymore.
---
 source/discussions/setup-py-deprecated.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/source/discussions/setup-py-deprecated.rst b/source/discussions/setup-py-deprecated.rst
index 4993d8a0d..1c2eae3fa 100644
--- a/source/discussions/setup-py-deprecated.rst
+++ b/source/discussions/setup-py-deprecated.rst
@@ -141,7 +141,6 @@ This guide does not make suggestions of replacement solutions for those commands
     * ``easy_install``
     * ``editable_wheel``
     * ``egg_info``
-    * ``install``
     * ``install_data``
     * ``install_egg_info``
     * ``install_headers``

From 8891fa5417c7ed0b60fab07c276d237cce8624ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A2muran=20=C4=B0mran?=
 <73625486+kamurani@users.noreply.github.com>
Date: Mon, 29 Jul 2024 15:45:21 +1000
Subject: [PATCH 379/733] fix typo

---
 source/guides/writing-pyproject-toml.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index e82bd893d..18a717a55 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -130,7 +130,7 @@ only field that cannot be marked as dynamic.
    [project]
    name = "spam-eggs"
 
-The project name must consists of ASCII letters, digits, underscores "``_``",
+The project name must consist of ASCII letters, digits, underscores "``_``",
 hyphens "``-``" and periods "``.``". It must not start or end with an
 underscore, hyphen or period.
 

From 4a5cbf920c6a7c7a37e155ff4c74c27a118d3e0b Mon Sep 17 00:00:00 2001
From: chrysle 
Date: Sat, 23 Dec 2023 15:21:43 +0100
Subject: [PATCH 380/733] Update "Dropping older Python versions" guide

---
 .../guides/dropping-older-python-versions.rst | 93 +++++++++++--------
 1 file changed, 53 insertions(+), 40 deletions(-)

diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst
index c0c2b4434..1804f35c2 100644
--- a/source/guides/dropping-older-python-versions.rst
+++ b/source/guides/dropping-older-python-versions.rst
@@ -4,23 +4,17 @@
 Dropping support for older Python versions
 ==========================================
 
-Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a "Requires-Python" attribute.
+Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a :ref:`"Requires-Python" ` attribute.
 
 Metadata 1.2+ clients, such as Pip 9.0+, will adhere to this specification by matching the current Python runtime and comparing it with the required version
 in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime.
 
-This mechanism can be used to drop support for older Python versions, by amending the "Requires-Python" attribute in the package metadata.
-
-This guide is specifically for users of :ref:`setuptools`, other packaging tools such as ``flit`` may offer similar functionality but users will need to consult relevant documentation.
+This mechanism can be used to drop support for older Python versions, by amending the ``Requires-Python`` attribute in the package metadata.
 
 Requirements
 ------------
 
-This workflow requires that:
-
-1. The publisher is using the latest version of :ref:`setuptools`,
-2. The latest version of :ref:`twine` is used to upload the package,
-3. The user installing the package has at least Pip 9.0, or a client that supports the Metadata 1.2 specification.
+This workflow requires that the user installing the package has at least Pip 9.0, or a client that supports the Metadata 1.2 specification.
 
 Dealing with the universal wheels
 ---------------------------------
@@ -52,42 +46,50 @@ explicitly set ``universal`` to ``0``:
 Defining the Python version required
 ------------------------------------
 
-1. Download the newest version of Setuptools
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Ensure that before you generate source distributions or binary distributions, you update Setuptools and install twine.
+1. Install twine
+~~~~~~~~~~~~~~~~
 
+Ensure that you have twine available at its latest version.
 Steps:
 
 .. tab:: Unix/macOS
 
     .. code-block:: bash
 
-        python3 -m pip install --upgrade setuptools twine
+        python3 -m pip install --upgrade twine
 
 .. tab:: Windows
 
     .. code-block:: bat
 
-        py -m pip install --upgrade setuptools twine
-
-``setuptools`` version should be above 24.0.0.
+        py -m pip install --upgrade twine
 
 2. Specify the version ranges for supported Python distributions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can specify version ranges and exclusion rules, such as at least Python 3. Or, Python 2.7, 3.4 and beyond.
-
-Examples:
+You can specify version ranges and exclusion rules (complying with the :ref:`version-specifiers` specification),
+such as at least Python 3. Or, Python 2.7, 3.4 and beyond:
 
 .. code-block:: text
 
-    Requires-Python: ">=3"
-    Requires-Python: ">2.7,!=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
+    Requires-Python: ">= 3"
+    Requires-Python: ">= 2.7, != 3.0.*, != 3.1.*, != 3.2.*, != 3.3.*"
+
+
+The way to set those values is within your :file:`pyproject.toml`. The :ref:`requires-python` field of the
+``[project]`` table corresponds to the ``Requires-Python`` metadata field.
+
+.. code-block:: toml
 
-The way to set those values is within the call to ``setup`` within your
-:file:`setup.py` script. This will insert the ``Requires-Python``
-metadata values based on the argument you provide in ``python_requires``.
+   [build-system]
+   ...
+
+   [project]
+   requires-python = ">= 3.8" # At least Python 3.8
+
+
+For :ref:`setuptools` users, another way to achieve this is using the ``python_requires`` parameter
+in the call to ``setup`` within your :file:`setup.py` script.
 
 .. code-block:: python
 
@@ -96,43 +98,54 @@ metadata values based on the argument you provide in ``python_requires``.
 
     setup(
         # Your setup arguments
-        python_requires='>=2.7',  # Your supported Python ranges
+        python_requires='>= 3.8',
     )
 
+It is warned against adding upper bounds to the version ranges, e. g. ``">= 3.8 < 3.10"``. This can cause different errors
+and version conflicts. See the `discourse discussion`_ for more information.
+
 3. Validating the Metadata before publishing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Within a Python source package (the zip or the tar-gz file you download) is a text file called PKG-INFO.
 
-This file is generated by :ref:`distutils` or :ref:`setuptools` when it generates the source package.
-The file contains a set of keys and values, the list of keys is part of the PyPa standard metadata format.
+This file is generated by the build backend when it generates the source package.
+The file contains a set of keys and values, the list of keys is part of the PyPA standard metadata format.
 
 You can see the contents of the generated file like this:
 
 .. code-block:: bash
 
-    tar xfO dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO
+    tar xf dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO -O
 
 Validate that the following is in place, before publishing the package:
 
 - If you have upgraded correctly, the Metadata-Version value should be 1.2 or higher.
-- The Requires-Python field is set and matches your specification in setup.py.
+- The ``Requires-Python`` field is set and matches your specification in the configuration file.
 
-4. Using Twine to publish
+4. Publishing the package
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Twine has a number of advantages, apart from being faster it is now the supported method for publishing packages.
+Proceed as suggested in :ref:`Uploading your Project to PyPI`.
 
-Make sure you are using the newest version of Twine, at least 1.9.
-
-Dropping a Python release
+Dropping a Python version
 -------------------------
 
-Once you have published a package with the Requires-Python metadata, you can then make a further update removing that Python runtime from support.
+In principle, at least metadata support for Python versions should be kept as long as possible, because
+once that has been dropped, people still depending on a version will be forced to downgrade.
+If however supporting a specific version becomes a blocker for a new feature or other issues occur, the metadata
+``Requires-Python`` should be amended. Of course this also depends on whether the project needs to be stable and
+well-covered for a wider range of users.
+
+Each version compatibility change should have an own release.
+
+For example, you published version 1.0.0 of your package with ``Requires-Python: ">= 2.7"`` metadata.
+
+If you then update the version string to ``">= 3.5"``, and publish a new version 2.0.0 of your package, any users running Pip 9.0+ from version 2.7 will have version 1.0.0 of the package installed, and any ``>= 3.5`` users will receive version 2.0.0.
 
-It must be done in this order for the automated fallback to work.
+It may be a good idea to create a minor release, stating that it is the last one compatible with the Python version to be removed, just before dropping that version.
 
-For example, you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.
+When dropping a Python version, it might also be rewarding to upgrade the project's code syntax generally, apart from updating the versions used in visible places (like the testing environment). Tools like pyupgrade_ can simplify this task.
 
-If you were then to update the version string to ">=3.5", and publish a new version 2.0.0 of your package, any users running Pip 9.0+ from version 2.7 will
-have version 1.0.0 of the package installed, and any >=3.5 users will receive version 2.0.0.
+.. _discourse discussion: https://discuss.python.org/t/requires-python-upper-limits/12663
+.. _pyupgrade: https://pypi.org/project/pyupgrade/

From a02e0691a89d59d128302ff4223e443d7476c439 Mon Sep 17 00:00:00 2001
From: chrysle <96722107+chrysle@users.noreply.github.com>
Date: Fri, 5 Jul 2024 16:11:49 +0200
Subject: [PATCH 381/733] Apply review comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <578543+webknjaz@users.noreply.github.com>
Co-authored-by: Jean Abou Samra <37271310+jeanas@users.noreply.github.com>
Co-authored-by: Edgar Ramírez Mondragón <16805946+edgarrmondragon@users.noreply.github.com>
---
 .../guides/dropping-older-python-versions.rst | 64 ++++++++-----------
 1 file changed, 28 insertions(+), 36 deletions(-)

diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst
index 1804f35c2..9fdc35fa8 100644
--- a/source/guides/dropping-older-python-versions.rst
+++ b/source/guides/dropping-older-python-versions.rst
@@ -4,9 +4,9 @@
 Dropping support for older Python versions
 ==========================================
 
-Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a :ref:`"Requires-Python" ` attribute.
+The ability to drop support for older Python versions is enabled by the standard :ref:`core-metadata` 1.2 specification via the :ref:`"Requires-Python" ` attribute.
 
-Metadata 1.2+ clients, such as Pip 9.0+, will adhere to this specification by matching the current Python runtime and comparing it with the required version
+Metadata 1.2+ clients, such as Pip, will adhere to this specification by matching the current Python runtime and comparing it with the required version
 in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime.
 
 This mechanism can be used to drop support for older Python versions, by amending the ``Requires-Python`` attribute in the package metadata.
@@ -14,18 +14,17 @@ This mechanism can be used to drop support for older Python versions, by amendin
 Requirements
 ------------
 
-This workflow requires that the user installing the package has at least Pip 9.0, or a client that supports the Metadata 1.2 specification.
+This workflow requires that the user installing the package uses Pip [#]_, or another client that supports the Metadata 1.2 specification.
 
 Dealing with the universal wheels
 ---------------------------------
 
-Traditionally, projects providing Python code that is semantically
+Traditionally, :ref:`setuptools` projects providing Python code that is semantically
 compatible with both Python 2 and Python 3, produce :term:`wheels
 ` that have a ``py2.py3`` tag in their names. When dropping
 support for Python 2, it is important not to forget to change this tag
 to just ``py3``. It is often configured within :file:`setup.cfg` under
-the ``[bdist_wheel]`` section by setting ``universal = 1`` if they
-use setuptools.
+the ``[bdist_wheel]`` section by setting ``universal = 1``.
 
 If you use this method, either remove this option or section, or
 explicitly set ``universal`` to ``0``:
@@ -37,11 +36,10 @@ explicitly set ``universal`` to ``0``:
    [bdist_wheel]
    universal = 0  # Make the generated wheels have "py3" tag
 
-.. tip::
+.. hint::
 
-   Since it is possible to override the :file:`setup.cfg` settings via
-   CLI flags, make sure that your scripts don't have ``--universal`` in
-   your package creation scripts.
+   Regarding :ref:`deprecated ` direct ``setup.py`` invocations,
+   passing the ``--universal`` flag on the command line could override this setting.
 
 Defining the Python version required
 ------------------------------------
@@ -68,16 +66,16 @@ Steps:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can specify version ranges and exclusion rules (complying with the :ref:`version-specifiers` specification),
-such as at least Python 3. Or, Python 2.7, 3.4 and beyond:
+such as at least Python 3. Or, Python 3.7, 3.8, 3.13 and beyond:
 
 .. code-block:: text
 
     Requires-Python: ">= 3"
-    Requires-Python: ">= 2.7, != 3.0.*, != 3.1.*, != 3.2.*, != 3.3.*"
+    Requires-Python: ">= 3.7, != 3.9.*, != 3.10.*, != 3.11.*, != 3.12.*"
 
 
-The way to set those values is within your :file:`pyproject.toml`. The :ref:`requires-python` field of the
-``[project]`` table corresponds to the ``Requires-Python`` metadata field.
+Those values can be set within your :file:`pyproject.toml`. The :ref:`requires-python` configuration field
+corresponds to the ``Requires-Python`` metadata field.
 
 .. code-block:: toml
 
@@ -89,34 +87,29 @@ The way to set those values is within your :file:`pyproject.toml`. The :ref:`req
 
 
 For :ref:`setuptools` users, another way to achieve this is using the ``python_requires`` parameter
-in the call to ``setup`` within your :file:`setup.py` script.
-
-.. code-block:: python
-
-    from setuptools import setup
-
+in your :file:`setup.cfg` config or the :file:`setup.py` script. ``setuptools < 61`` does not support
+declaring the package metadata in :file:`pyproject.toml`.
 
-    setup(
-        # Your setup arguments
-        python_requires='>= 3.8',
-    )
+Consult the ``setuptools`` `dependency-management`_ documentation for information about the appropriate
+way to configure each of these files.
 
-It is warned against adding upper bounds to the version ranges, e. g. ``">= 3.8 < 3.10"``. This can cause different errors
-and version conflicts. See the `discourse discussion`_ for more information.
+.. caution::
+        It is warned against adding upper bounds to the version ranges, e. g. ``">= 3.8 < 3.10"``. This can cause different errors
+        and version conflicts. See the `discourse-discussion`_ for more information.
 
 3. Validating the Metadata before publishing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Within a Python source package (the zip or the tar-gz file you download) is a text file called PKG-INFO.
 
-This file is generated by the build backend when it generates the source package.
+This file is generated by the :term:`build backend ` when it generates the source package.
 The file contains a set of keys and values, the list of keys is part of the PyPA standard metadata format.
 
 You can see the contents of the generated file like this:
 
 .. code-block:: bash
 
-    tar xf dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO -O
+    tar xfO dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO
 
 Validate that the following is in place, before publishing the package:
 
@@ -137,15 +130,14 @@ If however supporting a specific version becomes a blocker for a new feature or
 ``Requires-Python`` should be amended. Of course this also depends on whether the project needs to be stable and
 well-covered for a wider range of users.
 
-Each version compatibility change should have an own release.
+Each version compatibility change should have its own release.
 
-For example, you published version 1.0.0 of your package with ``Requires-Python: ">= 2.7"`` metadata.
-
-If you then update the version string to ``">= 3.5"``, and publish a new version 2.0.0 of your package, any users running Pip 9.0+ from version 2.7 will have version 1.0.0 of the package installed, and any ``>= 3.5`` users will receive version 2.0.0.
-
-It may be a good idea to create a minor release, stating that it is the last one compatible with the Python version to be removed, just before dropping that version.
+.. tip::
 
-When dropping a Python version, it might also be rewarding to upgrade the project's code syntax generally, apart from updating the versions used in visible places (like the testing environment). Tools like pyupgrade_ can simplify this task.
+        When dropping a Python version, it might also be rewarding to upgrade the project's code syntax generally, apart from updating the versions used in visible         places (like the testing environment). Tools like pyupgrade_ can simplify this task.
 
-.. _discourse discussion: https://discuss.python.org/t/requires-python-upper-limits/12663
+.. _discourse-discussion: https://discuss.python.org/t/requires-python-upper-limits/12663
 .. _pyupgrade: https://pypi.org/project/pyupgrade/
+.. _dependency-management: https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#python-requirement
+
+.. [#] Support for the Metadata 1.2 specification has been added in Pip 9.0.

From c5723dfac9563d5885ee667c358dbaad3cea92e6 Mon Sep 17 00:00:00 2001
From: chrysle <96722107+chrysle@users.noreply.github.com>
Date: Sat, 20 Jul 2024 17:59:53 +0200
Subject: [PATCH 382/733] Use `pyproject.toml` instead of core metadata syntax

Better version range examples, tweak grammar, mention `ruff`
as helper tool for Python version upgrade

Co-authored-by: Jason R. Coombs <308610+jaraco@users.noreply.github.com>
---
 .../guides/dropping-older-python-versions.rst | 37 ++++++++-----------
 1 file changed, 16 insertions(+), 21 deletions(-)

diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst
index 9fdc35fa8..f3945dd6f 100644
--- a/source/guides/dropping-older-python-versions.rst
+++ b/source/guides/dropping-older-python-versions.rst
@@ -6,7 +6,7 @@ Dropping support for older Python versions
 
 The ability to drop support for older Python versions is enabled by the standard :ref:`core-metadata` 1.2 specification via the :ref:`"Requires-Python" ` attribute.
 
-Metadata 1.2+ clients, such as Pip, will adhere to this specification by matching the current Python runtime and comparing it with the required version
+Metadata 1.2+ installers, such as Pip, will adhere to this specification by matching the current Python runtime and comparing it with the required version
 in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime.
 
 This mechanism can be used to drop support for older Python versions, by amending the ``Requires-Python`` attribute in the package metadata.
@@ -14,7 +14,7 @@ This mechanism can be used to drop support for older Python versions, by amendin
 Requirements
 ------------
 
-This workflow requires that the user installing the package uses Pip [#]_, or another client that supports the Metadata 1.2 specification.
+This workflow requires that the user installing the package uses Pip [#]_, or another installer that supports the Metadata 1.2 specification.
 
 Dealing with the universal wheels
 ---------------------------------
@@ -65,17 +65,9 @@ Steps:
 2. Specify the version ranges for supported Python distributions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can specify version ranges and exclusion rules (complying with the :ref:`version-specifiers` specification),
-such as at least Python 3. Or, Python 3.7, 3.8, 3.13 and beyond:
-
-.. code-block:: text
-
-    Requires-Python: ">= 3"
-    Requires-Python: ">= 3.7, != 3.9.*, != 3.10.*, != 3.11.*, != 3.12.*"
-
-
-Those values can be set within your :file:`pyproject.toml`. The :ref:`requires-python` configuration field
-corresponds to the ``Requires-Python`` metadata field.
+Set the version ranges declaring which Python distributions are supported  
+within your project's :file:`pyproject.toml`. The :ref:`requires-python` configuration field
+corresponds to the :ref:`Requires-Python ` core metadata field:
 
 .. code-block:: toml
 
@@ -85,16 +77,19 @@ corresponds to the ``Requires-Python`` metadata field.
    [project]
    requires-python = ">= 3.8" # At least Python 3.8
 
+You can specify version ranges and exclusion rules (complying with the :ref:`version-specifiers` specification),
+such as at least Python 3.9. Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point releases:
+
+.. code-block:: toml
+
+    requires-python = ">= 3.9"
+    requires-python = ">= 3.7, != 3.7.0, != 3.7.1"
 
-For :ref:`setuptools` users, another way to achieve this is using the ``python_requires`` parameter
-in your :file:`setup.cfg` config or the :file:`setup.py` script. ``setuptools < 61`` does not support
-declaring the package metadata in :file:`pyproject.toml`.
 
-Consult the ``setuptools`` `dependency-management`_ documentation for information about the appropriate
-way to configure each of these files.
+If using the :ref:`setuptools` build backend, consult the `dependency-management`_ documentation for more options.
 
 .. caution::
-        It is warned against adding upper bounds to the version ranges, e. g. ``">= 3.8 < 3.10"``. This can cause different errors
+        Avoid adding upper bounds to the version ranges, e. g. ``">= 3.8, < 3.10"``. Doing so can cause different errors
         and version conflicts. See the `discourse-discussion`_ for more information.
 
 3. Validating the Metadata before publishing
@@ -113,7 +108,7 @@ You can see the contents of the generated file like this:
 
 Validate that the following is in place, before publishing the package:
 
-- If you have upgraded correctly, the Metadata-Version value should be 1.2 or higher.
+- If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 or higher.
 - The ``Requires-Python`` field is set and matches your specification in the configuration file.
 
 4. Publishing the package
@@ -134,7 +129,7 @@ Each version compatibility change should have its own release.
 
 .. tip::
 
-        When dropping a Python version, it might also be rewarding to upgrade the project's code syntax generally, apart from updating the versions used in visible         places (like the testing environment). Tools like pyupgrade_ can simplify this task.
+        When dropping a Python version, it might also be rewarding to upgrade the project's code syntax generally, apart from updating the versions used in visible places (like the testing environment). Tools like pyupgrade_ or `ruff `_ can automate some of this work.
 
 .. _discourse-discussion: https://discuss.python.org/t/requires-python-upper-limits/12663
 .. _pyupgrade: https://pypi.org/project/pyupgrade/

From 2b6bc988c5f7867de72fb6278b95f745bbf2712f Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sat, 20 Jul 2024 16:05:06 +0000
Subject: [PATCH 383/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/guides/dropping-older-python-versions.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst
index f3945dd6f..267d7b923 100644
--- a/source/guides/dropping-older-python-versions.rst
+++ b/source/guides/dropping-older-python-versions.rst
@@ -65,7 +65,7 @@ Steps:
 2. Specify the version ranges for supported Python distributions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Set the version ranges declaring which Python distributions are supported  
+Set the version ranges declaring which Python distributions are supported
 within your project's :file:`pyproject.toml`. The :ref:`requires-python` configuration field
 corresponds to the :ref:`Requires-Python ` core metadata field:
 

From f6d6e5ce3165c7ce6b92c8d6b6f2bd9341154565 Mon Sep 17 00:00:00 2001
From: chrysle <96722107+chrysle@users.noreply.github.com>
Date: Mon, 29 Jul 2024 10:41:44 +0200
Subject: [PATCH 384/733] Temporarily ignore https://pyscaffold.org, fix Fedora
 link

---
 source/conf.py                                 | 1 +
 source/guides/installing-using-linux-tools.rst | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/source/conf.py b/source/conf.py
index cd459ffb2..c777550ce 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -132,6 +132,7 @@
     # Ignore while StackOverflow is blocking GitHub CI. Ref:
     # https://github.com/pypa/packaging.python.org/pull/1474
     "https://stackoverflow.com/*",
+    "https://pyscaffold.org/*",
 ]
 linkcheck_retries = 5
 # Ignore anchors for links to GitHub project pages -- GitHub adds anchors from
diff --git a/source/guides/installing-using-linux-tools.rst b/source/guides/installing-using-linux-tools.rst
index f0914f8dc..56647f3e9 100644
--- a/source/guides/installing-using-linux-tools.rst
+++ b/source/guides/installing-using-linux-tools.rst
@@ -51,7 +51,7 @@ To install pip and wheel for the system Python, there are two options:
 
 1. Enable the `EPEL repository `_ using
    `these instructions
-   `__.
+   `__.
    On EPEL 7, you can install pip and wheel like so:
 
    .. code-block:: bash

From 85dc060158e2e2f0764033bf9fb4a4ceea0bc0ae Mon Sep 17 00:00:00 2001
From: chrysle <96722107+chrysle@users.noreply.github.com>
Date: Sat, 25 May 2024 20:19:01 +0200
Subject: [PATCH 385/733] Add guide on packaging command-line tooling

---
 .../analyzing-pypi-package-downloads.rst      |   2 +
 source/guides/creating-command-line-tools.rst | 213 ++++++++++++++++++
 ...talling-stand-alone-command-line-tools.rst |   2 +
 source/guides/section-build-and-publish.rst   |   1 +
 4 files changed, 218 insertions(+)
 create mode 100644 source/guides/creating-command-line-tools.rst

diff --git a/source/guides/analyzing-pypi-package-downloads.rst b/source/guides/analyzing-pypi-package-downloads.rst
index 62efea7ab..5fecc99c1 100644
--- a/source/guides/analyzing-pypi-package-downloads.rst
+++ b/source/guides/analyzing-pypi-package-downloads.rst
@@ -1,3 +1,5 @@
+.. _analyzing-pypi-package-downloads:
+
 ================================
 Analyzing PyPI package downloads
 ================================
diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst
new file mode 100644
index 000000000..80aaf30a1
--- /dev/null
+++ b/source/guides/creating-command-line-tools.rst
@@ -0,0 +1,213 @@
+.. _creating-command-line-tools:
+
+=========================================
+Creating and packaging command-line tools
+=========================================
+
+This guide will walk you through creating and packaging a standalone command-line application
+that can be installed with :ref:`pipx`, a tool creating and managing :term:`Python Virtual Environments `
+and exposing the executable scripts of packages (and available manual pages) for use on the command-line.
+
+Creating the package
+====================
+
+First of all, we'll need to create a source tree for the :term:`project `. For the sake of an example, we'll
+create a simple tool outputting a greeting (a string) for a person based on arguments given on the command-line.
+
+.. todo:: Advise on the optimal structure of a Python package in another guide or discussion and link to it here.
+
+This project will adhere to :ref:`src-layout ` and in the end be alike this file tree,
+with the top-level folder and package name ``greetings``:
+
+::
+
+    .
+    ├── pyproject.toml
+    └── src
+        └── greetings
+            ├── cli.py
+            ├── greet.py
+            ├── __init__.py
+            └── __main__.py
+
+The actual code responsible for the tool's functionality will be stored in the file :file:`greet.py`,
+named after the main module:
+
+.. code-block:: python
+
+	def greet(name="", gender="", knight=False, count=1):
+	    greeting = "Greetings, dear "
+	    masculine = gender == "masculine"
+	    feminine = gender == "feminine"
+	    if gender or knight:
+	        salutation = ""
+	        if knight:
+	            salutation = "Sir "
+	        elif masculine:
+	            salutation = "Mr. "
+	        elif feminine:
+	            salutation = "Ms. "
+	        greeting += salutation
+	        if name:
+	            greeting += f"{name}!"
+	        else:
+	            pronoun = "her" if feminine else "his" if masculine or knight else "its"
+	            greeting += f"what's-{pronoun}-name!"
+	    else:
+	        if name:
+	            greeting += f"{name}!"
+	        elif not gender:
+	            greeting += "friend!"
+	    for i in range(0, count):
+	        print(greeting)
+
+The above function receives several keyword arguments that determine how the greeting to output is constructed.
+Now, the command-line interface to provision it with the same needs to be constructed, which is done
+in :file:`cli.py`:
+
+.. code-block:: python
+
+	import argparse
+	import sys
+
+	from .greet import greet
+
+	_arg_spec = {
+	    '--name': {
+	        'metavar': 'STRING',
+	        'type': str,
+	        'help': 'The (last, if "gender" is given) name of the person to greet',
+	    },
+	    '--count': {
+	        'metavar': 'INT',
+	        'type': int,
+	        'default': 1,
+	        'help': 'Number of times to greet the person',
+	    },
+
+	}
+	_arg_spec_mutually_exclusive = {
+	    '--gender': {
+	        'metavar': 'STRING',
+	        'type': str,
+	        'help': 'The gender of the person to greet',
+	    },
+	    '--knight': {
+	        'action': 'store_true',
+	        'default': False,
+	        'help': 'Whether the person is a knight',
+	    },
+	}
+
+
+	def main():
+	    parser = argparse.ArgumentParser(
+	        description="Greet a person (semi-)formally."
+	    )
+	    group = parser.add_mutually_exclusive_group()
+	    for arg, spec in _arg_spec.items():
+	        parser.add_argument(arg, **spec)
+	    for arg, spec in _arg_spec_mutually_exclusive.items():
+	        group.add_argument(arg, **spec)
+	    parsed_args = parser.parse_args()
+	    args = {
+	        arg: value
+	        for arg, value in vars(parsed_args).items()
+	        if value is not None
+	    }
+        # Run the function with the command-line arguments as keyword arguments.
+        # A more complex setup is normally initialized at this point.
+	    greet(**args)
+
+
+	if __name__ == "__main__":
+	    sys.exit(main())
+
+The command-line interface is built with :py:mod:`argparse`, a command-line parser which is included in Python's
+standard library. It is a bit rudimentary but sufficient for most needs. Another easy-to-use alternative is docopt_;
+advanced users are encouraged to make use of click_.
+
+We'll add an empty :file:`__init__.py` file, too, to define the project as a regular :term:`import package `.
+
+The file :file:`__main__.py` marks the main entry point for the application when running it via ``python -m greetings``,
+so we'll just initizalize the command-line interface here. The first condition isn't necessary, but may be added in order
+to make the package runnable directly from the source tree, by prepending the package folder to Python's :py:data:`sys.path`:
+
+.. code-block:: python
+
+	import os
+	import sys
+
+	if not __package__:
+        # Make package runnable from source tree with
+        #    python src/greetings
+	    package_source_path = os.path.dirname(os.path.dirname(__file__))
+	    sys.path.insert(0, package_source_path)
+
+	if __name__ == "__main__":
+	    from greetings.cli import main
+	    sys.exit(main())
+
+
+``pyproject.toml``
+------------------
+
+The project's :term:`metadata ` is placed in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as described in :ref:`writing-pyproject-toml`.
+
+For the project to be recognised as a command-line tool, additionally a ``console_scripts`` :ref:`entry point ` (see :ref:`console_scripts`) needs to be added as a :term:`subkey `:
+
+.. code-block:: toml
+
+	[project.scripts]
+	greet = "greetings.cli:main"
+
+Besides, it could prove rewarding to add a ``pipx``-specific entry point, the meaning of which is described below:
+
+.. code-block:: toml
+
+	[project.entry-points."pipx.run"]
+	greetings = "greetings.cli:main"
+
+
+Now, the project's source tree is ready to be transformed into a :term:`distribution package `,
+which makes it installable.
+
+
+Installing the package with ``pipx``
+====================================
+
+After installing ``pipx`` as described in :ref:`installing-stand-alone-command-line-tools`, you're ready to install your project:
+
+.. code-block:: console
+
+	$ pipx install ./greetings/
+
+This will expose the executable script we defined as an entry point and make the command ``greet`` available to you.
+Let's test it:
+
+.. code-block:: console
+
+	$ greet --knight --name Lancelot
+	Greetings, dear Sir Lancelot!
+	$ greet --gender feminine --name Parks
+	Greetings, dear Ms. Parks!
+	$ greet --gender masculine
+	Greetings, dear Mr. what's-his-name!
+
+To just run the program without installing it permanently, you could use ``pipx run``, which will create a temporary (but cached) virtual environment for it:
+
+.. code-block:: console
+
+	$ pipx run ./greetings/ --knight
+
+Thanks to the entry point we defined above (which *must* match the package name), ``pipx`` will pick up the executable script as the
+default one and run it; otherwise, you'd need to specify the entry point's name explicitly with ``pipx run --spec ./greetings/ greet --knight``.
+
+Conclusion
+==========
+
+You know by now how to package a command-line application written in Python. A further step could be to distribute you package,
+meaning uploading it to a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions at :ref:`Packaging your project`. And once you're done, don't forget to :ref:`do some research ` on how your package is received!
+
+.. _click: https://click.palletsprojects.com/
+.. _docopt: https://docopt.readthedocs.io/en/latest/
diff --git a/source/guides/installing-stand-alone-command-line-tools.rst b/source/guides/installing-stand-alone-command-line-tools.rst
index 8578a3b28..c078fd1e4 100644
--- a/source/guides/installing-stand-alone-command-line-tools.rst
+++ b/source/guides/installing-stand-alone-command-line-tools.rst
@@ -1,3 +1,5 @@
+.. _installing-stand-alone-command-line-tools:
+
 Installing stand alone command line tools
 =========================================
 
diff --git a/source/guides/section-build-and-publish.rst b/source/guides/section-build-and-publish.rst
index 2af29d763..8e0c9ab3b 100644
--- a/source/guides/section-build-and-publish.rst
+++ b/source/guides/section-build-and-publish.rst
@@ -11,6 +11,7 @@ Building and Publishing
    dropping-older-python-versions
    packaging-binary-extensions
    packaging-namespace-packages
+   creating-command-line-tools
    creating-and-discovering-plugins
    using-testpypi
    making-a-pypi-friendly-readme

From 6729b3d1f6fbcf3950fd18b6a37c6ffc4291ee5b Mon Sep 17 00:00:00 2001
From: chrysle <96722107+chrysle@users.noreply.github.com>
Date: Mon, 24 Jun 2024 17:08:42 +0200
Subject: [PATCH 386/733] Refine structure

Make the guide more easily comprehensible, mention difference between
src and flat layout concerning `runpy` behaviour, mention typer CLI
parser, tighten language

Co-authored-by: Jason R. Coombs <308610+jaraco@users.noreply.github.com>
---
 .../discussions/src-layout-vs-flat-layout.rst | 24 +++++++
 source/guides/creating-command-line-tools.rst | 69 +++++++++++--------
 2 files changed, 63 insertions(+), 30 deletions(-)

diff --git a/source/discussions/src-layout-vs-flat-layout.rst b/source/discussions/src-layout-vs-flat-layout.rst
index bfa405729..c38968345 100644
--- a/source/discussions/src-layout-vs-flat-layout.rst
+++ b/source/discussions/src-layout-vs-flat-layout.rst
@@ -79,3 +79,27 @@ layout and the flat layout:
   ``tox.ini``) and packaging/tooling configuration files (eg: ``setup.py``,
   ``noxfile.py``) on the import path. This would make certain imports work
   in editable installations but not regular installations.
+
+.. _running-cli-from-source-src-layout:
+
+Running a command-line interface from source with src-layout
+============================================================
+
+Due to the firstly mentioned specialty of the src layout, a command-line
+interface can not be run directly from the :term:`source tree `,
+but requires installation of the package in
+:doc:`Development Mode `
+for testing purposes. Since this can be unpractical in some situations,
+a workaround could be to prepend the package folder to  Python's
+:py:data:`sys.path` when called via its :file:`__main__.py` file:
+
+.. code-block:: python
+
+    import os
+    import sys
+
+    if not __package__:
+        # Make CLI runnable from source tree with
+        #    python src/package
+        package_source_path = os.path.dirname(os.path.dirname(__file__))
+        sys.path.insert(0, package_source_path)
diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst
index 80aaf30a1..f7c3fc74a 100644
--- a/source/guides/creating-command-line-tools.rst
+++ b/source/guides/creating-command-line-tools.rst
@@ -11,8 +11,8 @@ and exposing the executable scripts of packages (and available manual pages) for
 Creating the package
 ====================
 
-First of all, we'll need to create a source tree for the :term:`project `. For the sake of an example, we'll
-create a simple tool outputting a greeting (a string) for a person based on arguments given on the command-line.
+First of all, create a source tree for the :term:`project `. For the sake of an example, we'll
+build a simple tool outputting a greeting (a string) for a person based on arguments given on the command-line.
 
 .. todo:: Advise on the optimal structure of a Python package in another guide or discussion and link to it here.
 
@@ -62,7 +62,7 @@ named after the main module:
 	        print(greeting)
 
 The above function receives several keyword arguments that determine how the greeting to output is constructed.
-Now, the command-line interface to provision it with the same needs to be constructed, which is done
+Now, construct the command-line interface to provision it with the same, which is done
 in :file:`cli.py`:
 
 .. code-block:: python
@@ -125,29 +125,28 @@ in :file:`cli.py`:
 
 The command-line interface is built with :py:mod:`argparse`, a command-line parser which is included in Python's
 standard library. It is a bit rudimentary but sufficient for most needs. Another easy-to-use alternative is docopt_;
-advanced users are encouraged to make use of click_.
+advanced users are encouraged to make use of click_ or typer_.
 
-We'll add an empty :file:`__init__.py` file, too, to define the project as a regular :term:`import package `.
+Now, add an empty :file:`__init__.py` file, to define the project as a regular :term:`import package `.
 
-The file :file:`__main__.py` marks the main entry point for the application when running it via ``python -m greetings``,
-so we'll just initizalize the command-line interface here. The first condition isn't necessary, but may be added in order
-to make the package runnable directly from the source tree, by prepending the package folder to Python's :py:data:`sys.path`:
+The file :file:`__main__.py` marks the main entry point for the application when running it via :mod:`runpy`
+(i.e. ``python -m greetings``, which works immediately with flat layout, but requires installation of the package with src layout),
+so initizalize the command-line interface here:
 
 .. code-block:: python
 
-	import os
 	import sys
 
-	if not __package__:
-        # Make package runnable from source tree with
-        #    python src/greetings
-	    package_source_path = os.path.dirname(os.path.dirname(__file__))
-	    sys.path.insert(0, package_source_path)
-
 	if __name__ == "__main__":
 	    from greetings.cli import main
 	    sys.exit(main())
 
+.. note::
+
+    In order to enable calling the command-line interface directly from the :term:`source tree `,
+    i.e. as ``python src/greetings``, a certain hack could be placed in this file; read more at
+    :ref:`running-cli-from-source-src-layout`.
+
 
 ``pyproject.toml``
 ------------------
@@ -161,14 +160,6 @@ For the project to be recognised as a command-line tool, additionally a ``consol
 	[project.scripts]
 	greet = "greetings.cli:main"
 
-Besides, it could prove rewarding to add a ``pipx``-specific entry point, the meaning of which is described below:
-
-.. code-block:: toml
-
-	[project.entry-points."pipx.run"]
-	greetings = "greetings.cli:main"
-
-
 Now, the project's source tree is ready to be transformed into a :term:`distribution package `,
 which makes it installable.
 
@@ -176,13 +167,14 @@ which makes it installable.
 Installing the package with ``pipx``
 ====================================
 
-After installing ``pipx`` as described in :ref:`installing-stand-alone-command-line-tools`, you're ready to install your project:
+After installing ``pipx`` as described in :ref:`installing-stand-alone-command-line-tools`, install your project:
 
 .. code-block:: console
 
-	$ pipx install ./greetings/
+    $ cd path/to/greetings/
+    $ pipx install .
 
-This will expose the executable script we defined as an entry point and make the command ``greet`` available to you.
+This will expose the executable script we defined as an entry point and make the command ``greet`` available.
 Let's test it:
 
 .. code-block:: console
@@ -194,14 +186,30 @@ Let's test it:
 	$ greet --gender masculine
 	Greetings, dear Mr. what's-his-name!
 
-To just run the program without installing it permanently, you could use ``pipx run``, which will create a temporary (but cached) virtual environment for it:
+To just run the program without installing it permanently, use ``pipx run``, which will create a temporary (but cached) virtual environment for it:
 
 .. code-block:: console
 
-	$ pipx run ./greetings/ --knight
+	$ pipx run --spec . greet --knight
+
+This syntax is a bit unpractical, 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).
+
+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`:
+
+.. code-block:: toml
+
+    [project.entry-points."pipx.run"]
+    greetings = "greetings.cli:main"
+
+
+Thanks to this entry point (which *must* match the package name), ``pipx`` will pick up the executable script as the
+default one and run it, which makes this command possible:
+
+.. code-block:: console
 
-Thanks to the entry point we defined above (which *must* match the package name), ``pipx`` will pick up the executable script as the
-default one and run it; otherwise, you'd need to specify the entry point's name explicitly with ``pipx run --spec ./greetings/ greet --knight``.
+    $ pipx run . --knight
 
 Conclusion
 ==========
@@ -211,3 +219,4 @@ meaning uploading it to a :term:`package index `, most commonly :
 
 .. _click: https://click.palletsprojects.com/
 .. _docopt: https://docopt.readthedocs.io/en/latest/
+.. _typer: https://typer.tiangolo.com/

From 2d7be49b8c179a94eb773bbc702e07df763189ce Mon Sep 17 00:00:00 2001
From: chrysle <96722107+chrysle@users.noreply.github.com>
Date: Thu, 4 Jul 2024 17:22:55 +0200
Subject: [PATCH 387/733] Use `typer` for command-line interface creation

---
 source/guides/creating-command-line-tools.rst | 152 +++++++-----------
 1 file changed, 61 insertions(+), 91 deletions(-)

diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst
index f7c3fc74a..9f040ce7d 100644
--- a/source/guides/creating-command-line-tools.rst
+++ b/source/guides/creating-command-line-tools.rst
@@ -35,31 +35,40 @@ named after the main module:
 
 .. code-block:: python
 
-	def greet(name="", gender="", knight=False, count=1):
-	    greeting = "Greetings, dear "
-	    masculine = gender == "masculine"
-	    feminine = gender == "feminine"
-	    if gender or knight:
-	        salutation = ""
-	        if knight:
-	            salutation = "Sir "
-	        elif masculine:
-	            salutation = "Mr. "
-	        elif feminine:
-	            salutation = "Ms. "
-	        greeting += salutation
-	        if name:
-	            greeting += f"{name}!"
-	        else:
-	            pronoun = "her" if feminine else "his" if masculine or knight else "its"
-	            greeting += f"what's-{pronoun}-name!"
-	    else:
-	        if name:
-	            greeting += f"{name}!"
-	        elif not gender:
-	            greeting += "friend!"
-	    for i in range(0, count):
-	        print(greeting)
+    import typer
+    from typing_extensions import Annotated
+
+
+    def greet(
+        name: Annotated[str, typer.Argument(help="The (last, if --gender is given) name of the person to greet")] = "",
+        gender: Annotated[str, typer.Option(help="The gender of the person to greet")] = "",
+        knight: Annotated[bool, typer.Option(help="Whether the person is a knight")] = False,
+        count: Annotated[int, typer.Option(help="Number of times to greet the person")] = 1
+    ):
+        greeting = "Greetings, dear "
+        masculine = gender == "masculine"
+        feminine = gender == "feminine"
+        if gender or knight:
+            salutation = ""
+            if knight:
+                salutation = "Sir "
+            elif masculine:
+                salutation = "Mr. "
+            elif feminine:
+                salutation = "Ms. "
+            greeting += salutation
+            if name:
+                greeting += f"{name}!"
+            else:
+                pronoun = "her" if feminine else "his" if masculine or knight else "its"
+                greeting += f"what's-{pronoun}-name"
+        else:
+            if name:
+                greeting += f"{name}!"
+            elif not gender:
+                greeting += "friend!"
+        for i in range(0, count):
+            print(greeting)
 
 The above function receives several keyword arguments that determine how the greeting to output is constructed.
 Now, construct the command-line interface to provision it with the same, which is done
@@ -67,65 +76,23 @@ in :file:`cli.py`:
 
 .. code-block:: python
 
-	import argparse
-	import sys
-
-	from .greet import greet
-
-	_arg_spec = {
-	    '--name': {
-	        'metavar': 'STRING',
-	        'type': str,
-	        'help': 'The (last, if "gender" is given) name of the person to greet',
-	    },
-	    '--count': {
-	        'metavar': 'INT',
-	        'type': int,
-	        'default': 1,
-	        'help': 'Number of times to greet the person',
-	    },
-
-	}
-	_arg_spec_mutually_exclusive = {
-	    '--gender': {
-	        'metavar': 'STRING',
-	        'type': str,
-	        'help': 'The gender of the person to greet',
-	    },
-	    '--knight': {
-	        'action': 'store_true',
-	        'default': False,
-	        'help': 'Whether the person is a knight',
-	    },
-	}
-
-
-	def main():
-	    parser = argparse.ArgumentParser(
-	        description="Greet a person (semi-)formally."
-	    )
-	    group = parser.add_mutually_exclusive_group()
-	    for arg, spec in _arg_spec.items():
-	        parser.add_argument(arg, **spec)
-	    for arg, spec in _arg_spec_mutually_exclusive.items():
-	        group.add_argument(arg, **spec)
-	    parsed_args = parser.parse_args()
-	    args = {
-	        arg: value
-	        for arg, value in vars(parsed_args).items()
-	        if value is not None
-	    }
-        # Run the function with the command-line arguments as keyword arguments.
-        # A more complex setup is normally initialized at this point.
-	    greet(**args)
+    import typer
 
+    from .hello import greet
+
+
+    app = typer.Typer()
+    app.command()(greet)
 
-	if __name__ == "__main__":
-	    sys.exit(main())
 
-The command-line interface is built with :py:mod:`argparse`, a command-line parser which is included in Python's
-standard library. It is a bit rudimentary but sufficient for most needs. Another easy-to-use alternative is docopt_;
-advanced users are encouraged to make use of click_ or typer_.
+    if __name__ == "__main__":
+        app()
+
+The command-line interface is built with typer_, an easy-to-use CLI parser based on Python type hints. It provides
+auto-completion and nicely styled command-line help out of the box. Another option would be :py:mod:`argparse`,
+a command-line parser which is included in Python's standard library. It is sufficient for most needs, but requires
+a lot of code, usually in ``cli.py``, to function properly. Alternatively, docopt_ makes it possible to create CLI
+interfaces based solely on docstrings; advanced users are encouraged to make use of click_ (on which ``typer`` is based).
 
 Now, add an empty :file:`__init__.py` file, to define the project as a regular :term:`import package `.
 
@@ -135,11 +102,9 @@ so initizalize the command-line interface here:
 
 .. code-block:: python
 
-	import sys
-
 	if __name__ == "__main__":
-	    from greetings.cli import main
-	    sys.exit(main())
+	    from greetings.cli import app
+	    app()
 
 .. note::
 
@@ -151,14 +116,15 @@ so initizalize the command-line interface here:
 ``pyproject.toml``
 ------------------
 
-The project's :term:`metadata ` is placed in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as described in :ref:`writing-pyproject-toml`.
+The project's :term:`metadata ` is placed in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as described in :ref:`writing-pyproject-toml`, adding a dependency
+on ``typer`` (this tutorial uses version *0.12.3*).
 
 For the project to be recognised as a command-line tool, additionally a ``console_scripts`` :ref:`entry point ` (see :ref:`console_scripts`) needs to be added as a :term:`subkey `:
 
 .. code-block:: toml
 
 	[project.scripts]
-	greet = "greetings.cli:main"
+	greet = "greetings.cli:app"
 
 Now, the project's source tree is ready to be transformed into a :term:`distribution package `,
 which makes it installable.
@@ -179,14 +145,18 @@ Let's test it:
 
 .. code-block:: console
 
-	$ greet --knight --name Lancelot
+	$ greet --knight Lancelot
 	Greetings, dear Sir Lancelot!
-	$ greet --gender feminine --name Parks
+	$ greet --gender feminine Parks
 	Greetings, dear Ms. Parks!
 	$ greet --gender masculine
 	Greetings, dear Mr. what's-his-name!
 
-To just run the program without installing it permanently, use ``pipx run``, which will create a temporary (but cached) virtual environment for it:
+Since this example uses ``typer``, you could now also get an overview of the program's usage by calling it with
+the ``--help`` option, or configure completions via the ``--install-completion`` option.
+
+To just run the program without installing it permanently, use ``pipx run``, which will create a temporary
+(but cached) virtual environment for it:
 
 .. code-block:: console
 
@@ -201,7 +171,7 @@ The same can be defined as follows in :file:`pyproject.toml`:
 .. code-block:: toml
 
     [project.entry-points."pipx.run"]
-    greetings = "greetings.cli:main"
+    greetings = "greetings.cli:app"
 
 
 Thanks to this entry point (which *must* match the package name), ``pipx`` will pick up the executable script as the

From 0bdccb0898cd38058722523fead9278e4ead354e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ville=20Skytt=C3=A4?= 
Date: Mon, 15 Jul 2024 23:35:06 +0300
Subject: [PATCH 388/733] Spelling and grammar fixes

---
 source/specifications/direct-url-data-structure.rst       | 2 +-
 source/specifications/externally-managed-environments.rst | 2 +-
 source/specifications/simple-repository-api.rst           | 6 +++---
 source/specifications/version-specifiers.rst              | 2 +-
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index 231198ee8..9ec8e2e34 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -44,7 +44,7 @@ expression:
 
 Additionally, the user:password section of the URL MAY be a
 well-known, non security sensitive string. A typical example is ``git``
-in the case of an URL such as ``ssh://git@gitlab.com/user/repo``.
+in the case of a URL such as ``ssh://git@gitlab.com/user/repo``.
 
 VCS URLs
 --------
diff --git a/source/specifications/externally-managed-environments.rst b/source/specifications/externally-managed-environments.rst
index 2944eb3da..65fc14a62 100644
--- a/source/specifications/externally-managed-environments.rst
+++ b/source/specifications/externally-managed-environments.rst
@@ -205,7 +205,7 @@ virtual environment to install packages.
 
 Software distributors who have a non-Python-specific package manager
 that manages libraries in the ``sys.path`` of their Python package
-should, in general, ship a ``EXTERNALLY-MANAGED`` file in their
+should, in general, ship an ``EXTERNALLY-MANAGED`` file in their
 standard library directory. For instance, Debian may ship a file in
 ``/usr/lib/python3.9/EXTERNALLY-MANAGED`` consisting of something like
 
diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
index b9f87ce7b..0d65a58aa 100644
--- a/source/specifications/simple-repository-api.rst
+++ b/source/specifications/simple-repository-api.rst
@@ -360,7 +360,7 @@ spec:
 * All JSON responses will *always* be a JSON object rather than an array or other
   type.
 
-* While JSON doesn't natively support an URL type, any value that represents an
+* While JSON doesn't natively support a URL type, any value that represents an
   URL in this API may be either absolute or relative as long as they point to
   the correct location. If relative, they are relative to the current URL as if
   it were HTML.
@@ -616,7 +616,7 @@ likely just be treated the same as a ``406 Not Acceptable`` error.
 This spec **does** require that if the meta version ``latest`` is being used, the
 server **MUST** respond with the content type for the actual version that is
 contained in the response
-(i.e. A ``Accept: application/vnd.pypi.simple.latest+json`` request that returns
+(i.e. an ``Accept: application/vnd.pypi.simple.latest+json`` request that returns
 a ``v1.x`` response should have a ``Content-Type`` of
 ``application/vnd.pypi.simple.v1+json``).
 
@@ -725,7 +725,7 @@ may *optionally* be used instead.
 URL Parameter
 ^^^^^^^^^^^^^
 
-Servers that implement the Simple API may choose to support an URL parameter named
+Servers that implement the Simple API may choose to support a URL parameter named
 ``format`` to allow the clients to request a specific version of the URL.
 
 The value of the ``format`` parameter should be **one** of the valid content types.
diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index cde0bc49a..a5ba36498 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -1178,7 +1178,7 @@ more information on ``file://`` URLs on Windows see
 Summary of differences from pkg_resources.parse_version
 =======================================================
 
-* Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at
+* Note: this comparison is to ``pkg_resources.parse_version`` as it existed at
   the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 and
   later versions adopted the behaviour described here.
 

From 342f9eb0a597d33f9c0b0e7cd5d9192c0521e34f Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 25 Jul 2024 09:34:31 -0700
Subject: [PATCH 389/733] updated single_source_version with a much simpler
 page -- essentially refering folks to their build system of choice.

---
 source/single_source_version.rst | 51 ++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 source/single_source_version.rst

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
new file mode 100644
index 000000000..206ff5020
--- /dev/null
+++ b/source/single_source_version.rst
@@ -0,0 +1,51 @@
+.. _`Single sourcing the version`:
+
+===================================
+Single-sourcing the Project Version
+===================================
+
+:Page Status: Complete
+:Last Reviewed: 2015-09-08
+
+One of the challenges in building packages is that the version string can be required in multiple places.
+
+* It needs to be specified when building the package (e.g. in pyproject.toml)
+   - That will assure that it is properly assigned in the distribution file name, and in teh installed package.
+
+* Some projects require that there be a version string available as an attribute in the importable module, e.g::
+
+    import a_package
+    print(a_package.__version__)
+
+While different projects have different needs, it's important to make sure that there is a single source of truth for the version number.
+
+In general, the options are:
+
+1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS.
+
+2) The version can be hard-coded into the `pyproject.toml` file -- and the build system can copy it into other locations it may be required.
+
+3) The version string can be hard-coded into the source code -- either in a special purpose file, such as `_version.txt`, or as a attribute in the `__init__.py`, and the build system can extract it at build time.
+
+If the version string is not in the source, it can be extracted at runtime with code in `__init__.py`, such as::
+
+    import importlib.metadata
+    __version__ = importlib.metadata.version('the_distribution_name')
+
+
+Consult your build system documentation for how to implement your preferred method.
+
+Put links in to build system docs?
+-- I have no idea which are currently robust and maintained -- do we want to get into seeming endorsing particular tools in this doc?
+
+
+* setuptools:
+
+* hatch:
+
+* poetry:
+
+* PyBuilder:
+
+* Others?
+

From ce0d4bc9951776e01c55189868dac892b3045c56 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 25 Jul 2024 11:17:19 -0700
Subject: [PATCH 390/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 206ff5020..766247711 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -9,7 +9,7 @@ Single-sourcing the Project Version
 
 One of the challenges in building packages is that the version string can be required in multiple places.
 
-* It needs to be specified when building the package (e.g. in pyproject.toml)
+* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
    - That will assure that it is properly assigned in the distribution file name, and in teh installed package.
 
 * Some projects require that there be a version string available as an attribute in the importable module, e.g::

From 6cd1b9bb78a9819cab9e74bb6ca735c613e1d983 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 25 Jul 2024 11:20:08 -0700
Subject: [PATCH 391/733] Update source/single_source_version.rst

Co-authored-by: Thomas A Caswell 
---
 source/single_source_version.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 766247711..c075e56a9 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -16,6 +16,7 @@ One of the challenges in building packages is that the version string can be req
 
     import a_package
     print(a_package.__version__)
+* In the metadata of the artifacts for each of the packaging ecosystems    
 
 While different projects have different needs, it's important to make sure that there is a single source of truth for the version number.
 

From dbac2356e9d71ee70dc8f3813d44370e0dbffd45 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 25 Jul 2024 14:51:07 -0700
Subject: [PATCH 392/733] Added links to build tools

---
 source/single_source_version.rst | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index c075e56a9..e307dd5a7 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -10,12 +10,13 @@ Single-sourcing the Project Version
 One of the challenges in building packages is that the version string can be required in multiple places.
 
 * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
-   - That will assure that it is properly assigned in the distribution file name, and in teh installed package.
+   - That will assure that it is properly assigned in the distribution file name, and in the installed package.
 
 * Some projects require that there be a version string available as an attribute in the importable module, e.g::
 
     import a_package
     print(a_package.__version__)
+
 * In the metadata of the artifacts for each of the packaging ecosystems    
 
 While different projects have different needs, it's important to make sure that there is a single source of truth for the version number.
@@ -36,17 +37,15 @@ If the version string is not in the source, it can be extracted at runtime with
 
 Consult your build system documentation for how to implement your preferred method.
 
-Put links in to build system docs?
--- I have no idea which are currently robust and maintained -- do we want to get into seeming endorsing particular tools in this doc?
-
+Here are the common ones:
 
-* setuptools:
+* `Hatch `_
 
-* hatch:
+* `Setuptools `_
 
-* poetry:
+  -  `setuptools_scm `_
 
-* PyBuilder:
+* `Flit `_
 
-* Others?
+* `PDM `_
 

From 438198fafd7fccc1bf76f2fb6191e244961be1ad Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 25 Jul 2024 14:53:58 -0700
Subject: [PATCH 393/733] swap prefer for require

---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index e307dd5a7..46954a8e2 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -12,7 +12,7 @@ One of the challenges in building packages is that the version string can be req
 * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
    - That will assure that it is properly assigned in the distribution file name, and in the installed package.
 
-* Some projects require that there be a version string available as an attribute in the importable module, e.g::
+* Some projects prefer that there be a version string available as an attribute in the importable module, e.g::
 
     import a_package
     print(a_package.__version__)

From 51e2c23fa69792d318e388bdf96cbb8c00eafa65 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 25 Jul 2024 15:11:36 -0700
Subject: [PATCH 394/733] replace text about __version__

---
 source/single_source_version.rst | 22 +++++++++-------------
 1 file changed, 9 insertions(+), 13 deletions(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 46954a8e2..8a2eb5cf8 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -9,15 +9,13 @@ Single-sourcing the Project Version
 
 One of the challenges in building packages is that the version string can be required in multiple places.
 
-* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
+* It needs to be specified when building the package (e.g. in :file:``pyproject.toml``)
    - That will assure that it is properly assigned in the distribution file name, and in the installed package.
 
-* Some projects prefer that there be a version string available as an attribute in the importable module, e.g::
+* A package may, if the maintainers think it useful, to be able to determine the version of the package from Python code without relying on a package manager's metadata, set a top level ``__version__`` attribute.
+The value of ``__version__`` attribute and that passed to the build system can (and should) be kept in sync in :ref:`the build systems's recommended way `.
 
-    import a_package
-    print(a_package.__version__)
-
-* In the metadata of the artifacts for each of the packaging ecosystems    
+Should a package not set a top level ``__version__`` attribute, the version can still be accessed using ``importlib.metadata.version("distribution_name")``.
 
 While different projects have different needs, it's important to make sure that there is a single source of truth for the version number.
 
@@ -27,17 +25,15 @@ In general, the options are:
 
 2) The version can be hard-coded into the `pyproject.toml` file -- and the build system can copy it into other locations it may be required.
 
-3) The version string can be hard-coded into the source code -- either in a special purpose file, such as `_version.txt`, or as a attribute in the `__init__.py`, and the build system can extract it at build time.
-
-If the version string is not in the source, it can be extracted at runtime with code in `__init__.py`, such as::
-
-    import importlib.metadata
-    __version__ = importlib.metadata.version('the_distribution_name')
+3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time.
 
 
 Consult your build system documentation for how to implement your preferred method.
 
-Here are the common ones:
+.. _how_to_set_version_links:
+
+Build System Version Handling
+----------------------------
 
 * `Hatch `_
 

From 6d4aeb3b602f5987843cec7db024a725364f1ed9 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Fri, 26 Jul 2024 09:39:32 -0700
Subject: [PATCH 395/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Brénainn Woodsend 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 8a2eb5cf8..2f5f0bc60 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -28,7 +28,7 @@ In general, the options are:
 3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time.
 
 
-Consult your build system documentation for how to implement your preferred method.
+Consult your build system's documentation for their recommended method.
 
 .. _how_to_set_version_links:
 

From 49e743d1b91866b7ab22677ae88c87dfc7a362c5 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Fri, 26 Jul 2024 10:01:56 -0700
Subject: [PATCH 396/733] Update source/single_source_version.rst

Co-authored-by: Thomas A Caswell 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 2f5f0bc60..431b8ec62 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -15,7 +15,7 @@ One of the challenges in building packages is that the version string can be req
 * A package may, if the maintainers think it useful, to be able to determine the version of the package from Python code without relying on a package manager's metadata, set a top level ``__version__`` attribute.
 The value of ``__version__`` attribute and that passed to the build system can (and should) be kept in sync in :ref:`the build systems's recommended way `.
 
-Should a package not set a top level ``__version__`` attribute, the version can still be accessed using ``importlib.metadata.version("distribution_name")``.
+In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``.
 
 While different projects have different needs, it's important to make sure that there is a single source of truth for the version number.
 

From 0598c698d133c4679d2535907119f82eb66c0f00 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Fri, 26 Jul 2024 10:02:18 -0700
Subject: [PATCH 397/733] Update source/single_source_version.rst

Co-authored-by: Thomas A Caswell 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 431b8ec62..ac5c62445 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -17,7 +17,7 @@ The value of ``__version__`` attribute and that passed to the build system can (
 
 In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``.
 
-While different projects have different needs, it's important to make sure that there is a single source of truth for the version number.
+To ensure that version numbers do not get out of sync, it is recommended that there is a single source of truth for the version number.
 
 In general, the options are:
 

From 2a3249985cc35c9ed6f5b632cb2071bf804bdbd7 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Fri, 26 Jul 2024 10:31:38 -0700
Subject: [PATCH 398/733] updated the __version__ description

---
 source/single_source_version.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index ac5c62445..682ab8d22 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -12,8 +12,7 @@ One of the challenges in building packages is that the version string can be req
 * It needs to be specified when building the package (e.g. in :file:``pyproject.toml``)
    - That will assure that it is properly assigned in the distribution file name, and in the installed package.
 
-* A package may, if the maintainers think it useful, to be able to determine the version of the package from Python code without relying on a package manager's metadata, set a top level ``__version__`` attribute.
-The value of ``__version__`` attribute and that passed to the build system can (and should) be kept in sync in :ref:`the build systems's recommended way `.
+* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
 
 In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``.
 

From d1cbce9c0d6acb5caeee8d59811c4b96cfebe652 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 13:08:40 -0700
Subject: [PATCH 399/733] a few suggestions from the PR discussion

---
 source/single_source_version.rst | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 682ab8d22..63bc3f870 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -5,7 +5,7 @@ Single-sourcing the Project Version
 ===================================
 
 :Page Status: Complete
-:Last Reviewed: 2015-09-08
+:Last Reviewed: 2024-??
 
 One of the challenges in building packages is that the version string can be required in multiple places.
 
@@ -34,13 +34,15 @@ Consult your build system's documentation for their recommended method.
 Build System Version Handling
 ----------------------------
 
-* `Hatch `_
+* `Flit `_
+
+* `Hatchling `_
+
+* `PDM `_
 
 * `Setuptools `_
 
   -  `setuptools_scm `_
 
-* `Flit `_
 
-* `PDM `_
 

From 0fc5aca7f34220df01f482412dd59d89371877ff Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 11:14:57 -0700
Subject: [PATCH 400/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 63bc3f870..866073ab9 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -22,7 +22,7 @@ In general, the options are:
 
 1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS.
 
-2) The version can be hard-coded into the `pyproject.toml` file -- and the build system can copy it into other locations it may be required.
+2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required.
 
 3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time.
 

From 7d60695531dc8adbe65f42cd27d36bd3a988c9cb Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 11:15:18 -0700
Subject: [PATCH 401/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 866073ab9..0fa7488c7 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -10,7 +10,7 @@ Single-sourcing the Project Version
 One of the challenges in building packages is that the version string can be required in multiple places.
 
 * It needs to be specified when building the package (e.g. in :file:``pyproject.toml``)
-   - That will assure that it is properly assigned in the distribution file name, and in the installed package.
+   - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata.
 
 * A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
 

From 28c8bcbd0e05edc8c728750327b81d3f0f356827 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 11:59:12 -0700
Subject: [PATCH 402/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 0fa7488c7..a77183a27 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -9,7 +9,7 @@ Single-sourcing the Project Version
 
 One of the challenges in building packages is that the version string can be required in multiple places.
 
-* It needs to be specified when building the package (e.g. in :file:``pyproject.toml``)
+* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
    - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata.
 
 * A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.

From 00d86455f7cacd33ebf3798e6973d0b1b8ee4246 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 11:59:28 -0700
Subject: [PATCH 403/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index a77183a27..0e5034b5d 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -24,7 +24,7 @@ In general, the options are:
 
 2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required.
 
-3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time.
+3) The version string can be hard-coded into the source code -- either in a special purpose file, such as :file:`_version.txt`, or as a attribute in the :file:`__init__.py`, and the build system can extract it at build time.
 
 
 Consult your build system's documentation for their recommended method.

From 50a588f3b8ba35be43fb5090f436bd71d45d9de8 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 12:15:02 -0700
Subject: [PATCH 404/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 0e5034b5d..974a09a68 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -20,7 +20,7 @@ To ensure that version numbers do not get out of sync, it is recommended that th
 
 In general, the options are:
 
-1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS.
+1) If the code is in a version control system (VCS), e.g. Git, then the version can be extracted from the VCS.
 
 2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required.
 

From db4e9884b67e10e9f08aac7955c41d7116650bc9 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 13:13:49 -0700
Subject: [PATCH 405/733] minor formatting edit

---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 974a09a68..28d963858 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -32,7 +32,7 @@ Consult your build system's documentation for their recommended method.
 .. _how_to_set_version_links:
 
 Build System Version Handling
-----------------------------
+-----------------------------
 
 * `Flit `_
 

From 83c7f246e1889b5156d8ff1fd95f375ab0fa727e Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Wed, 31 Jul 2024 15:04:58 -0700
Subject: [PATCH 406/733] Update source/single_source_version.rst

Co-authored-by: Thomas A Caswell 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 28d963858..0a3c234be 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -12,7 +12,7 @@ One of the challenges in building packages is that the version string can be req
 * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
    - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata.
 
-* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
+* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
 
 In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``.
 

From a1df94c25b95c482a5b9a62b5b6e632eff12fe85 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Wed, 31 Jul 2024 15:25:49 -0700
Subject: [PATCH 407/733] a few more edits from the PR comments, and adding it
 back to the index (in the right place?)

---
 source/single_source_version.rst | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 0a3c234be..3eea6af50 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -12,9 +12,9 @@ One of the challenges in building packages is that the version string can be req
 * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
    - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata.
 
-* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
+* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
 
-In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``.
+In any case, The installed distribution version should be accessible using ``importlib.metadata.version("distribution_name")``.
 
 To ensure that version numbers do not get out of sync, it is recommended that there is a single source of truth for the version number.
 
@@ -29,11 +29,13 @@ In general, the options are:
 
 Consult your build system's documentation for their recommended method.
 
-.. _how_to_set_version_links:
+.. _Build system version handling:
 
 Build System Version Handling
 -----------------------------
 
+The following are links to some build system's documentation for handling version strings.
+
 * `Flit `_
 
 * `Hatchling `_

From ba32cc627044665cccab4d3fe0ac30bf716ac85c Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Wed, 31 Jul 2024 16:58:17 -0700
Subject: [PATCH 408/733] added single_source page back in -- not sure if it's
 the right section.

---
 source/discussions/index.rst                       | 1 +
 source/{ => discussions}/single_source_version.rst | 0
 2 files changed, 1 insertion(+)
 rename source/{ => discussions}/single_source_version.rst (100%)

diff --git a/source/discussions/index.rst b/source/discussions/index.rst
index bc1154507..907b61403 100644
--- a/source/discussions/index.rst
+++ b/source/discussions/index.rst
@@ -13,3 +13,4 @@ specific topic. If you're just trying to get stuff done, see
    install-requires-vs-requirements
    wheel-vs-egg
    src-layout-vs-flat-layout
+   single_source_version
diff --git a/source/single_source_version.rst b/source/discussions/single_source_version.rst
similarity index 100%
rename from source/single_source_version.rst
rename to source/discussions/single_source_version.rst

From 476f9160889801d91a6d1e6cf2fa6aba14070c97 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 25 Jul 2024 09:34:31 -0700
Subject: [PATCH 409/733] updated single_source_version with a much simpler
 page -- essentially refering folks to their build system of choice.

---
 source/single_source_version.rst | 51 ++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 source/single_source_version.rst

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
new file mode 100644
index 000000000..206ff5020
--- /dev/null
+++ b/source/single_source_version.rst
@@ -0,0 +1,51 @@
+.. _`Single sourcing the version`:
+
+===================================
+Single-sourcing the Project Version
+===================================
+
+:Page Status: Complete
+:Last Reviewed: 2015-09-08
+
+One of the challenges in building packages is that the version string can be required in multiple places.
+
+* It needs to be specified when building the package (e.g. in pyproject.toml)
+   - That will assure that it is properly assigned in the distribution file name, and in teh installed package.
+
+* Some projects require that there be a version string available as an attribute in the importable module, e.g::
+
+    import a_package
+    print(a_package.__version__)
+
+While different projects have different needs, it's important to make sure that there is a single source of truth for the version number.
+
+In general, the options are:
+
+1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS.
+
+2) The version can be hard-coded into the `pyproject.toml` file -- and the build system can copy it into other locations it may be required.
+
+3) The version string can be hard-coded into the source code -- either in a special purpose file, such as `_version.txt`, or as a attribute in the `__init__.py`, and the build system can extract it at build time.
+
+If the version string is not in the source, it can be extracted at runtime with code in `__init__.py`, such as::
+
+    import importlib.metadata
+    __version__ = importlib.metadata.version('the_distribution_name')
+
+
+Consult your build system documentation for how to implement your preferred method.
+
+Put links in to build system docs?
+-- I have no idea which are currently robust and maintained -- do we want to get into seeming endorsing particular tools in this doc?
+
+
+* setuptools:
+
+* hatch:
+
+* poetry:
+
+* PyBuilder:
+
+* Others?
+

From 0512c222a23ca9118657dc70d20e519c6840f804 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 25 Jul 2024 11:17:19 -0700
Subject: [PATCH 410/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 206ff5020..766247711 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -9,7 +9,7 @@ Single-sourcing the Project Version
 
 One of the challenges in building packages is that the version string can be required in multiple places.
 
-* It needs to be specified when building the package (e.g. in pyproject.toml)
+* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
    - That will assure that it is properly assigned in the distribution file name, and in teh installed package.
 
 * Some projects require that there be a version string available as an attribute in the importable module, e.g::

From 892d0454094b85fcfb09db855223a2178215143a Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 25 Jul 2024 11:20:08 -0700
Subject: [PATCH 411/733] Update source/single_source_version.rst

Co-authored-by: Thomas A Caswell 
---
 source/single_source_version.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 766247711..c075e56a9 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -16,6 +16,7 @@ One of the challenges in building packages is that the version string can be req
 
     import a_package
     print(a_package.__version__)
+* In the metadata of the artifacts for each of the packaging ecosystems    
 
 While different projects have different needs, it's important to make sure that there is a single source of truth for the version number.
 

From 6db49ef0cda4b869604679895024fe39f54882b7 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 25 Jul 2024 14:51:07 -0700
Subject: [PATCH 412/733] Added links to build tools

---
 source/single_source_version.rst | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index c075e56a9..e307dd5a7 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -10,12 +10,13 @@ Single-sourcing the Project Version
 One of the challenges in building packages is that the version string can be required in multiple places.
 
 * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
-   - That will assure that it is properly assigned in the distribution file name, and in teh installed package.
+   - That will assure that it is properly assigned in the distribution file name, and in the installed package.
 
 * Some projects require that there be a version string available as an attribute in the importable module, e.g::
 
     import a_package
     print(a_package.__version__)
+
 * In the metadata of the artifacts for each of the packaging ecosystems    
 
 While different projects have different needs, it's important to make sure that there is a single source of truth for the version number.
@@ -36,17 +37,15 @@ If the version string is not in the source, it can be extracted at runtime with
 
 Consult your build system documentation for how to implement your preferred method.
 
-Put links in to build system docs?
--- I have no idea which are currently robust and maintained -- do we want to get into seeming endorsing particular tools in this doc?
-
+Here are the common ones:
 
-* setuptools:
+* `Hatch `_
 
-* hatch:
+* `Setuptools `_
 
-* poetry:
+  -  `setuptools_scm `_
 
-* PyBuilder:
+* `Flit `_
 
-* Others?
+* `PDM `_
 

From afa38c49a3f65d1c364021a46400ded3f4ac9b19 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 25 Jul 2024 14:53:58 -0700
Subject: [PATCH 413/733] swap prefer for require

---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index e307dd5a7..46954a8e2 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -12,7 +12,7 @@ One of the challenges in building packages is that the version string can be req
 * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
    - That will assure that it is properly assigned in the distribution file name, and in the installed package.
 
-* Some projects require that there be a version string available as an attribute in the importable module, e.g::
+* Some projects prefer that there be a version string available as an attribute in the importable module, e.g::
 
     import a_package
     print(a_package.__version__)

From b9bb45d3fd7d9c6ce47fb44407f59dba3a66d1c2 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 25 Jul 2024 15:11:36 -0700
Subject: [PATCH 414/733] replace text about __version__

---
 source/single_source_version.rst | 22 +++++++++-------------
 1 file changed, 9 insertions(+), 13 deletions(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 46954a8e2..8a2eb5cf8 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -9,15 +9,13 @@ Single-sourcing the Project Version
 
 One of the challenges in building packages is that the version string can be required in multiple places.
 
-* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
+* It needs to be specified when building the package (e.g. in :file:``pyproject.toml``)
    - That will assure that it is properly assigned in the distribution file name, and in the installed package.
 
-* Some projects prefer that there be a version string available as an attribute in the importable module, e.g::
+* A package may, if the maintainers think it useful, to be able to determine the version of the package from Python code without relying on a package manager's metadata, set a top level ``__version__`` attribute.
+The value of ``__version__`` attribute and that passed to the build system can (and should) be kept in sync in :ref:`the build systems's recommended way `.
 
-    import a_package
-    print(a_package.__version__)
-
-* In the metadata of the artifacts for each of the packaging ecosystems    
+Should a package not set a top level ``__version__`` attribute, the version can still be accessed using ``importlib.metadata.version("distribution_name")``.
 
 While different projects have different needs, it's important to make sure that there is a single source of truth for the version number.
 
@@ -27,17 +25,15 @@ In general, the options are:
 
 2) The version can be hard-coded into the `pyproject.toml` file -- and the build system can copy it into other locations it may be required.
 
-3) The version string can be hard-coded into the source code -- either in a special purpose file, such as `_version.txt`, or as a attribute in the `__init__.py`, and the build system can extract it at build time.
-
-If the version string is not in the source, it can be extracted at runtime with code in `__init__.py`, such as::
-
-    import importlib.metadata
-    __version__ = importlib.metadata.version('the_distribution_name')
+3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time.
 
 
 Consult your build system documentation for how to implement your preferred method.
 
-Here are the common ones:
+.. _how_to_set_version_links:
+
+Build System Version Handling
+----------------------------
 
 * `Hatch `_
 

From 635908378ba7759579afcf509d50cf9166df67b2 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Fri, 26 Jul 2024 09:39:32 -0700
Subject: [PATCH 415/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Brénainn Woodsend 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 8a2eb5cf8..2f5f0bc60 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -28,7 +28,7 @@ In general, the options are:
 3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time.
 
 
-Consult your build system documentation for how to implement your preferred method.
+Consult your build system's documentation for their recommended method.
 
 .. _how_to_set_version_links:
 

From e6b0ed9b9cc471eef860670e38f8526e617b7a2a Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Fri, 26 Jul 2024 10:01:56 -0700
Subject: [PATCH 416/733] Update source/single_source_version.rst

Co-authored-by: Thomas A Caswell 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 2f5f0bc60..431b8ec62 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -15,7 +15,7 @@ One of the challenges in building packages is that the version string can be req
 * A package may, if the maintainers think it useful, to be able to determine the version of the package from Python code without relying on a package manager's metadata, set a top level ``__version__`` attribute.
 The value of ``__version__`` attribute and that passed to the build system can (and should) be kept in sync in :ref:`the build systems's recommended way `.
 
-Should a package not set a top level ``__version__`` attribute, the version can still be accessed using ``importlib.metadata.version("distribution_name")``.
+In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``.
 
 While different projects have different needs, it's important to make sure that there is a single source of truth for the version number.
 

From 54906dae953b022672c13f6645d4273326a0e22f Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Fri, 26 Jul 2024 10:02:18 -0700
Subject: [PATCH 417/733] Update source/single_source_version.rst

Co-authored-by: Thomas A Caswell 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 431b8ec62..ac5c62445 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -17,7 +17,7 @@ The value of ``__version__`` attribute and that passed to the build system can (
 
 In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``.
 
-While different projects have different needs, it's important to make sure that there is a single source of truth for the version number.
+To ensure that version numbers do not get out of sync, it is recommended that there is a single source of truth for the version number.
 
 In general, the options are:
 

From 398b4fbc5d5f92d8fee80bffb8b724b90b96e4f3 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Fri, 26 Jul 2024 10:31:38 -0700
Subject: [PATCH 418/733] updated the __version__ description

---
 source/single_source_version.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index ac5c62445..682ab8d22 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -12,8 +12,7 @@ One of the challenges in building packages is that the version string can be req
 * It needs to be specified when building the package (e.g. in :file:``pyproject.toml``)
    - That will assure that it is properly assigned in the distribution file name, and in the installed package.
 
-* A package may, if the maintainers think it useful, to be able to determine the version of the package from Python code without relying on a package manager's metadata, set a top level ``__version__`` attribute.
-The value of ``__version__`` attribute and that passed to the build system can (and should) be kept in sync in :ref:`the build systems's recommended way `.
+* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
 
 In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``.
 

From e7d23699b39f4cffcc8a1619f375334f88a207a0 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 13:08:40 -0700
Subject: [PATCH 419/733] a few suggestions from the PR discussion

---
 source/single_source_version.rst | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 682ab8d22..63bc3f870 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -5,7 +5,7 @@ Single-sourcing the Project Version
 ===================================
 
 :Page Status: Complete
-:Last Reviewed: 2015-09-08
+:Last Reviewed: 2024-??
 
 One of the challenges in building packages is that the version string can be required in multiple places.
 
@@ -34,13 +34,15 @@ Consult your build system's documentation for their recommended method.
 Build System Version Handling
 ----------------------------
 
-* `Hatch `_
+* `Flit `_
+
+* `Hatchling `_
+
+* `PDM `_
 
 * `Setuptools `_
 
   -  `setuptools_scm `_
 
-* `Flit `_
 
-* `PDM `_
 

From 0ff8c16eb5605d4350b9ae0c3c4f93e0f450dcb9 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 11:14:57 -0700
Subject: [PATCH 420/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 63bc3f870..866073ab9 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -22,7 +22,7 @@ In general, the options are:
 
 1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS.
 
-2) The version can be hard-coded into the `pyproject.toml` file -- and the build system can copy it into other locations it may be required.
+2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required.
 
 3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time.
 

From 8529adad95a8e095bf39736918384874306556db Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 11:15:18 -0700
Subject: [PATCH 421/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 866073ab9..0fa7488c7 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -10,7 +10,7 @@ Single-sourcing the Project Version
 One of the challenges in building packages is that the version string can be required in multiple places.
 
 * It needs to be specified when building the package (e.g. in :file:``pyproject.toml``)
-   - That will assure that it is properly assigned in the distribution file name, and in the installed package.
+   - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata.
 
 * A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
 

From 840474d649b870236722c9bf72e1341a3b9eaee8 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 11:59:12 -0700
Subject: [PATCH 422/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 0fa7488c7..a77183a27 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -9,7 +9,7 @@ Single-sourcing the Project Version
 
 One of the challenges in building packages is that the version string can be required in multiple places.
 
-* It needs to be specified when building the package (e.g. in :file:``pyproject.toml``)
+* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
    - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata.
 
 * A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.

From 61dc0b8a1bdffd1f5700126ffab11d4b772f9975 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 11:59:28 -0700
Subject: [PATCH 423/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index a77183a27..0e5034b5d 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -24,7 +24,7 @@ In general, the options are:
 
 2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required.
 
-3) The version string can be hard-coded into the source code -- either in a special purpose file, such as ``_version.txt``, or as a attribute in the ``__init__.py``, and the build system can extract it at build time.
+3) The version string can be hard-coded into the source code -- either in a special purpose file, such as :file:`_version.txt`, or as a attribute in the :file:`__init__.py`, and the build system can extract it at build time.
 
 
 Consult your build system's documentation for their recommended method.

From f93293500062f2b1a86923b1132ea344052dad02 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 12:15:02 -0700
Subject: [PATCH 424/733] Update source/single_source_version.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 0e5034b5d..974a09a68 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -20,7 +20,7 @@ To ensure that version numbers do not get out of sync, it is recommended that th
 
 In general, the options are:
 
-1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS.
+1) If the code is in a version control system (VCS), e.g. Git, then the version can be extracted from the VCS.
 
 2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required.
 

From ae2ad095a85cebe23395e7554fa5ec47a42a28a8 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Tue, 30 Jul 2024 13:13:49 -0700
Subject: [PATCH 425/733] minor formatting edit

---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 974a09a68..28d963858 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -32,7 +32,7 @@ Consult your build system's documentation for their recommended method.
 .. _how_to_set_version_links:
 
 Build System Version Handling
-----------------------------
+-----------------------------
 
 * `Flit `_
 

From 01f66a96054e5164a766238705d7fac3eb1d381b Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Wed, 31 Jul 2024 15:04:58 -0700
Subject: [PATCH 426/733] Update source/single_source_version.rst

Co-authored-by: Thomas A Caswell 
---
 source/single_source_version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 28d963858..0a3c234be 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -12,7 +12,7 @@ One of the challenges in building packages is that the version string can be req
 * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
    - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata.
 
-* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the installed package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
+* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
 
 In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``.
 

From 9d353a75cc6b3b4171ca5dda95fb2e59a85afa64 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Wed, 31 Jul 2024 15:25:49 -0700
Subject: [PATCH 427/733] a few more edits from the PR comments, and adding it
 back to the index (in the right place?)

---
 source/single_source_version.rst | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/source/single_source_version.rst b/source/single_source_version.rst
index 0a3c234be..3eea6af50 100644
--- a/source/single_source_version.rst
+++ b/source/single_source_version.rst
@@ -12,9 +12,9 @@ One of the challenges in building packages is that the version string can be req
 * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
    - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata.
 
-* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
+* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
 
-In the cases where a package does not set a top level ``__version__`` attribute, the version may still be accessible using ``importlib.metadata.version("distribution_name")``.
+In any case, The installed distribution version should be accessible using ``importlib.metadata.version("distribution_name")``.
 
 To ensure that version numbers do not get out of sync, it is recommended that there is a single source of truth for the version number.
 
@@ -29,11 +29,13 @@ In general, the options are:
 
 Consult your build system's documentation for their recommended method.
 
-.. _how_to_set_version_links:
+.. _Build system version handling:
 
 Build System Version Handling
 -----------------------------
 
+The following are links to some build system's documentation for handling version strings.
+
 * `Flit `_
 
 * `Hatchling `_

From 1aae700cd7adf7e2c387c1af9ca0b25ad7c3bb16 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Wed, 31 Jul 2024 16:58:17 -0700
Subject: [PATCH 428/733] added single_source page back in -- not sure if it's
 the right section.

---
 source/discussions/index.rst                       | 1 +
 source/{ => discussions}/single_source_version.rst | 0
 2 files changed, 1 insertion(+)
 rename source/{ => discussions}/single_source_version.rst (100%)

diff --git a/source/discussions/index.rst b/source/discussions/index.rst
index d262bcff2..531e5c126 100644
--- a/source/discussions/index.rst
+++ b/source/discussions/index.rst
@@ -16,3 +16,4 @@ specific topic. If you're just trying to get stuff done, see
    package-formats
    src-layout-vs-flat-layout
    setup-py-deprecated
+   single_source_version
diff --git a/source/single_source_version.rst b/source/discussions/single_source_version.rst
similarity index 100%
rename from source/single_source_version.rst
rename to source/discussions/single_source_version.rst

From f130e816f962320ba847efc43c0221477a0c923d Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 1 Aug 2024 00:21:18 +0000
Subject: [PATCH 429/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/discussions/single_source_version.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/source/discussions/single_source_version.rst b/source/discussions/single_source_version.rst
index 3eea6af50..5fbb89b00 100644
--- a/source/discussions/single_source_version.rst
+++ b/source/discussions/single_source_version.rst
@@ -45,6 +45,3 @@ The following are links to some build system's documentation for handling versio
 * `Setuptools `_
 
   -  `setuptools_scm `_
-
-
-

From 5b40e9c6745650c86facb37c1b6eca9aec181178 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Wed, 31 Jul 2024 17:40:25 -0700
Subject: [PATCH 430/733] updated notes on conda.

---
 source/key_projects.rst | 40 ++++++++++++++++++++++------------------
 1 file changed, 22 insertions(+), 18 deletions(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 531c28066..6c8e5d16a 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -404,26 +404,30 @@ conda
 
 :doc:`Docs `
 
-conda is the package management tool for `Anaconda
-`__ Python installations.
-Anaconda Python is a distribution from `Anaconda, Inc
-`__ specifically aimed at the scientific
-community, and in particular on Windows where the installation of binary
-extensions is often difficult.
+Conda is a package, dependency, and environment management system for any language — Python, R,
+Ruby, C/C++, Fortran, and more. It is written in Python and
+widely used in the Python scientific computing community, due to its support for non-Python
+compiled libraries and extensions. It is used as the basis of the `Anaconda
+`__ Python distribution from `Anaconda, Inc.specifically
+aimed at the scientific community, community, but can also be used on its own, or with the
+:doc:`miniconda `, `miniforge `_ or
+`pixi `_ systems. It is available for Windows, Mac and Linux systems.
 
 Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, but provides
-many of their combined features in terms of package management, virtual environment
-management and deployment of binary extensions.
-
-Conda does not install packages from PyPI and can install only from
-the official Anaconda repositories, or anaconda.org (a place for
-user-contributed *conda* packages), or a local (e.g. intranet) package
-server.  However, note that :ref:`pip` can be installed into, and work
-side-by-side with conda for managing :term:`distributions
-` from PyPI. Also, `conda skeleton
-`__
-is a tool to make Python packages installable by conda by first
-fetching them from PyPI and modifying their metadata.
+many of their combined features, such as package management, virtual environment
+management and deployment of binary extensions and other binary code.
+
+Conda does not install packages from PyPI -- it can only manage packages built specifically
+for conda, which can be made available on a "conda channel", such as those hosted on
+`anaconda.org `__ or a local (e.g. intranet) package server.
+In addition to the "default" channels managed by `Anaconda, Inc. `__, there are a wide variety of packages from the community supported
+`conda-forge project `__
+
+Note that :ref:`pip` can be installed into, and work side-by-side with conda
+for managing :term:`distributions ` from PyPI. It is also possible
+to build conda packages from Python source packages using tools such as
+`conda skeleton
+`__: a tool to automatically make conda packages from Python packages available on PyPI.
 
 .. _devpi:
 

From 934e11b5fda9dafaad0cb1c3c3a4ae9db1b2ecc6 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Wed, 31 Jul 2024 17:53:50 -0700
Subject: [PATCH 431/733] added updated conda info to the scientific packages
 page.

---
 source/guides/installing-scientific-packages.rst | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst
index 5677d382a..654db3d62 100644
--- a/source/guides/installing-scientific-packages.rst
+++ b/source/guides/installing-scientific-packages.rst
@@ -134,5 +134,10 @@ native virtual environments. Conda makes environments first-class citizens,
 making it easy to create independent environments even for C libraries. It is
 written in Python, but is Python-agnostic. Conda manages Python itself as a
 package, so that :command:`conda update python` is possible, in contrast to
-pip, which only manages Python packages. Conda is available in Anaconda and
-Miniconda (an easy-to-install download with just Python and conda).
+pip, which only manages Python packages.
+
+The conda package manager is available in `Anaconda `_, `miniconda `_, `miniforge `_, and `pixi `_.
+
+Conda packages are available on multiple channels on Anaconda.org, including the
+default channel supported by Anaconda, Inc, and the community supported conda-forge
+channel, which provides a wide variety of pre-built packages.

From a08ca8023c0ecb924edb26098ea753b7c7cbb416 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ville=20Skytt=C3=A4?= 
Date: Mon, 15 Jul 2024 23:31:13 +0300
Subject: [PATCH 432/733] Refer to platform tag as such in use example

There's no arch tag.
---
 source/specifications/platform-compatibility-tags.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 381b84ca9..740a28a1a 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -256,7 +256,7 @@ The full list of simple tags is::
 
     for x in pytag.split('.'):
         for y in abitag.split('.'):
-            for z in archtag.split('.'):
+            for z in platformtag.split('.'):
                 yield '-'.join((x, y, z))
 
 A bdist format that implements this scheme should include the expanded

From 3d9aced31ab5cf68777fd57dea7a3d22ddc7d84d Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan 
Date: Thu, 8 Aug 2024 18:25:00 +1000
Subject: [PATCH 433/733] Add Direct URL security heading

No changes to the spec, just adding a heading to
highlight the notes on avoiding credential leaks.
---
 source/specifications/direct-url-data-structure.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index 9ec8e2e34..6a4e8fe01 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -31,6 +31,9 @@ Depending on what ``url`` refers to, the second field MUST be one of ``vcs_info`
 local directory). These info fields have a (possibly empty) subdictionary as
 value, with the possible keys defined below.
 
+Security Considerations
+-----------------------
+
 When persisted, ``url`` MUST be stripped of any sensitive authentication information,
 for security reasons.
 

From c6a145509b9acc17121bb619ef7265d12bf3b4a7 Mon Sep 17 00:00:00 2001
From: "Eden Ross Duff, MSc" 
Date: Sun, 11 Aug 2024 21:42:12 -0500
Subject: [PATCH 434/733] clarify ``Provides-Dist`` example to match warehouse
 wheel metadata validation

---
 source/specifications/core-metadata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 90793c791..fb6570fbb 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -725,7 +725,7 @@ This field may be followed by an environment marker after a semicolon.
 Examples::
 
     Provides-Dist: OtherProject
-    Provides-Dist: AnotherProject (3.4)
+    Provides-Dist: AnotherProject==3.4
     Provides-Dist: virtual_package; python_version >= "3.4"
 
 .. _core-metadata-obsoletes-dist:

From e9713306df7753e9fe7397ff559cbbcb9d4cae00 Mon Sep 17 00:00:00 2001
From: Stephen Nixon <45946693+arrowtype@users.noreply.github.com>
Date: Fri, 16 Aug 2024 22:48:58 -0400
Subject: [PATCH 435/733] Update creating-command-line-tools.rst to fix typo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The import statement, as written, fails. It doesn’t match the name of the file that is set up with the greet() function.
---
 source/guides/creating-command-line-tools.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst
index 9f040ce7d..49ce0c9ed 100644
--- a/source/guides/creating-command-line-tools.rst
+++ b/source/guides/creating-command-line-tools.rst
@@ -78,7 +78,7 @@ in :file:`cli.py`:
 
     import typer
 
-    from .hello import greet
+    from .greet import greet
 
 
     app = typer.Typer()

From c864782b753b81e88fe55e586566d28bbf5e9543 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 19 Aug 2024 17:06:58 -0400
Subject: [PATCH 436/733] Update source/key_projects.rst

Co-authored-by: Alyssa Coghlan 
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 6c8e5d16a..7af8996a2 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -408,7 +408,7 @@ Conda is a package, dependency, and environment management system for any langua
 Ruby, C/C++, Fortran, and more. It is written in Python and
 widely used in the Python scientific computing community, due to its support for non-Python
 compiled libraries and extensions. It is used as the basis of the `Anaconda
-`__ Python distribution from `Anaconda, Inc.specifically
+`__ Python distribution from Anaconda, Inc. It waas originally
 aimed at the scientific community, community, but can also be used on its own, or with the
 :doc:`miniconda `, `miniforge `_ or
 `pixi `_ systems. It is available for Windows, Mac and Linux systems.

From 049603c58dab76dcb44b6f6226d934dfa3d84032 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 19 Aug 2024 17:07:45 -0400
Subject: [PATCH 437/733] Update source/key_projects.rst

Co-authored-by: Alyssa Coghlan 
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 7af8996a2..67bac3a54 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -409,7 +409,7 @@ Ruby, C/C++, Fortran, and more. It is written in Python and
 widely used in the Python scientific computing community, due to its support for non-Python
 compiled libraries and extensions. It is used as the basis of the `Anaconda
 `__ Python distribution from Anaconda, Inc. It waas originally
-aimed at the scientific community, community, but can also be used on its own, or with the
+aimed at the scientific community, but can also be used on its own, or with the
 :doc:`miniconda `, `miniforge `_ or
 `pixi `_ systems. It is available for Windows, Mac and Linux systems.
 

From e0c0e7ae3c627437e8430a2743ac71798768cca9 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 19 Aug 2024 17:08:09 -0400
Subject: [PATCH 438/733] Update source/key_projects.rst

Co-authored-by: Alyssa Coghlan 
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 67bac3a54..d8312e327 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -419,7 +419,7 @@ management and deployment of binary extensions and other binary code.
 
 Conda does not install packages from PyPI -- it can only manage packages built specifically
 for conda, which can be made available on a "conda channel", such as those hosted on
-`anaconda.org `__ or a local (e.g. intranet) package server.
+`anaconda.org `__, or a local (e.g. intranet) package server.
 In addition to the "default" channels managed by `Anaconda, Inc. `__, there are a wide variety of packages from the community supported
 `conda-forge project `__
 

From f62b5b5b51a6927dc6bf26627b35735dd351d9fd Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 19 Aug 2024 17:20:23 -0400
Subject: [PATCH 439/733] reworked intro paragraph to address duplicate links,
 and cleaner entry into conda vs. Anaconda.

---
 .../guides/installing-scientific-packages.rst | 20 ++++++++-----------
 1 file changed, 8 insertions(+), 12 deletions(-)

diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst
index 654db3d62..2d3e99920 100644
--- a/source/guides/installing-scientific-packages.rst
+++ b/source/guides/installing-scientific-packages.rst
@@ -14,7 +14,7 @@ In particular, `NumPy `__, which provides the basis
 for most of the software in the `scientific Python stack
 `_ can be configured
 to interoperate with different FORTRAN libraries, and can take advantage
-of different levels of vectorised instructions available in modern CPUs.
+of different levels of vectorized instructions available in modern CPUs.
 
 Starting with version 1.10.4 of NumPy and version 1.0.0 of SciPy, pre-built
 32-bit and 64-bit binaries in the ``wheel`` format are available for all major
@@ -118,17 +118,11 @@ be loaded and unloaded from the user's environment.
 The conda cross-platform package manager
 ----------------------------------------
 
-`Anaconda `_ is a Python distribution
-published by Anaconda, Inc. It is a stable collection of Open Source
-packages for big data and scientific use.  As of the 5.0 release of Anaconda,
-about 200 packages are installed by default, and a total of 400-500 can be
-installed and updated from the Anaconda repository.
-
 ``conda`` is an open source (BSD licensed) package management system and
-environment management system included in Anaconda that allows users to install
+environment management system that allows users to install
 multiple versions of binary software packages and their dependencies, and
 easily switch between them. It is a cross-platform tool working on Windows,
-macOS, and Linux. Conda can be used to package up and distribute all kinds of
+MacOS, and Linux. Conda can be used to package up and distribute all kinds of
 packages, it is not limited to just Python packages. It has full support for
 native virtual environments. Conda makes environments first-class citizens,
 making it easy to create independent environments even for C libraries. It is
@@ -136,8 +130,10 @@ written in Python, but is Python-agnostic. Conda manages Python itself as a
 package, so that :command:`conda update python` is possible, in contrast to
 pip, which only manages Python packages.
 
-The conda package manager is available in `Anaconda `_, `miniconda `_, `miniforge `_, and `pixi `_.
+Anaconda `Anaconda `_ is a Python distribution published by Anaconda, Inc. It is a stable collection of Open Source packages for big data and scientific use, and a collection of Graphical Interface utilities for managing conda environments.
+
+In addition to the full distribution provided by Anaconda, the conda package manager itself is available in  `miniconda `_, `miniforge `_, and `pixi `_.
+
 
 Conda packages are available on multiple channels on Anaconda.org, including the
-default channel supported by Anaconda, Inc, and the community supported conda-forge
-channel, which provides a wide variety of pre-built packages.
+default channel supported by Anaconda, Inc, the community supported conda-forge channel, which provides a wide variety of pre-built packages, and some domain-specific package collections.

From fd59cbedc028170f531d2b5c68f131c7154bf6b6 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 19 Aug 2024 17:24:01 -0400
Subject: [PATCH 440/733] Update source/key_projects.rst

Co-authored-by: sinoroc <5529267+sinoroc@users.noreply.github.com>
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index d8312e327..315897593 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -408,7 +408,7 @@ Conda is a package, dependency, and environment management system for any langua
 Ruby, C/C++, Fortran, and more. It is written in Python and
 widely used in the Python scientific computing community, due to its support for non-Python
 compiled libraries and extensions. It is used as the basis of the `Anaconda
-`__ Python distribution from Anaconda, Inc. It waas originally
+`__ Python distribution from Anaconda, Inc. It was originally
 aimed at the scientific community, but can also be used on its own, or with the
 :doc:`miniconda `, `miniforge `_ or
 `pixi `_ systems. It is available for Windows, Mac and Linux systems.

From e3e561f475a05a4fd5175d13082ca2dc0e1abee0 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 19 Aug 2024 17:27:57 -0400
Subject: [PATCH 441/733] fixed netlib link

---
 source/guides/installing-scientific-packages.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst
index 2d3e99920..eded4fa5b 100644
--- a/source/guides/installing-scientific-packages.rst
+++ b/source/guides/installing-scientific-packages.rst
@@ -20,7 +20,7 @@ Starting with version 1.10.4 of NumPy and version 1.0.0 of SciPy, pre-built
 32-bit and 64-bit binaries in the ``wheel`` format are available for all major
 operating systems (Windows, macOS, and Linux) on PyPI. Note, however, that on
 Windows, NumPy binaries are linked against the `ATLAS
-`__ BLAS/LAPACK library, restricted to SSE2
+`__ BLAS/LAPACK library, restricted to SSE2
 instructions, so they may not provide optimal linear algebra performance.
 
 There are a number of alternative options for obtaining scientific Python

From bf026f9978ada745dac68b658f31382cf3f1aab3 Mon Sep 17 00:00:00 2001
From: hutcho 
Date: Tue, 20 Aug 2024 16:40:15 +1000
Subject: [PATCH 442/733] Clarified note on [build-system] and [project]

Used clearer wording, instead of referring to tables as 'former' and 'latter'.
Grammar cleanup.
---
 source/guides/writing-pyproject-toml.rst | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 18a717a55..a705fde1e 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -22,19 +22,19 @@ three possible TOML tables in this file.
 
 .. note::
 
-   There is a significant difference between the ``[build-system]`` and
-   ``[project]`` tables. The former should always be present, regardless of
-   which build backend you use (since it *defines* the tool you use). The latter
-   is understood by *most* build backends, but some build backends use a
-   different format.
+   The ``[build-system]`` table should always be present,
+   regardless of which build backend you use (``[build-system]`` *defines* the
+   build tool you use). 
 
-   At the time of writing this (November 2023), Poetry_ is a notable build
-   backend that does not use the ``[project]`` table (it uses the
-   ``[tool.poetry]`` table instead).
+   On the other hand, the ``[project]`` table is understood by *most* build 
+   backends, but some build backends use a different format.
 
+   As of August 2024, Poetry_ is a notable build backend that does not use 
+   the ``[project]`` table, it uses the ``[tool.poetry]`` table instead. 
    Also, the setuptools_ build backend supports both the ``[project]`` table,
-   and the older format in ``setup.cfg`` or ``setup.py``. For new projects, it
-   is recommended to use the ``[project]`` table, and keep ``setup.py`` only if
+   and the older format in ``setup.cfg`` or ``setup.py``. 
+
+   For new projects, use the ``[project]`` table, and keep ``setup.py`` only if
    some programmatic configuration is needed (such as building C extensions),
    but the ``setup.cfg`` and ``setup.py`` formats are still valid. See
    :ref:`setup-py-deprecated`.

From 854030bc7c34f852c07f413afc051a8f1f685181 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 20 Aug 2024 06:42:43 +0000
Subject: [PATCH 443/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/guides/writing-pyproject-toml.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index a705fde1e..d11b8a87c 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -24,15 +24,15 @@ three possible TOML tables in this file.
 
    The ``[build-system]`` table should always be present,
    regardless of which build backend you use (``[build-system]`` *defines* the
-   build tool you use). 
+   build tool you use).
 
-   On the other hand, the ``[project]`` table is understood by *most* build 
+   On the other hand, the ``[project]`` table is understood by *most* build
    backends, but some build backends use a different format.
 
-   As of August 2024, Poetry_ is a notable build backend that does not use 
-   the ``[project]`` table, it uses the ``[tool.poetry]`` table instead. 
+   As of August 2024, Poetry_ is a notable build backend that does not use
+   the ``[project]`` table, it uses the ``[tool.poetry]`` table instead.
    Also, the setuptools_ build backend supports both the ``[project]`` table,
-   and the older format in ``setup.cfg`` or ``setup.py``. 
+   and the older format in ``setup.cfg`` or ``setup.py``.
 
    For new projects, use the ``[project]`` table, and keep ``setup.py`` only if
    some programmatic configuration is needed (such as building C extensions),

From 0aefb9e6df908047a3c0323e7e488c82294e88df Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Wed, 21 Aug 2024 16:48:49 -0700
Subject: [PATCH 444/733] Update source/discussions/single_source_version.rst

Co-authored-by: Philipp A. 
---
 source/discussions/single_source_version.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/discussions/single_source_version.rst b/source/discussions/single_source_version.rst
index 5fbb89b00..f08dc19cc 100644
--- a/source/discussions/single_source_version.rst
+++ b/source/discussions/single_source_version.rst
@@ -10,11 +10,11 @@ Single-sourcing the Project Version
 One of the challenges in building packages is that the version string can be required in multiple places.
 
 * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
-   - That will assure that it is properly assigned in the distribution file name, and in the installed package metadata.
+   This will make it available in the installed package’s metadata, from where it will be accessible at runtime using ``importlib.metadata.version("distribution_name")``.
 
-* A package may set a top level ``__version__`` attribute to provide runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
+* A package may set a top level ``__version__`` attribute to provide an alternative means of runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
 
-In any case, The installed distribution version should be accessible using ``importlib.metadata.version("distribution_name")``.
+* If the code is in in a version control system (VCS), e.g. Git, the version may appear in a *tag* such as ``v1.2.3``.
 
 To ensure that version numbers do not get out of sync, it is recommended that there is a single source of truth for the version number.
 

From 3b05459a595a4cbf83f6ea007436a7182a4bdd4a Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Wed, 21 Aug 2024 17:18:22 -0700
Subject: [PATCH 445/733] normalized the page file name

---
 source/discussions/index.rst                                    | 2 +-
 .../{single_source_version.rst => single-source-version.rst}    | 0
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename source/discussions/{single_source_version.rst => single-source-version.rst} (100%)

diff --git a/source/discussions/index.rst b/source/discussions/index.rst
index 531e5c126..1f5ff1f2b 100644
--- a/source/discussions/index.rst
+++ b/source/discussions/index.rst
@@ -16,4 +16,4 @@ specific topic. If you're just trying to get stuff done, see
    package-formats
    src-layout-vs-flat-layout
    setup-py-deprecated
-   single_source_version
+   single-source-version
diff --git a/source/discussions/single_source_version.rst b/source/discussions/single-source-version.rst
similarity index 100%
rename from source/discussions/single_source_version.rst
rename to source/discussions/single-source-version.rst

From c335757c2783a9a6245bb1955c3f107f62e9d602 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 22 Aug 2024 12:17:03 -0700
Subject: [PATCH 446/733] Update source/discussions/single-source-version.rst

Co-authored-by: Anderson Bravalheri 
---
 source/discussions/single-source-version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/single-source-version.rst b/source/discussions/single-source-version.rst
index f08dc19cc..74ecb6989 100644
--- a/source/discussions/single-source-version.rst
+++ b/source/discussions/single-source-version.rst
@@ -12,7 +12,7 @@ One of the challenges in building packages is that the version string can be req
 * It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
    This will make it available in the installed package’s metadata, from where it will be accessible at runtime using ``importlib.metadata.version("distribution_name")``.
 
-* A package may set a top level ``__version__`` attribute to provide an alternative means of runtime access to the version of the imported package. If this is done, the value of ``__version__`` attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
+* A package may set a module attribute (e.g., ``__version__``) to provide an alternative means of runtime access to the version of the imported package. If this is done, the value of the attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
 
 * If the code is in in a version control system (VCS), e.g. Git, the version may appear in a *tag* such as ``v1.2.3``.
 

From b35bd14a3ce8a8081aee7f51d45c84b061b2a7f6 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 22 Aug 2024 12:23:21 -0700
Subject: [PATCH 447/733] Update source/discussions/single-source-version.rst

Co-authored-by: Anderson Bravalheri 
---
 source/discussions/single-source-version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/single-source-version.rst b/source/discussions/single-source-version.rst
index 74ecb6989..05c2f962e 100644
--- a/source/discussions/single-source-version.rst
+++ b/source/discussions/single-source-version.rst
@@ -24,7 +24,7 @@ In general, the options are:
 
 2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required.
 
-3) The version string can be hard-coded into the source code -- either in a special purpose file, such as :file:`_version.txt`, or as a attribute in the :file:`__init__.py`, and the build system can extract it at build time.
+3) The version string can be hard-coded into the source code -- either in a special purpose file, such as :file:`_version.txt`, or as a attribute in a module, such as :file:`__init__.py`, and the build system can extract it at build time.
 
 
 Consult your build system's documentation for their recommended method.

From e0cb805e371e7144d8398f8e301ab345a3ffaf0f Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Thu, 22 Aug 2024 12:26:05 -0700
Subject: [PATCH 448/733] Update source/discussions/single-source-version.rst

Co-authored-by: Anderson Bravalheri 
---
 source/discussions/single-source-version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/single-source-version.rst b/source/discussions/single-source-version.rst
index 05c2f962e..2e7241cd7 100644
--- a/source/discussions/single-source-version.rst
+++ b/source/discussions/single-source-version.rst
@@ -42,6 +42,6 @@ The following are links to some build system's documentation for handling versio
 
 * `PDM `_
 
-* `Setuptools `_
+* `Setuptools `_
 
   -  `setuptools_scm `_

From b120a516ed3a986ae68149112cd8ad3fff98d5af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sviatoslav=20Sydorenko=20=28=D0=A1=D0=B2=D1=8F=D1=82=D0=BE?=
 =?UTF-8?q?=D1=81=D0=BB=D0=B0=D0=B2=20=D0=A1=D0=B8=D0=B4=D0=BE=D1=80=D0=B5?=
 =?UTF-8?q?=D0=BD=D0=BA=D0=BE=29?= 
Date: Sat, 24 Aug 2024 02:15:25 +0200
Subject: [PATCH 449/733] Make the single-sourcing discussion label unique

---
 source/discussions/single-source-version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/single-source-version.rst b/source/discussions/single-source-version.rst
index 2e7241cd7..115b8ded4 100644
--- a/source/discussions/single-source-version.rst
+++ b/source/discussions/single-source-version.rst
@@ -1,4 +1,4 @@
-.. _`Single sourcing the version`:
+.. _`Single sourcing the version discussion`:
 
 ===================================
 Single-sourcing the Project Version

From 4d7e33a875adb9fae0295f5d2995df7b3d41cf0c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sviatoslav=20Sydorenko=20=28=D0=A1=D0=B2=D1=8F=D1=82=D0=BE?=
 =?UTF-8?q?=D1=81=D0=BB=D0=B0=D0=B2=20=D0=A1=D0=B8=D0=B4=D0=BE=D1=80=D0=B5?=
 =?UTF-8?q?=D0=BD=D0=BA=D0=BE=29?= 
Date: Sat, 24 Aug 2024 02:16:42 +0200
Subject: [PATCH 450/733] =?UTF-8?q?=F0=9F=87=BA=F0=9F=87=A6=20Set=20the=20?=
 =?UTF-8?q?last-reviewed=20date=20in=20the=20single-sourced=20version=20di?=
 =?UTF-8?q?scussion?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 source/discussions/single-source-version.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/single-source-version.rst b/source/discussions/single-source-version.rst
index 115b8ded4..9bcab6291 100644
--- a/source/discussions/single-source-version.rst
+++ b/source/discussions/single-source-version.rst
@@ -5,7 +5,7 @@ Single-sourcing the Project Version
 ===================================
 
 :Page Status: Complete
-:Last Reviewed: 2024-??
+:Last Reviewed: 2024-08-24
 
 One of the challenges in building packages is that the version string can be required in multiple places.
 

From f7891eb22c50db1ae39d259ab0851f3486cbaaba Mon Sep 17 00:00:00 2001
From: Ee Durbin 
Date: Tue, 3 Sep 2024 09:45:08 -0400
Subject: [PATCH 451/733] add documentation for PEP 639, License-Expression and
 License-Field

---
 source/specifications/core-metadata.rst | 53 ++++++++++++++++++++++++-
 1 file changed, 51 insertions(+), 2 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index fb6570fbb..66218b178 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -48,7 +48,7 @@ Metadata-Version
 .. versionadded:: 1.0
 
 Version of the file format; legal values are "1.0", "1.1", "1.2", "2.1",
-"2.2", and "2.3".
+"2.2", "2.3", and "2.4".
 
 Automated tools consuming metadata SHOULD warn if ``metadata_version`` is
 greater than the highest version they support, and MUST fail if
@@ -63,7 +63,7 @@ all of the needed fields.
 
 Example::
 
-    Metadata-Version: 2.3
+    Metadata-Version: 2.4
 
 
 .. _core-metadata-name:
@@ -477,6 +477,50 @@ Examples::
     License: GPL version 3, excluding DRM provisions
 
 
+.. _license-expression-optional:
+.. _core-metadata-license-expression:
+
+License-Expression
+==================
+
+.. versionadded:: 2.4
+
+Text string that is a valid SPDX
+`license expression `__
+as `defined in PEP 639 `__.
+
+Examples::
+
+    License-Expression: MIT
+    License-Expression: BSD-3-Clause
+    License-Expression: MIT AND (Apache-2.0 OR BSD-2-Clause)
+    License-Expression: MIT OR GPL-2.0-or-later OR (FSFUL AND BSD-2-Clause)
+    License-Expression: GPL-3.0-only WITH Classpath-Exception-2.0 OR BSD-3-Clause
+    License-Expression: LicenseRef-Special-License OR CC0-1.0 OR Unlicense
+    License-Expression: LicenseRef-Proprietary
+
+
+.. _license-file-optional:
+.. _core-metadata-license-file:
+
+License-File (multiple use)
+===========================
+
+.. versionadded:: 2.4
+
+Each entry is a string representation of the path of a license-related file.
+The path is located within the project source tree, relative to the project
+root directory.
+
+Examples::
+
+    License-File: LICENSE
+    License-File: AUTHORS
+    License-File: LICENSE.txt
+    License-File: licenses/LICENSE.MIT
+    License-File: licenses/LICENSE.CC0
+
+
 .. _metadata-classifier:
 .. _core-metadata-classifier:
 
@@ -864,6 +908,11 @@ History
 
   - Restricted extra names to be normalized.
 
+- August 2024: Core metadata 2.4 was approved through :pep:`639`.
+
+  - Added the ``License-Expression`` field.
+  - Added the ``License-File`` field.
+
 ----
 
 .. [1] reStructuredText markup:

From 5821db4e1e59447e57602eaea23f3983bafd4581 Mon Sep 17 00:00:00 2001
From: Markus Grotz 
Date: Tue, 3 Sep 2024 23:45:46 -0700
Subject: [PATCH 452/733] Update download-artifact plugin in
 publish-to-test-pypi.yml to fix vulnerability

Versions of actions/download-artifact before 4.1.7 are vulnerable to arbitrary file write when downloading and extracting a specifically crafted artifact that contains path traversal filenames.

Fore more details see: https://github.com/advisories/GHSA-6q32-hq47-5qq3
---
 .../github-actions-ci-cd-sample/publish-to-test-pypi.yml  | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
index 3bd06cccc..3c0192b53 100644
--- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
+++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
@@ -22,7 +22,7 @@ jobs:
     - name: Build a binary wheel and a source tarball
       run: python3 -m build
     - name: Store the distribution packages
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: python-package-distributions
         path: dist/
@@ -42,7 +42,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
       with:
         name: python-package-distributions
         path: dist/
@@ -63,7 +63,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
       with:
         name: python-package-distributions
         path: dist/
@@ -107,7 +107,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
       with:
         name: python-package-distributions
         path: dist/

From a222c4a83b8f13f79f1e709772f1db447cad250d Mon Sep 17 00:00:00 2001
From: Ee Durbin 
Date: Sun, 15 Sep 2024 20:52:26 -0400
Subject: [PATCH 453/733] document deprecations and conflicts

---
 source/specifications/core-metadata.rst | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 66218b178..97686c543 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -460,6 +460,14 @@ License
 =======
 
 .. versionadded:: 1.0
+.. deprecated:: 2.4
+   in favour of ``License-Expression``.
+
+.. warning::
+    As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually
+    exclusive. If both are specified, tools which parse metadata will disregard
+    ``License`` and PyPI will reject uploads.
+    See `PEP 639 `__.
 
 Text indicating the license covering the distribution where the license
 is not a selection from the "License" Trove classifiers. See
@@ -510,7 +518,7 @@ License-File (multiple use)
 
 Each entry is a string representation of the path of a license-related file.
 The path is located within the project source tree, relative to the project
-root directory.
+root directory. For details see :pep:`639`.
 
 Examples::
 
@@ -534,6 +542,11 @@ for the distribution.  Classifiers are described in :pep:`301`,
 and the Python Package Index publishes a dynamic list of
 `currently defined classifiers `__.
 
+.. note::
+    The use of ``License ::`` classifiers  is deprecated as of Metadata 2.4,
+    use ``License-Expression`` instead. See
+    `PEP 639 `_.
+
 This field may be followed by an environment marker after a semicolon.
 
 Examples::

From 30450630fc30a76c03a4ef9bba4d86911a846170 Mon Sep 17 00:00:00 2001
From: Ee Durbin 
Date: Thu, 19 Sep 2024 08:48:07 -0400
Subject: [PATCH 454/733] fix broken link

---
 source/specifications/platform-compatibility-tags.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 740a28a1a..3679cf4ad 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -343,5 +343,5 @@ History
 
 
 .. _musl: https://musl.libc.org
-.. _ldd: https://www.unix.com/man-page/posix/1/ldd/
+.. _ldd: https://www.man7.org/linux/man-pages/man1/ldd.1.html
 .. _elf: https://refspecs.linuxfoundation.org/elf/elf.pdf

From fdc8df8ebdd13b589b5643c7b7634ac59fbfd410 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Fri, 11 Oct 2024 14:24:15 +0100
Subject: [PATCH 455/733] guides, specifications: update for PEP 753

Signed-off-by: William Woodruff 
---
 source/guides/writing-pyproject-toml.rst      |  12 +-
 source/specifications/core-metadata.rst       |  64 ++++---
 source/specifications/pyproject-toml.rst      |   3 +-
 .../section-distribution-metadata.rst         |   1 +
 .../well-known-project-urls.rst               | 176 ++++++++++++++++++
 5 files changed, 226 insertions(+), 30 deletions(-)
 create mode 100644 source/specifications/well-known-project-urls.rst

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index d11b8a87c..cb1639f50 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -399,6 +399,7 @@ To prevent a package from being uploaded to PyPI, use the special ``Private ::
 Do Not Upload`` classifier. PyPI will always reject packages with classifiers
 beginning with ``Private ::``.
 
+.. _writing-pyproject-toml-urls:
 
 ``urls``
 --------
@@ -406,6 +407,13 @@ beginning with ``Private ::``.
 A list of URLs associated with your project, displayed on the left
 sidebar of your PyPI project page.
 
+.. note::
+
+    See :ref:`well-known-labels` for a listing
+    of labels that PyPI and other packaging tools are specifically aware of,
+    and `PyPI's project metadata docs `_
+    for PyPI-specific URL processing.
+
 .. code-block:: toml
 
    [project.urls]
@@ -415,12 +423,10 @@ sidebar of your PyPI project page.
    Issues = "https://github.com/me/spam/issues"
    Changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
 
-Note that if the key contains spaces, it needs to be quoted, e.g.,
+Note that if the label contains spaces, it needs to be quoted, e.g.,
 ``Website = "https://example.com"`` but
 ``"Official Website" = "https://example.com"``.
 
-
-
 Advanced plugins
 ================
 
diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 97686c543..c1ce528e7 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -341,32 +341,6 @@ Example::
    These tools have been very widely used for many years, so it was
    easier to update the specification to match the de facto standard.
 
-.. _home-page-optional:
-.. _core-metadata-home-page:
-
-Home-page
-=========
-
-.. versionadded:: 1.0
-
-A string containing the URL for the distribution's home page.
-
-Example::
-
-    Home-page: http://www.example.com/~cschultz/bvote/
-
-.. _core-metadata-download-url:
-
-Download-URL
-============
-
-.. versionadded:: 1.1
-
-A string containing the URL from which this version of the distribution
-can be downloaded.  (This means that the URL can't be something like
-".../BeagleVote-latest.tgz", but instead must be ".../BeagleVote-0.45.tgz".)
-
-
 .. _author-optional:
 .. _core-metadata-author:
 
@@ -669,6 +643,10 @@ Example::
 
 The label is free text limited to 32 characters.
 
+Starting with :pep:`753`, project metadata consumers (such as the Python
+Package Index) can use a standard normalization process to discover "well-known"
+labels, which can then be given special presentations when being rendered
+for human consumption. See :ref:`well-known-project-urls`.
 
 .. _metadata_provides_extra:
 .. _core-metadata-provides-extra:
@@ -819,6 +797,40 @@ Examples::
 Deprecated Fields
 =================
 
+.. _home-page-optional:
+.. _core-metadata-home-page:
+
+Home-page
+---------
+
+.. versionadded:: 1.0
+
+.. deprecated:: 1.2
+
+    Per :pep:`753`, use :ref:`core-metadata-project-url` instead.
+
+A string containing the URL for the distribution's home page.
+
+Example::
+
+    Home-page: http://www.example.com/~cschultz/bvote/
+
+.. _core-metadata-download-url:
+
+Download-URL
+------------
+
+.. versionadded:: 1.1
+
+.. deprecated:: 1.2
+
+    Per :pep:`753`, use :ref:`core-metadata-project-url` instead.
+
+A string containing the URL from which this version of the distribution
+can be downloaded.  (This means that the URL can't be something like
+"``.../BeagleVote-latest.tgz``", but instead must be
+"``.../BeagleVote-0.45.tgz``".)
+
 Requires
 --------
 
diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index efa562a73..400e43105 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -318,7 +318,8 @@ Trove classifiers which apply to the project.
   :ref:`Project-URL `
 
 A table of URLs where the key is the URL label and the value is the
-URL itself.
+URL itself. See :ref:`well-known-project-urls` for normalization rules
+and well-known rules when processing metadata for presentation.
 
 
 Entry points
diff --git a/source/specifications/section-distribution-metadata.rst b/source/specifications/section-distribution-metadata.rst
index 7fd3361a0..0c0a8aaba 100644
--- a/source/specifications/section-distribution-metadata.rst
+++ b/source/specifications/section-distribution-metadata.rst
@@ -12,3 +12,4 @@ Package Distribution Metadata
    pyproject-toml
    inline-script-metadata
    platform-compatibility-tags
+   well-known-project-urls
diff --git a/source/specifications/well-known-project-urls.rst b/source/specifications/well-known-project-urls.rst
new file mode 100644
index 000000000..9ce2d8ba2
--- /dev/null
+++ b/source/specifications/well-known-project-urls.rst
@@ -0,0 +1,176 @@
+.. _`well-known-project-urls`:
+
+===================================
+Well-known Project URLs in Metadata
+===================================
+
+.. important::
+
+    This document is primarily of interest to metadata *consumers*,
+    who should use the normalization rules and well-known list below
+    to make their presentation of project URLs consistent across the
+    Python ecosystem.
+
+    Metadata *producers* (such as build tools and individual package
+    maintainers) may continue to use any labels they please, within the
+    overall ``Project-URL`` length restrictions. However, users are
+    *encouraged* to pick meaningful labels that normalize to well-known
+    labels.
+
+.. note::
+
+    See :ref:`Writing your pyproject.toml - urls `
+    for user-oriented guidance on choosing project URL labels in your package's
+    metadata.
+
+.. note:: This specification was originally defined in :pep:`753`.
+
+:pep:`753` deprecates the :ref:`core-metadata-home-page` and
+:ref:`core-metadata-download-url` metadata fields in favor of
+:ref:`core-metadata-project-url`, and defines a normalization and
+lookup procedure for determining whether a ``Project-URL`` is
+"well-known," i.e. has the semantics assigned to ``Home-page``,
+``Download-URL``, or other common project URLs.
+
+This allows indices (such as the Python Package Index) and other downstream
+metadata consumers to specialize their presentations of project URLs in a
+consistent manner.
+
+.. _project-url-label-normalization:
+
+Label normalization
+===================
+
+.. note::
+
+    Label normalization is performed by metadata *consumers*, not metadata
+    producers.
+
+To determine whether a ``Project-URL`` label is "well-known," metadata
+consumers should first normalize the label before comparing it to the
+:ref:`list of well-known labels `.
+
+The normalization procedure for ``Project-URL`` labels is defined
+by the following Python function:
+
+.. code-block:: python
+
+    import string
+
+    def normalize_label(label: str) -> str:
+        chars_to_remove = string.punctuation + string.whitespace
+        removal_map = str.maketrans("", "", chars_to_remove)
+        return label.translate(removal_map).lower()
+
+In plain language: a label is *normalized* by deleting all ASCII punctuation
+and whitespace, and then converting the result to lowercase.
+
+The following table shows examples of labels before (raw) and after
+normalization:
+
+.. list-table::
+    :header-rows: 1
+
+    * - Raw
+      - Normalized
+    * - ``Homepage``
+      - ``homepage``
+    * - ``Home-page``
+      - ``homepage``
+    * - ``Home page``
+      - ``homepage``
+    * - ``Change_Log``
+      - ``changelog``
+    * - ``What's New?``
+      - ``whatsnew``
+    * - ``github``
+      - ``github``
+
+.. _well-known-labels:
+
+Well-known labels
+=================
+
+.. note::
+
+    The list of well-known labels is a living standard, maintained as part of
+    this document.
+
+The following table lists labels that are well-known for the purpose of
+specializing the presentation of ``Project-URL`` metadata:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Label (Human-readable equivalent)
+     - Description
+     - Aliases
+   * - ``homepage`` (Homepage)
+     - The project's home page
+     - *(none)*
+   * - ``source`` (Source Code)
+     - The project's hosted source code or repository
+     - ``repository``, ``sourcecode``, ``github``
+   * - ``download`` (Download)
+     - A download URL for the current distribution, equivalent to ``Download-URL``
+     - *(none)*
+   * - ``changelog`` (Changelog)
+     - The project's comprehensive changelog
+     - ``changes``, ``whatsnew``, ``history``
+   * - ``releasenotes`` (Release Notes)
+     - The project's curated release notes
+     - *(none)*
+   * - ``documentation`` (Documentation)
+     - The project's online documentation
+     - ``docs``
+   * - ``issues`` (Issue Tracker)
+     - The project's bug tracker
+     - ``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``
+   * - ``funding`` (Funding)
+     - Funding Information
+     - ``sponsor``, ``donate``, ``donation``
+
+Package metadata consumers may choose to render aliased labels the same as
+their "parent" well known label, or further specialize them.
+
+Example behavior
+================
+
+The following shows the flow of project URL metadata from
+``pyproject.toml`` to core metadata to a potential index presentation:
+
+.. code-block:: toml
+    :caption: Example project URLs in standard configuration
+
+    [project.urls]
+    "Home Page" = "https://example.com"
+    DOCUMENTATION = "https://readthedocs.org"
+    Repository = "https://upstream.example.com/me/spam.git"
+    GitHub = "https://github.com/example/spam"
+
+.. code-block:: email
+    :caption: Core metadata representation
+
+    Project-URL: Home page, https://example.com
+    Project-URL: DOCUMENTATION, https://readthedocs.org
+    Project-URL: Repository, https://upstream.example.com/me/spam.git
+    Project-URL: GitHub, https://github.com/example/spam
+
+.. code-block:: text
+    :caption: Potential rendering
+
+    Homepage: https://example.com
+    Documentation: https://readthedocs.org
+    Source Code: https://upstream.example.com/me/spam.git
+    Source Code (GitHub): https://github.com/example/spam
+
+Observe that the core metadata appears in the form provided by the user
+(since metadata *producers* do not perform normalization), but the
+metadata *consumer* correctly normalizes and identifies appropriate
+human-readable equivalents based on the normalized form:
+
+* ``Home page`` becomes ``homepage``, which is rendered as ``Homepage``
+* ``DOCUMENTATION`` becomes ``documentation``, which is rendered as ``Documentation``
+* ``Repository`` becomes ``repository``, which is rendered as ``Source Code``
+* ``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)``
+  (as a specialization of ``Source Code``)

From daa5daf39c08518963ae8e314027b4f82d39eef4 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Fri, 11 Oct 2024 15:03:57 +0100
Subject: [PATCH 456/733] Update well-known-project-urls.rst

Co-authored-by: Paul Moore 
---
 source/specifications/well-known-project-urls.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/well-known-project-urls.rst b/source/specifications/well-known-project-urls.rst
index 9ce2d8ba2..efaeb35c2 100644
--- a/source/specifications/well-known-project-urls.rst
+++ b/source/specifications/well-known-project-urls.rst
@@ -166,7 +166,7 @@ The following shows the flow of project URL metadata from
 
 Observe that the core metadata appears in the form provided by the user
 (since metadata *producers* do not perform normalization), but the
-metadata *consumer* correctly normalizes and identifies appropriate
+metadata *consumer* normalizes and identifies appropriate
 human-readable equivalents based on the normalized form:
 
 * ``Home page`` becomes ``homepage``, which is rendered as ``Homepage``

From 5a6c37d56c032a0bdbc96d0c62883594edf7bbc4 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Fri, 11 Oct 2024 15:08:56 +0100
Subject: [PATCH 457/733] don't say guidance

Signed-off-by: William Woodruff 
---
 source/specifications/well-known-project-urls.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/specifications/well-known-project-urls.rst b/source/specifications/well-known-project-urls.rst
index efaeb35c2..c2df976b5 100644
--- a/source/specifications/well-known-project-urls.rst
+++ b/source/specifications/well-known-project-urls.rst
@@ -20,8 +20,8 @@ Well-known Project URLs in Metadata
 .. note::
 
     See :ref:`Writing your pyproject.toml - urls `
-    for user-oriented guidance on choosing project URL labels in your package's
-    metadata.
+    for user-oriented documentation on setting project URL labels in your
+    package's metadata.
 
 .. note:: This specification was originally defined in :pep:`753`.
 

From 032153630e04fde4749af3e9b25b61b50d57bbb6 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Fri, 11 Oct 2024 16:52:45 +0100
Subject: [PATCH 458/733] Revert "don't say guidance"

This reverts commit 5a6c37d56c032a0bdbc96d0c62883594edf7bbc4.
---
 source/specifications/well-known-project-urls.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/specifications/well-known-project-urls.rst b/source/specifications/well-known-project-urls.rst
index c2df976b5..efaeb35c2 100644
--- a/source/specifications/well-known-project-urls.rst
+++ b/source/specifications/well-known-project-urls.rst
@@ -20,8 +20,8 @@ Well-known Project URLs in Metadata
 .. note::
 
     See :ref:`Writing your pyproject.toml - urls `
-    for user-oriented documentation on setting project URL labels in your
-    package's metadata.
+    for user-oriented guidance on choosing project URL labels in your package's
+    metadata.
 
 .. note:: This specification was originally defined in :pep:`753`.
 

From b24d423c743e5a4398f03b74935bc94d80a60ad5 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Fri, 11 Oct 2024 17:15:08 +0100
Subject: [PATCH 459/733] guide: make URL guidance more guide-y

Signed-off-by: William Woodruff 
---
 source/guides/writing-pyproject-toml.rst | 25 ++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index cb1639f50..833bac23a 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -427,6 +427,31 @@ Note that if the label contains spaces, it needs to be quoted, e.g.,
 ``Website = "https://example.com"`` but
 ``"Official Website" = "https://example.com"``.
 
+Users are advised to use :ref:`well-known-labels` for their project URLs
+where appropriate, since consumers of metadata (like package indices) can
+specialize their presentation.
+
+For example in the following metadata, neither ``MyHomepage`` nor
+``"Download Link"`` is a well-known label, so they will be rendered verbatim:
+
+.. code-block:: toml
+
+   [project.urls]
+   MyHomepage = "https://example.com"
+   "Download Link" = "https://example.com/abc.tar.gz"
+
+
+Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have
+well-known equivalents (``homepage`` and ``download``), and can be presented
+with those semantics in mind (the project's home page and its external
+download location, respectively).
+
+.. code-block:: toml
+
+   [project.urls]
+   HomePage = "https://example.com"
+   DOWNLOAD = "https://example.com/abc.tar.gz"
+
 Advanced plugins
 ================
 

From e0699855a36e3cd0521f43f1fe4f901021cf99eb Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan 
Date: Sun, 6 Oct 2024 17:38:18 +1000
Subject: [PATCH 460/733] Add notes on runtime version access
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Also redirects the obsolete single-source version guide to the
updated single-source version discussion.

Co-authored-by: Éric 
Co-authored-by: wim glenn 
---
 source/discussions/single-source-version.rst  |  41 ++--
 source/discussions/versioning.rst             |  59 +++++-
 source/guides/section-build-and-publish.rst   |   1 -
 .../single-sourcing-package-version.rst       | 175 +-----------------
 source/guides/writing-pyproject-toml.rst      |   4 +-
 5 files changed, 93 insertions(+), 187 deletions(-)

diff --git a/source/discussions/single-source-version.rst b/source/discussions/single-source-version.rst
index 9bcab6291..c7dc8d1e1 100644
--- a/source/discussions/single-source-version.rst
+++ b/source/discussions/single-source-version.rst
@@ -1,34 +1,49 @@
-.. _`Single sourcing the version discussion`:
+.. _single-source-version:
 
 ===================================
 Single-sourcing the Project Version
 ===================================
 
 :Page Status: Complete
-:Last Reviewed: 2024-08-24
+:Last Reviewed: 2024-10-07
 
-One of the challenges in building packages is that the version string can be required in multiple places.
+Many Python :term:`distribution packages ` publish a single
+Python :term:`import package ` where it is desired that the runtime
+``__version__`` attribute on the import package report the same version specifier
+as :func:`importlib.metadata.version` reports for the distribution package
+(as described in :ref:`runtime-version-access`).
 
-* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`)
-   This will make it available in the installed package’s metadata, from where it will be accessible at runtime using ``importlib.metadata.version("distribution_name")``.
+It is also frequently desired that this version information be derived from a version
+control system *tag* (such as ``v1.2.3``) rather than being manually updated in the
+source code.
 
-* A package may set a module attribute (e.g., ``__version__``) to provide an alternative means of runtime access to the version of the imported package. If this is done, the value of the attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `.
+Some projects may choose to simply live with the data entry duplication, and rely
+on automated testing to ensure the different values do not diverge.
 
-* If the code is in in a version control system (VCS), e.g. Git, the version may appear in a *tag* such as ``v1.2.3``.
-
-To ensure that version numbers do not get out of sync, it is recommended that there is a single source of truth for the version number.
+Alternatively, a project's chosen build system may offer a way to define a single
+source of truth for the version number.
 
 In general, the options are:
 
-1) If the code is in a version control system (VCS), e.g. Git, then the version can be extracted from the VCS.
-
-2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required.
+1) If the code is in a version control system (VCS), such as Git, then the version can be extracted from the VCS.
 
-3) The version string can be hard-coded into the source code -- either in a special purpose file, such as :file:`_version.txt`, or as a attribute in a module, such as :file:`__init__.py`, and the build system can extract it at build time.
+2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it
+   into other locations it may be required.
 
+3) The version string can be hard-coded into the source code -- either in a special purpose file,
+   such as :file:`_version.txt` (which must then be shipped as part of the project's source distribution
+   package), or as an attribute in a particular module, such as :file:`__init__.py`. The build
+   system can then extract it from the runtime location at build time.
 
 Consult your build system's documentation for their recommended method.
 
+When the intention is that a distribution package and its associated import package
+share the same version, it is recommended that the project include an automated test
+case that ensures ``import_name.__version__`` and ``importlib.metadata.version("dist-name")``
+report the same value (note: for many projects, ``import_name`` and ``dist-name`` will
+be the same name).
+
+
 .. _Build system version handling:
 
 Build System Version Handling
diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst
index 49fbbf0de..8f318bae9 100644
--- a/source/discussions/versioning.rst
+++ b/source/discussions/versioning.rst
@@ -153,7 +153,6 @@ numbering scheme that readily conveys the approximate age of a release, but
 doesn't otherwise commit to a particular release cadence within the year.
 
 
-
 Local version identifiers
 =========================
 
@@ -172,6 +171,55 @@ since the latest release, setuptools-scm generates a version like
 "0.5.dev1+gd00980f", or if the repository has untracked changes, like
 "0.5.dev1+gd00980f.d20231217".
 
+.. _runtime-version-access:
+
+Accessing version information at runtime
+========================================
+
+Version information for all :term:`distribution packages `
+that are locally available in the current environment can be obtained at runtime
+using the standard library's :func:`importlib.metadata.version` function::
+
+   >>> importlib.metadata.version("cryptography")
+   '41.0.7'
+
+Many projects also choose to version their top level
+:term:`import packages ` by providing a package level
+``__version__`` attribute::
+
+   >>> import cryptography
+   >>> cryptography.__version__
+   '41.0.7'
+
+This technique can be particularly valuable for CLI applications which want
+to ensure that version query invocations (such as ``pip -V``) run as quickly
+as possible.
+
+Package publishers wishing to ensure their reported distribution package and
+import package versions are consistent with each other can review the
+:ref:`single-source-version` discussion for potential approaches to doing so.
+
+As import packages and modules are not *required* to publish runtime
+version information in this way (see the rejected proposal in
+:pep:`PEP 396 <396>`), the ``__version__`` attribute should either only be
+queried with interfaces that are known to provide it (such as a project
+querying its own version or the version of one of its direct dependencies),
+or else the querying code should be designed to handle the case where the
+attribute is missing [#fallback-to-dist-version]_.
+
+Some projects may need to publish version information for external APIs
+that don't meet the requirements for Python distribution package
+:ref:`version specifiers `. Such projects should
+define their own project-specific ways of obtaining the relevant information
+at runtime. For example, the standard library's :mod:`ssl` module offers
+multiple ways to access the underlying OpenSSL library version::
+
+   >>> ssl.OPENSSL_VERSION
+   'OpenSSL 3.2.2 4 Jun 2024'
+   >>> ssl.OPENSSL_VERSION_INFO
+   (3, 2, 0, 2, 0)
+   >>> hex(ssl.OPENSSL_VERSION_NUMBER)
+   '0x30200020'
 
 --------------------------------------------------------------------------------
 
@@ -184,6 +232,15 @@ since the latest release, setuptools-scm generates a version like
    Brett Cannon `_. For a humoristic take, read about
    ZeroVer_.
 
+.. [#fallback-to-dist-version] A full list mapping the top level names available
+   for import to the distribution packages that provide those import packages and
+   modules may be obtained through the standard library's
+   :func:`importlib.metadata.packages_distributions` function. This means that
+   even code that is attempting to infer a version to report for all importable
+   top-level names has a means to fall back to reporting the distribution
+   version information if no ``__version__`` attribute is defined. Only standard
+   library modules, and modules added via means other than Python package
+   installation would fail to have version information reported in that case.
 
 
 .. _zerover: https://0ver.org
diff --git a/source/guides/section-build-and-publish.rst b/source/guides/section-build-and-publish.rst
index 8e0c9ab3b..eb10c389f 100644
--- a/source/guides/section-build-and-publish.rst
+++ b/source/guides/section-build-and-publish.rst
@@ -7,7 +7,6 @@ Building and Publishing
 
    writing-pyproject-toml
    distributing-packages-using-setuptools
-   single-sourcing-package-version
    dropping-older-python-versions
    packaging-binary-extensions
    packaging-namespace-packages
diff --git a/source/guides/single-sourcing-package-version.rst b/source/guides/single-sourcing-package-version.rst
index 5c8af21e0..7ed3d87da 100644
--- a/source/guides/single-sourcing-package-version.rst
+++ b/source/guides/single-sourcing-package-version.rst
@@ -1,173 +1,8 @@
-.. _`Single sourcing the version`:
+:orphan:
 
-===================================
-Single-sourcing the package version
-===================================
+.. meta::
+   :http-equiv=refresh: 0; url=../../discussions/single-source-version/
 
-.. todo:: Update this page for build backends other than setuptools.
+Redirecting stale single-source package version link...
 
-There are many techniques to maintain a single source of truth for the version
-number of your project:
-
-#.  Read the file in :file:`setup.py` and get the version. Example (from `pip setup.py
-    `_)::
-
-        import codecs
-        import os.path
-
-        def read(rel_path):
-            here = os.path.abspath(os.path.dirname(__file__))
-            with codecs.open(os.path.join(here, rel_path), 'r') as fp:
-                return fp.read()
-
-        def get_version(rel_path):
-            for line in read(rel_path).splitlines():
-                if line.startswith('__version__'):
-                    delim = '"' if '"' in line else "'"
-                    return line.split(delim)[1]
-            else:
-                raise RuntimeError("Unable to find version string.")
-
-        setup(
-           ...
-           version=get_version("package/__init__.py")
-           ...
-        )
-
-    .. note::
-
-       As of the release of setuptools 46.4.0, one can accomplish the same
-       thing by instead placing the following in the project's
-       :file:`setup.cfg` file (replacing "package" with the import name of the
-       package):
-
-       .. code-block:: ini
-
-           [metadata]
-           version = attr: package.__version__
-
-       As of the release of setuptools 61.0.0, one can specify the
-       version dynamically in the project's :file:`pyproject.toml` file.
-
-       .. code-block:: toml
-
-            [project]
-            name = "package"
-            dynamic = ["version"]
-
-            [tool.setuptools.dynamic]
-            version = {attr = "package.__version__"}
-
-       Please be aware that declarative config indicators, including the
-       ``attr:`` directive, are not supported in parameters to
-       :file:`setup.py`.
-
-#.  Use an external build tool that either manages updating both locations, or
-    offers an API that both locations can use.
-
-    Few tools you could use, in no particular order, and not necessarily complete:
-    `bump2version `_,
-    `changes `_,
-    `commitizen `_,
-    `zest.releaser `_.
-
-
-#.  Set the value to a ``__version__`` global variable in a dedicated module in
-    your project (e.g. :file:`version.py`), then have :file:`setup.py` read and
-    ``exec`` the value into a variable.
-
-    ::
-
-        version = {}
-        with open("...sample/version.py") as fp:
-            exec(fp.read(), version)
-        # later on we use: version['__version__']
-
-    Example using this technique: `warehouse `_.
-
-#.  Place the value in a simple ``VERSION`` text file and have both
-    :file:`setup.py` and the project code read it.
-
-    ::
-
-        with open(os.path.join(mypackage_root_dir, 'VERSION')) as version_file:
-            version = version_file.read().strip()
-
-    An advantage with this technique is that it's not specific to Python.  Any
-    tool can read the version.
-
-    .. warning::
-
-        With this approach you must make sure that the ``VERSION`` file is included in
-        all your source and binary distributions (e.g. add ``include VERSION`` to your
-        :file:`MANIFEST.in`).
-
-#.  Set the value in :file:`setup.py`, and have the project code use the
-    ``importlib.metadata`` API to fetch the value at runtime.
-    (``importlib.metadata`` was introduced in Python 3.8 and is available to
-    older versions as the ``importlib-metadata`` project.)  An installed
-    project's version can be fetched with the API as follows::
-
-        import sys
-
-        if sys.version_info >= (3, 8):
-            from importlib import metadata
-        else:
-            import importlib_metadata as metadata
-
-        assert metadata.version('pip') == '1.2.0'
-
-    Be aware that the ``importlib.metadata`` API only knows about what's in the
-    installation metadata, which is not necessarily the code that's currently
-    imported.
-
-    If a project uses this method to fetch its version at runtime, then its
-    ``install_requires`` value needs to be edited to install
-    ``importlib-metadata`` on pre-3.8 versions of Python like so::
-
-        setup(
-            ...
-            install_requires=[
-                ...
-                'importlib-metadata >= 1.0 ; python_version < "3.8"',
-                ...
-            ],
-            ...
-        )
-
-    An older (and less efficient) alternative to ``importlib.metadata`` is the
-    ``pkg_resources`` API provided by ``setuptools``::
-
-        import pkg_resources
-        assert pkg_resources.get_distribution('pip').version == '1.2.0'
-
-    If a project uses ``pkg_resources`` to fetch its own version at runtime,
-    then ``setuptools`` must be added to the project's ``install_requires``
-    list.
-
-    Example using this technique: `setuptools `_.
-
-
-#.  Set the value to ``__version__`` in ``sample/__init__.py`` and import
-    ``sample`` in :file:`setup.py`.
-
-    ::
-
-        import sample
-        setup(
-            ...
-            version=sample.__version__
-            ...
-        )
-
-    .. warning::
-
-        Although this technique is common, beware that it will fail if
-        ``sample/__init__.py`` imports packages from ``install_requires``
-        dependencies, which will very likely not be installed yet when
-        :file:`setup.py` is run.
-
-
-#.  Keep the version number in the tags of a version control system (Git, Mercurial, etc)
-    instead of in the code, and automatically extract it from there using
-    `setuptools_scm `_.
+If the page doesn't automatically refresh, see :ref:`single-source-version`.
diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index d11b8a87c..144cc3525 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -163,8 +163,8 @@ This field is required, although it is often marked as dynamic using
    dynamic = ["version"]
 
 This allows use cases such as filling the version from a ``__version__``
-attribute or a Git tag. Consult :ref:`Single sourcing the version` for more
-details.
+attribute or a Git tag. Consult the :ref:`single-source-version`
+discussion for more details.
 
 
 Dependencies and requirements

From 0c94fea4f5b4e95f3fcfc6ef26ff0bc8f4f7d9f7 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Sat, 12 Oct 2024 21:00:41 +0100
Subject: [PATCH 461/733] Apply suggestions from code review

Co-authored-by: Carol Willing 
---
 source/specifications/well-known-project-urls.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/specifications/well-known-project-urls.rst b/source/specifications/well-known-project-urls.rst
index efaeb35c2..30fefd12b 100644
--- a/source/specifications/well-known-project-urls.rst
+++ b/source/specifications/well-known-project-urls.rst
@@ -13,7 +13,7 @@ Well-known Project URLs in Metadata
 
     Metadata *producers* (such as build tools and individual package
     maintainers) may continue to use any labels they please, within the
-    overall ``Project-URL`` length restrictions. However, users are
+    overall ``Project-URL`` length restrictions. However, when possible, users are
     *encouraged* to pick meaningful labels that normalize to well-known
     labels.
 
@@ -33,7 +33,7 @@ lookup procedure for determining whether a ``Project-URL`` is
 ``Download-URL``, or other common project URLs.
 
 This allows indices (such as the Python Package Index) and other downstream
-metadata consumers to specialize their presentations of project URLs in a
+metadata consumers to present project URLs in a
 consistent manner.
 
 .. _project-url-label-normalization:
@@ -47,7 +47,7 @@ Label normalization
     producers.
 
 To determine whether a ``Project-URL`` label is "well-known," metadata
-consumers should first normalize the label before comparing it to the
+consumers should normalize the label before comparing it to the
 :ref:`list of well-known labels `.
 
 The normalization procedure for ``Project-URL`` labels is defined

From 7e848422448d19489cb113dfb5d956d6d46616fa Mon Sep 17 00:00:00 2001
From: shenxianpeng 
Date: Sun, 13 Oct 2024 13:25:57 +0000
Subject: [PATCH 462/733] fix: upgrade gh-action-sigstore-python to v3.0.0

---
 .../guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
index 3c0192b53..152597d49 100644
--- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
+++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
@@ -68,7 +68,7 @@ jobs:
         name: python-package-distributions
         path: dist/
     - name: Sign the dists with Sigstore
-      uses: sigstore/gh-action-sigstore-python@v2.1.1
+      uses: sigstore/gh-action-sigstore-python@v3.0.0
       with:
         inputs: >-
           ./dist/*.tar.gz

From f80aff3c5990b7c0bccca5c6c079f47236d6ebb8 Mon Sep 17 00:00:00 2001
From: csteiner <47841949+clintonsteiner@users.noreply.github.com>
Date: Thu, 17 Oct 2024 18:16:13 -0500
Subject: [PATCH 463/733] Update contribute.rst reference to out of date django
 documentation version

Point at dev dependency, which should always stay up to date
---
 source/contribute.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/contribute.rst b/source/contribute.rst
index a246751e4..95d127837 100644
--- a/source/contribute.rst
+++ b/source/contribute.rst
@@ -45,7 +45,7 @@ Tutorials are focused on teaching the reader new concepts by accomplishing a
 goal. They are opinionated step-by-step guides. They do not include extraneous
 warnings or information. `example tutorial-style document`_.
 
-.. _example tutorial-style document: https://docs.djangoproject.com/en/1.11/intro/
+.. _example tutorial-style document: https://docs.djangoproject.com/en/dev/intro/
 
 Guides
 ------

From 27b919dd934338a1fa95141f8860610eb00457d4 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 21 Oct 2024 20:18:24 +0000
Subject: [PATCH 464/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/pre-commit/pre-commit-hooks: v4.6.0 → v5.0.0](https://github.com/pre-commit/pre-commit-hooks/compare/v4.6.0...v5.0.0)
- [github.com/astral-sh/ruff-pre-commit: v0.4.10 → v0.7.0](https://github.com/astral-sh/ruff-pre-commit/compare/v0.4.10...v0.7.0)
---
 .pre-commit-config.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c6372ec30..d8ac1c6eb 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.6.0
+  rev: v5.0.0
   hooks:
   - id: check-added-large-files
   - id: check-case-conflict
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.4.10
+  rev: v0.7.0
   hooks:
     - id: ruff
     - id: ruff-format

From ff4f1f16fb065672eee8b67e8b261746bd93061e Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan 
Date: Thu, 24 Oct 2024 01:01:17 +1000
Subject: [PATCH 465/733] PEP 396 was reclassifed as Withdrawn

---
 source/discussions/versioning.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst
index 8f318bae9..6d9ef5af7 100644
--- a/source/discussions/versioning.rst
+++ b/source/discussions/versioning.rst
@@ -200,7 +200,7 @@ import package versions are consistent with each other can review the
 :ref:`single-source-version` discussion for potential approaches to doing so.
 
 As import packages and modules are not *required* to publish runtime
-version information in this way (see the rejected proposal in
+version information in this way (see the withdrawn proposal in
 :pep:`PEP 396 <396>`), the ``__version__`` attribute should either only be
 queried with interfaces that are known to provide it (such as a project
 querying its own version or the version of one of its direct dependencies),

From 7d2a208782613f4b27e4b9ceffe2c1fe35221b04 Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan 
Date: Thu, 24 Oct 2024 01:04:16 +1000
Subject: [PATCH 466/733] Fix another bit of wording that irked me

---
 source/discussions/versioning.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst
index 6d9ef5af7..a7fb51f8b 100644
--- a/source/discussions/versioning.rst
+++ b/source/discussions/versioning.rst
@@ -208,8 +208,7 @@ or else the querying code should be designed to handle the case where the
 attribute is missing [#fallback-to-dist-version]_.
 
 Some projects may need to publish version information for external APIs
-that don't meet the requirements for Python distribution package
-:ref:`version specifiers `. Such projects should
+that aren't the version of the module itself. Such projects should
 define their own project-specific ways of obtaining the relevant information
 at runtime. For example, the standard library's :mod:`ssl` module offers
 multiple ways to access the underlying OpenSSL library version::

From d4ea4c1f5278c0fdb0803f8f174af9de6d65c9dc Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 28 Oct 2024 20:29:58 +0000
Subject: [PATCH 467/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.7.0 → v0.7.1](https://github.com/astral-sh/ruff-pre-commit/compare/v0.7.0...v0.7.1)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index d8ac1c6eb..785b392ab 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.7.0
+  rev: v0.7.1
   hooks:
     - id: ruff
     - id: ruff-format

From a9110fdce5c76bcc45b8491c223ae32c9b66ac29 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Mon, 28 Oct 2024 18:15:44 -0400
Subject: [PATCH 468/733] version-specifiers: add a custom anchor for
 `Pre-releases` section

Signed-off-by: William Woodruff 
---
 source/specifications/version-specifiers.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index a5ba36498..d18596ee0 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -237,6 +237,8 @@ release scheme using the year and month of the release::
     ...
 
 
+.. _pre-release-versions:
+
 Pre-releases
 ------------
 

From 6c7c95a4090c9699af6287f9f892c3f2167bbdb9 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Wed, 31 Jul 2024 17:40:25 -0700
Subject: [PATCH 469/733] updated notes on conda.

---
 source/key_projects.rst | 40 ++++++++++++++++++++++------------------
 1 file changed, 22 insertions(+), 18 deletions(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 531c28066..6c8e5d16a 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -404,26 +404,30 @@ conda
 
 :doc:`Docs `
 
-conda is the package management tool for `Anaconda
-`__ Python installations.
-Anaconda Python is a distribution from `Anaconda, Inc
-`__ specifically aimed at the scientific
-community, and in particular on Windows where the installation of binary
-extensions is often difficult.
+Conda is a package, dependency, and environment management system for any language — Python, R,
+Ruby, C/C++, Fortran, and more. It is written in Python and
+widely used in the Python scientific computing community, due to its support for non-Python
+compiled libraries and extensions. It is used as the basis of the `Anaconda
+`__ Python distribution from `Anaconda, Inc.specifically
+aimed at the scientific community, community, but can also be used on its own, or with the
+:doc:`miniconda `, `miniforge `_ or
+`pixi `_ systems. It is available for Windows, Mac and Linux systems.
 
 Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, but provides
-many of their combined features in terms of package management, virtual environment
-management and deployment of binary extensions.
-
-Conda does not install packages from PyPI and can install only from
-the official Anaconda repositories, or anaconda.org (a place for
-user-contributed *conda* packages), or a local (e.g. intranet) package
-server.  However, note that :ref:`pip` can be installed into, and work
-side-by-side with conda for managing :term:`distributions
-` from PyPI. Also, `conda skeleton
-`__
-is a tool to make Python packages installable by conda by first
-fetching them from PyPI and modifying their metadata.
+many of their combined features, such as package management, virtual environment
+management and deployment of binary extensions and other binary code.
+
+Conda does not install packages from PyPI -- it can only manage packages built specifically
+for conda, which can be made available on a "conda channel", such as those hosted on
+`anaconda.org `__ or a local (e.g. intranet) package server.
+In addition to the "default" channels managed by `Anaconda, Inc. `__, there are a wide variety of packages from the community supported
+`conda-forge project `__
+
+Note that :ref:`pip` can be installed into, and work side-by-side with conda
+for managing :term:`distributions ` from PyPI. It is also possible
+to build conda packages from Python source packages using tools such as
+`conda skeleton
+`__: a tool to automatically make conda packages from Python packages available on PyPI.
 
 .. _devpi:
 

From 7763ab9db0afa386cf992eb55e5054c7b5d0eda7 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Wed, 31 Jul 2024 17:53:50 -0700
Subject: [PATCH 470/733] added updated conda info to the scientific packages
 page.

---
 source/guides/installing-scientific-packages.rst | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst
index 5677d382a..654db3d62 100644
--- a/source/guides/installing-scientific-packages.rst
+++ b/source/guides/installing-scientific-packages.rst
@@ -134,5 +134,10 @@ native virtual environments. Conda makes environments first-class citizens,
 making it easy to create independent environments even for C libraries. It is
 written in Python, but is Python-agnostic. Conda manages Python itself as a
 package, so that :command:`conda update python` is possible, in contrast to
-pip, which only manages Python packages. Conda is available in Anaconda and
-Miniconda (an easy-to-install download with just Python and conda).
+pip, which only manages Python packages.
+
+The conda package manager is available in `Anaconda `_, `miniconda `_, `miniforge `_, and `pixi `_.
+
+Conda packages are available on multiple channels on Anaconda.org, including the
+default channel supported by Anaconda, Inc, and the community supported conda-forge
+channel, which provides a wide variety of pre-built packages.

From 43d4f09f319c43163f7f13aba9c41cbe4874acf1 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 19 Aug 2024 17:06:58 -0400
Subject: [PATCH 471/733] Update source/key_projects.rst

Co-authored-by: Alyssa Coghlan 
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 6c8e5d16a..7af8996a2 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -408,7 +408,7 @@ Conda is a package, dependency, and environment management system for any langua
 Ruby, C/C++, Fortran, and more. It is written in Python and
 widely used in the Python scientific computing community, due to its support for non-Python
 compiled libraries and extensions. It is used as the basis of the `Anaconda
-`__ Python distribution from `Anaconda, Inc.specifically
+`__ Python distribution from Anaconda, Inc. It waas originally
 aimed at the scientific community, community, but can also be used on its own, or with the
 :doc:`miniconda `, `miniforge `_ or
 `pixi `_ systems. It is available for Windows, Mac and Linux systems.

From b605abf5e715c4d1ad43a2c78ff2abe722c26afa Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 19 Aug 2024 17:07:45 -0400
Subject: [PATCH 472/733] Update source/key_projects.rst

Co-authored-by: Alyssa Coghlan 
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 7af8996a2..67bac3a54 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -409,7 +409,7 @@ Ruby, C/C++, Fortran, and more. It is written in Python and
 widely used in the Python scientific computing community, due to its support for non-Python
 compiled libraries and extensions. It is used as the basis of the `Anaconda
 `__ Python distribution from Anaconda, Inc. It waas originally
-aimed at the scientific community, community, but can also be used on its own, or with the
+aimed at the scientific community, but can also be used on its own, or with the
 :doc:`miniconda `, `miniforge `_ or
 `pixi `_ systems. It is available for Windows, Mac and Linux systems.
 

From fee8b5a054487347bdade0ffbfc26deeb355fe64 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 19 Aug 2024 17:08:09 -0400
Subject: [PATCH 473/733] Update source/key_projects.rst

Co-authored-by: Alyssa Coghlan 
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 67bac3a54..d8312e327 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -419,7 +419,7 @@ management and deployment of binary extensions and other binary code.
 
 Conda does not install packages from PyPI -- it can only manage packages built specifically
 for conda, which can be made available on a "conda channel", such as those hosted on
-`anaconda.org `__ or a local (e.g. intranet) package server.
+`anaconda.org `__, or a local (e.g. intranet) package server.
 In addition to the "default" channels managed by `Anaconda, Inc. `__, there are a wide variety of packages from the community supported
 `conda-forge project `__
 

From 485460ab87cd94dc00758b945ac23051988db090 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 19 Aug 2024 17:20:23 -0400
Subject: [PATCH 474/733] reworked intro paragraph to address duplicate links,
 and cleaner entry into conda vs. Anaconda.

---
 .../guides/installing-scientific-packages.rst | 20 ++++++++-----------
 1 file changed, 8 insertions(+), 12 deletions(-)

diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst
index 654db3d62..2d3e99920 100644
--- a/source/guides/installing-scientific-packages.rst
+++ b/source/guides/installing-scientific-packages.rst
@@ -14,7 +14,7 @@ In particular, `NumPy `__, which provides the basis
 for most of the software in the `scientific Python stack
 `_ can be configured
 to interoperate with different FORTRAN libraries, and can take advantage
-of different levels of vectorised instructions available in modern CPUs.
+of different levels of vectorized instructions available in modern CPUs.
 
 Starting with version 1.10.4 of NumPy and version 1.0.0 of SciPy, pre-built
 32-bit and 64-bit binaries in the ``wheel`` format are available for all major
@@ -118,17 +118,11 @@ be loaded and unloaded from the user's environment.
 The conda cross-platform package manager
 ----------------------------------------
 
-`Anaconda `_ is a Python distribution
-published by Anaconda, Inc. It is a stable collection of Open Source
-packages for big data and scientific use.  As of the 5.0 release of Anaconda,
-about 200 packages are installed by default, and a total of 400-500 can be
-installed and updated from the Anaconda repository.
-
 ``conda`` is an open source (BSD licensed) package management system and
-environment management system included in Anaconda that allows users to install
+environment management system that allows users to install
 multiple versions of binary software packages and their dependencies, and
 easily switch between them. It is a cross-platform tool working on Windows,
-macOS, and Linux. Conda can be used to package up and distribute all kinds of
+MacOS, and Linux. Conda can be used to package up and distribute all kinds of
 packages, it is not limited to just Python packages. It has full support for
 native virtual environments. Conda makes environments first-class citizens,
 making it easy to create independent environments even for C libraries. It is
@@ -136,8 +130,10 @@ written in Python, but is Python-agnostic. Conda manages Python itself as a
 package, so that :command:`conda update python` is possible, in contrast to
 pip, which only manages Python packages.
 
-The conda package manager is available in `Anaconda `_, `miniconda `_, `miniforge `_, and `pixi `_.
+Anaconda `Anaconda `_ is a Python distribution published by Anaconda, Inc. It is a stable collection of Open Source packages for big data and scientific use, and a collection of Graphical Interface utilities for managing conda environments.
+
+In addition to the full distribution provided by Anaconda, the conda package manager itself is available in  `miniconda `_, `miniforge `_, and `pixi `_.
+
 
 Conda packages are available on multiple channels on Anaconda.org, including the
-default channel supported by Anaconda, Inc, and the community supported conda-forge
-channel, which provides a wide variety of pre-built packages.
+default channel supported by Anaconda, Inc, the community supported conda-forge channel, which provides a wide variety of pre-built packages, and some domain-specific package collections.

From 2fee517b06a5c80af1fb6550b19c05c309f24974 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 19 Aug 2024 17:24:01 -0400
Subject: [PATCH 475/733] Update source/key_projects.rst

Co-authored-by: sinoroc <5529267+sinoroc@users.noreply.github.com>
---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index d8312e327..315897593 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -408,7 +408,7 @@ Conda is a package, dependency, and environment management system for any langua
 Ruby, C/C++, Fortran, and more. It is written in Python and
 widely used in the Python scientific computing community, due to its support for non-Python
 compiled libraries and extensions. It is used as the basis of the `Anaconda
-`__ Python distribution from Anaconda, Inc. It waas originally
+`__ Python distribution from Anaconda, Inc. It was originally
 aimed at the scientific community, but can also be used on its own, or with the
 :doc:`miniconda `, `miniforge `_ or
 `pixi `_ systems. It is available for Windows, Mac and Linux systems.

From 0f301cee5856a16238f573a69a8114dd9849e2f9 Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 19 Aug 2024 17:27:57 -0400
Subject: [PATCH 476/733] fixed netlib link

---
 source/guides/installing-scientific-packages.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst
index 2d3e99920..eded4fa5b 100644
--- a/source/guides/installing-scientific-packages.rst
+++ b/source/guides/installing-scientific-packages.rst
@@ -20,7 +20,7 @@ Starting with version 1.10.4 of NumPy and version 1.0.0 of SciPy, pre-built
 32-bit and 64-bit binaries in the ``wheel`` format are available for all major
 operating systems (Windows, macOS, and Linux) on PyPI. Note, however, that on
 Windows, NumPy binaries are linked against the `ATLAS
-`__ BLAS/LAPACK library, restricted to SSE2
+`__ BLAS/LAPACK library, restricted to SSE2
 instructions, so they may not provide optimal linear algebra performance.
 
 There are a number of alternative options for obtaining scientific Python

From bc813837dae0650e22f5e276faa0afb864decd23 Mon Sep 17 00:00:00 2001
From: shenxianpeng 
Date: Wed, 30 Oct 2024 12:30:21 +0000
Subject: [PATCH 477/733] change pre-commit.ci autoupdate_schedule to quarterly

---
 .pre-commit-config.yaml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 785b392ab..db8b1131a 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,3 +1,6 @@
+ci:
+  autoupdate_schedule: quarterly
+
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v5.0.0

From 5a59ab3ac44d50d83569ee48771f4dfc53dea18e Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 4 Nov 2024 09:31:43 -0800
Subject: [PATCH 478/733] slight edit to anaconda.org link

---
 source/key_projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/key_projects.rst b/source/key_projects.rst
index 315897593..e4501fe0e 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -419,7 +419,7 @@ management and deployment of binary extensions and other binary code.
 
 Conda does not install packages from PyPI -- it can only manage packages built specifically
 for conda, which can be made available on a "conda channel", such as those hosted on
-`anaconda.org `__, or a local (e.g. intranet) package server.
+`anaconda.org `__, or a local (e.g. intranet) package server.
 In addition to the "default" channels managed by `Anaconda, Inc. `__, there are a wide variety of packages from the community supported
 `conda-forge project `__
 

From 4e1e75d28af15fc6cc095657654ec9e500d9bc2a Mon Sep 17 00:00:00 2001
From: Chris Barker 
Date: Mon, 4 Nov 2024 09:38:28 -0800
Subject: [PATCH 479/733] added https://anaconda.org to linkcheck-ignore -- the
 link checker doesn't like it, but it's valid.

---
 source/conf.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/source/conf.py b/source/conf.py
index c777550ce..f4ec55093 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -133,6 +133,7 @@
     # https://github.com/pypa/packaging.python.org/pull/1474
     "https://stackoverflow.com/*",
     "https://pyscaffold.org/*",
+    "https://anaconda.org",
 ]
 linkcheck_retries = 5
 # Ignore anchors for links to GitHub project pages -- GitHub adds anchors from

From 3d0c2afb906cbb54a70848295b88e83ad73f78e7 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Fri, 8 Nov 2024 12:06:44 -0500
Subject: [PATCH 480/733] specifications: create living copy of PEP 740

Signed-off-by: William Woodruff 
---
 source/conf.py                                |   1 +
 .../index-hosted-attestations.rst             | 368 ++++++++++++++++++
 .../section-package-indices.rst               |   1 +
 .../specifications/simple-repository-api.rst  |  17 +-
 4 files changed, 386 insertions(+), 1 deletion(-)
 create mode 100644 source/specifications/index-hosted-attestations.rst

diff --git a/source/conf.py b/source/conf.py
index c777550ce..cd0f41302 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -193,6 +193,7 @@
     "tox": ("https://tox.wiki/en/latest/", None),
     "twine": ("https://twine.readthedocs.io/en/stable/", None),
     "virtualenv": ("https://virtualenv.pypa.io/en/stable/", None),
+    "warehouse": ("https://warehouse.pypa.io/", None),
 }
 
 # -- Options for todo extension --------------------------------------------------------
diff --git a/source/specifications/index-hosted-attestations.rst b/source/specifications/index-hosted-attestations.rst
new file mode 100644
index 000000000..395ffc10c
--- /dev/null
+++ b/source/specifications/index-hosted-attestations.rst
@@ -0,0 +1,368 @@
+
+.. _index-hosted-attestations:
+
+=========================
+Index hosted attestations
+=========================
+
+.. note:: This specification was originally defined in :pep:`740`.
+
+.. note::
+
+    :pep:`740` includes changes to the HTML and JSON index APIs.
+    These changes are documented in the :ref:`simple-repository-api`
+    under :ref:`simple-repository-api-base` and :ref:`json-serialization`.
+
+Specification
+=============
+
+.. _upload-endpoint:
+
+Upload endpoint changes
+-----------------------
+
+.. important::
+
+    The "legacy" upload API is not standardized.
+    See :ref:`Warehouse's Upload API documentation
+    ` for how attestations are uploaded.
+
+.. _attestation-object:
+
+Attestation objects
+-------------------
+
+An attestation object is a JSON object with several required keys; applications
+or signers may include additional keys so long as all explicitly
+listed keys are provided. The required layout of an attestation
+object is provided as pseudocode below.
+
+.. code-block:: python
+
+  @dataclass
+  class Attestation:
+      version: Literal[1]
+      """
+      The attestation object's version, which is always 1.
+      """
+
+      verification_material: VerificationMaterial
+      """
+      Cryptographic materials used to verify `envelope`.
+      """
+
+      envelope: Envelope
+      """
+      The enveloped attestation statement and signature.
+      """
+
+
+  @dataclass
+  class Envelope:
+      statement: bytes
+      """
+      The attestation statement.
+
+      This is represented as opaque bytes on the wire (encoded as base64),
+      but it MUST be an JSON in-toto v1 Statement.
+      """
+
+      signature: bytes
+      """
+      A signature for the above statement, encoded as base64.
+      """
+
+  @dataclass
+  class VerificationMaterial:
+      certificate: str
+      """
+      The signing certificate, as `base64(DER(cert))`.
+      """
+
+      transparency_entries: list[object]
+      """
+      One or more transparency log entries for this attestation's signature
+      and certificate.
+      """
+
+A full data model for each object in ``transparency_entries`` is provided in
+:ref:`appendix`. Attestation objects **SHOULD** include one or more
+transparency log entries, and **MAY** include additional keys for other
+sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a
+`Roughtime `__ server).
+
+Attestation objects are versioned; this PEP specifies version 1. Each version
+is tied to a single cryptographic suite to minimize unnecessary cryptographic
+agility. In version 1, the suite is as follows:
+
+* Certificates are specified as X.509 certificates, and comply with the
+  profile in :rfc:`5280`.
+* The message signature algorithm is ECDSA, with the P-256 curve for public keys
+  and SHA-256 as the cryptographic digest function.
+
+Future PEPs may change this suite (and the overall shape of the attestation
+object) by selecting a new version number.
+
+.. _payload-and-signature-generation:
+
+Attestation statement and signature generation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *attestation statement* is the actual claim that is cryptographically signed
+over within the attestation object (i.e., the ``envelope.statement``).
+
+The attestation statement is encoded as a
+`v1 in-toto Statement object `__,
+in JSON form. When serialized the statement is treated as an opaque binary blob,
+avoiding the need for canonicalization.
+
+In addition to being a v1 in-toto Statement, the attestation statement is constrained
+in the following ways:
+
+* The in-toto ``subject`` **MUST** contain only a single subject.
+* ``subject[0].name`` is the distribution's filename, which **MUST** be
+  a valid :ref:`source distribution ` or
+  :ref:`wheel distribution ` filename.
+* ``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests
+  **MAY** be present. The digests **MUST** be represented as hexadecimal strings.
+* The following ``predicateType`` values are supported:
+
+  * `SLSA Provenance `__: ``https://slsa.dev/provenance/v1``
+  * `PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``
+
+The signature over this statement is constructed using the
+`v1 DSSE signature protocol `__,
+with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` and a ``PAYLOAD_BODY`` of the JSON-encoded
+statement above. No other ``PAYLOAD_TYPE`` is permitted.
+
+.. _provenance-object:
+
+Provenance objects
+------------------
+
+The index will serve uploaded attestations along with metadata that can assist
+in verifying them in the form of JSON serialized objects.
+
+These *provenance objects* will be available via both the Simple Index
+and JSON-based Simple API as described above, and will have the following layout:
+
+.. code-block:: json
+
+    {
+        "version": 1,
+        "attestation_bundles": [
+          {
+            "publisher": {
+              "kind": "important-ci-service",
+              "claims": {},
+              "vendor-property": "foo",
+              "another-property": 123
+            },
+            "attestations": [
+              { /* attestation 1 ... */ },
+              { /* attestation 2 ... */ }
+            ]
+          }
+        ]
+    }
+
+or, as pseudocode:
+
+.. code-block:: python
+
+  @dataclass
+  class Publisher:
+      kind: string
+      """
+      The kind of Trusted Publisher.
+      """
+
+      claims: object | None
+      """
+      Any context-specific claims retained by the index during Trusted Publisher
+      authentication.
+      """
+
+      _rest: object
+      """
+      Each publisher object is open-ended, meaning that it MAY contain additional
+      fields beyond the ones specified explicitly above. This field signals that,
+      but is not itself present.
+      """
+
+  @dataclass
+  class AttestationBundle:
+      publisher: Publisher
+      """
+      The publisher associated with this set of attestations.
+      """
+
+      attestations: list[Attestation]
+      """
+      The set of attestations included in this bundle.
+      """
+
+  @dataclass
+  class Provenance:
+      version: Literal[1]
+      """
+      The provenance object's version, which is always 1.
+      """
+
+      attestation_bundles: list[AttestationBundle]
+      """
+      One or more attestation "bundles".
+      """
+
+* ``version`` is ``1``. Like attestation objects, provenance objects are
+  versioned, and this PEP only defines version ``1``.
+* ``attestation_bundles`` is a **required** JSON array, containing one
+  or more "bundles" of attestations. Each bundle corresponds to a
+  signing identity (such as a Trusted Publishing identity), and contains
+  one or more attestation objects.
+
+  As noted in the ``Publisher`` model,
+  each ``AttestationBundle.publisher`` object is specific to its Trusted Publisher
+  but must include at minimum:
+
+  * A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the
+    kind of Trusted Publisher.
+  * A ``claims`` key, which **MUST** be a JSON object containing any context-specific
+    claims retained by the index during Trusted Publisher authentication.
+
+  All other keys in the publisher object are publisher-specific.
+
+  Each array of attestation objects is a superset of the ``attestations``
+  array supplied by the uploaded through the ``attestations`` field at upload
+  time, as described in :ref:`upload-endpoint` and
+  :ref:`changes-to-provenance-objects`.
+
+.. _changes-to-provenance-objects:
+
+Changes to provenance objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Provenance objects are *not* immutable, and may change over time. Reasons
+for changes to the provenance object include but are not limited to:
+
+* Addition of new attestations for a pre-existing signing identity: the index
+  **MAY** choose to allow additional attestations by pre-existing signing
+  identities, such as newer attestation versions for already uploaded
+  files.
+
+* Addition of new signing identities and associated attestations: the index
+  **MAY** choose to support attestations from sources other than the file's
+  uploader, such as third-party auditors or the index itself. These attestations
+  may be performed asynchronously, requiring the index to insert them into
+  the provenance object *post facto*.
+
+.. _attestation-verification:
+
+Attestation verification
+------------------------
+
+Verifying an attestation object against a distribution file requires verification of each of the
+following:
+
+* ``version`` is ``1``. The verifier **MUST** reject any other version.
+* ``verification_material.certificate`` is a valid signing certificate, as
+  issued by an *a priori* trusted authority (such as a root of trust already
+  present within the verifying client).
+* ``verification_material.certificate`` identifies an appropriate signing
+  subject, such as the machine identity of the Trusted Publisher that published
+  the package.
+* ``envelope.statement`` is a valid in-toto v1 Statement, with a subject
+  and digest that **MUST** match the distribution's filename and contents.
+  For the distribution's filename, matching **MUST** be performed by parsing
+  using the appropriate source distribution or wheel filename format, as
+  the statement's subject may be equivalent but normalized.
+* ``envelope.signature`` is a valid signature for ``envelope.statement``
+  corresponding to ``verification_material.certificate``,
+  as reconstituted via the
+  `v1 DSSE signature protocol `__.
+
+In addition to the above required steps, a verifier **MAY** additionally verify
+``verification_material.transparency_entries`` on a policy basis, e.g. requiring
+at least one transparency log entry or a threshold of entries. When verifying
+transparency entries, the verifier **MUST** confirm that the inclusion time for
+each entry lies within the signing certificate's validity period.
+
+.. _appendix:
+
+Appendix: Data models for Transparency Log Entries
+====================================================
+
+This appendix contains pseudocoded data models for transparency log entries
+in attestation objects. Each transparency log entry serves as a source
+of signed inclusion time, and can be verified either online or offline.
+
+.. code-block:: python
+
+  @dataclass
+  class TransparencyLogEntry:
+      log_index: int
+      """
+      The global index of the log entry, used when querying the log.
+      """
+
+      log_id: str
+      """
+      An opaque, unique identifier for the log.
+      """
+
+      entry_kind: str
+      """
+      The kind (type) of log entry.
+      """
+
+      entry_version: str
+      """
+      The version of the log entry's submitted format.
+      """
+
+      integrated_time: int
+      """
+      The UNIX timestamp from the log from when the entry was persisted.
+      """
+
+      inclusion_proof: InclusionProof
+      """
+      The actual inclusion proof of the log entry.
+      """
+
+
+  @dataclass
+  class InclusionProof:
+      log_index: int
+      """
+      The index of the entry in the tree it was written to.
+      """
+
+      root_hash: str
+      """
+      The digest stored at the root of the Merkle tree at the time of proof
+      generation.
+      """
+
+      tree_size: int
+      """
+      The size of the Merkle tree at the time of proof generation.
+      """
+
+      hashes: list[str]
+      """
+      A list of hashes required to complete the inclusion proof, sorted
+      in order from leaf to root. The leaf and root hashes are not themselves
+      included in this list; the root is supplied via `root_hash` and the client
+      must calculate the leaf hash.
+      """
+
+      checkpoint: str
+      """
+      The signed tree head's signature, at the time of proof generation.
+      """
+
+      cosigned_checkpoints: list[str]
+      """
+      Cosigned checkpoints from zero or more log witnesses.
+      """
diff --git a/source/specifications/section-package-indices.rst b/source/specifications/section-package-indices.rst
index 13ba98113..73004b4d3 100644
--- a/source/specifications/section-package-indices.rst
+++ b/source/specifications/section-package-indices.rst
@@ -7,3 +7,4 @@ Package Index Interfaces
 
    pypirc
    simple-repository-api
+   index-hosted-attestations
diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
index 0d65a58aa..9ec8e4bf2 100644
--- a/source/specifications/simple-repository-api.rst
+++ b/source/specifications/simple-repository-api.rst
@@ -96,6 +96,15 @@ In addition to the above, the following constraints are placed on the API:
   In the attribute value, < and > have to be HTML encoded as ``<`` and
   ``>``, respectively.
 
+* A repository **MAY** include a ``data-provenance`` attribute on a file link.
+  The value of this attribute **MUST** be a fully qualified URL, signaling that
+  the file's provenance can be found at that URL. This URL **MUST** represent
+  a `secure origin `_.
+
+  .. note::
+
+    The format of the linked provenance is defined in :ref:`index-hosted-attestations`.
+
 Normalized Names
 ----------------
 
@@ -495,6 +504,10 @@ Each individual file dictionary has the following keys:
   and is a truthy value, then it **SHOULD** be interpreted as indicating that the
   file pointed to by the ``url`` field has been "Yanked" as per :ref:`the API
   yank specification `.
+- ``provenance``: An **optional** key which, if present **MUST** be either a JSON
+  string or ``null``. If not ``null``, it **MUST** be a URL to the file's
+  associated provenance, with the same rules as ``data-provenance`` in the
+  :ref:`base HTML API specification `.
 
 As an example:
 
@@ -518,7 +531,8 @@ As an example:
           "url": "https://example.com/files/holygrail-1.0-py3-none-any.whl",
           "hashes": {"sha256": "...", "blake2b": "..."},
           "requires-python": ">=3.7",
-          "dist-info-metadata": true
+          "dist-info-metadata": true,
+          "provenance": "https://example.com/files/holygrail-1.0-py3-none-any.whl.provenance"
         }
       ]
     }
@@ -986,3 +1000,4 @@ History
   format, in :pep:`700`
 * June 2023: renaming the field which provides package metadata independently
   from a package, in :pep:`714`
+* November 2024: provenance metadata in the HTML and JSON formats, in :pep:`740`

From b8439b2cf6235ff8310df39b9a52b92983c01344 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Sun, 10 Nov 2024 22:00:02 +0200
Subject: [PATCH 481/733] Use syntax highlighting for BigQuery queries

---
 source/guides/analyzing-pypi-package-downloads.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/source/guides/analyzing-pypi-package-downloads.rst b/source/guides/analyzing-pypi-package-downloads.rst
index 5fecc99c1..2ad02fed5 100644
--- a/source/guides/analyzing-pypi-package-downloads.rst
+++ b/source/guides/analyzing-pypi-package-downloads.rst
@@ -103,7 +103,7 @@ Counting package downloads
 The following query counts the total number of downloads for the project
 "pytest".
 
-::
+.. code-block:: sql
 
     #standardSQL
     SELECT COUNT(*) AS num_downloads
@@ -123,7 +123,7 @@ The following query counts the total number of downloads for the project
 To count downloads from pip only, filter on the ``details.installer.name``
 column.
 
-::
+.. code-block:: sql
 
     #standardSQL
     SELECT COUNT(*) AS num_downloads
@@ -147,7 +147,7 @@ Package downloads over time
 To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also
 filtering by this column reduces corresponding costs.
 
-::
+.. code-block:: sql
 
     #standardSQL
     SELECT
@@ -185,7 +185,7 @@ Python versions over time
 Extract the Python version from the ``details.python`` column. Warning: This
 query processes over 500 GB of data.
 
-::
+.. code-block:: sql
 
     #standardSQL
     SELECT
@@ -228,7 +228,7 @@ column, which includes the hash and artifact filename.
 .. note::
    The URL generated here is not guaranteed to be stable, but currently aligns with the URL where PyPI artifacts are hosted.
 
-::
+.. code-block:: sql
 
     SELECT
       CONCAT('https://files.pythonhosted.org/packages', path) as url

From b54b35da4af6f3eb56f24cee3076d9d14e39421d Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri 
Date: Wed, 13 Nov 2024 16:50:49 +0000
Subject: [PATCH 482/733] Add simple issue template

---
 .github/ISSUE_TEMPLATE/config.yml  |  6 ++++++
 .github/ISSUE_TEMPLATE/general.yml | 25 +++++++++++++++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml
 create mode 100644 .github/ISSUE_TEMPLATE/general.yml

diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 000000000..bd4d53ae7
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,6 @@
+blank_issues_enabled: false
+contact_links:
+  - name: "Community Guidelines"
+    url: "https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md"
+    about: "Please make sure to follow the PSF Code of Conduct when participating in this repository."
+
diff --git a/.github/ISSUE_TEMPLATE/general.yml b/.github/ISSUE_TEMPLATE/general.yml
new file mode 100644
index 000000000..356520c15
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/general.yml
@@ -0,0 +1,25 @@
+name: General Issue
+description: Please fill out the form below to submit an issue.
+labels: []
+assignees: []
+
+body:
+  - type: textarea
+    id: issue_description
+    attributes:
+      label: "Issue Description"
+      description: "Please provide a detailed description of your issue."
+      placeholder: "Describe your issue here..."
+      value: ""
+
+  - type: checkboxes
+    id: code_of_conduct
+    attributes:
+      label: Code of Conduct
+      description: |
+        **Please read the [PSF Code of Conduct][CoC] first.**
+        [CoC]: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md
+      options:
+        - label: "I am aware that participants in this repository must follow the PSF Code of Conduct."
+          required: true
+

From 17c228847d8b6fa87a70b36d94c5c99895fe7522 Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri 
Date: Wed, 13 Nov 2024 16:57:42 +0000
Subject: [PATCH 483/733] Make issue description mandatory

---
 .github/ISSUE_TEMPLATE/general.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/ISSUE_TEMPLATE/general.yml b/.github/ISSUE_TEMPLATE/general.yml
index 356520c15..8d75b88ef 100644
--- a/.github/ISSUE_TEMPLATE/general.yml
+++ b/.github/ISSUE_TEMPLATE/general.yml
@@ -11,6 +11,7 @@ body:
       description: "Please provide a detailed description of your issue."
       placeholder: "Describe your issue here..."
       value: ""
+      required: true
 
   - type: checkboxes
     id: code_of_conduct

From 8869f451492cdd32b7e483fcca6df1eb6b9eb43d Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 13 Nov 2024 17:04:09 +0000
Subject: [PATCH 484/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .github/ISSUE_TEMPLATE/config.yml  | 1 -
 .github/ISSUE_TEMPLATE/general.yml | 1 -
 2 files changed, 2 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index bd4d53ae7..fbc581cd6 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -3,4 +3,3 @@ contact_links:
   - name: "Community Guidelines"
     url: "https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md"
     about: "Please make sure to follow the PSF Code of Conduct when participating in this repository."
-
diff --git a/.github/ISSUE_TEMPLATE/general.yml b/.github/ISSUE_TEMPLATE/general.yml
index 8d75b88ef..47fa75d7d 100644
--- a/.github/ISSUE_TEMPLATE/general.yml
+++ b/.github/ISSUE_TEMPLATE/general.yml
@@ -23,4 +23,3 @@ body:
       options:
         - label: "I am aware that participants in this repository must follow the PSF Code of Conduct."
           required: true
-

From c4195ad83188f0259501e0439084a3dc8997ba23 Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri 
Date: Wed, 13 Nov 2024 22:45:38 +0000
Subject: [PATCH 485/733] Implement suggestions from code review

---
 .github/ISSUE_TEMPLATE/general.yml | 32 ++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/general.yml b/.github/ISSUE_TEMPLATE/general.yml
index 47fa75d7d..4cfc57efb 100644
--- a/.github/ISSUE_TEMPLATE/general.yml
+++ b/.github/ISSUE_TEMPLATE/general.yml
@@ -4,22 +4,34 @@ labels: []
 assignees: []
 
 body:
+  - type: markdown
+    attributes:
+      value: |
+        **Thanks for taking a minute to file an issue!**
+
+        Read the [PSF Code of Conduct][CoC] first.
+        [CoC]: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md
+
+        ⚠
+        Verify first that your issue is not [already reported on
+        GitHub][issue search].
+
+        _Please fill out the form below with as many precise
+        details as possible._
+
+        [issue search]: ../search?q=is%3Aissue&type=issues
+
   - type: textarea
-    id: issue_description
     attributes:
-      label: "Issue Description"
-      description: "Please provide a detailed description of your issue."
-      placeholder: "Describe your issue here..."
-      value: ""
+      label: Issue Description
+      description: Please provide a detailed description of your issue.
+      placeholder: Describe your issue here...
+    validations:
       required: true
 
   - type: checkboxes
-    id: code_of_conduct
     attributes:
       label: Code of Conduct
-      description: |
-        **Please read the [PSF Code of Conduct][CoC] first.**
-        [CoC]: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md
       options:
-        - label: "I am aware that participants in this repository must follow the PSF Code of Conduct."
+        - label: I am aware that participants in this repository must follow the PSF Code of Conduct.
           required: true

From 3486a240d0e3e5235cc508284e430f69aff8de28 Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri 
Date: Wed, 13 Nov 2024 22:46:50 +0000
Subject: [PATCH 486/733] Fix URL linking

---
 .github/ISSUE_TEMPLATE/general.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/ISSUE_TEMPLATE/general.yml b/.github/ISSUE_TEMPLATE/general.yml
index 4cfc57efb..d41731613 100644
--- a/.github/ISSUE_TEMPLATE/general.yml
+++ b/.github/ISSUE_TEMPLATE/general.yml
@@ -10,7 +10,6 @@ body:
         **Thanks for taking a minute to file an issue!**
 
         Read the [PSF Code of Conduct][CoC] first.
-        [CoC]: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md
 
         ⚠
         Verify first that your issue is not [already reported on
@@ -19,6 +18,7 @@ body:
         _Please fill out the form below with as many precise
         details as possible._
 
+        [CoC]: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md
         [issue search]: ../search?q=is%3Aissue&type=issues
 
   - type: textarea

From 11861f8c61bfa4d0a888226ec72ea25dbf93a981 Mon Sep 17 00:00:00 2001
From: Evan Kohilas 
Date: Fri, 15 Nov 2024 23:17:03 +1100
Subject: [PATCH 487/733] Update packaging-projects.rst for entering API token

---
 source/tutorials/packaging-projects.rst | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 4c205e28f..93826321d 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -421,16 +421,15 @@ Once installed, run Twine to upload all of the archives under :file:`dist`:
 
         py -m twine upload --repository testpypi dist/*
 
-You will be prompted for a username and password. For the username,
-use ``__token__``. For the password, use the token value, including
-the ``pypi-`` prefix.
+You will be prompted for an API token. Use the token value, including the ``pypi-``
+prefix. Note that the input will be hidden, so be sure to paste correctly.
 
 After the command completes, you should see output similar to this:
 
 .. code-block::
 
     Uploading distributions to https://test.pypi.org/legacy/
-    Enter your username: __token__
+    Enter your API token:
     Uploading example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
     100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.2/8.2 kB • 00:01 • ?
     Uploading example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz

From 685b68092eec6beecbccdaa996fb6b1128712a9f Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Mon, 18 Nov 2024 13:59:30 +0100
Subject: [PATCH 488/733] Fix the alphabetic order of terms in Glossary

---
 source/glossary.rst | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index 00d798e39..dc6211833 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -119,15 +119,6 @@ Glossary
         extensions.
 
 
-    Known Good Set (KGS)
-
-        A set of distributions at specified versions which are compatible with
-        each other. Typically a test suite will be run which passes all tests
-        before a specific set of packages is declared a known good set. This
-        term is commonly used by frameworks and toolkits which are comprised of
-        multiple individual distributions.
-
-
     Import Package
 
         A Python module which can contain other modules or recursively, other
@@ -147,6 +138,15 @@ Glossary
         as described in the specicifcation :ref:`recording-installed-packages`.
 
 
+    Known Good Set (KGS)
+
+        A set of distributions at specified versions which are compatible with
+        each other. Typically a test suite will be run which passes all tests
+        before a specific set of packages is declared a known good set. This
+        term is commonly used by frameworks and toolkits which are comprised of
+        multiple individual distributions.
+
+
     Module
 
         The basic unit of code reusability in Python, existing in one of two

From 1f4a641730e99a3c1df997ae94e1fc6219a74f6d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sviatoslav=20Sydorenko=20=28=D0=A1=D0=B2=D1=8F=D1=82=D0=BE?=
 =?UTF-8?q?=D1=81=D0=BB=D0=B0=D0=B2=20=D0=A1=D0=B8=D0=B4=D0=BE=D1=80=D0=B5?=
 =?UTF-8?q?=D0=BD=D0=BA=D0=BE=29?= 
Date: Thu, 10 Oct 2024 14:17:32 +0200
Subject: [PATCH 489/733] Add a label to pganssle's post link on deprecating
 `setup.py`

I noticed it as it ended up in the translation strings.
---
 source/discussions/setup-py-deprecated.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/setup-py-deprecated.rst b/source/discussions/setup-py-deprecated.rst
index 1c2eae3fa..a9fc70aa3 100644
--- a/source/discussions/setup-py-deprecated.rst
+++ b/source/discussions/setup-py-deprecated.rst
@@ -210,6 +210,6 @@ has now been reduced to the role of a build backend.
 Where to read more about this?
 ==============================
 
-* https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html
+* `Why you shouldn't invoke setup.py directly by Paul Ganssle `__
 
 * :doc:`setuptools:deprecated/commands`

From 39033e24c16bca7f7bd781bb00adee9f90f22bf8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sviatoslav=20Sydorenko=20=28=D0=A1=D0=B2=D1=8F=D1=82=D0=BE?=
 =?UTF-8?q?=D1=81=D0=BB=D0=B0=D0=B2=20=D0=A1=D0=B8=D0=B4=D0=BE=D1=80=D0=B5?=
 =?UTF-8?q?=D0=BD=D0=BA=D0=BE=29?= 
Date: Fri, 11 Oct 2024 00:54:38 +0200
Subject: [PATCH 490/733] Move Paul out of the link label

Co-authored-by: Pradyun Gedam 
---
 source/discussions/setup-py-deprecated.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/setup-py-deprecated.rst b/source/discussions/setup-py-deprecated.rst
index a9fc70aa3..6bcd15b58 100644
--- a/source/discussions/setup-py-deprecated.rst
+++ b/source/discussions/setup-py-deprecated.rst
@@ -210,6 +210,6 @@ has now been reduced to the role of a build backend.
 Where to read more about this?
 ==============================
 
-* `Why you shouldn't invoke setup.py directly by Paul Ganssle `__
+* `Why you shouldn't invoke setup.py directly `__ by Paul Ganssle
 
 * :doc:`setuptools:deprecated/commands`

From dcd35fd41dd3d7c29ead52084d75167b715aaed5 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Mon, 25 Nov 2024 09:39:23 -0500
Subject: [PATCH 491/733] fix upload API URL

Signed-off-by: William Woodruff 
---
 source/specifications/index-hosted-attestations.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/specifications/index-hosted-attestations.rst b/source/specifications/index-hosted-attestations.rst
index 395ffc10c..d078e87bd 100644
--- a/source/specifications/index-hosted-attestations.rst
+++ b/source/specifications/index-hosted-attestations.rst
@@ -24,8 +24,8 @@ Upload endpoint changes
 .. important::
 
     The "legacy" upload API is not standardized.
-    See :ref:`Warehouse's Upload API documentation
-    ` for how attestations are uploaded.
+    See `PyPI's Upload API documentation `_
+    for how attestations are uploaded.
 
 .. _attestation-object:
 

From 0655509a966c7641c473c32e5e85fe016d4885f2 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Mon, 25 Nov 2024 15:02:48 -0500
Subject: [PATCH 492/733] tool-recommendations: update Trusted Publisher
 providers

Signed-off-by: William Woodruff 
---
 source/guides/tool-recommendations.rst | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index 3903232b9..ece067993 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -139,15 +139,25 @@ to build distributable wheels.
 Uploading to PyPI
 =================
 
-For projects hosted on GitHub, it is recommended to use the :ref:`trusted publishing
-`, which allows the package to be securely uploaded to PyPI
-from a GitHub Actions job. (This is not yet supported on software forges other
-than GitHub.)
+For projects hosted on or published via supported CI/CD platforms, it is
+recommended to use the :ref:`Trusted Publishing `, which
+allows the package to be securely uploaded to PyPI from a CI/CD workflow
+without a manually configured API token.
+
+As of November 2024, PyPI supports the following platforms as Trusted Publishing
+providers:
+
+* GitHub Actions (on ``https://github.com``)
+* GitLab CI/CD (on ``https://gitlab.com``)
+* ActiveState
+* Google Cloud
 
 The other available method is to upload the package manually using :ref:`twine`.
 
-**Never** use ``python setup.py upload`` for this task. In addition to being
-:ref:`deprecated `, it is insecure.
+.. warning::
+
+    **Never** use ``python setup.py upload`` for this task. In addition to being
+    :ref:`deprecated `, it is insecure.
 
 
 Workflow tools

From e8193e1ce6e6d6dc77a80569ae20cf711e9a2ab1 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Mon, 25 Nov 2024 16:37:01 -0500
Subject: [PATCH 493/733] Update source/guides/tool-recommendations.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/guides/tool-recommendations.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index ece067993..1ba36ed61 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -154,7 +154,7 @@ providers:
 
 The other available method is to upload the package manually using :ref:`twine`.
 
-.. warning::
+.. danger::
 
     **Never** use ``python setup.py upload`` for this task. In addition to being
     :ref:`deprecated `, it is insecure.

From f86b4d08bce2febb2f65c627c0fb34bcfbfd90e0 Mon Sep 17 00:00:00 2001
From: Olavo Bacelar 
Date: Thu, 28 Nov 2024 23:42:38 +0100
Subject: [PATCH 494/733] fix: typo in installed project glossary

---
 source/glossary.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index dc6211833..43db5413a 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -135,7 +135,7 @@ Glossary
 
         A :term:`Project` that is installed for use with
         a Python interpreter or :term:`Virtual Environment`,
-        as described in the specicifcation :ref:`recording-installed-packages`.
+        as described in the specification :ref:`recording-installed-packages`.
 
 
     Known Good Set (KGS)

From 38f9bfb7c714931eb02b208cdaba0901bee710a7 Mon Sep 17 00:00:00 2001
From: konstin 
Date: Fri, 6 Dec 2024 10:24:12 +0100
Subject: [PATCH 495/733] Clarify that the scripts directory is for files only

Following https://github.com/astral-sh/uv/issues/9656 and the discussion in the pypa discord (https://discord.com/channels/803025117553754132/837243676814999553/1314391181656064040), add a clarifying sentence that the scripts directory in wheels if for files only.

A future specification may want to extend this to "regular files and symlinks", for not it's limited to regular for clear rewrite semantics.
---
 source/specifications/binary-distribution-format.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index 8da38357a..7b07dee81 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -189,7 +189,7 @@ its version, e.g. ``1.0.0``, consist of:
 #. Python scripts must appear in ``scripts`` and begin with exactly
    ``b'#!python'`` in order to enjoy script wrapper generation and
    ``#!python`` rewriting at install time.  They may have any or no
-   extension.
+   extension.  The ``scripts`` directory may only contain regular files.
 #. ``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1
    or greater format metadata.
 #. ``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive

From 40842ab77bd8d54db9f0d6e946ba90552e37a173 Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan 
Date: Sun, 8 Dec 2024 14:37:24 +1000
Subject: [PATCH 496/733] Add a History note about the clarification

---
 source/specifications/binary-distribution-format.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index 7b07dee81..68f62639d 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -423,6 +423,10 @@ History
 - February 2013: This specification was approved through :pep:`427`.
 - February 2021: The rules on escaping in wheel filenames were revised, to bring
   them into line with what popular tools actually do.
+- December 2024: Clarified that the ``scripts`` folder should only contain
+  regular files (the expected behaviour of consuming tools when encountering
+  symlinks or subdirectories in this folder is not formally defined, and hence
+  may vary between tools).
 
 
 Appendix

From e45233770ba92fb1eff6bd4fee1baeca601f3686 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Tue, 26 Nov 2024 11:14:07 +0200
Subject: [PATCH 497/733] Add view and edit buttons

---
 requirements.txt | 2 +-
 source/conf.py   | 5 +++++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/requirements.txt b/requirements.txt
index 077adb580..a3269a025 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,4 +1,4 @@
-furo==2023.9.10
+furo==2024.8.6
 sphinx==7.2.6
 sphinx-autobuild==2021.3.14
 sphinx-inline-tabs==2023.4.21
diff --git a/source/conf.py b/source/conf.py
index ab14e315a..f08f6e836 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -62,6 +62,11 @@
 html_title = "Python Packaging User Guide"
 html_theme = "furo"
 
+html_theme_options = {
+    "source_edit_link": "https://github.com/pypa/packaging.python.org/edit/main/source/{filename}",
+    "source_view_link": "https://github.com/pypa/packaging.python.org/blob/main/source/{filename}?plain=true",
+}
+
 html_favicon = "assets/py.png"
 html_last_updated_fmt = ""
 

From 99af225ab240808564fb9c9967aba346d4742199 Mon Sep 17 00:00:00 2001
From: Stephen Rosen 
Date: Mon, 16 Dec 2024 12:55:56 -0600
Subject: [PATCH 498/733] Add doc for dependency-groups, import from PEP

This content is copied from the PEP, with the following
characteristics:
- the initial overview and examples are new
- the "History" footer is new
- all of the other sections are copied from the PEP verbatim
---
 source/specifications/dependency-groups.rst   | 272 ++++++++++++++++++
 .../section-distribution-metadata.rst         |   1 +
 2 files changed, 273 insertions(+)
 create mode 100644 source/specifications/dependency-groups.rst

diff --git a/source/specifications/dependency-groups.rst b/source/specifications/dependency-groups.rst
new file mode 100644
index 000000000..8206a7063
--- /dev/null
+++ b/source/specifications/dependency-groups.rst
@@ -0,0 +1,272 @@
+.. _dependency-groups:
+
+=================
+Dependency Groups
+=================
+
+This specification defines Dependency Groups, a mechanism for storing package
+requirements in ``pyproject.toml`` files such that they are not included in
+project metadata when it is built.
+
+Dependency Groups are suitable for internal development use-cases like linting
+and testing, as well as for projects which are not built for distribution, like
+collections of related scripts.
+
+Fundamentally, Dependency Groups should be thought of as being a standardized
+subset of the capabilities of ``requirements.txt`` files (which are
+``pip``-specific).
+
+Specification
+=============
+
+Examples
+--------
+
+This is a simple table which shows a ``test`` group::
+
+    [dependency-groups]
+    test = ["pytest>7", "coverage"]
+
+and a similar table which defines ``test`` and ``coverage`` groups::
+
+    [dependency-groups]
+    coverage = ["coverage[toml]"]
+    test = ["pytest>7", {include-group = "coverage"}]
+
+The ``[dependency-groups]`` Table
+---------------------------------
+
+This PEP defines a new section (table) in ``pyproject.toml`` files named
+``dependency-groups``. The ``dependency-groups`` table contains an arbitrary
+number of user-defined keys, each of which has, as its value, a list of
+requirements (defined below). These keys must be
+`valid non-normalized names `__,
+and must be
+`normalized `__
+before comparisons.
+
+Tools SHOULD prefer to present the original, non-normalized name to users by
+default. If duplicate names, after normalization, are encountered, tools SHOULD
+emit an error.
+
+Requirement lists under ``dependency-groups`` may contain strings, tables
+("dicts" in Python), or a mix of strings and tables.
+
+Strings in requirement lists must be valid
+`Dependency Specifiers `__,
+as defined in :pep:`508`.
+
+Tables in requirement lists must be valid Dependency Object Specifiers.
+
+Dependency Object Specifiers
+----------------------------
+
+Dependency Object Specifiers are tables which define zero or more dependencies.
+
+This PEP standardizes only one type of Dependency Object Specifier, a
+"Dependency Group Include". Other types may be added in future standards.
+
+Dependency Group Include
+''''''''''''''''''''''''
+
+A Dependency Group Include includes the dependencies of another Dependency
+Group in the current Dependency Group.
+
+An include is defined as a table with exactly one key, ``"include-group"``,
+whose value is a string, the name of another Dependency Group.
+
+For example, ``{include-group = "test"}`` is an include which expands to the
+contents of the ``test`` Dependency Group.
+
+Includes are defined to be exactly equivalent to the contents of the named
+Dependency Group, inserted into the current group at the location of the include.
+For example, if ``foo = ["a", "b"]`` is one group, and
+``bar = ["c", {include-group = "foo"}, "d"]`` is another, then ``bar`` should
+evaluate to ``["c", "a", "b", "d"]`` when Dependency Group Includes are expanded.
+
+Dependency Group Includes may specify the same package multiple times. Tools
+SHOULD NOT deduplicate or otherwise alter the list contents produced by the
+include. For example, given the following table:
+
+.. code:: toml
+
+    [dependency-groups]
+    group-a = ["foo"]
+    group-b = ["foo>1.0"]
+    group-c = ["foo<1.0"]
+    all = ["foo", {include-group = "group-a"}, {include-group = "group-b"}, {include-group = "group-c"}]
+
+The resolved value of ``all`` SHOULD be ``["foo", "foo", "foo>1.0", "foo<1.0"]``.
+Tools should handle such a list exactly as they would handle any other case in
+which they are asked to process the same requirement multiple times with
+different version constraints.
+
+Dependency Group Includes may include lists containing Dependency Group
+Includes, in which case those includes should be expanded as well. Dependency
+Group Includes MUST NOT include cycles, and tools SHOULD report an error if
+they detect a cycle.
+
+Package Building
+----------------
+
+Build backends MUST NOT include Dependency Group data in built distributions as
+package metadata. This means that PKG-INFO in sdists and METADATA in wheels
+do not include any referencable fields containing Dependency Groups.
+
+It is valid to use Dependency Groups in the evaluation of dynamic metadata, and
+``pyproject.toml`` files included in sdists will naturally still contain the
+``[dependency-groups]`` table. However, the table contents are not part of a
+published package's interfaces.
+
+Installing Dependency Groups
+----------------------------
+
+Tools which support Dependency Groups are expected to provide new options and
+interfaces to allow users to install from Dependency Groups.
+
+No syntax is defined for expressing the Dependency Group of a package, for two
+reasons:
+
+* it would not be valid to refer to the Dependency Groups of a third-party
+  package from PyPI (because the data is defined to be unpublished)
+
+* there is not guaranteed to be a current package for Dependency Groups -- part
+  of their purpose is to support non-package projects
+
+For example, a possible pip interface for installing Dependency Groups
+would be:
+
+.. code:: shell
+
+    pip install --dependency-groups=test,typing
+
+Note that this is only an example. This PEP does not declare any requirements
+for how tools support the installation of Dependency Groups.
+
+Overlapping Install UX with Extras
+''''''''''''''''''''''''''''''''''
+
+Tools MAY choose to provide the same interfaces for installing Dependency
+Groups as they do for installing extras.
+
+Note that this specification does not forbid having an extra whose name matches
+a Dependency Group.
+
+Users are advised to avoid creating Dependency Groups whose names match extras.
+Tools MAY treat such matching as an error.
+
+Validation and Compatibility
+----------------------------
+
+Tools supporting Dependency Groups may want to validate data before using it.
+However, tools implementing such validation behavior should be careful to allow
+for future expansions to this spec, so that they do not unnecessarily emit
+errors or warnings in the presence of new syntax.
+
+Tools SHOULD error when evaluating or processing unrecognized data in
+Dependency Groups.
+
+Tools SHOULD NOT eagerly validate the list contents of **all** Dependency
+Groups.
+
+This means that in the presence of the following data, most tools will allow
+the ``foo`` group to be used, and will only error when the ``bar`` group is
+used:
+
+Reference Implementation
+========================
+
+The following Reference Implementation prints the contents of a Dependency
+Group to stdout, newline delimited.
+The output is therefore valid ``requirements.txt`` data.
+
+.. code-block:: python
+
+    import re
+    import sys
+    import tomllib
+    from collections import defaultdict
+
+    from packaging.requirements import Requirement
+
+
+    def _normalize_name(name: str) -> str:
+        return re.sub(r"[-_.]+", "-", name).lower()
+
+
+    def _normalize_group_names(dependency_groups: dict) -> dict:
+        original_names = defaultdict(list)
+        normalized_groups = {}
+
+        for group_name, value in dependency_groups.items():
+            normed_group_name = _normalize_name(group_name)
+            original_names[normed_group_name].append(group_name)
+            normalized_groups[normed_group_name] = value
+
+        errors = []
+        for normed_name, names in original_names.items():
+            if len(names) > 1:
+                errors.append(f"{normed_name} ({', '.join(names)})")
+        if errors:
+            raise ValueError(f"Duplicate dependency group names: {', '.join(errors)}")
+
+        return normalized_groups
+
+
+    def _resolve_dependency_group(
+        dependency_groups: dict, group: str, past_groups: tuple[str, ...] = ()
+    ) -> list[str]:
+        if group in past_groups:
+            raise ValueError(f"Cyclic dependency group include: {group} -> {past_groups}")
+
+        if group not in dependency_groups:
+            raise LookupError(f"Dependency group '{group}' not found")
+
+        raw_group = dependency_groups[group]
+        if not isinstance(raw_group, list):
+            raise ValueError(f"Dependency group '{group}' is not a list")
+
+        realized_group = []
+        for item in raw_group:
+            if isinstance(item, str):
+                # packaging.requirements.Requirement parsing ensures that this is a valid
+                # PEP 508 Dependency Specifier
+                # raises InvalidRequirement on failure
+                Requirement(item)
+                realized_group.append(item)
+            elif isinstance(item, dict):
+                if tuple(item.keys()) != ("include-group",):
+                    raise ValueError(f"Invalid dependency group item: {item}")
+
+                include_group = _normalize_name(next(iter(item.values())))
+                realized_group.extend(
+                    _resolve_dependency_group(
+                        dependency_groups, include_group, past_groups + (group,)
+                    )
+                )
+            else:
+                raise ValueError(f"Invalid dependency group item: {item}")
+
+        return realized_group
+
+
+    def resolve(dependency_groups: dict, group: str) -> list[str]:
+        if not isinstance(dependency_groups, dict):
+            raise TypeError("Dependency Groups table is not a dict")
+        if not isinstance(group, str):
+            raise TypeError("Dependency group name is not a str")
+        return _resolve_dependency_group(dependency_groups, group)
+
+
+    if __name__ == "__main__":
+        with open("pyproject.toml", "rb") as fp:
+            pyproject = tomllib.load(fp)
+
+        dependency_groups_raw = pyproject["dependency-groups"]
+        dependency_groups = _normalize_group_names(dependency_groups_raw)
+        print("\n".join(resolve(pyproject["dependency-groups"], sys.argv[1])))
+
+History
+=======
+
+- October 2024: This specification was approved through :pep:`735`.
diff --git a/source/specifications/section-distribution-metadata.rst b/source/specifications/section-distribution-metadata.rst
index 0c0a8aaba..af7c1c3e6 100644
--- a/source/specifications/section-distribution-metadata.rst
+++ b/source/specifications/section-distribution-metadata.rst
@@ -10,6 +10,7 @@ Package Distribution Metadata
    version-specifiers
    dependency-specifiers
    pyproject-toml
+   dependency-groups
    inline-script-metadata
    platform-compatibility-tags
    well-known-project-urls

From bb6f6cc042950bc052fe98bdba8768acd1b19563 Mon Sep 17 00:00:00 2001
From: Stephen Rosen 
Date: Mon, 16 Dec 2024 13:00:44 -0600
Subject: [PATCH 499/733] Refine dependency-groups documentation

This is a significant revision from the PEP content to make the
content appropriate for the packaging specs. In particular, the
following changes are made:

- references to "this PEP" are all removed
- "Dependency Object Specifiers" are a layer of indirection around
  includes, and are removed from the documentation -- instead, the doc
  jumps straight to the (only) specific case now: the includes
- the section on install UX and extras has been rewritten for brevity,
  removing the hypothetical example `pip` interface and folding
  together the install notes and the notes about extras
- the section on validation/linting has been reorganized around an
  example, and the note on linters has been moved to a `note`
  admonition block
---
 source/specifications/dependency-groups.rst | 154 +++++++++-----------
 1 file changed, 66 insertions(+), 88 deletions(-)

diff --git a/source/specifications/dependency-groups.rst b/source/specifications/dependency-groups.rst
index 8206a7063..b6a3e6fad 100644
--- a/source/specifications/dependency-groups.rst
+++ b/source/specifications/dependency-groups.rst
@@ -36,47 +36,33 @@ and a similar table which defines ``test`` and ``coverage`` groups::
 The ``[dependency-groups]`` Table
 ---------------------------------
 
-This PEP defines a new section (table) in ``pyproject.toml`` files named
+Dependency Groups are defined as a table in ``pyproject.toml`` named
 ``dependency-groups``. The ``dependency-groups`` table contains an arbitrary
 number of user-defined keys, each of which has, as its value, a list of
-requirements (defined below). These keys must be
-`valid non-normalized names `__,
-and must be
-`normalized `__
-before comparisons.
+requirements.
 
-Tools SHOULD prefer to present the original, non-normalized name to users by
-default. If duplicate names, after normalization, are encountered, tools SHOULD
-emit an error.
+``[dependency-groups]`` keys, sometimes also called "group names", must be
+:ref:`valid non-normalized names `. Tools which handle Dependency
+Groups MUST :ref:`normalize ` these names before
+comparisons.
 
-Requirement lists under ``dependency-groups`` may contain strings, tables
-("dicts" in Python), or a mix of strings and tables.
+Tools SHOULD prefer to present the original, non-normalized name to users, and
+if duplicate names are detected after normalization, tools SHOULD emit an
+error.
 
-Strings in requirement lists must be valid
-`Dependency Specifiers `__,
-as defined in :pep:`508`.
-
-Tables in requirement lists must be valid Dependency Object Specifiers.
-
-Dependency Object Specifiers
-----------------------------
-
-Dependency Object Specifiers are tables which define zero or more dependencies.
-
-This PEP standardizes only one type of Dependency Object Specifier, a
-"Dependency Group Include". Other types may be added in future standards.
+Requirement lists, the values in ``[dependency-groups]``, may contain strings,
+tables (``dict`` in Python), or a mix of strings and tables. Strings must be
+valid :ref:`dependency specifiers `, and tables must be
+valid Dependency Group Includes.
 
 Dependency Group Include
-''''''''''''''''''''''''
-
-A Dependency Group Include includes the dependencies of another Dependency
-Group in the current Dependency Group.
+------------------------
 
-An include is defined as a table with exactly one key, ``"include-group"``,
-whose value is a string, the name of another Dependency Group.
+A Dependency Group Include includes another Dependency Group in the current
+group.
 
-For example, ``{include-group = "test"}`` is an include which expands to the
-contents of the ``test`` Dependency Group.
+An include is a table with exactly one key, ``"include-group"``, whose value is
+a string, the name of another Dependency Group.
 
 Includes are defined to be exactly equivalent to the contents of the named
 Dependency Group, inserted into the current group at the location of the include.
@@ -84,94 +70,86 @@ For example, if ``foo = ["a", "b"]`` is one group, and
 ``bar = ["c", {include-group = "foo"}, "d"]`` is another, then ``bar`` should
 evaluate to ``["c", "a", "b", "d"]`` when Dependency Group Includes are expanded.
 
-Dependency Group Includes may specify the same package multiple times. Tools
-SHOULD NOT deduplicate or otherwise alter the list contents produced by the
+Dependency Group Includes may specify the same package multiple times.
+Tools SHOULD NOT deduplicate or otherwise alter the list contents produced by the
 include. For example, given the following table:
 
-.. code:: toml
+.. code-block:: toml
 
     [dependency-groups]
     group-a = ["foo"]
     group-b = ["foo>1.0"]
     group-c = ["foo<1.0"]
-    all = ["foo", {include-group = "group-a"}, {include-group = "group-b"}, {include-group = "group-c"}]
+    all = [
+        "foo",
+        {include-group = "group-a"},
+        {include-group = "group-b"},
+        {include-group = "group-c"},
+    ]
 
 The resolved value of ``all`` SHOULD be ``["foo", "foo", "foo>1.0", "foo<1.0"]``.
 Tools should handle such a list exactly as they would handle any other case in
 which they are asked to process the same requirement multiple times with
 different version constraints.
 
-Dependency Group Includes may include lists containing Dependency Group
-Includes, in which case those includes should be expanded as well. Dependency
-Group Includes MUST NOT include cycles, and tools SHOULD report an error if
-they detect a cycle.
+Dependency Group Includes may include groups containing Dependency Group Includes,
+in which case those includes should be expanded as well. Dependency Group Includes
+MUST NOT include cycles, and tools SHOULD report an error if they detect a cycle.
 
 Package Building
 ----------------
 
 Build backends MUST NOT include Dependency Group data in built distributions as
-package metadata. This means that PKG-INFO in sdists and METADATA in wheels
-do not include any referencable fields containing Dependency Groups.
-
-It is valid to use Dependency Groups in the evaluation of dynamic metadata, and
-``pyproject.toml`` files included in sdists will naturally still contain the
-``[dependency-groups]`` table. However, the table contents are not part of a
-published package's interfaces.
-
-Installing Dependency Groups
-----------------------------
-
-Tools which support Dependency Groups are expected to provide new options and
-interfaces to allow users to install from Dependency Groups.
-
-No syntax is defined for expressing the Dependency Group of a package, for two
-reasons:
+package metadata. This means that sdist ``PKG-INFO`` and wheel ``METADATA``
+files should not include referenceable fields containing Dependency Groups.
 
-* it would not be valid to refer to the Dependency Groups of a third-party
-  package from PyPI (because the data is defined to be unpublished)
+It is, however, valid to use Dependency Groups in the evaluation of dynamic
+metadata, and ``pyproject.toml`` files included in sdists will still contain
+``[dependency-groups]``. However, the table's contents are not part of a built
+package's interfaces.
 
-* there is not guaranteed to be a current package for Dependency Groups -- part
-  of their purpose is to support non-package projects
+Installing Dependency Groups & Extras
+-------------------------------------
 
-For example, a possible pip interface for installing Dependency Groups
-would be:
+There is no syntax or specification-defined interface for installing or
+referring to Dependency Groups. Tools are expected to provide dedicated
+interfaces for this purpose.
 
-.. code:: shell
-
-    pip install --dependency-groups=test,typing
-
-Note that this is only an example. This PEP does not declare any requirements
-for how tools support the installation of Dependency Groups.
-
-Overlapping Install UX with Extras
-''''''''''''''''''''''''''''''''''
-
-Tools MAY choose to provide the same interfaces for installing Dependency
-Groups as they do for installing extras.
-
-Note that this specification does not forbid having an extra whose name matches
-a Dependency Group.
-
-Users are advised to avoid creating Dependency Groups whose names match extras.
-Tools MAY treat such matching as an error.
+Tools MAY choose to provide the same or similar interfaces for interacting
+with Dependency Groups as they do for managing extras. Tools authors are
+advised that the specification does not forbid having an extra whose name
+matches a Dependency Group. Separately, users are advised to avoid creating
+Dependency Groups whose names match extras, and tools MAY treat such matching
+as an error.
 
 Validation and Compatibility
 ----------------------------
 
 Tools supporting Dependency Groups may want to validate data before using it.
-However, tools implementing such validation behavior should be careful to allow
-for future expansions to this spec, so that they do not unnecessarily emit
-errors or warnings in the presence of new syntax.
+When implementing such validation, authors should be aware of the possibility
+of future extensions to the specification, so that they do not unnecessarily
+emit errors or warnings.
 
 Tools SHOULD error when evaluating or processing unrecognized data in
 Dependency Groups.
 
-Tools SHOULD NOT eagerly validate the list contents of **all** Dependency
-Groups.
+Tools SHOULD NOT eagerly validate the contents of *all* Dependency Groups
+unless they have a need to do so.
+
+This means that in the presence of the following data, most tools should allow
+the ``foo`` group to be used and only error if the ``bar`` group is used:
+
+.. code-block:: toml
+
+    [dependency-groups]
+    foo = ["pyparsing"]
+    bar = [{set-phasers-to = "stun"}]
+
+.. note::
 
-This means that in the presence of the following data, most tools will allow
-the ``foo`` group to be used, and will only error when the ``bar`` group is
-used:
+    There are several known cases of tools which have good cause to be
+    stricter. Linters and validators are an example, as their purpose is to
+    validate the contents of all Dependency Groups.
 
 Reference Implementation
 ========================

From 5e4e015fb665cd7d2d748705a4266a702c30b046 Mon Sep 17 00:00:00 2001
From: Alex Tomkins 
Date: Sun, 22 Dec 2024 20:32:57 +0000
Subject: [PATCH 500/733] Use environment variables instead of contexts

Fixes potential issues found by zizmor: https://github.com/woodruffw/zizmor
---
 .../github-actions-ci-cd-sample/publish-to-test-pypi.yml  | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
index 152597d49..5c4b3edcf 100644
--- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
+++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
@@ -78,8 +78,8 @@ jobs:
         GITHUB_TOKEN: ${{ github.token }}
       run: >-
         gh release create
-        '${{ github.ref_name }}'
-        --repo '${{ github.repository }}'
+        "$GITHUB_REF_NAME"
+        --repo "$GITHUB_REPOSITORY"
         --notes ""
     - name: Upload artifact signatures to GitHub Release
       env:
@@ -89,8 +89,8 @@ jobs:
       # sigstore-produced signatures and certificates.
       run: >-
         gh release upload
-        '${{ github.ref_name }}' dist/**
-        --repo '${{ github.repository }}'
+        "$GITHUB_REF_NAME" dist/**
+        --repo "$GITHUB_REPOSITORY"
 
   publish-to-testpypi:
     name: Publish Python 🐍 distribution 📦 to TestPyPI

From 6a1376f1e2c823e969cf608f712dbfa6b3d6e64d Mon Sep 17 00:00:00 2001
From: Alex Tomkins 
Date: Sun, 22 Dec 2024 20:49:10 +0000
Subject: [PATCH 501/733] Don't persist GitHub credentials after checkout

Fixes potential issue found by zizmor: https://github.com/woodruffw/zizmor
---
 .../guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
index 5c4b3edcf..7051540ef 100644
--- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
+++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
@@ -9,6 +9,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
     - name: Set up Python
       uses: actions/setup-python@v5
       with:

From 085b29c2604695cfd7f30c47f220a98c0cbad69c Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan 
Date: Mon, 23 Dec 2024 13:02:10 +1000
Subject: [PATCH 502/733] Ignore PyPI anchors when checking links

Closes #1744
---
 source/conf.py | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index f08f6e836..c73dabdf2 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -141,11 +141,13 @@
     "https://anaconda.org",
 ]
 linkcheck_retries = 5
-# Ignore anchors for links to GitHub project pages -- GitHub adds anchors from
-# README.md headings through JavaScript, so Sphinx's linkcheck can't find them
-# in the HTML.
+# Ignore anchors for common targets when we know they likely won't be found
 linkcheck_anchors_ignore_for_url = [
+    # GitHub synthesises anchors in JavaScript, so Sphinx can't find them in the HTML
     r"https://github\.com/",
+    # While PyPI has its botscraping defenses active, Sphinx can't resolve the anchors
+    # https://github.com/pypa/packaging.python.org/issues/1744
+    r"https://pypi\.org/",
 ]
 
 # -- Options for extlinks ----------------------------------------------------------

From 8eb247b5501362eb763e5939c91b50aa54a1407b Mon Sep 17 00:00:00 2001
From: Dustin Ingram 
Date: Thu, 2 Jan 2025 18:23:49 +0000
Subject: [PATCH 503/733] Add and configure zizmor

---
 .github/workflows/zizmor.yml | 38 ++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 .github/workflows/zizmor.yml

diff --git a/.github/workflows/zizmor.yml b/.github/workflows/zizmor.yml
new file mode 100644
index 000000000..d99b6473c
--- /dev/null
+++ b/.github/workflows/zizmor.yml
@@ -0,0 +1,38 @@
+# From https://woodruffw.github.io/zizmor/usage/#use-in-github-actions
+
+name: GitHub Actions Security Analysis with zizmor 🌈
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  zizmor:
+    name: zizmor latest via PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      # required for workflows in private repositories
+      contents: read
+      actions: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Run zizmor 🌈
+        run: uvx zizmor --format sarif source/guides/github-actions-ci-cd-sample/* > results.sarif
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload SARIF file
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif
+          category: zizmor

From 5889433636e4e51a4ed54b0f9cd2ca63569d929d Mon Sep 17 00:00:00 2001
From: Gregory Bell 
Date: Sat, 4 Jan 2025 14:37:36 -0700
Subject: [PATCH 504/733] Correct typo in docs for project.scripts

---
 source/guides/writing-pyproject-toml.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index a497842a1..63aac1010 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -236,7 +236,7 @@ To install a command as part of your package, declare it in the
 
 In this example, after installing your project, a ``spam-cli`` command
 will be available. Executing this command will do the equivalent of
-``from spam import main_cli; main_cli()``.
+``from spam import main_cli; exit(main_cli())``.
 
 On Windows, scripts packaged this way need a terminal, so if you launch
 them from within a graphical application, they will make a terminal pop

From 1ce29502ec3d942267041f56ae69a2c191322e2d Mon Sep 17 00:00:00 2001
From: Dustin Ingram 
Date: Mon, 6 Jan 2025 16:46:49 -0500
Subject: [PATCH 505/733] Fix link with missing anchor tag

This page has changed significantly, linking to the entire page probably makes more sense instead now.
---
 source/guides/installing-scientific-packages.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst
index eded4fa5b..a1aeae567 100644
--- a/source/guides/installing-scientific-packages.rst
+++ b/source/guides/installing-scientific-packages.rst
@@ -89,7 +89,7 @@ SciPy distributions
 -------------------
 
 The SciPy site lists `several distributions
-`_
+`_
 that provide the full SciPy stack to
 end users in an easy to use and update format.
 

From e5fe84238d578a65d9cc1a64066877dc1ecaf231 Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Mon, 18 Nov 2024 13:58:21 +0100
Subject: [PATCH 506/733] Introduce licensing terms in Glossary

Copied and adapted from PEP 639.
---
 source/glossary.rst | 51 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/source/glossary.rst b/source/glossary.rst
index dc6211833..2ce4b1bfd 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -147,6 +147,40 @@ Glossary
         multiple individual distributions.
 
 
+    License Classifier
+
+        A PyPI Trove classifier
+        (as :ref:`described `
+        in the :term:`Core Metadata` specification)
+        which begins with ``License ::``.
+
+
+    License Expression
+    SPDX Expression
+
+        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)
+        and how they inter-relate.
+        Examples:
+        ``GPL-3.0-or-later``,
+        ``MIT AND (Apache-2.0 OR BSD-2-Clause)``
+
+
+    License Identifier
+    SPDX Identifier
+
+        A valid SPDX short-form license identifier,
+        originally specified in :pep:`639`.
+        This includes all valid SPDX identifiers and
+        the custom ``LicenseRef-[idstring]`` strings conforming to the
+        SPDX specification.
+        Examples:
+        ``MIT``,
+        ``GPL-3.0-only``,
+        ``LicenseRef-My-Custom-License``
+
+
     Module
 
         The basic unit of code reusability in Python, existing in one of two
@@ -313,6 +347,23 @@ Glossary
        docs on :ref:`pip:Requirements Files`.
 
 
+    Root License Directory
+    License Directory
+
+        The directory under which license files are stored in a
+        :term:`Project Source Tree`, :term:`Distribution Archive`
+        or :term:`Installed Project`.
+        For a :term:`Project Source Tree` or
+        :term:`Source Distribution (or "sdist")`, this is the
+        :term:`Project Root Directory`.
+        For a :term:`Built Distribution` or :term:`Installed Project`,
+        this is the :file:`.dist-info/licenses/` directory of
+        the wheel archive or project folder respectively.
+        Also, the root directory that paths
+        recorded in the ``License-File``
+        :term:`Core Metadata Field` are relative to.
+
+
     setup.py
     setup.cfg
 

From b55403272c274eef06f6003992c35a9358c5da06 Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Mon, 18 Nov 2024 14:56:02 +0100
Subject: [PATCH 507/733] Update pyproject.toml specification according to PEP
 639

Redefine the license key, add license-files, mention that license
classifiers are deprecated now.
---
 source/specifications/pyproject-toml.rst | 79 +++++++++++++++++++++---
 1 file changed, 71 insertions(+), 8 deletions(-)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 400e43105..7e575b9aa 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -138,6 +138,7 @@ The complete list of keys allowed in the ``[project]`` table are:
 - ``gui-scripts``
 - ``keywords``
 - ``license``
+- ``license-files``
 - ``maintainers``
 - ``name``
 - ``optional-dependencies``
@@ -236,16 +237,70 @@ The Python version requirements of the project.
 ``license``
 -----------
 
-- TOML_ type: table
+- TOML_ type: string
+- Corresponding :ref:`core metadata ` field:
+  :ref:`License-Expression `
+
+Text string that is a valid SPDX license expression as defined in :pep:`639`.
+Tools SHOULD validate and perform case normalization of the expression.
+
+The table subkeys of the ``license`` key are deprecated.
+
+
+``license-files``
+-----------------
+
+- TOML_ type: array of strings
 - Corresponding :ref:`core metadata ` field:
-  :ref:`License `
+  :ref:`License-Expression `
+
+An array specifying paths in the project source tree relative to the project
+root directory (i.e. directory containing :file:`pyproject.toml` or legacy project
+configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.)
+to file(s) containing licenses and other legal notices to be
+distributed with the package.
+
+The strings MUST contain valid glob patterns, as specified below:
 
-The table may have one of two keys. The ``file`` key has a string
-value that is a file path relative to ``pyproject.toml`` to the file
-which contains the license for the project. Tools MUST assume the
-file's encoding is UTF-8. The ``text`` key has a string value which is
-the license of the project.  These keys are mutually exclusive, so a
-tool MUST raise an error if the metadata specifies both keys.
+- Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots (``.``)
+  MUST be matched verbatim.
+
+- Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]``
+  containing only the verbatim matched characters MUST be supported.
+  Within ``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``,
+  order based on Unicode code points).
+  Hyphens at the start or end are matched literally.
+
+- Path delimiters MUST be the forward slash character (``/``).
+  Patterns are relative to the directory containing :file:`pyproject.toml`,
+  therefore the leading slash character MUST NOT be used.
+
+- Parent directory indicators (``..``) MUST NOT be used.
+
+Any characters or character sequences not covered by this specification are
+invalid. Projects MUST NOT use such values.
+Tools consuming this field SHOULD reject invalid values with an error.
+
+Tools MUST assume that license file content is valid UTF-8 encoded text,
+and SHOULD validate this and raise an error if it is not.
+
+Literal paths (e.g. :file:`LICENSE`) are valid globs which means they
+can also be defined.
+
+Build tools:
+
+- MUST treat each value as a glob pattern, and MUST raise an error if the
+  pattern contains invalid glob syntax.
+- MUST include all files matched by a listed pattern in all distribution
+  archives.
+- MUST list each matched file path under a License-File field in the
+  Core Metadata.
+- MUST raise an error if any individual user-specified pattern does not match
+  at least one file.
+
+If the ``license-files`` key is present and
+is set to a value of an empty array, then tools MUST NOT include any
+license files and MUST NOT raise an error.
 
 
 ``authors``/``maintainers``
@@ -309,6 +364,12 @@ The keywords for the project.
 
 Trove classifiers which apply to the project.
 
+The use of ``License ::`` classifiers is deprecated and tools MAY issue a
+warning informing users about that.
+Build tools MAY raise an error if both the ``license`` string value
+(translating to ``License-Expression`` metadata field) and the ``License ::``
+classifiers are used.
+
 
 ``urls``
 --------
@@ -450,6 +511,8 @@ History
 - November 2020: The specification of the ``[project]`` table was approved
   through :pep:`621`.
 
+- December 2024: The ``license`` key was redefined, the ``license-files`` key was
+  added and ``License::`` classifiers were deprecated through :pep:`639`.
 
 
 .. _TOML: https://toml.io

From b466436ad03bbe8446619b47e1069fef8acedeec Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Tue, 19 Nov 2024 09:41:48 +0100
Subject: [PATCH 508/733] Document inclusion of license files in the sdist per
 PEP 639

---
 source/specifications/source-distribution-format.rst | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst
index bae618df1..5e4d608b4 100644
--- a/source/specifications/source-distribution-format.rst
+++ b/source/specifications/source-distribution-format.rst
@@ -58,10 +58,15 @@ A ``.tar.gz`` source distribution (sdist) contains a single top-level directory
 called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the source files of
 the package. The name and version MUST match the metadata stored in the file.
 This directory must also contain a :file:`pyproject.toml` in the format defined in
-:ref:`pyproject-toml-spec`, and a ``PKG-INFO`` file containing
+:ref:`pyproject-toml-spec`, and a :file:`PKG-INFO` file containing
 metadata in the format described in the :ref:`core-metadata` specification. The
 metadata MUST conform to at least version 2.2 of the metadata specification.
 
+If the metadata version is 2.4 or greater, the source distribution MUST contain
+any license files specified by the ``License-File`` field in the :file:`PKG-INFO`
+at their respective paths relative to the root directory of the sdist
+(containing the :file:`pyproject.toml` and the :file:`PKG-INFO` metadata).
+
 No other content of a sdist is required or defined. Build systems can store
 whatever information they need in the sdist to build the project.
 
@@ -150,3 +155,5 @@ History
   :pep:`625`.
 * August 2023: Source distribution archive features were standardized through
   :pep:`721`.
+* December 2024: License files inclusion into source distribution was standardized
+  through :pep:`639`.

From f999ef0a220b23ac1c6f5041a43bd682f1aad6af Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Tue, 19 Nov 2024 11:50:44 +0100
Subject: [PATCH 509/733] Document inclusion of license files in the
 .dist-info/licenses per PEP 639
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 .../specifications/binary-distribution-format.rst   | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index 68f62639d..be21aedcd 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -182,6 +182,7 @@ its version, e.g. ``1.0.0``, consist of:
    ``purelib`` or ``platlib`` as specified in ``WHEEL``.  ``purelib`` and
    ``platlib`` are usually both ``site-packages``.
 #. ``{distribution}-{version}.dist-info/`` contains metadata.
+#. :file:`{distribution}-{version}.dist-info/licenses/` contains license files.
 #. ``{distribution}-{version}.data/`` contains one subdirectory
    for each non-empty install scheme key not already covered, where
    the subdirectory name is an index into a dictionary of install paths
@@ -250,6 +251,16 @@ The .dist-info directory
    mentioned and correctly hashed in RECORD.
 
 
+The :file:`.dist-info/licenses/` directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the metadata version is 2.4 or greater and one or more ``License-File``
+fields is specified, the :file:`.dist-info/` directory MUST contain a
+:file:`licenses/` subdirectory, which MUST contain the files listed in the
+``License-File`` fields in the :file:`METADATA` file at their respective paths
+relative to the :file:`licenses/` directory.
+
+
 The .data directory
 ^^^^^^^^^^^^^^^^^^^
 
@@ -427,6 +438,8 @@ History
   regular files (the expected behaviour of consuming tools when encountering
   symlinks or subdirectories in this folder is not formally defined, and hence
   may vary between tools).
+- December 2024: The :file:`.dist-info/licenses/` directory was specified through
+  :pep:`639`.
 
 
 Appendix

From cdf84bacf4ba20ff29af8ef080ea1bf345be13c5 Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Tue, 19 Nov 2024 12:58:10 +0100
Subject: [PATCH 510/733] Document how to install .dist-info/licenses per PEP
 639
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 .../recording-installed-packages.rst          | 20 ++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst
index ee8e69f79..9e01ef6f1 100644
--- a/source/specifications/recording-installed-packages.rst
+++ b/source/specifications/recording-installed-packages.rst
@@ -66,6 +66,11 @@ The ``METADATA`` file is mandatory.
 All other files may be omitted at the installing tool's discretion.
 Additional installer-specific files may be present.
 
+This :file:`.dist-info/` directory may contain the following directory, described in
+detail below:
+
+* :file:`licenses/`: contains license files.
+
 .. note::
 
    The :ref:`binary-distribution-format` specification describes additional
@@ -144,7 +149,7 @@ Here is an example snippet of a possible ``RECORD`` file::
     __pycache__/black.cpython-38.pyc,,
     __pycache__/blackd.cpython-38.pyc,,
     black-19.10b0.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
-    black-19.10b0.dist-info/LICENSE,sha256=nAQo8MO0d5hQz1vZbhGqqK_HLUqG1KNiI9erouWNbgA,1080
+    black-19.10b0.dist-info/licenses/LICENSE,sha256=nAQo8MO0d5hQz1vZbhGqqK_HLUqG1KNiI9erouWNbgA,1080
     black-19.10b0.dist-info/METADATA,sha256=UN40nGoVVTSpvLrTBwNsXgZdZIwoKFSrrDDHP6B7-A0,58841
     black-19.10b0.dist-info/RECORD,,
     black.py,sha256=45IF72OgNfF8WpeNHnxV2QGfbCLubV5Xjl55cI65kYs,140161
@@ -219,6 +224,17 @@ of requirement (i.e. name plus version specifier).
 Its detailed specification is at :ref:`direct-url`.
 
 
+The :file:`licenses/` subdirectory
+==================================
+
+If the metadata version is 2.4 or greater and one or more ``License-File``
+fields is specified, the :file:`.dist-info/` directory MUST contain a :file:`licenses/`
+subdirectory which MUST contain the files listed in the ``License-File`` fields in
+the :file:`METADATA` file at their respective paths relative to the
+:file:`licenses/` directory.
+Any files in this directory MUST be copied from wheels by the install tools.
+
+
 Intentionally preventing changes to installed packages
 ======================================================
 
@@ -259,3 +275,5 @@ History
   for the full definition.
 - September 2020: Various amendments and clarifications were approved through
   :pep:`627`.
+- December 2024: The :file:`.dist-info/licenses/` directory was specified through
+  :pep:`639`.

From a8f6ba6c2b691e6d2d4047bda6c669686a485359 Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Tue, 19 Nov 2024 15:13:34 +0100
Subject: [PATCH 511/733] Update the Writing pyproject.toml guide with new
 licensing guidelines

---
 source/guides/writing-pyproject-toml.rst | 61 ++++++++++++++++++------
 1 file changed, 47 insertions(+), 14 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index a497842a1..dd962d5f1 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -324,26 +324,59 @@ You can also specify the format explicitly, like this:
 ``license``
 -----------
 
-This can take two forms. You can put your license in a file, typically
-``LICENSE`` or ``LICENSE.txt``, and link that file here:
+This is a valid :term:`SPDX license expression ` consisting
+of one or more :term:`license identifiers `.
+The full license list is available at the
+`SPDX license list page `_. The supported list version is
+3.17 or any later compatible one.
 
 .. code-block:: toml
 
     [project]
-    license = {file = "LICENSE"}
+    license = "GPL-3.0-or-later"
+    # or
+    license = "MIT AND (Apache-2.0 OR BSD-2-Clause)"
 
-or you can write the name of the license:
+As a general rule, it is a good idea to use a standard, well-known
+license, both to avoid confusion and because some organizations avoid software
+whose license is unapproved.
+
+If your project is licensed with a license that doesn't have an existing SPDX
+identifier, you can create a custom one in format ``LicenseRef-[idstring]``.
+The custom identifiers must follow the SPDX specification,
+`clause 10.1 `_ of the version 2.2 or any later compatible one.
 
 .. code-block:: toml
 
     [project]
-    license = {text = "MIT License"}
+    license = "LicenseRef-My-Custom-License"
 
-If you are using a standard, well-known license, it is not necessary to use this
-field. Instead, you should use one of the :ref:`classifiers` starting with ``License
-::``. (As a general rule, it is a good idea to use a standard, well-known
-license, both to avoid confusion and because some organizations avoid software
-whose license is unapproved.)
+
+``license-files``
+-----------------
+
+This is a list of license files and files containing other legal
+information you want to distribute with your package.
+
+.. code-block:: toml
+
+    [project]
+    license-files = ["LICEN[CS]E*", "vendored/licenses/*.txt", "AUTHORS.md"]
+
+The glob patterns must follow the specification:
+
+- Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots (``.``)
+  will be matched verbatim.
+- Special characters: ``*``, ``?``, ``**`` and character ranges: [] are supported.
+- Path delimiters must be the forward slash character (``/``).
+- Patterns are relative to the directory containing :file:`pyproject.toml`, and
+  thus may not start with a slash character.
+- Parent directory indicators (``..``) must not be used.
+- Each glob must match at least one file.
+
+Literal paths are valid globs.
+Any characters or character sequences not covered by this specification are
+invalid.
 
 
 ``keywords``
@@ -379,9 +412,6 @@ A list of PyPI classifiers that apply to your project. Check the
       "Intended Audience :: Developers",
       "Topic :: Software Development :: Build Tools",
 
-      # Pick your license as you wish (see also "license" above)
-      "License :: OSI Approved :: MIT License",
-
       # Specify the Python versions you support here.
       "Programming Language :: Python :: 3",
       "Programming Language :: Python :: 3.6",
@@ -498,7 +528,8 @@ A full example
    ]
    description = "Lovely Spam! Wonderful Spam!"
    readme = "README.rst"
-   license = {file = "LICENSE.txt"}
+   license = "MIT"
+   license-files = ["LICEN[CS]E.*"]
    keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
    classifiers = [
      "Development Status :: 4 - Beta",
@@ -545,3 +576,5 @@ A full example
 .. _pytest: https://pytest.org
 .. _pygments: https://pygments.org
 .. _rest: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+.. _spdxcustomids: https://spdx.github.io/spdx-spec/v2.2.2/other-licensing-information-detected/
+.. _spdxlicenselist: https://spdx.org/licenses/

From dd5ed07f3ceea67e396e182d516af5d29d6d92e2 Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Tue, 19 Nov 2024 15:32:08 +0100
Subject: [PATCH 512/733] Add the licensing examples and user scenarios
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adapted from:
- https://peps.python.org/pep-0639/appendix-examples/
- https://peps.python.org/pep-0639/appendix-user-scenarios/

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 .../licensing-examples-and-user-scenarios.rst | 356 ++++++++++++++++++
 source/guides/section-build-and-publish.rst   |   1 +
 2 files changed, 357 insertions(+)
 create mode 100644 source/guides/licensing-examples-and-user-scenarios.rst

diff --git a/source/guides/licensing-examples-and-user-scenarios.rst b/source/guides/licensing-examples-and-user-scenarios.rst
new file mode 100644
index 000000000..5b05d97ea
--- /dev/null
+++ b/source/guides/licensing-examples-and-user-scenarios.rst
@@ -0,0 +1,356 @@
+.. _licensing-examples-and-user-scenarios:
+
+
+=====================================
+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.
+This document aims to provide clear guidance how to migrate from the legacy
+to the standardized way of declaring licenses.
+
+
+Licensing Examples
+==================
+
+.. _licensing-example-basic:
+
+Basic example
+-------------
+
+The Setuptools project itself, as of `version 75.6.0 `__,
+does not use the ``License`` field in its own project source metadata.
+Further, it no longer explicitly specifies ``license_file``/``license_files``
+as it did previously, since Setuptools relies on its own automatic
+inclusion of license-related files matching common patterns,
+such as the :file:`LICENSE` file it uses.
+
+It includes the following license-related metadata in its
+:file:`pyproject.toml`:
+
+.. code-block:: toml
+
+    [project]
+    classifiers = [
+        "License :: OSI Approved :: MIT License"
+    ]
+
+The simplest migration to PEP 639 would consist of using this instead:
+
+.. code-block:: toml
+
+    [project]
+    license = "MIT"
+
+Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:
+
+.. code-block:: ini
+
+    [metadata]
+    license = MIT
+
+The output Core Metadata for the distribution packages would then be:
+
+.. code-block:: email
+
+    License-Expression: MIT
+    License-File: LICENSE
+
+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.
+
+
+.. _licensing-example-advanced:
+
+Advanced example
+----------------
+
+Suppose Setuptools were to include the licenses of the third-party projects
+that are vendored in the :file:`setuptools/_vendor/` and :file:`pkg_resources/_vendor/`
+directories; specifically:
+
+.. code-block:: text
+
+    packaging==21.2
+    pyparsing==2.2.1
+    ordered-set==3.1.1
+    more_itertools==8.8.0
+
+The license expressions for these projects are:
+
+.. code-block:: text
+
+    packaging: Apache-2.0 OR BSD-2-Clause
+    pyparsing: MIT
+    ordered-set: MIT
+    more_itertools: MIT
+
+A comprehensive license expression covering both Setuptools
+proper and its vendored dependencies would contain these metadata,
+combining all the license expressions into one. Such an expression might be:
+
+.. code-block:: text
+
+    MIT AND (Apache-2.0 OR BSD-2-Clause)
+
+In addition, per the requirements of the licenses, the relevant license files
+must be included in the package. Suppose the :file:`LICENSE` file contains the text
+of the MIT license and the copyrights used by Setuptools, ``pyparsing``,
+``more_itertools`` and ``ordered-set``; and the :file:`LICENSE*` files in the
+:file:`setuptools/_vendor/packaging/` directory contain the Apache 2.0 and
+2-clause BSD license text, and the Packaging copyright statement and
+`license choice notice `__.
+
+Specifically, we assume the license files are located at the following
+paths in the project source tree (relative to the project root and
+:file:`pyproject.toml`):
+
+.. code-block:: text
+
+    LICENSE
+    setuptools/_vendor/packaging/LICENSE
+    setuptools/_vendor/packaging/LICENSE.APACHE
+    setuptools/_vendor/packaging/LICENSE.BSD
+
+Putting it all together, our :file:`pyproject.toml` would be:
+
+.. code-block:: toml
+
+    [project]
+    license = "MIT AND (Apache-2.0 OR BSD-2-Clause)"
+    license-files = [
+        "LICENSE*",
+        "setuptools/_vendor/LICENSE*",
+    ]
+
+Or alternatively, the license files can be specified explicitly (paths will be
+interpreted as glob patterns):
+
+.. code-block:: toml
+
+    [project]
+    license = "MIT AND (Apache-2.0 OR BSD-2-Clause)"
+    license-files = [
+        "LICENSE",
+        "setuptools/_vendor/LICENSE",
+        "setuptools/_vendor/LICENSE.APACHE",
+        "setuptools/_vendor/LICENSE.BSD",
+    ]
+
+If our project used :file:`setup.cfg`, we could define this in :
+
+.. code-block:: ini
+
+    [metadata]
+    license = MIT AND (Apache-2.0 OR BSD-2-Clause)
+    license_files =
+        LICENSE
+        setuptools/_vendor/packaging/LICENSE
+        setuptools/_vendor/packaging/LICENSE.APACHE
+        setuptools/_vendor/packaging/LICENSE.BSD
+
+With either approach, the output Core Metadata in the distribution
+would be:
+
+.. code-block:: email
+
+    License-Expression: MIT AND (Apache-2.0 OR BSD-2-Clause)
+    License-File: LICENSE
+    License-File: setuptools/_vendor/packaging/LICENSE
+    License-File: setuptools/_vendor/packaging/LICENSE.APACHE
+    License-File: setuptools/_vendor/packaging/LICENSE.BSD
+
+In the resulting sdist, with :file:`/` as the root of the archive and ``{VERSION}``
+the version of the Setuptools release specified in the Core Metadata,
+the license files would be located at the paths:
+
+.. code-block:: text
+
+    /setuptools-{VERSION}/LICENSE
+    /setuptools-{VERSION}/setuptools/_vendor/packaging/LICENSE
+    /setuptools-{VERSION}/setuptools/_vendor/packaging/LICENSE.APACHE
+    /setuptools-{VERSION}/setuptools/_vendor/packaging/LICENSE.BSD
+
+In the built wheel, with :file:`/` being the root of the archive and
+``{VERSION}`` as the previous, the license files would be stored at:
+
+.. code-block:: text
+
+    /setuptools-{VERSION}.dist-info/licenses/LICENSE
+    /setuptools-{VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE
+    /setuptools-{VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.APACHE
+    /setuptools-{VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.BSD
+
+Finally, in the installed project, with :file:`site-packages/` being the site dir
+and ``{VERSION}`` as the previous, the license files would be installed to:
+
+.. code-block:: text
+
+    site-packages/setuptools-{VERSION}.dist-info/licenses/LICENSE
+    site-packages/setuptools-{VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE
+    site-packages/setuptools-{VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.APACHE
+    site-packages/setuptools-{VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.BSD
+
+
+Expression examples
+'''''''''''''''''''
+
+Some additional examples of valid ``License-Expression`` values:
+
+.. code-block:: email
+
+    License-Expression: MIT
+    License-Expression: BSD-3-Clause
+    License-Expression: MIT AND (Apache-2.0 OR BSD-2-Clause)
+    License-Expression: MIT OR GPL-2.0-or-later OR (FSFUL AND BSD-2-Clause)
+    License-Expression: GPL-3.0-only WITH Classpath-Exception-2.0 OR BSD-3-Clause
+    License-Expression: LicenseRef-Public-Domain OR CC0-1.0 OR Unlicense
+    License-Expression: LicenseRef-Proprietary
+    License-Expression: LicenseRef-Custom-License
+
+
+User Scenarios
+==============
+
+The following covers the range of common use cases from a user perspective,
+providing guidance for each. Do note that the following
+should **not** be considered legal advice, and readers should consult a
+licensed legal practitioner in their jurisdiction if they are unsure about
+the specifics for their situation.
+
+
+I have a private package that won't be distributed
+--------------------------------------------------
+
+If your package isn't shared publicly, i.e. outside your company,
+organization or household, it *usually* isn't strictly necessary to include
+a formal license, so you wouldn't necessarily have to do anything extra here.
+
+However, it is still a good idea to include ``LicenseRef-Proprietary``
+as a license expression in your package configuration, and/or a
+copyright statement and any legal notices in a :file:`LICENSE.txt` file
+in the root of your project directory, which will be automatically
+included by packaging tools.
+
+
+I just want to share my own work without legal restrictions
+-----------------------------------------------------------
+
+While you aren't required to include a license, if you don't, no one has
+`any permission to download, use or improve your work `__,
+so that's probably the *opposite* of what you actually want.
+The `MIT license `__ is a great choice instead, as it's simple,
+widely used and allows anyone to do whatever they want with your work
+(other than sue you, which you probably also don't want).
+
+To apply it, just paste `the text `__ into a file named
+:file:`LICENSE.txt` at the root of your repo, and add the year and your name to
+the copyright line. Then, just add ``license = "MIT"`` under
+``[project]`` in your :file:`pyproject.toml` if your packaging tool supports it,
+or in its config file/section. You're done!
+
+
+I want to distribute my project under a specific license
+--------------------------------------------------------
+
+To use a particular license, simply paste its text into a :file:`LICENSE.txt`
+file at the root of your repo, if you don't have it in a file starting with
+:file:`LICENSE` or :file:`COPYING` already, and add
+``license = "LICENSE-ID"`` under ``[project]`` in your
+:file:`pyproject.toml` if your packaging tool supports it, or else in its
+config file. You can find the ``LICENSE-ID``
+and copyable license text on sites like
+`ChooseALicense `__ or `SPDX `__.
+
+Many popular code hosts, project templates and packaging tools can add the
+license file for you, and may support the expression as well in the future.
+
+
+I maintain an existing package that's already licensed
+------------------------------------------------------
+
+If you already have license files and metadata in your project, you
+should only need to make a couple of tweaks to take advantage of the new
+functionality.
+
+In your project config file, enter your license expression under
+``license`` (``[project]`` table in :file:`pyproject.toml`),
+or the equivalent for your packaging tool,
+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 `__ for the identifier
+that matches the license used in your project.
+
+Make sure to list your license files under ``license-files``
+under ``[project]`` in :file:`pyproject.toml`
+or else in your tool's configuration file.
+
+See the :ref:`licensing-example-basic` for a simple but complete real-world demo
+of how this works in practice.
+See also the best-effort guidance on how to translate license classifiers
+into license expression provided by the :pep:`639` authors:
+`Mapping License Classifiers to SPDX Identifiers `__.
+Packaging tools may support automatically converting legacy licensing
+metadata; check your tool's documentation for more information.
+
+
+My package includes other code under different licenses
+-------------------------------------------------------
+
+If your project includes code from others covered by different licenses,
+such as vendored dependencies or files copied from other open source
+software, you can construct a license expression
+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.
+
+In your project config file, enter your license expression under
+``license`` (``[project]`` table of :file:`pyproject.toml`),
+or the equivalent for your packaging tool,
+and make sure to remove any legacy ``license`` table subkeys
+or ``License ::`` classifiers.
+
+Also, make sure you add the full license text of all the licenses as files
+somewhere in your project repository. List the
+relative path or glob patterns to each of them under ``license-files``
+under ``[project]`` in :file:`pyproject.toml`
+(if your tool supports it), or else in your tool's configuration file.
+
+As an example, if your project was licensed MIT but incorporated
+a vendored dependency (say, ``packaging``) that was licensed under
+either Apache 2.0 or the 2-clause BSD, your license expression would
+be ``MIT AND (Apache-2.0 OR BSD-2-Clause)``. You might have a
+:file:`LICENSE.txt` in your repo root, and a :file:`LICENSE-APACHE.txt` and
+:file:`LICENSE-BSD.txt` in the :file:`_vendor/` subdirectory, so to include
+all of them, you'd specify ``["LICENSE.txt", "_vendor/packaging/LICENSE*"]``
+as glob patterns, or
+``["LICENSE.txt", "_vendor/LICENSE-APACHE.txt", "_vendor/LICENSE-BSD.txt"]``
+as literal file paths.
+
+See a fully worked out :ref:`licensing-example-advanced` for an end-to-end
+application of this to a real-world complex project, with many technical
+details, and consult a `tutorial `__ for more help and examples
+using SPDX identifiers and expressions.
+
+
+.. _chooseamitlicense: https://choosealicense.com/licenses/mit/
+.. _choosealicenselist: https://choosealicense.com/licenses/
+.. _dontchoosealicense: https://choosealicense.com/no-permission/
+.. _mappingclassifierstospdx: https://peps.python.org/pep-0639/appendix-mapping-classifiers/
+.. _packaginglicense: https://github.com/pypa/packaging/blob/21.2/LICENSE
+.. _setuptools7560: https://github.com/pypa/setuptools/blob/v75.6.0/pyproject.toml
+.. _spdxlist: https://spdx.org/licenses/
+.. _spdxtutorial: https://github.com/david-a-wheeler/spdx-tutorial
diff --git a/source/guides/section-build-and-publish.rst b/source/guides/section-build-and-publish.rst
index eb10c389f..52f827553 100644
--- a/source/guides/section-build-and-publish.rst
+++ b/source/guides/section-build-and-publish.rst
@@ -16,3 +16,4 @@ Building and Publishing
    making-a-pypi-friendly-readme
    publishing-package-distribution-releases-using-github-actions-ci-cd-workflows
    modernize-setup-py-project
+   licensing-examples-and-user-scenarios

From 32d55c847afd46c300fd4e256067b7e4b923c939 Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Tue, 26 Nov 2024 12:53:51 +0100
Subject: [PATCH 513/733] Update the packaging tutorial according to PEP 639

---
 source/tutorials/packaging-projects.rst | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 93826321d..9357fdfa2 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -213,9 +213,10 @@ following this tutorial.
     requires-python = ">=3.8"
     classifiers = [
         "Programming Language :: Python :: 3",
-        "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
     ]
+    license = "MIT"
+    license-files = ["LICEN[CS]E*"]
 
     [project.urls]
     Homepage = "https://github.com/pypa/sampleproject"
@@ -242,11 +243,15 @@ following this tutorial.
   packages until it finds one that has a matching Python version.
 - ``classifiers`` gives the index and :ref:`pip` some additional metadata
   about your package. In this case, the package is only compatible with Python
-  3, is licensed under the MIT license, and is OS-independent. You should
-  always include at least which version(s) of Python your package works on,
-  which license your package is available under, and which operating systems
+  3 and is OS-independent. You should
+  always include at least which version(s) of Python your package works on
+  and which operating systems
   your package will work on. For a complete list of classifiers, see
   https://pypi.org/classifiers/.
+- ``license`` is the :term:`SPDX license expression ` of
+  your package.
+- ``license-files`` is the list of glob paths to the license files,
+  relative to the directory where :file:`pyproject.toml` is located.
 - ``urls`` lets you list any number of extra links to show on PyPI.
   Generally this could be to the source, documentation, issue trackers, etc.
 
@@ -305,6 +310,9 @@ MIT license:
 
 Most build backends automatically include license files in packages. See your
 backend's documentation for more details.
+If you include the path to license in the ``license-files`` key of
+:file:`pyproject.toml`, and your build backend supports :pep:`639`,
+the file will be automatically included in the package.
 
 
 Including other files

From 0fba2a92f158ff9553e5f0c71d87c3c20619f10c Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Fri, 13 Dec 2024 18:26:17 +0100
Subject: [PATCH 514/733] When license-files are not defined, tools are free to
 choose

---
 source/specifications/pyproject-toml.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 7e575b9aa..c82fdd936 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -301,6 +301,9 @@ Build tools:
 If the ``license-files`` key is present and
 is set to a value of an empty array, then tools MUST NOT include any
 license files and MUST NOT raise an error.
+If the ``license-files`` key is not defined, tools can decide how to handle
+license files. For example they can choose not to include any files or use
+their own logic to discover the appropriate files in the distribution.
 
 
 ``authors``/``maintainers``

From 27e9e5d0e342a3491e691c3671e96536c8bf73aa Mon Sep 17 00:00:00 2001
From: Julian Berman 
Date: Tue, 7 Jan 2025 10:17:57 -0500
Subject: [PATCH 515/733] Minor fix to a missing in the inline script metadata
 doc.

---
 source/specifications/inline-script-metadata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/inline-script-metadata.rst b/source/specifications/inline-script-metadata.rst
index f40b9ac4a..6fa832a3e 100644
--- a/source/specifications/inline-script-metadata.rst
+++ b/source/specifications/inline-script-metadata.rst
@@ -79,7 +79,7 @@ script metadata (dependency data and tool configuration).
 This document MAY include the top-level fields ``dependencies`` and ``requires-python``,
 and MAY optionally include a ``[tool]`` table.
 
-The ``[tool]`` MAY be used by any tool, script runner or otherwise, to configure
+The ``[tool]`` table MAY be used by any tool, script runner or otherwise, to configure
 behavior. It has the same semantics as the :ref:`[tool] table in pyproject.toml
 `.
 

From 98216cf9f70fc98d40beb0f106d7f9357c6a0e43 Mon Sep 17 00:00:00 2001
From: Gregory Bell 
Date: Tue, 7 Jan 2025 12:52:13 -0700
Subject: [PATCH 516/733] Update writing-pyproject-toml.rst

---
 source/guides/writing-pyproject-toml.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 63aac1010..636429abb 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -236,7 +236,7 @@ To install a command as part of your package, declare it in the
 
 In this example, after installing your project, a ``spam-cli`` command
 will be available. Executing this command will do the equivalent of
-``from spam import main_cli; exit(main_cli())``.
+``import sys; from spam import main_cli; sys.exit(main_cli())``.
 
 On Windows, scripts packaged this way need a terminal, so if you launch
 them from within a graphical application, they will make a terminal pop

From 26fb5aa44cb6ecbfb4ee860c27efdeb99a4fb8cb Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Tue, 7 Jan 2025 15:58:13 -0800
Subject: [PATCH 517/733] Add labels to dependency-specifiers.rst for
 cross-referencing

---
 source/specifications/dependency-specifiers.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index d6713f713..06897da27 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -128,6 +128,8 @@ Whitespace
 Non line-breaking whitespace is mostly optional with no semantic meaning. The
 sole exception is detecting the end of a URL requirement.
 
+.. _dependency-specifiers-names:
+
 Names
 -----
 
@@ -142,6 +144,8 @@ with re.IGNORECASE) is::
 
     ^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$
 
+.. _dependency-specifiers-extras:
+
 Extras
 ------
 
@@ -159,6 +163,8 @@ are listed in the "security" extra of requests.
 
 If multiple extras are listed, all the dependencies are unioned together.
 
+.. _dependency-specifiers-versions:
+
 Versions
 --------
 
@@ -170,6 +176,8 @@ via a URL. Version comparison are also used in the markers feature. The
 optional brackets around a version are present for compatibility with
 :pep:`345` but should not be generated, only accepted.
 
+.. _dependency-specifiers-environment-markers:
+
 Environment Markers
 -------------------
 
@@ -294,6 +302,8 @@ The ``implementation_version`` marker variable is derived from
 This environment markers section, initially defined through :pep:`508`, supersedes the environment markers
 section in :pep:`345`.
 
+.. _dependency-specifiers-grammar:
+
 Complete Grammar
 ================
 

From 05fb0b06f51c5602f68b89cd4af152d3c516ffb5 Mon Sep 17 00:00:00 2001
From: Ilya Popov 
Date: Wed, 8 Jan 2025 12:11:53 +0100
Subject: [PATCH 518/733] Add a note that Poetry supports [project] now

Fixes #1771
---
 source/guides/writing-pyproject-toml.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 636429abb..b86d11827 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -29,8 +29,9 @@ three possible TOML tables in this file.
    On the other hand, the ``[project]`` table is understood by *most* build
    backends, but some build backends use a different format.
 
-   As of August 2024, Poetry_ is a notable build backend that does not use
-   the ``[project]`` table, it uses the ``[tool.poetry]`` table instead.
+   A notable exception is Poetry_, which before version 2.0 (released January
+   5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]``
+   table instead. With version 2.0, it supports both.
    Also, the setuptools_ build backend supports both the ``[project]`` table,
    and the older format in ``setup.cfg`` or ``setup.py``.
 

From 1f6b6ad4eb05e99df50fe04f905ceae82cfaed8b Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Wed, 8 Jan 2025 13:54:37 -0800
Subject: [PATCH 519/733] Add labels to source-distribution-format.rst for
 cross-referencing

Specifically cover source trees and sdist as files.
---
 source/specifications/source-distribution-format.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst
index bae618df1..a1c310244 100644
--- a/source/specifications/source-distribution-format.rst
+++ b/source/specifications/source-distribution-format.rst
@@ -20,6 +20,8 @@ specification.
 
 Source distributions are also known as *sdists* for short.
 
+.. _source-distribution-format-source-tree:
+
 Source trees
 ============
 
@@ -30,6 +32,8 @@ directories. :pep:`517` and :pep:`518` specify what is required to meet the
 definition of what :file:`pyproject.toml` must contain for something to be
 deemed a source tree.
 
+.. _source-distribution-format-sdist:
+
 Source distribution file name
 =============================
 

From 51487e890322197ad15c305fc175dd49d2dea012 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Wed, 8 Jan 2025 14:00:42 -0800
Subject: [PATCH 520/733] Add labels to direct-url-data-structure.rst for
 cross-referencing

---
 source/specifications/direct-url-data-structure.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index 6a4e8fe01..0d243652d 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -49,6 +49,8 @@ Additionally, the user:password section of the URL MAY be a
 well-known, non security sensitive string. A typical example is ``git``
 in the case of a URL such as ``ssh://git@gitlab.com/user/repo``.
 
+.. _direct-url-data-structure-vcs:
+
 VCS URLs
 --------
 
@@ -72,6 +74,8 @@ as a dictionary with the following keys:
   ``commit_id`` in order to reference an immutable
   version of the source code.
 
+.. _direct-url-data-structure-archive:
+
 Archive URLs
 ------------
 
@@ -104,6 +108,8 @@ When both the ``hash`` and ``hashes`` keys are present, the hash represented in
 ``hash`` key MUST also be present in the ``hashes`` dictionary, so consumers can
 consider the ``hashes`` key only if it is present, and fall back to ``hash`` otherwise.
 
+.. _direct-url-data-structure-local-directory:
+
 Local directories
 -----------------
 
@@ -118,6 +124,8 @@ be compliant with :rfc:`8089`. In
 particular, the path component must be absolute. Symbolic links SHOULD be
 preserved when making relative paths absolute.
 
+.. _direct-url-data-structure-subdirectories:
+
 Projects in subdirectories
 --------------------------
 
@@ -125,6 +133,8 @@ A top-level ``subdirectory`` field MAY be present containing a directory path,
 relative to the root of the VCS repository, source archive or local directory,
 to specify where ``pyproject.toml`` or ``setup.py`` is located.
 
+.. _direct-url-data-structure-registered-vcs:
+
 Registered VCS
 ==============
 

From 499a91dbb0e0448947660e6936949ec229e68890 Mon Sep 17 00:00:00 2001
From: Dustin Ingram 
Date: Tue, 14 Jan 2025 15:25:29 +0000
Subject: [PATCH 521/733] Update Dynamic specification to include deprecated
 fields

---
 source/specifications/core-metadata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index c1ce528e7..316736ff0 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -110,7 +110,7 @@ Dynamic (multiple use)
 
 A string containing the name of another core metadata field. The field
 names ``Name``, ``Version``, and ``Metadata-Version`` may not be specified
-in this field.
+in this field. Deprecated fields MAY be specified in this field.
 
 When found in the metadata of a source distribution, the following
 rules apply:

From 8c9fb25dd07c41e0edb14e1fac40a3d1d5d56a57 Mon Sep 17 00:00:00 2001
From: Dustin Ingram 
Date: Tue, 14 Jan 2025 17:28:16 +0000
Subject: [PATCH 522/733] Revert "Update Dynamic specification to include
 deprecated fields"

This reverts commit 499a91dbb0e0448947660e6936949ec229e68890.
---
 source/specifications/core-metadata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 316736ff0..c1ce528e7 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -110,7 +110,7 @@ Dynamic (multiple use)
 
 A string containing the name of another core metadata field. The field
 names ``Name``, ``Version``, and ``Metadata-Version`` may not be specified
-in this field. Deprecated fields MAY be specified in this field.
+in this field.
 
 When found in the metadata of a source distribution, the following
 rules apply:

From 8dfac8d1f0a811987f84966ce737a8f253de7da0 Mon Sep 17 00:00:00 2001
From: Dustin Ingram 
Date: Tue, 14 Jan 2025 17:29:14 +0000
Subject: [PATCH 523/733] Add a definition of 'deprecated' instead

---
 source/specifications/core-metadata.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index c1ce528e7..422d30cd4 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -800,6 +800,10 @@ Deprecated Fields
 .. _home-page-optional:
 .. _core-metadata-home-page:
 
+Deprecated fields are valid metadata fields for any metadata version. Tools
+MUST attempt to convert deprecated fields to non-deprecated fields when
+appropriate. Tools SHOULD warn users when deprecated fields are used.
+
 Home-page
 ---------
 

From f2904b3d752daba59b834c7005e3631285135ef9 Mon Sep 17 00:00:00 2001
From: Dustin Ingram 
Date: Tue, 14 Jan 2025 17:43:27 +0000
Subject: [PATCH 524/733] Don't require conversion

---
 source/specifications/core-metadata.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 422d30cd4..832c25bb4 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -801,8 +801,7 @@ Deprecated Fields
 .. _core-metadata-home-page:
 
 Deprecated fields are valid metadata fields for any metadata version. Tools
-MUST attempt to convert deprecated fields to non-deprecated fields when
-appropriate. Tools SHOULD warn users when deprecated fields are used.
+SHOULD warn users when deprecated fields are used.
 
 Home-page
 ---------

From 017f3d6995546d1dfd1c384e78d47c9d18170f45 Mon Sep 17 00:00:00 2001
From: Dustin Ingram 
Date: Tue, 14 Jan 2025 17:44:03 +0000
Subject: [PATCH 525/733] Move text before link targets

---
 source/specifications/core-metadata.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 832c25bb4..f410eca09 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -797,12 +797,12 @@ Examples::
 Deprecated Fields
 =================
 
-.. _home-page-optional:
-.. _core-metadata-home-page:
-
 Deprecated fields are valid metadata fields for any metadata version. Tools
 SHOULD warn users when deprecated fields are used.
 
+.. _home-page-optional:
+.. _core-metadata-home-page:
+
 Home-page
 ---------
 

From 55f3ddeae1e91be40bf1ae4f50271b0e020cf840 Mon Sep 17 00:00:00 2001
From: Dustin Ingram 
Date: Tue, 14 Jan 2025 20:15:00 +0000
Subject: [PATCH 526/733] Commit suggestion

---
 source/specifications/core-metadata.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index f410eca09..2129be541 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -797,8 +797,10 @@ Examples::
 Deprecated Fields
 =================
 
-Deprecated fields are valid metadata fields for any metadata version. Tools
-SHOULD warn users when deprecated fields are used.
+Deprecated fields should be avoided, but they are valid metadata fields. They
+may be removed in future versions of the core metadata standard (at which point
+they will only be valid in files that specify a metadata version prior to the
+removal). Tools SHOULD warn users when deprecated fields are used.
 
 .. _home-page-optional:
 .. _core-metadata-home-page:

From f14dab6c4b4801c40df6fc27cad4d43f748de1e7 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Wed, 15 Jan 2025 13:14:05 -0800
Subject: [PATCH 527/733] Clearly specify that the name and version should be
 normalized for `.dist-info` and `.data` directories in wheels

It's implied by https://packaging.python.org/en/latest/specifications/recording-installed-packages/#the-dist-info-directory as the resulting directory upon unpacking is supposed to be normalized.
---
 source/specifications/binary-distribution-format.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index be21aedcd..9b1678c0a 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -175,8 +175,10 @@ File contents
 '''''''''''''
 
 The contents of a wheel file, where {distribution} is replaced with the
-name of the package, e.g. ``beaglevote`` and {version} is replaced with
-its version, e.g. ``1.0.0``, consist of:
+:ref:`normalized name ` of the package, e.g. 
+``beaglevote`` and {version} is replaced
+with its :ref:`normalized version `,
+e.g. ``1.0.0``, consist of:
 
 #. ``/``, the root of the archive, contains all files to be installed in
    ``purelib`` or ``platlib`` as specified in ``WHEEL``.  ``purelib`` and

From 5b0cb92e8a690d8797284a687f443ad1382aa3e5 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 15 Jan 2025 21:14:59 +0000
Subject: [PATCH 528/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/specifications/binary-distribution-format.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index 9b1678c0a..bcb73b0a2 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -175,7 +175,7 @@ File contents
 '''''''''''''
 
 The contents of a wheel file, where {distribution} is replaced with the
-:ref:`normalized name ` of the package, e.g. 
+:ref:`normalized name ` of the package, e.g.
 ``beaglevote`` and {version} is replaced
 with its :ref:`normalized version `,
 e.g. ``1.0.0``, consist of:

From f132c2ffe0da00359ac3debd4212a25f50c709b7 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Wed, 15 Jan 2025 14:46:18 -0800
Subject: [PATCH 529/733] Update
 source/specifications/binary-distribution-format.rst

Co-authored-by: Paul Moore 
---
 source/specifications/binary-distribution-format.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index bcb73b0a2..f16c191d7 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -178,7 +178,7 @@ The contents of a wheel file, where {distribution} is replaced with the
 :ref:`normalized name ` of the package, e.g.
 ``beaglevote`` and {version} is replaced
 with its :ref:`normalized version `,
-e.g. ``1.0.0``, consist of:
+e.g. ``1.0.0``, (with dash (`-`) characters replaced with underscore (`_`) characters in both fields) consist of:
 
 #. ``/``, the root of the archive, contains all files to be installed in
    ``purelib`` or ``platlib`` as specified in ``WHEEL``.  ``purelib`` and

From dbbc9b14e53f5912fcb1c08ef3fba7ec1b2d1011 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Thu, 16 Jan 2025 13:27:46 -0800
Subject: [PATCH 530/733] Add an entry to the History section

---
 .../specifications/binary-distribution-format.rst   | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index f16c191d7..4d94e1052 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -150,10 +150,10 @@ this character cannot appear within any component. This is handled as follows:
 - In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE
   and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase
   characters should be replaced with corresponding lowercase ones. This is
-  equivalent to regular :ref:`name normalization ` followed by replacing ``-`` with ``_``.
-  Tools consuming wheels must be prepared to accept ``.`` (FULL STOP) and
-  uppercase letters, however, as these were allowed by an earlier version of
-  this specification.
+  equivalent to regular :ref:`name normalization ` followed
+  by replacing ``-`` with ``_``. Tools consuming wheels must be prepared to accept
+  ``.`` (FULL STOP) and uppercase letters, however, as these were allowed by an earlier
+  version of this specification.
 - Version numbers should be normalised according to the :ref:`Version specifier
   specification `. Normalised version numbers cannot contain ``-``.
 - The remaining components may not contain ``-`` characters, so no escaping
@@ -178,7 +178,8 @@ The contents of a wheel file, where {distribution} is replaced with the
 :ref:`normalized name ` of the package, e.g.
 ``beaglevote`` and {version} is replaced
 with its :ref:`normalized version `,
-e.g. ``1.0.0``, (with dash (`-`) characters replaced with underscore (`_`) characters in both fields) consist of:
+e.g. ``1.0.0``, (with dash/``-`` characters replaced with underscore/``_`` characters
+in both fields) consist of:
 
 #. ``/``, the root of the archive, contains all files to be installed in
    ``purelib`` or ``platlib`` as specified in ``WHEEL``.  ``purelib`` and
@@ -442,6 +443,8 @@ History
   may vary between tools).
 - December 2024: The :file:`.dist-info/licenses/` directory was specified through
   :pep:`639`.
+- January 2025: Clarified that name and version needs to be normalized for
+  ``.dist-info`` and ``.data`` directories.
 
 
 Appendix

From 96058cc8d3b42c00c26fb04cc5bb2c530dc67d4e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Mon, 27 Jan 2025 18:08:49 +0100
Subject: [PATCH 531/733] Start a discussion on helping downstream packaging

Start the discussion aimed at making downstream packaging easier.
The first section focuses on providing source distributions.

Also related to bug #1494, though it's focused on why having these
extra files is helpful to downstreams, rather than setting a hard
standard on what should be included.
---
 source/discussions/downstream-packaging.rst | 84 +++++++++++++++++++++
 source/discussions/index.rst                |  1 +
 2 files changed, 85 insertions(+)
 create mode 100644 source/discussions/downstream-packaging.rst

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
new file mode 100644
index 000000000..1573bca06
--- /dev/null
+++ b/source/discussions/downstream-packaging.rst
@@ -0,0 +1,84 @@
+.. _downstream-packaging:
+
+========================================
+How to make downstream packaging easier?
+========================================
+
+:Page Status: Draft
+:Last Reviewed: 2025-?
+
+While PyPI and the Python packaging tools such as :ref:`pip` are the primary
+means of distributing your packages, they are often also made available as part
+of other packaging ecosystems. These repackaging efforts are collectively called
+*downstream* packaging (your own efforts are called *upstream* packaging),
+and include such projects as Linux distributions, Conda, Homebrew and MacPorts.
+They often aim to provide good support for use cases that cannot be handled
+via Python packaging tools alone, such as good integration with non-Python
+software.
+
+This discussion attempts to explain how downstream packaging is usually done,
+and what challenges are downstream packagers facing. It ultimately aims to give
+you some hints on how you can make downstream packaging easier.
+
+Please note that downstream builds include not only binary redistribution,
+but also source builds done on user systems, in source-first distributions
+such as Gentoo Linux.
+
+
+.. _Provide complete source distributions:
+
+Provide complete source distributions
+-------------------------------------
+The vast majority of downstream packagers prefer to build packages from source,
+rather than use the upstream-provided binary packages. This is also true
+of pure Python packages that provide universal wheels. The reasons for using
+source distributions may include:
+
+- being able to audit the source code of all packages
+
+- being able to run the test suite and build documentation
+
+- being able to easily apply patches, including backporting commits from your
+  repository and sending patches back to you
+
+- being able to build against a specific platform that is not covered
+  by upstream builds
+
+- being able to build against specific versions of system libraries
+
+- having a consistent build process across all Python packages
+
+Ideally, a source distribution archive should include all the files necessary
+to build the package itself, run its test suite, build and install its
+documentation, and any other files that may be useful to end users, such
+as shell completions, editor support files, and so on.
+
+Some projects are concerned about increasing the size of source distribution,
+or do not wish Python packaging tools to fall back to source distributions
+automatically.  In these cases, a good compromise may be to publish a separate
+source archive for downstream use, for example by attaching it to a GitHub
+release.
+
+While it is usually possible to build packages from a git repository, there are
+a few important reasons to provide a static archive file instead:
+
+- Fetching a single file is often more efficient, more reliable and better
+  supported than e.g. using a git clone. This can help users with a shoddy
+  Internet connection.
+
+- Downstreams often use checksums to verify the authenticity of source files
+  on subsequent builds, which require that they remain bitwise identical over
+  time. For example, automatically generated git archives do not guarantee
+  that.
+
+- Archive files can be mirrored, reducing both upstream and downstream
+  bandwidth use. The actual builds can afterwards be performed in firewalled
+  or offline environments, that can only access source files provided
+  by the local mirror or redistributed earlier.
+
+A good idea is to use a release workflow that starts by building a source
+distribution, and then performs all the remaining release steps (such as
+running tests and building wheels) from the unpacked source distribution. This
+ensures that the source distribution is actually tested, and reduces the risk
+that users installing from it will hit build failures or install an incomplete
+package.
diff --git a/source/discussions/index.rst b/source/discussions/index.rst
index 1f5ff1f2b..b1b84f97a 100644
--- a/source/discussions/index.rst
+++ b/source/discussions/index.rst
@@ -17,3 +17,4 @@ specific topic. If you're just trying to get stuff done, see
    src-layout-vs-flat-layout
    setup-py-deprecated
    single-source-version
+   downstream-packaging

From b4cb7d2d6bed24af2f6831d07fb7d8fb5edf3f12 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Mon, 27 Jan 2025 20:50:17 +0100
Subject: [PATCH 532/733] Add a section on Internet access

---
 source/discussions/downstream-packaging.rst | 39 +++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 1573bca06..f40fafac8 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -82,3 +82,42 @@ running tests and building wheels) from the unpacked source distribution. This
 ensures that the source distribution is actually tested, and reduces the risk
 that users installing from it will hit build failures or install an incomplete
 package.
+
+
+.. _Do not use the Internet during the build process:
+
+Do not use the Internet during the build process
+------------------------------------------------
+Downstream builds are frequently done in sandboxed environments that cannot
+access the Internet. Therefore, it is important that your source distribution
+includes all the files needed for the package to build or allows provisioning
+them externally, and can build successfully without Internet access.
+
+Ideally, it should not even attempt to access the Internet at all, unless
+explicitly requested to. If that is not possible to achieve, the next best
+thing is to provide an opt-out switch to disable all Internet access, and fail
+if some of the required files are missing instead of trying to fetch them. This
+could be done e.g. by checking whether a ``NO_NETWORK`` environment variable is
+to a non-empty value. Please also remember that if you are fetching remote
+resources, you should verify their authenticity, e.g.  against a checksum, to
+protect against the file being substituted by a malicious party.
+
+Even if downloads are properly authenticated, using the Internet is discouraged
+for a number of reasons:
+
+- The Internet connection may be unstable (e.g. poor reception) or suffer from
+  temporary problems that could cause the downloads to fail or hang.
+
+- The remote resources may become temporarily or even permanently unavailable,
+  making the build no longer possible. This is especially problematic when
+  someone needs to build an old package version.
+
+- Accessing remote servers poses a privacy issue and a potential security issue,
+  as it exposes information about the system building the package.
+
+- The user may be using a service with a limited data plan, in which
+  uncontrolled Internet access may result in additional charges or other
+  inconveniences.
+
+Since downstreams frequently also run tests and build documentation, the above
+should ideally extend to these processes as well.

From df7081cea024faf99a4c1e95f457e42cf8f8ecb6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Mon, 27 Jan 2025 20:51:23 +0100
Subject: [PATCH 533/733] Also suggest the option of splitting test data into
 separate archive

---
 source/discussions/downstream-packaging.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index f40fafac8..f8f4d9d42 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -57,7 +57,8 @@ Some projects are concerned about increasing the size of source distribution,
 or do not wish Python packaging tools to fall back to source distributions
 automatically.  In these cases, a good compromise may be to publish a separate
 source archive for downstream use, for example by attaching it to a GitHub
-release.
+release. Alternatively, large files, such as test data, can be split into
+separate archives.
 
 While it is usually possible to build packages from a git repository, there are
 a few important reasons to provide a static archive file instead:

From cff76df08c13f83b5a8bb4d25192e957c516d108 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Tue, 28 Jan 2025 15:14:02 +0100
Subject: [PATCH 534/733] Add a section on system dependencies

---
 source/discussions/downstream-packaging.rst | 70 +++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index f8f4d9d42..50e00ac91 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -122,3 +122,73 @@ for a number of reasons:
 
 Since downstreams frequently also run tests and build documentation, the above
 should ideally extend to these processes as well.
+
+
+.. _Support building against system dependencies:
+
+Support building against system dependencies
+--------------------------------------------
+Some Python projects have non-Python dependencies, such as libraries written
+in C or C++. Trying to use the system versions of these dependencies
+in upstream packaging may cause a number of problems for end users:
+
+- The published wheels require a binary-compatible version of the used library
+  to be present on the user's system. If the library is missing or installed
+  in incompatible version, the Python package may fail with errors that
+  are not clear to inexperienced users, or even misbehave at runtime.
+
+- Building from source distribution requires a source-compatible version
+  of the dependency to be present, along with its development headers and other
+  auxiliary files that some systems package separately from the library itself.
+
+- Even for an experienced user, installing a compatible dependency version
+  may be very hard. For example, the used Linux distribution may not provide
+  the required version, or some other package may require an incompatible
+  version.
+
+- The linkage between the Python package and its system dependency is not
+  recorded by the packaging system. The next system update may upgrade
+  the library to a newer version that breaks binary compatibility with
+  the Python package, and requires user intervention to fix.
+
+For these reasons, you may reasonable to decide to either link statically
+to your dependencies, or to provide a local copies in the installed package.
+You may also vendor the dependency in your source distribution.  Sometimes
+these dependencies are also repackaged on PyPI, and can be installed
+like a regular Python packages.
+
+However, none of these issues apply to downstream packaging, and downstreams
+have good reasons to prefer dynamically linking to system dependencies.
+In particular:
+
+- Static linking and vendoring obscures the use of external dependencies,
+  making source auditing harder.
+
+- Dynamic linking makes it possible to easily and quickly replace the used
+  libraries, which can be particularly important when they turn out to
+  be vulnerable or buggy.
+
+- Using system dependencies makes the package benefit from downstream
+  customization that can improve the user experience on a particular platform,
+  without the downstream maintainers having to consistently patch
+  the dependencies vendored in different packages. This can include
+  compatibility improvements and security hardening.
+
+- Static linking and vendoring could result in multiple different versions
+  of the same library being loaded in the same process (e.g. when you use two
+  Python packages that link to different versions of the same library).
+  This can cause no problems, but it could also lead to anything from subtle
+  bugs to catastrophic failures.
+
+- Last but not least, static linking and vendoring results in duplication,
+  and may increase the use of both the disk space and memory.
+
+A good compromise between the needs of both parties is to provide a switch
+between using vendored and system dependencies. Ideally, if the package has
+multiple vendored dependencies, it should provide both individual switches
+for each dependency, and a general switch, for example using
+a  ``USE_SYSTEM_DEPS`` environment variable to control the default. If switched
+on, and a particular dependency is either missing or incompatible, the build
+should fail with an explanatory message, giving the packager an explicit
+indication of the problem and a chance to consciously decide on the preferred
+course of action.

From be242a80635933692d238bb7e74c3ea962b480df Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Tue, 28 Jan 2025 16:52:12 +0100
Subject: [PATCH 535/733] Add a section on downstream testing

---
 source/discussions/downstream-packaging.rst | 79 +++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 50e00ac91..7d09bdb73 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -192,3 +192,82 @@ on, and a particular dependency is either missing or incompatible, the build
 should fail with an explanatory message, giving the packager an explicit
 indication of the problem and a chance to consciously decide on the preferred
 course of action.
+
+
+.. _Support downstream testing:
+
+Support downstream testing
+--------------------------
+A variety of downstream projects run some degree of testing on the packaged
+Python projects. Depending on the particular case, this can range from minimal
+smoke testing to comprehensive runs of the complete test suite. There can
+be various reasons for doing this, for example:
+
+- Verifying that the downstream packaging did not introduce any bugs.
+
+- Testing on a platform that is not covered by upstream testing.
+
+- Finding subtle bugs that can only be reproduced on a particular hardware,
+  system package versions, and so on.
+
+- Testing the released package against newer dependency version than the ones
+  present during upstream release testing.
+
+- Testing the package in an environment closely resembling the production
+  setup. This can detect issues caused by nontrivial interactions between
+  different installed packages, including packages that are not dependencies
+  of your package, but nevertheless can cause issues.
+
+- Testing the released package against newer Python versions (including newer
+  point releases), or less tested Python implementations such as PyPy.
+
+Admittedly, sometimes downstream testing may yield false positives or
+inconvenience you about scenarios that you are not interested in supporting.
+However, perhaps even more often it does provide early notice of problems,
+or find nontrivial bugs that would otherwise cause issues for your users
+in production. And believe me, the majority of downstream packagers are doing
+their best to double-check their results, and help you triage and fix the bugs
+that they report.
+
+There is a number of things that you can do to help us test your package
+better. Some of them were already mentioned in this discussion. Some examples
+are:
+
+- Include the test files and fixtures in the source distribution, or make it
+  possible to easily download them separately.
+
+- Do not write to the package during testing. Downstream test setups sometimes
+  run tests on top of the installed package, and test-time modifications can
+  end up being part of the production package!
+
+- Make the test suite work offline. Mock network interactions, using packages
+  such as responses_ or vcrpy_. If that is not possible, make it possible
+  to easily disable the tests using Internet access, e.g. via a pytest marker.
+  Use pytest-socket_ to verify that your tests work offline.
+
+- Make your tests work without a specialized setup, or perform the necessary
+  setup as part of test fixtures. Do not ever assume that you can connect
+  to system services such as databases — in an extreme case, you could crash
+  a production service!
+
+- Do not assume that the test suite will be run with ``-Werror``. Downstreams
+  often need to disable that, as it causes false positives, e.g. due to newer
+  dependency versions. Assert for warnings using ``pytest.warns()`` rather
+  than ``pytest.raises()``!
+
+- Aim to make your test suite reliable. Avoid flaky tests. Avoid depending
+  on specific platform details, don't rely on exact results of floating-point
+  computation, or timing of operations, and so on. Fuzzing has its advantages,
+  but you want to have static test cases for completeness as well.
+
+- Split tests by their purpose, and make it easy to skip categories that are
+  irrelevant or problematic. Since the primary purpose of downstream testing is
+  to ensure that the package itself works, we generally are not interested
+  in e.g. checking code coverage, code formatting, typing or running
+  benchmarks. These tests can fail as dependencies are upgraded or the system
+  is under load, without actually affecting the package itself.
+
+
+.. _responses: https://pypi.org/project/responses/
+.. _vcrpy: https://pypi.org/project/vcrpy/
+.. _pytest-socket: https://pypi.org/project/pytest-socket/

From 9f9af53be8e3fe63af9449481b588f6642e71627 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Wed, 29 Jan 2025 20:49:45 +0100
Subject: [PATCH 536/733] Expand on downstream testing, and add emphasis for
 readability

---
 source/discussions/downstream-packaging.rst | 60 +++++++++++++++------
 1 file changed, 43 insertions(+), 17 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 7d09bdb73..fe909b9cd 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -233,41 +233,67 @@ There is a number of things that you can do to help us test your package
 better. Some of them were already mentioned in this discussion. Some examples
 are:
 
-- Include the test files and fixtures in the source distribution, or make it
+- **Include the test files and fixtures in the source distribution**, or make it
   possible to easily download them separately.
 
-- Do not write to the package during testing. Downstream test setups sometimes
-  run tests on top of the installed package, and test-time modifications can
-  end up being part of the production package!
+- **Do not write to the package directories during testing.** Downstream test
+  setups sometimes run tests on top of the installed package, and modifications
+  performed during testing and temporary test files may end up being part
+  of the installed package!
 
-- Make the test suite work offline. Mock network interactions, using packages
-  such as responses_ or vcrpy_. If that is not possible, make it possible
-  to easily disable the tests using Internet access, e.g. via a pytest marker.
-  Use pytest-socket_ to verify that your tests work offline.
+- **Make the test suite work offline.** Mock network interactions, using
+  packages such as responses_ or vcrpy_. If that is not possible, make it
+  possible to easily disable the tests using Internet access, e.g. via a pytest
+  marker.  Use pytest-socket_ to verify that your tests work offline. This
+  often makes your own test workflows faster and more reliable as well.
 
-- Make your tests work without a specialized setup, or perform the necessary
+- **Make your tests work without a specialized setup**, or perform the necessary
   setup as part of test fixtures. Do not ever assume that you can connect
   to system services such as databases — in an extreme case, you could crash
   a production service!
 
-- Do not assume that the test suite will be run with ``-Werror``. Downstreams
+- **If your package has optional dependencies, make their tests optional as
+  well.** Either skip them if the needed packages are not installed, or add
+  markers to make deselecting easy.
+
+- More generally, **add markers to tests with special requirements**. These can
+  include e.g. significant space usage, significant memory usage, long runtime,
+  incompatibility with parallel testing.
+
+- **Do not assume that the test suite will be run with -Werror.** Downstreams
   often need to disable that, as it causes false positives, e.g. due to newer
   dependency versions. Assert for warnings using ``pytest.warns()`` rather
   than ``pytest.raises()``!
 
-- Aim to make your test suite reliable. Avoid flaky tests. Avoid depending
-  on specific platform details, don't rely on exact results of floating-point
-  computation, or timing of operations, and so on. Fuzzing has its advantages,
-  but you want to have static test cases for completeness as well.
+- **Aim to make your test suite reliable and reproducible.** Avoid flaky tests.
+  Avoid depending on specific platform details, don't rely on exact results
+  of floating-point computation, or timing of operations, and so on. Fuzzing
+  has its advantages, but you want to have static test cases for completeness
+  as well.
 
-- Split tests by their purpose, and make it easy to skip categories that are
-  irrelevant or problematic. Since the primary purpose of downstream testing is
-  to ensure that the package itself works, we generally are not interested
+- **Split tests by their purpose, and make it easy to skip categories that are
+  irrelevant or problematic.** Since the primary purpose of downstream testing
+  is to ensure that the package itself works, we generally are not interested
   in e.g. checking code coverage, code formatting, typing or running
   benchmarks. These tests can fail as dependencies are upgraded or the system
   is under load, without actually affecting the package itself.
 
+- If your test suite takes significant time to run, **support testing
+  in parallel.** Downstreams often maintain a large number of packages,
+  and testing them all takes a lot of time. Using pytest-xdist_ can help them
+  avoid bottlenecks.
+
+- Ideally, **support running your test suite via PyTest**. PyTest_ has many
+  command-line arguments that are truly helpful to downstreams, such as
+  the ability to conveniently deselect tests, rerun flaky tests
+  (via pytest-rerunfailures_), add a timeout to prevent tests from hanging
+  (via pytest-timeout_) or run tests in parallel (via pytest-xdist_).
+
 
 .. _responses: https://pypi.org/project/responses/
 .. _vcrpy: https://pypi.org/project/vcrpy/
 .. _pytest-socket: https://pypi.org/project/pytest-socket/
+.. _pytest-xdist: https://pypi.org/project/pytest-xdist/
+.. _pytest: https://pytest.org/
+.. _pytest-rerunfailures: https://pypi.org/project/pytest-rerunfailures/
+.. _pytest-timeout: https://pypi.org/project/pytest-timeout/

From 00f39e5a434e7dd17ba9743072c9c33222b6c378 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Wed, 29 Jan 2025 21:19:40 +0100
Subject: [PATCH 537/733] Reorganize into why/how sections, and add emphasis

Hopefully, this will make it easier for people who aren't interested
in reading all the rationale to find the important details -- and for
people who read it once to quickly find the point they need later.
---
 source/discussions/downstream-packaging.rst | 212 +++++++++++---------
 1 file changed, 117 insertions(+), 95 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index fe909b9cd..71d02e7d0 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -29,97 +29,108 @@ such as Gentoo Linux.
 
 Provide complete source distributions
 -------------------------------------
+Why?
+~~~~
 The vast majority of downstream packagers prefer to build packages from source,
 rather than use the upstream-provided binary packages. This is also true
 of pure Python packages that provide universal wheels. The reasons for using
 source distributions may include:
 
-- being able to audit the source code of all packages
+- being able to **audit the source code** of all packages
 
-- being able to run the test suite and build documentation
+- being able to **run the test suite and build documentation**
 
-- being able to easily apply patches, including backporting commits from your
-  repository and sending patches back to you
+- being able to **easily apply patches**, including backporting commits
+  from your repository and sending patches back to you
 
-- being able to build against a specific platform that is not covered
+- being able to **build on a specific platform** that is not covered
   by upstream builds
 
-- being able to build against specific versions of system libraries
+- being able to **build against specific versions of system libraries**
 
 - having a consistent build process across all Python packages
 
-Ideally, a source distribution archive should include all the files necessary
-to build the package itself, run its test suite, build and install its
-documentation, and any other files that may be useful to end users, such
-as shell completions, editor support files, and so on.
-
-Some projects are concerned about increasing the size of source distribution,
-or do not wish Python packaging tools to fall back to source distributions
-automatically.  In these cases, a good compromise may be to publish a separate
-source archive for downstream use, for example by attaching it to a GitHub
-release. Alternatively, large files, such as test data, can be split into
-separate archives.
-
 While it is usually possible to build packages from a git repository, there are
 a few important reasons to provide a static archive file instead:
 
-- Fetching a single file is often more efficient, more reliable and better
-  supported than e.g. using a git clone. This can help users with a shoddy
+- Fetching a single file is often **more efficient, more reliable and better
+  supported** than e.g. using a git clone. This can help users with a shoddy
   Internet connection.
 
-- Downstreams often use checksums to verify the authenticity of source files
+- Downstreams often **use checksums to verify the authenticity** of source files
   on subsequent builds, which require that they remain bitwise identical over
   time. For example, automatically generated git archives do not guarantee
   that.
 
-- Archive files can be mirrored, reducing both upstream and downstream
+- Archive files can be **mirrored**, reducing both upstream and downstream
   bandwidth use. The actual builds can afterwards be performed in firewalled
   or offline environments, that can only access source files provided
   by the local mirror or redistributed earlier.
 
-A good idea is to use a release workflow that starts by building a source
-distribution, and then performs all the remaining release steps (such as
-running tests and building wheels) from the unpacked source distribution. This
-ensures that the source distribution is actually tested, and reduces the risk
-that users installing from it will hit build failures or install an incomplete
-package.
+How?
+~~~~
+Ideally, **a source distribution archive should include all the files**
+necessary to build the package itself, run its test suite, build and install
+its documentation, and any other files that may be useful to end users, such as
+shell completions, editor support files, and so on.
+
+Some projects are concerned about increasing the size of source distribution,
+or do not wish Python packaging tools to fall back to source distributions
+automatically.  In these cases, a good compromise may be to publish a separate
+source archive for downstream use, for example by attaching it to a GitHub
+release. Alternatively, large files, such as test data, can be split into
+separate archives.
+
+A good idea is to **use your source distribution in the release workflow**.
+That is, build it first, then unpack it and perform all the remaining steps
+using the unpacked distribution rather than the git repostiry — run tests,
+build documentation, build wheels. This ensures that it is well-tested,
+and reduces the risk that some users would hit build failures or install
+an incomplete package.
 
 
 .. _Do not use the Internet during the build process:
 
 Do not use the Internet during the build process
 ------------------------------------------------
-Downstream builds are frequently done in sandboxed environments that cannot
-access the Internet. Therefore, it is important that your source distribution
-includes all the files needed for the package to build or allows provisioning
-them externally, and can build successfully without Internet access.
-
-Ideally, it should not even attempt to access the Internet at all, unless
-explicitly requested to. If that is not possible to achieve, the next best
-thing is to provide an opt-out switch to disable all Internet access, and fail
-if some of the required files are missing instead of trying to fetch them. This
-could be done e.g. by checking whether a ``NO_NETWORK`` environment variable is
-to a non-empty value. Please also remember that if you are fetching remote
-resources, you should verify their authenticity, e.g.  against a checksum, to
-protect against the file being substituted by a malicious party.
-
-Even if downloads are properly authenticated, using the Internet is discouraged
-for a number of reasons:
+Why?
+~~~~
+Downstream builds are frequently done in sandboxed environments that **cannot
+access the Internet**. Even if this is not the case, and assuming that you took
+sufficient care to **properly authenticate downloads**, using the Internet
+is discouraged for a number of reasons:
 
-- The Internet connection may be unstable (e.g. poor reception) or suffer from
-  temporary problems that could cause the downloads to fail or hang.
+- The Internet **connection may be unstable** (e.g. due to poor reception)
+  or suffer from temporary problems that could cause the process to fail
+  or hang.
 
-- The remote resources may become temporarily or even permanently unavailable,
-  making the build no longer possible. This is especially problematic when
-  someone needs to build an old package version.
+- The remote resources may **become temporarily or even permanently
+  unavailable**, making the build no longer possible. This is especially
+  problematic when someone needs to build an old package version.
 
-- Accessing remote servers poses a privacy issue and a potential security issue,
-  as it exposes information about the system building the package.
+- Accessing remote servers poses a **privacy** issue and a potential
+  **security** issue, as it exposes information about the system building
+  the package.
 
 - The user may be using a service with a limited data plan, in which
-  uncontrolled Internet access may result in additional charges or other
+  uncontrolled Internet access may result in **additional charges** or other
   inconveniences.
 
+How?
+~~~~
+Your source distribution should either **include all the files needed
+for the package to build**, or allow provisioning them externally. Ideally,
+it should not even attempt to access the Internet at all, unless explicitly
+requested to. If that is not possible to achieve, the next best thing
+is to **provide an opt-out switch to disable all Internet access**.
+
+When such a switch is used, the build process should fail if some
+of the required files are missing, rather than try to fetch them automatically.
+This could be done e.g. by checking whether a ``NO_NETWORK`` environment
+variable is set to a non-empty value. Please also remember that if you are
+fetching remote resources, you must **verify their authenticity**, e.g. against
+a checksum, to protect against the file being substituted by a malicious party.
+
 Since downstreams frequently also run tests and build documentation, the above
 should ideally extend to these processes as well.
 
@@ -128,107 +139,118 @@ should ideally extend to these processes as well.
 
 Support building against system dependencies
 --------------------------------------------
+Why?
+~~~~
 Some Python projects have non-Python dependencies, such as libraries written
 in C or C++. Trying to use the system versions of these dependencies
 in upstream packaging may cause a number of problems for end users:
 
-- The published wheels require a binary-compatible version of the used library
-  to be present on the user's system. If the library is missing or installed
-  in incompatible version, the Python package may fail with errors that
-  are not clear to inexperienced users, or even misbehave at runtime.
+- The published wheels **require a binary-compatible version of the used
+  library** to be present on the user's system. If the library is missing
+  or installed in incompatible version, the Python package may fail with errors
+  that are not clear to inexperienced users, or even misbehave at runtime.
 
-- Building from source distribution requires a source-compatible version
-  of the dependency to be present, along with its development headers and other
-  auxiliary files that some systems package separately from the library itself.
+- Building from source distribution **requires a source-compatible version
+  of the dependency** to be present, along with its development headers
+  and other auxiliary files that some systems package separately
+  from the library itself.
 
 - Even for an experienced user, installing a compatible dependency version
   may be very hard. For example, the used Linux distribution may not provide
-  the required version, or some other package may require an incompatible
-  version.
+  the required version, or some **other package may require an incompatible
+  version**.
 
 - The linkage between the Python package and its system dependency is not
-  recorded by the packaging system. The next system update may upgrade
-  the library to a newer version that breaks binary compatibility with
+  recorded by the packaging system. The next system update may **upgrade
+  the library to a newer version that breaks binary compatibility** with
   the Python package, and requires user intervention to fix.
 
-For these reasons, you may reasonable to decide to either link statically
+For these reasons, you may reasonable to decide to either **link statically**
 to your dependencies, or to provide a local copies in the installed package.
-You may also vendor the dependency in your source distribution.  Sometimes
+You may also **vendor the dependency** in your source distribution.  Sometimes
 these dependencies are also repackaged on PyPI, and can be installed
 like a regular Python packages.
 
 However, none of these issues apply to downstream packaging, and downstreams
-have good reasons to prefer dynamically linking to system dependencies.
+have good reasons to prefer **dynamically linking to system dependencies**.
 In particular:
 
 - Static linking and vendoring obscures the use of external dependencies,
-  making source auditing harder.
+  **making source auditing harder**.
 
-- Dynamic linking makes it possible to easily and quickly replace the used
-  libraries, which can be particularly important when they turn out to
+- Dynamic linking makes it possible to easily and **quickly replace the used
+  libraries**, which can be particularly important when they turn out to
   be vulnerable or buggy.
 
-- Using system dependencies makes the package benefit from downstream
-  customization that can improve the user experience on a particular platform,
+- Using system dependencies makes the package benefit from **downstream
+  customization** that can improve the user experience on a particular platform,
   without the downstream maintainers having to consistently patch
   the dependencies vendored in different packages. This can include
-  compatibility improvements and security hardening.
+  **compatibility improvements and security hardening**.
 
-- Static linking and vendoring could result in multiple different versions
-  of the same library being loaded in the same process (e.g. when you use two
+- Static linking and vendoring could result in **multiple different versions
+  of the same library being loaded in the same process** (e.g. when you use two
   Python packages that link to different versions of the same library).
   This can cause no problems, but it could also lead to anything from subtle
   bugs to catastrophic failures.
 
 - Last but not least, static linking and vendoring results in duplication,
-  and may increase the use of both the disk space and memory.
+  and may increase the **use of both the disk space and memory**.
 
-A good compromise between the needs of both parties is to provide a switch
-between using vendored and system dependencies. Ideally, if the package has
+How?
+~~~~
+A good compromise between the needs of both parties is to **provide a switch
+between using vendored and system dependencies**. Ideally, if the package has
 multiple vendored dependencies, it should provide both individual switches
-for each dependency, and a general switch, for example using
-a  ``USE_SYSTEM_DEPS`` environment variable to control the default. If switched
-on, and a particular dependency is either missing or incompatible, the build
-should fail with an explanatory message, giving the packager an explicit
-indication of the problem and a chance to consciously decide on the preferred
-course of action.
+for each dependency, and a general switch to control the default for them,
+e.g. via a ``USE_SYSTEM_DEPS`` environment variable.
+
+If the user requests using system dependencies, and **a particular dependency
+is either missing or incompatible, the build should fail** with an explanatory
+message rather than fall back to a vendored version. This gives the packager
+the opportunity to notice their mistake and a chance to consciously decide
+how to solve it.
 
 
 .. _Support downstream testing:
 
 Support downstream testing
 --------------------------
+Why?
+~~~~
 A variety of downstream projects run some degree of testing on the packaged
 Python projects. Depending on the particular case, this can range from minimal
 smoke testing to comprehensive runs of the complete test suite. There can
 be various reasons for doing this, for example:
 
-- Verifying that the downstream packaging did not introduce any bugs.
+- Verifying that the downstream **packaging did not introduce any bugs**.
 
-- Testing on a platform that is not covered by upstream testing.
+- Testing on **additional platforms** that are not covered by upstream testing.
 
-- Finding subtle bugs that can only be reproduced on a particular hardware,
-  system package versions, and so on.
+- Finding subtle bugs that can only be reproduced on a **particular hardware,
+  system package versions**, and so on.
 
-- Testing the released package against newer dependency version than the ones
-  present during upstream release testing.
+- Testing the released package against **newer dependency versions** than
+  the ones present during upstream release testing.
 
-- Testing the package in an environment closely resembling the production
-  setup. This can detect issues caused by nontrivial interactions between
+- Testing the package in an environment closely resembling **the production
+  setup**. This can detect issues caused by nontrivial interactions between
   different installed packages, including packages that are not dependencies
   of your package, but nevertheless can cause issues.
 
-- Testing the released package against newer Python versions (including newer
-  point releases), or less tested Python implementations such as PyPy.
+- Testing the released package against **newer Python versions** (including
+  newer point releases), or less tested Python implementations such as PyPy.
 
 Admittedly, sometimes downstream testing may yield false positives or
 inconvenience you about scenarios that you are not interested in supporting.
 However, perhaps even more often it does provide early notice of problems,
 or find nontrivial bugs that would otherwise cause issues for your users
-in production. And believe me, the majority of downstream packagers are doing
+in production. And believe me, the majority of **downstream packagers are doing
 their best to double-check their results, and help you triage and fix the bugs
-that they report.
+that they report**.
 
+How?
+~~~~
 There is a number of things that you can do to help us test your package
 better. Some of them were already mentioned in this discussion. Some examples
 are:

From 08c70e87a763d40832d177be70968e7280af821d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Wed, 29 Jan 2025 21:32:26 +0100
Subject: [PATCH 538/733] Elaborate a bit more on why it's good to help
 downstreams

---
 source/discussions/downstream-packaging.rst | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 71d02e7d0..d3f33668f 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -13,12 +13,22 @@ of other packaging ecosystems. These repackaging efforts are collectively called
 *downstream* packaging (your own efforts are called *upstream* packaging),
 and include such projects as Linux distributions, Conda, Homebrew and MacPorts.
 They often aim to provide good support for use cases that cannot be handled
-via Python packaging tools alone, such as good integration with non-Python
-software.
+via Python packaging tools alone, such as **good integration with non-Python
+software**.
 
 This discussion attempts to explain how downstream packaging is usually done,
 and what challenges are downstream packagers facing. It ultimately aims to give
-you some hints on how you can make downstream packaging easier.
+you some hints on how you can **make downstream packaging easier**.
+
+Establishing a good relationship between software maintainers and downstream
+packagers can bring mutual benefits. Downstreams are often willing to **share
+their experience, time and hardware** to improve your package. They are
+sometimes in a better position to see **the bigger picture**, and to provide
+you with **information about other packages** that would otherwise require you
+to put significant effort to obtain. Packagers often can **find bugs** before
+your users hit them on production, **provide bug reports of good quality**
+and **supply patches** whenever they can. For example, they are often
+in the vanguard when **a new Python version** comes out.
 
 Please note that downstream builds include not only binary redistribution,
 but also source builds done on user systems, in source-first distributions

From 24f552e00ca448d4f6389d3422d8222bbd90224f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Wed, 29 Jan 2025 21:36:12 +0100
Subject: [PATCH 539/733] Correct "pytest" capitalization

---
 source/discussions/downstream-packaging.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index d3f33668f..6ea05a348 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -315,7 +315,7 @@ are:
   and testing them all takes a lot of time. Using pytest-xdist_ can help them
   avoid bottlenecks.
 
-- Ideally, **support running your test suite via PyTest**. PyTest_ has many
+- Ideally, **support running your test suite via pytest**. pytest_ has many
   command-line arguments that are truly helpful to downstreams, such as
   the ability to conveniently deselect tests, rerun flaky tests
   (via pytest-rerunfailures_), add a timeout to prevent tests from hanging

From 24b03467f59ba59e154b75fef77a86d250bd03d0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Thu, 30 Jan 2025 13:10:07 +0000
Subject: [PATCH 540/733] Apply suggestions from code review

Co-authored-by: Alyssa Coghlan 
---
 source/discussions/downstream-packaging.rst | 242 +++++++++++---------
 1 file changed, 137 insertions(+), 105 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 6ea05a348..25740ba29 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -1,84 +1,96 @@
 .. _downstream-packaging:
 
-========================================
-How to make downstream packaging easier?
-========================================
+=================================
+Simplifying downstream packaging
+=================================
 
 :Page Status: Draft
 :Last Reviewed: 2025-?
 
 While PyPI and the Python packaging tools such as :ref:`pip` are the primary
-means of distributing your packages, they are often also made available as part
+means of distributing Python packages, they are also often made available as part
 of other packaging ecosystems. These repackaging efforts are collectively called
 *downstream* packaging (your own efforts are called *upstream* packaging),
 and include such projects as Linux distributions, Conda, Homebrew and MacPorts.
-They often aim to provide good support for use cases that cannot be handled
-via Python packaging tools alone, such as **good integration with non-Python
-software**.
+They generally aim to provide improved support for use cases that cannot be handled
+via Python packaging tools alone, such as native integration with a specific operating
+system, or assured compatibility with specific versions of non-Python software.
 
 This discussion attempts to explain how downstream packaging is usually done,
-and what challenges are downstream packagers facing. It ultimately aims to give
-you some hints on how you can **make downstream packaging easier**.
+and what additional challenges downstream packagers typically face. It aims
+to provide some optional guidelines that project maintainers may choose to
+follow which help make downstream packaging *significantly* easier
+(without imposing any major maintenance hassles on the upstream project).
 
 Establishing a good relationship between software maintainers and downstream
-packagers can bring mutual benefits. Downstreams are often willing to **share
-their experience, time and hardware** to improve your package. They are
-sometimes in a better position to see **the bigger picture**, and to provide
-you with **information about other packages** that would otherwise require you
-to put significant effort to obtain. Packagers often can **find bugs** before
-your users hit them on production, **provide bug reports of good quality**
-and **supply patches** whenever they can. For example, they are often
-in the vanguard when **a new Python version** comes out.
+packagers can bring mutual benefits. Downstreams are often willing to share
+their experience, time and hardware to improve your package. They are
+sometimes in a better position to see how your package is used in practice,
+and to provide information about its relationships with other packages that
+would otherwise require significant effort to obtain.
+Packagers can often find bugs before your users hit them in production,
+provide bug reports of good quality, and supply patches whenever they can.
+For example, they are regularly active in ensuring the packages they redistribute
+are updated for any compatibility issues that arise when a new Python version
+is released.
 
 Please note that downstream builds include not only binary redistribution,
-but also source builds done on user systems, in source-first distributions
-such as Gentoo Linux.
+but also source builds done on user systems (in source-first distributions
+such as Gentoo Linux, for example).
 
 
-.. _Provide complete source distributions:
+.. _provide-complete-source-distributions:
 
 Provide complete source distributions
 -------------------------------------
+
 Why?
 ~~~~
+
 The vast majority of downstream packagers prefer to build packages from source,
 rather than use the upstream-provided binary packages. This is also true
 of pure Python packages that provide universal wheels. The reasons for using
 source distributions may include:
 
-- being able to **audit the source code** of all packages
+- being able to audit the source code of all packages
 
-- being able to **run the test suite and build documentation**
+- being able to run the test suite and build documentation
 
-- being able to **easily apply patches**, including backporting commits
-  from your repository and sending patches back to you
+- being able to easily apply patches, including backporting commits
+  from the project's repository and sending patches back to the project
 
-- being able to **build on a specific platform** that is not covered
+- being able to build on a specific platform that is not covered
   by upstream builds
 
-- being able to **build against specific versions of system libraries**
+- being able to build against specific versions of system libraries
 
 - having a consistent build process across all Python packages
 
 While it is usually possible to build packages from a git repository, there are
 a few important reasons to provide a static archive file instead:
 
-- Fetching a single file is often **more efficient, more reliable and better
-  supported** than e.g. using a git clone. This can help users with a shoddy
-  Internet connection.
+- Fetching a single file is often more efficient, more reliable and better
+  supported than e.g. using a git clone. This can help users with poor
+  Internet connectivity.
 
 - Downstreams often **use checksums to verify the authenticity** of source files
   on subsequent builds, which require that they remain bitwise identical over
   time. For example, automatically generated git archives do not guarantee
   that.
 
-- Archive files can be **mirrored**, reducing both upstream and downstream
+- Archive files can be mirrored, reducing both upstream and downstream
   bandwidth use. The actual builds can afterwards be performed in firewalled
   or offline environments, that can only access source files provided
   by the local mirror or redistributed earlier.
 
+- Explicitly publishing archive files can ensure that any dependencies on version control
+  system metadata are resolved when creating the source archive. For example, automatically
+  generated git archives omit all of the commit tag information, potentially resulting in
+  incorrect version details in the resulting builds.
+
 How?
 ~~~~
+
 Ideally, **a source distribution archive should include all the files**
 necessary to build the package itself, run its test suite, build and install
 its documentation, and any other files that may be useful to end users, such as
@@ -99,23 +111,25 @@ and reduces the risk that some users would hit build failures or install
 an incomplete package.
 
 
-.. _Do not use the Internet during the build process:
+.. _no-internet-access-in-builds:
 
 Do not use the Internet during the build process
 ------------------------------------------------
+
 Why?
 ~~~~
-Downstream builds are frequently done in sandboxed environments that **cannot
-access the Internet**. Even if this is not the case, and assuming that you took
-sufficient care to **properly authenticate downloads**, using the Internet
+
+Downstream builds are frequently done in sandboxed environments that cannot
+access the Internet. Even if this is not the case, and assuming that you took
+sufficient care to properly authenticate downloads, using the Internet
 is discouraged for a number of reasons:
 
-- The Internet **connection may be unstable** (e.g. due to poor reception)
+- The Internet connection may be unstable (e.g. due to poor reception)
   or suffer from temporary problems that could cause the process to fail
   or hang.
 
-- The remote resources may **become temporarily or even permanently
-  unavailable**, making the build no longer possible. This is especially
+- The remote resources may become temporarily or even permanently
+  unavailable, making the build no longer possible. This is especially
   problematic when someone needs to build an old package version.
 
 - Accessing remote servers poses a **privacy** issue and a potential
@@ -123,16 +137,17 @@ is discouraged for a number of reasons:
   the package.
 
 - The user may be using a service with a limited data plan, in which
-  uncontrolled Internet access may result in **additional charges** or other
+  uncontrolled Internet access may result in additional charges or other
   inconveniences.
 
 How?
 ~~~~
-Your source distribution should either **include all the files needed
-for the package to build**, or allow provisioning them externally. Ideally,
+
+Your source distribution should either include all the files needed
+for the package to build, or allow provisioning them externally. Ideally,
 it should not even attempt to access the Internet at all, unless explicitly
 requested to. If that is not possible to achieve, the next best thing
-is to **provide an opt-out switch to disable all Internet access**.
+is to provide an opt-out switch to disable all Internet access.
 
 When such a switch is used, the build process should fail if some
 of the required files are missing, rather than try to fetch them automatically.
@@ -145,114 +160,128 @@ Since downstreams frequently also run tests and build documentation, the above
 should ideally extend to these processes as well.
 
 
-.. _Support building against system dependencies:
+.. _support-system-dependencies-in-builds:
 
 Support building against system dependencies
 --------------------------------------------
+
 Why?
 ~~~~
+
 Some Python projects have non-Python dependencies, such as libraries written
 in C or C++. Trying to use the system versions of these dependencies
 in upstream packaging may cause a number of problems for end users:
 
-- The published wheels **require a binary-compatible version of the used
-  library** to be present on the user's system. If the library is missing
-  or installed in incompatible version, the Python package may fail with errors
+- The published wheels require a binary-compatible version of the used
+  library to be present on the user's system. If the library is missing
+  or an incompatible version is installed, the Python package may fail with errors
   that are not clear to inexperienced users, or even misbehave at runtime.
 
-- Building from source distribution **requires a source-compatible version
-  of the dependency** to be present, along with its development headers
+- Building from a source distribution requires a source-compatible version
+  of the dependency to be present, along with its development headers
   and other auxiliary files that some systems package separately
   from the library itself.
 
 - Even for an experienced user, installing a compatible dependency version
   may be very hard. For example, the used Linux distribution may not provide
-  the required version, or some **other package may require an incompatible
-  version**.
+  the required version, or some other package may require an incompatible
+  version.
 
 - The linkage between the Python package and its system dependency is not
-  recorded by the packaging system. The next system update may **upgrade
-  the library to a newer version that breaks binary compatibility** with
+  recorded by the packaging system. The next system update may upgrade
+  the library to a newer version that breaks binary compatibility with
   the Python package, and requires user intervention to fix.
 
-For these reasons, you may reasonable to decide to either **link statically**
-to your dependencies, or to provide a local copies in the installed package.
-You may also **vendor the dependency** in your source distribution.  Sometimes
-these dependencies are also repackaged on PyPI, and can be installed
-like a regular Python packages.
+For these reasons, you may reasonably decide to either statically link
+your dependencies, or to provide local copies in the installed package.
+You may also vendor the dependency in your source distribution.  Sometimes
+these dependencies are also repackaged on PyPI, and can be declared as
+project dependencies like any other Python package.
 
 However, none of these issues apply to downstream packaging, and downstreams
-have good reasons to prefer **dynamically linking to system dependencies**.
+have good reasons to prefer dynamically linking to system dependencies.
 In particular:
 
+- in many cases, reliably sharing dynamic dependencies between components is a large part
+  of the *purpose* of a downstream packaging ecosystem. Helping to support that makes it
+  easier for users of those systems to access upstream projects in their preferred format.
+
 - Static linking and vendoring obscures the use of external dependencies,
-  **making source auditing harder**.
+  making source auditing harder.
 
-- Dynamic linking makes it possible to easily and **quickly replace the used
-  libraries**, which can be particularly important when they turn out to
-  be vulnerable or buggy.
+- Dynamic linking makes it possible to quickly and systematically replace the used
+  libraries across an entire downstream packaging ecosystem, which can be particularly
+  important when they turn out to contain a security vulnerability or critical bug.
 
-- Using system dependencies makes the package benefit from **downstream
-  customization** that can improve the user experience on a particular platform,
+- Using system dependencies makes the package benefit from downstream
+  customization that can improve the user experience on a particular platform,
   without the downstream maintainers having to consistently patch
   the dependencies vendored in different packages. This can include
-  **compatibility improvements and security hardening**.
+  compatibility improvements and security hardening.
 
-- Static linking and vendoring could result in **multiple different versions
-  of the same library being loaded in the same process** (e.g. when you use two
-  Python packages that link to different versions of the same library).
-  This can cause no problems, but it could also lead to anything from subtle
-  bugs to catastrophic failures.
+- Static linking and vendoring can result in multiple different versions of the
+  same library being loaded in the same process (for example, attempting to
+  import two Python packages that link to different versions of the same library).
+  This sometimes works without incident, but it can also lead to anything from library
+  loading errors, to subtle runtime bugs, to catastrophic system failures.
 
 - Last but not least, static linking and vendoring results in duplication,
-  and may increase the **use of both the disk space and memory**.
+  and may increase the use of both disk space and memory.
 
 How?
 ~~~~
-A good compromise between the needs of both parties is to **provide a switch
-between using vendored and system dependencies**. Ideally, if the package has
+
+A good compromise between the needs of both parties is to provide a switch
+between using vendored and system dependencies. Ideally, if the package has
 multiple vendored dependencies, it should provide both individual switches
 for each dependency, and a general switch to control the default for them,
 e.g. via a ``USE_SYSTEM_DEPS`` environment variable.
 
-If the user requests using system dependencies, and **a particular dependency
-is either missing or incompatible, the build should fail** with an explanatory
+If the user requests using system dependencies, and a particular dependency
+is either missing or incompatible, the build should fail with an explanatory
 message rather than fall back to a vendored version. This gives the packager
 the opportunity to notice their mistake and a chance to consciously decide
 how to solve it.
 
+Note that it is reasonable for upstream projects to leave *testing* of building with
+system dependencies to their downstream repackagers. The goal of these guidelines
+is to facilitate more effective collaboration between upstream projects and downstream
+repackagers, not to suggest upstream projects take on tasks that downstream repackagers
+are better equipped to handle.
 
-.. _Support downstream testing:
+.. _support-downstream-testing:
 
 Support downstream testing
 --------------------------
+
 Why?
 ~~~~
+
 A variety of downstream projects run some degree of testing on the packaged
 Python projects. Depending on the particular case, this can range from minimal
 smoke testing to comprehensive runs of the complete test suite. There can
 be various reasons for doing this, for example:
 
-- Verifying that the downstream **packaging did not introduce any bugs**.
+- Verifying that the downstream packaging did not introduce any bugs.
 
-- Testing on **additional platforms** that are not covered by upstream testing.
+- Testing on additional platforms that are not covered by upstream testing.
 
-- Finding subtle bugs that can only be reproduced on a **particular hardware,
-  system package versions**, and so on.
+- Finding subtle bugs that can only be reproduced with particular hardware,
+  system package versions, and so on.
 
-- Testing the released package against **newer dependency versions** than
+- Testing the released package against newer (or older) dependency versions than
   the ones present during upstream release testing.
 
-- Testing the package in an environment closely resembling **the production
-  setup**. This can detect issues caused by nontrivial interactions between
+- Testing the package in an environment closely resembling the production
+  setup. This can detect issues caused by nontrivial interactions between
   different installed packages, including packages that are not dependencies
   of your package, but nevertheless can cause issues.
 
-- Testing the released package against **newer Python versions** (including
+- Testing the released package against newer Python versions (including
   newer point releases), or less tested Python implementations such as PyPy.
 
-Admittedly, sometimes downstream testing may yield false positives or
-inconvenience you about scenarios that you are not interested in supporting.
+Admittedly, sometimes downstream testing may yield false positives or bug
+reports about scenarios the upstream project is not interested in supporting.
 However, perhaps even more often it does provide early notice of problems,
 or find nontrivial bugs that would otherwise cause issues for your users
 in production. And believe me, the majority of **downstream packagers are doing
@@ -261,61 +290,64 @@ that they report**.
 
 How?
 ~~~~
-There is a number of things that you can do to help us test your package
-better. Some of them were already mentioned in this discussion. Some examples
-are:
 
-- **Include the test files and fixtures in the source distribution**, or make it
+There are a number of things that upstream projects can do to help downstream
+repackagers test their packages efficiently and effectively, including some of the suggestions
+already mentioned above. These are typically improvements that make the test suite more
+reliable and easier to use for everyone, not just downstream packagers.
+Some specific suggestions are:
+
+- Include the test files and fixtures in the source distribution, or make it
   possible to easily download them separately.
 
-- **Do not write to the package directories during testing.** Downstream test
+- Do not write to the package directories during testing. Downstream test
   setups sometimes run tests on top of the installed package, and modifications
   performed during testing and temporary test files may end up being part
   of the installed package!
 
-- **Make the test suite work offline.** Mock network interactions, using
+- Make the test suite work offline. Mock network interactions, using
   packages such as responses_ or vcrpy_. If that is not possible, make it
-  possible to easily disable the tests using Internet access, e.g. via a pytest
+  possible to easily disable the tests using Internet access, e.g. via a pytest_
   marker.  Use pytest-socket_ to verify that your tests work offline. This
   often makes your own test workflows faster and more reliable as well.
 
-- **Make your tests work without a specialized setup**, or perform the necessary
+- Make your tests work without a specialized setup, or perform the necessary
   setup as part of test fixtures. Do not ever assume that you can connect
   to system services such as databases — in an extreme case, you could crash
   a production service!
 
-- **If your package has optional dependencies, make their tests optional as
-  well.** Either skip them if the needed packages are not installed, or add
+- If your package has optional dependencies, make their tests optional as
+  well. Either skip them if the needed packages are not installed, or add
   markers to make deselecting easy.
 
-- More generally, **add markers to tests with special requirements**. These can
+- More generally, add markers to tests with special requirements. These can
   include e.g. significant space usage, significant memory usage, long runtime,
   incompatibility with parallel testing.
 
-- **Do not assume that the test suite will be run with -Werror.** Downstreams
+- Do not assume that the test suite will be run with ``-Werror``. Downstreams
   often need to disable that, as it causes false positives, e.g. due to newer
   dependency versions. Assert for warnings using ``pytest.warns()`` rather
   than ``pytest.raises()``!
 
-- **Aim to make your test suite reliable and reproducible.** Avoid flaky tests.
+- Aim to make your test suite reliable and reproducible. Avoid flaky tests.
   Avoid depending on specific platform details, don't rely on exact results
   of floating-point computation, or timing of operations, and so on. Fuzzing
   has its advantages, but you want to have static test cases for completeness
   as well.
 
-- **Split tests by their purpose, and make it easy to skip categories that are
-  irrelevant or problematic.** Since the primary purpose of downstream testing
-  is to ensure that the package itself works, we generally are not interested
-  in e.g. checking code coverage, code formatting, typing or running
+- Split tests by their purpose, and make it easy to skip categories that are
+  irrelevant or problematic. Since the primary purpose of downstream testing
+  is to ensure that the package itself works, downstreams are not generally interested
+  in tasks such as checking code coverage, code formatting, typechecking or running
   benchmarks. These tests can fail as dependencies are upgraded or the system
   is under load, without actually affecting the package itself.
 
-- If your test suite takes significant time to run, **support testing
-  in parallel.** Downstreams often maintain a large number of packages,
+- If your test suite takes significant time to run, support testing
+  in parallel. Downstreams often maintain a large number of packages,
   and testing them all takes a lot of time. Using pytest-xdist_ can help them
   avoid bottlenecks.
 
-- Ideally, **support running your test suite via pytest**. pytest_ has many
+- Ideally, support running your test suite via ``pytest``. pytest_ has many
   command-line arguments that are truly helpful to downstreams, such as
   the ability to conveniently deselect tests, rerun flaky tests
   (via pytest-rerunfailures_), add a timeout to prevent tests from hanging

From 16288af66e9877d1bb8a3812d6c74adfc2db19f9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Thu, 30 Jan 2025 13:12:57 +0000
Subject: [PATCH 541/733] Apply more suggestions from code review

Co-authored-by: Alyssa Coghlan 
---
 source/discussions/downstream-packaging.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 25740ba29..984816c14 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -165,9 +165,11 @@ should ideally extend to these processes as well.
 Support building against system dependencies
 --------------------------------------------
 
+
 Why?
 ~~~~
 
+
 Some Python projects have non-Python dependencies, such as libraries written
 in C or C++. Trying to use the system versions of these dependencies
 in upstream packaging may cause a number of problems for end users:
@@ -202,6 +204,10 @@ However, none of these issues apply to downstream packaging, and downstreams
 have good reasons to prefer dynamically linking to system dependencies.
 In particular:
 
+- in many cases, reliably sharing dynamic dependencies between components is a large part
+  of the *purpose* of a downstream packaging ecosystem. Helping to support that makes it
+  easier for users of those systems to access upstream projects in their preferred format.
+
 - in many cases, reliably sharing dynamic dependencies between components is a large part
   of the *purpose* of a downstream packaging ecosystem. Helping to support that makes it
   easier for users of those systems to access upstream projects in their preferred format.
@@ -231,6 +237,7 @@ In particular:
 How?
 ~~~~
 
+
 A good compromise between the needs of both parties is to provide a switch
 between using vendored and system dependencies. Ideally, if the package has
 multiple vendored dependencies, it should provide both individual switches
@@ -243,6 +250,11 @@ message rather than fall back to a vendored version. This gives the packager
 the opportunity to notice their mistake and a chance to consciously decide
 how to solve it.
 
+Note that it is reasonable for upstream projects to leave *testing* of building with
+system dependencies to their downstream repackagers. The goal of these guidelines
+is to facilitate more effective collaboration between upstream projects and downstream
+repackagers, not to suggest upstream projects take on tasks that downstream repackagers
+are better equipped to handle.
 Note that it is reasonable for upstream projects to leave *testing* of building with
 system dependencies to their downstream repackagers. The goal of these guidelines
 is to facilitate more effective collaboration between upstream projects and downstream
@@ -254,9 +266,11 @@ are better equipped to handle.
 Support downstream testing
 --------------------------
 
+
 Why?
 ~~~~
 
+
 A variety of downstream projects run some degree of testing on the packaged
 Python projects. Depending on the particular case, this can range from minimal
 smoke testing to comprehensive runs of the complete test suite. There can
@@ -291,6 +305,7 @@ that they report**.
 How?
 ~~~~
 
+
 There are a number of things that upstream projects can do to help downstream
 repackagers test their packages efficiently and effectively, including some of the suggestions
 already mentioned above. These are typically improvements that make the test suite more

From b4c7485665311525bf50951f6ecf50ff541caa18 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Thu, 30 Jan 2025 16:28:40 +0100
Subject: [PATCH 542/733] Attempt addressing the remaining review comments

---
 source/discussions/downstream-packaging.rst | 32 ++++++++++-----------
 1 file changed, 15 insertions(+), 17 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 984816c14..fc9514ade 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -73,10 +73,10 @@ a few important reasons to provide a static archive file instead:
   supported than e.g. using a git clone. This can help users with poor
   Internet connectivity.
 
-- Downstreams often **use checksums to verify the authenticity** of source files
+- Downstreams often use hashes to verify the authenticity of source files
   on subsequent builds, which require that they remain bitwise identical over
   time. For example, automatically generated git archives do not guarantee
-  that.
+  this, as the compressed data may change if gzip is upgraded on the server.
 
 - Archive files can be mirrored, reducing both upstream and downstream
   bandwidth use. The actual builds can afterwards be performed in firewalled
@@ -132,8 +132,8 @@ is discouraged for a number of reasons:
   unavailable, making the build no longer possible. This is especially
   problematic when someone needs to build an old package version.
 
-- Accessing remote servers poses a **privacy** issue and a potential
-  **security** issue, as it exposes information about the system building
+- Accessing remote servers poses a privacy issue and a potential
+  security issue, as it exposes information about the system building
   the package.
 
 - The user may be using a service with a limited data plan, in which
@@ -153,8 +153,8 @@ When such a switch is used, the build process should fail if some
 of the required files are missing, rather than try to fetch them automatically.
 This could be done e.g. by checking whether a ``NO_NETWORK`` environment
 variable is set to a non-empty value. Please also remember that if you are
-fetching remote resources, you must **verify their authenticity**, e.g. against
-a checksum, to protect against the file being substituted by a malicious party.
+fetching remote resources, you must *verify their authenticity* (usually against
+a hash), to protect against the file being substituted by a malicious party.
 
 Since downstreams frequently also run tests and build documentation, the above
 should ideally extend to these processes as well.
@@ -165,11 +165,9 @@ should ideally extend to these processes as well.
 Support building against system dependencies
 --------------------------------------------
 
-
 Why?
 ~~~~
 
-
 Some Python projects have non-Python dependencies, such as libraries written
 in C or C++. Trying to use the system versions of these dependencies
 in upstream packaging may cause a number of problems for end users:
@@ -237,7 +235,6 @@ In particular:
 How?
 ~~~~
 
-
 A good compromise between the needs of both parties is to provide a switch
 between using vendored and system dependencies. Ideally, if the package has
 multiple vendored dependencies, it should provide both individual switches
@@ -266,11 +263,9 @@ are better equipped to handle.
 Support downstream testing
 --------------------------
 
-
 Why?
 ~~~~
 
-
 A variety of downstream projects run some degree of testing on the packaged
 Python projects. Depending on the particular case, this can range from minimal
 smoke testing to comprehensive runs of the complete test suite. There can
@@ -287,7 +282,7 @@ be various reasons for doing this, for example:
   the ones present during upstream release testing.
 
 - Testing the package in an environment closely resembling the production
-  setup. This can detect issues caused by nontrivial interactions between
+  setup. This can detect issues caused by non-trivial interactions between
   different installed packages, including packages that are not dependencies
   of your package, but nevertheless can cause issues.
 
@@ -297,15 +292,14 @@ be various reasons for doing this, for example:
 Admittedly, sometimes downstream testing may yield false positives or bug
 reports about scenarios the upstream project is not interested in supporting.
 However, perhaps even more often it does provide early notice of problems,
-or find nontrivial bugs that would otherwise cause issues for your users
-in production. And believe me, the majority of **downstream packagers are doing
-their best to double-check their results, and help you triage and fix the bugs
-that they report**.
+or find non-trivial bugs that would otherwise cause issues for the upstream
+project's users. While mistakes do happen, the majority of downstream packagers
+are doing their best to double-check their results, and help upstream
+maintainers triage and fix the bugs that they reported.
 
 How?
 ~~~~
 
-
 There are a number of things that upstream projects can do to help downstream
 repackagers test their packages efficiently and effectively, including some of the suggestions
 already mentioned above. These are typically improvements that make the test suite more
@@ -367,6 +361,10 @@ Some specific suggestions are:
   the ability to conveniently deselect tests, rerun flaky tests
   (via pytest-rerunfailures_), add a timeout to prevent tests from hanging
   (via pytest-timeout_) or run tests in parallel (via pytest-xdist_).
+  Note that test suites don't need to be *written* with ``pytest`` to be
+  *executed* with ``pytest``: ``pytest`` is able to find and execute almost
+  all test cases that are compatible with the standard library's ``unittest``
+  test discovery.
 
 
 .. _responses: https://pypi.org/project/responses/

From df0c91a6f379ef4139b632c3f5aebdcb46e8ea58 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Thu, 30 Jan 2025 20:20:01 +0100
Subject: [PATCH 543/733] Add a section on stable channels

---
 source/discussions/downstream-packaging.rst | 66 +++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index fc9514ade..edb21dcc9 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -367,6 +367,71 @@ Some specific suggestions are:
   test discovery.
 
 
+.. _aim-for-stable-releases:
+
+Aim for stable releases
+-----------------------
+
+Why?
+~~~~
+
+Many downstreams provide stable release channels in addition to the main
+package streams. The goal of these channels is to provide more conservative
+upgrades to users with higher stability needs. These users often prefer
+to trade having the newest features available for lower risk of issues.
+
+While the exact policies differ, an important criterion for including a new
+package version in a stable release channel is for it to be available in testing
+for some time already, and have no known major regressions. For example,
+in Gentoo Linux a package is usually marked stable after being available
+in testing for a month, and being tested against the versions of its
+dependencies that are marked stable at the time.
+
+However, there are circumstances which demand more prompt action. For example,
+if a security vulnerability or a major bug is found in the version that is
+currently available in the stable channel, the downstream is facing a need
+to resolve it. In this case, they need to consider various options, such as:
+
+- putting a new version in the stable channel early,
+
+- adding patches to the version currently published,
+
+- or even downgrading the stable channel to an earlier release.
+
+Each of these options involves certain risks and a certain amount of work,
+and packagers needs to weigh them to determine the course of action.
+
+How?
+~~~~
+
+There are some things that upstreams can do to tailor their workflow to stable
+release channels. These actions often are beneficial to the package's users
+as well. Some specific suggestions are:
+
+- Adjust the release frequency to the rate of code changes. Packages that
+  are released rarely often bring significant changes with every release,
+  and a higher risk of accidental regressions.
+
+- Avoid mixing bug fixes and new features, if possible. In particular, if there
+  are known bug fixes merged already, consider making a new release before
+  merging feature branches.
+
+- Consider making prereleases after major changes, to provide more testing
+  opportunities for users and downstreams willing to opt-in.
+
+- If your project is subject to very intense development, consider splitting
+  one or more branches that include a more conservative subset of commits,
+  and are released separately. For example, Django_ currently maintains three
+  release branches in addition to main.
+
+- Even if you don't wish to maintain additional branches permanently, consider
+  making additional patch releases with minimal changes to the previous
+  version, especially when a security vulnerability is discovered.
+
+- Split your changes into focused commits that address one problem at a time,
+  to make it easier to cherry-pick changes to earlier releases when necessary.
+
+
 .. _responses: https://pypi.org/project/responses/
 .. _vcrpy: https://pypi.org/project/vcrpy/
 .. _pytest-socket: https://pypi.org/project/pytest-socket/
@@ -374,3 +439,4 @@ Some specific suggestions are:
 .. _pytest: https://pytest.org/
 .. _pytest-rerunfailures: https://pypi.org/project/pytest-rerunfailures/
 .. _pytest-timeout: https://pypi.org/project/pytest-timeout/
+.. _Django: https://www.djangoproject.com/

From fc72a38cc39b1590e752d1181118c5a073bcb813 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Fri, 31 Jan 2025 15:41:16 +0100
Subject: [PATCH 544/733] Retitle as "Supporting downstream packaging"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Thanks to @pfmoore for the suggestion.

Signed-off-by: Michał Górny 
---
 source/discussions/downstream-packaging.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index edb21dcc9..1ff735e99 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -1,8 +1,8 @@
 .. _downstream-packaging:
 
-=================================
-Simplifying downstream packaging
-=================================
+===============================
+Supporting downstream packaging
+===============================
 
 :Page Status: Draft
 :Last Reviewed: 2025-?

From 24462f4b05c838219b1fe9327caff32bbdd05a61 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Fri, 31 Jan 2025 15:42:51 +0100
Subject: [PATCH 545/733] Add a "not all-or-nothing" sentence
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Suggested by @pfmoore on https://discuss.python.org/t/request-for-feedback-packaging-p-o-discussion-on-helping-downstream-packaging/78985/2

Signed-off-by: Michał Górny 
---
 source/discussions/downstream-packaging.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 1ff735e99..d3df25ad1 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -21,6 +21,8 @@ and what additional challenges downstream packagers typically face. It aims
 to provide some optional guidelines that project maintainers may choose to
 follow which help make downstream packaging *significantly* easier
 (without imposing any major maintenance hassles on the upstream project).
+Note that this is not an all-or-nothing proposal — anything that upstream
+maintainers can do is useful, even if it's only a small part.
 
 Establishing a good relationship between software maintainers and downstream
 packagers can bring mutual benefits. Downstreams are often willing to share

From 29cc38acf6ac0649b88ec00d68165b3ec8dc25b2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Fri, 31 Jan 2025 15:53:41 +0100
Subject: [PATCH 546/733] Add a note that downstreams can send patches to fix
 these issues

---
 source/discussions/downstream-packaging.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index d3df25ad1..c4934b802 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -22,7 +22,8 @@ to provide some optional guidelines that project maintainers may choose to
 follow which help make downstream packaging *significantly* easier
 (without imposing any major maintenance hassles on the upstream project).
 Note that this is not an all-or-nothing proposal — anything that upstream
-maintainers can do is useful, even if it's only a small part.
+maintainers can do is useful, even if it's only a small part. Downstream
+maintainers are also willing to prepare patches to resolve these issues.
 
 Establishing a good relationship between software maintainers and downstream
 packagers can bring mutual benefits. Downstreams are often willing to share

From 9d5fbe6d212f0e50b6963594aec0128a1b0d999f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sat, 1 Feb 2025 15:44:41 +0100
Subject: [PATCH 547/733] Capitalize Git, per @pawamoy

---
 source/discussions/downstream-packaging.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index c4934b802..bc5edbf4d 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -69,16 +69,16 @@ source distributions may include:
 
 - having a consistent build process across all Python packages
 
-While it is usually possible to build packages from a git repository, there are
+While it is usually possible to build packages from a Git repository, there are
 a few important reasons to provide a static archive file instead:
 
 - Fetching a single file is often more efficient, more reliable and better
-  supported than e.g. using a git clone. This can help users with poor
+  supported than e.g. using a Git clone. This can help users with poor
   Internet connectivity.
 
 - Downstreams often use hashes to verify the authenticity of source files
   on subsequent builds, which require that they remain bitwise identical over
-  time. For example, automatically generated git archives do not guarantee
+  time. For example, automatically generated Git archives do not guarantee
   this, as the compressed data may change if gzip is upgraded on the server.
 
 - Archive files can be mirrored, reducing both upstream and downstream
@@ -88,7 +88,7 @@ a few important reasons to provide a static archive file instead:
 
 - Explicitly publishing archive files can ensure that any dependencies on version control
   system metadata are resolved when creating the source archive. For example, automatically
-  generated git archives omit all of the commit tag information, potentially resulting in
+  generated Git archives omit all of the commit tag information, potentially resulting in
   incorrect version details in the resulting builds.
 
 How?
@@ -108,7 +108,7 @@ separate archives.
 
 A good idea is to **use your source distribution in the release workflow**.
 That is, build it first, then unpack it and perform all the remaining steps
-using the unpacked distribution rather than the git repostiry — run tests,
+using the unpacked distribution rather than the Git repostiry — run tests,
 build documentation, build wheels. This ensures that it is well-tested,
 and reduces the risk that some users would hit build failures or install
 an incomplete package.

From 4d95da2cf538aec9f8eb81cc239a0a7279e9aee0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sat, 1 Feb 2025 15:46:23 +0100
Subject: [PATCH 548/733] Fix inconsistent case in bullet points and remove
 duplicate

Thanks to @pawamoy
---
 source/discussions/downstream-packaging.rst | 22 +++++++++------------
 1 file changed, 9 insertions(+), 13 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index bc5edbf4d..9110b1f82 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -55,19 +55,19 @@ rather than use the upstream-provided binary packages. This is also true
 of pure Python packages that provide universal wheels. The reasons for using
 source distributions may include:
 
-- being able to audit the source code of all packages
+- Being able to audit the source code of all packages.
 
-- being able to run the test suite and build documentation
+- Being able to run the test suite and build documentation.
 
-- being able to easily apply patches, including backporting commits
-  from the project's repository and sending patches back to the project
+- Being able to easily apply patches, including backporting commits
+  from the project's repository and sending patches back to the project.
 
-- being able to build on a specific platform that is not covered
-  by upstream builds
+- Being able to build on a specific platform that is not covered
+  by upstream builds.
 
-- being able to build against specific versions of system libraries
+- Being able to build against specific versions of system libraries.
 
-- having a consistent build process across all Python packages
+- Having a consistent build process across all Python packages.
 
 While it is usually possible to build packages from a Git repository, there are
 a few important reasons to provide a static archive file instead:
@@ -205,11 +205,7 @@ However, none of these issues apply to downstream packaging, and downstreams
 have good reasons to prefer dynamically linking to system dependencies.
 In particular:
 
-- in many cases, reliably sharing dynamic dependencies between components is a large part
-  of the *purpose* of a downstream packaging ecosystem. Helping to support that makes it
-  easier for users of those systems to access upstream projects in their preferred format.
-
-- in many cases, reliably sharing dynamic dependencies between components is a large part
+- In many cases, reliably sharing dynamic dependencies between components is a large part
   of the *purpose* of a downstream packaging ecosystem. Helping to support that makes it
   easier for users of those systems to access upstream projects in their preferred format.
 

From 6f557097a422beb7d81a3bcb245a3e5569a16c8e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sat, 1 Feb 2025 15:52:59 +0100
Subject: [PATCH 549/733] Apply typo fixes, thanks to @pawamoy

---
 source/discussions/downstream-packaging.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 9110b1f82..3aef888f4 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -99,7 +99,7 @@ necessary to build the package itself, run its test suite, build and install
 its documentation, and any other files that may be useful to end users, such as
 shell completions, editor support files, and so on.
 
-Some projects are concerned about increasing the size of source distribution,
+Some projects are concerned about increasing the size of source distributions,
 or do not wish Python packaging tools to fall back to source distributions
 automatically.  In these cases, a good compromise may be to publish a separate
 source archive for downstream use, for example by attaching it to a GitHub
@@ -108,7 +108,7 @@ separate archives.
 
 A good idea is to **use your source distribution in the release workflow**.
 That is, build it first, then unpack it and perform all the remaining steps
-using the unpacked distribution rather than the Git repostiry — run tests,
+using the unpacked distribution rather than the Git repository — run tests,
 build documentation, build wheels. This ensures that it is well-tested,
 and reduces the risk that some users would hit build failures or install
 an incomplete package.

From 548ab343b608b6885190f23d75d6f29bbf0ff1e3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sat, 1 Feb 2025 16:09:41 +0100
Subject: [PATCH 550/733] Clarify that source distribution needs only package's
 files

Let's add some clarification to the "complete source distribution" part
to make it clear that we're talking only of package's files, and not
requiring people to vendor all the dependencies.
---
 source/discussions/downstream-packaging.rst | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 3aef888f4..ae4dc5235 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -94,10 +94,19 @@ a few important reasons to provide a static archive file instead:
 How?
 ~~~~
 
-Ideally, **a source distribution archive should include all the files**
-necessary to build the package itself, run its test suite, build and install
-its documentation, and any other files that may be useful to end users, such as
-shell completions, editor support files, and so on.
+Ideally, **a source distribution archive should include all the files
+from the package's Git repository** that are necessary to build the package
+itself, run its test suite, build and install its documentation, and any other
+files that may be useful to end users, such as shell completions, editor
+support files, and so on.
+
+This point applies only to the files belonging to the package itself.
+The downstream packaging process, much like Python package managers, will
+provision the necessary Python dependencies, system tools and external
+libraries that are needed by your package and its build scripts. However,
+the files listing these dependencies (for example, ``requirements*.txt`` files)
+should also be included, to help downstreams determine the needed dependencies,
+and check for changes in them.
 
 Some projects are concerned about increasing the size of source distributions,
 or do not wish Python packaging tools to fall back to source distributions

From e925da1d066140ee628068f9438ec43def11556d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sat, 1 Feb 2025 16:10:39 +0100
Subject: [PATCH 551/733] Fix inconsistent whitespace between sentences

---
 source/discussions/downstream-packaging.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index ae4dc5235..ec6b782d3 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -110,7 +110,7 @@ and check for changes in them.
 
 Some projects are concerned about increasing the size of source distributions,
 or do not wish Python packaging tools to fall back to source distributions
-automatically.  In these cases, a good compromise may be to publish a separate
+automatically. In these cases, a good compromise may be to publish a separate
 source archive for downstream use, for example by attaching it to a GitHub
 release. Alternatively, large files, such as test data, can be split into
 separate archives.
@@ -206,7 +206,7 @@ in upstream packaging may cause a number of problems for end users:
 
 For these reasons, you may reasonably decide to either statically link
 your dependencies, or to provide local copies in the installed package.
-You may also vendor the dependency in your source distribution.  Sometimes
+You may also vendor the dependency in your source distribution. Sometimes
 these dependencies are also repackaged on PyPI, and can be declared as
 project dependencies like any other Python package.
 
@@ -325,7 +325,7 @@ Some specific suggestions are:
 - Make the test suite work offline. Mock network interactions, using
   packages such as responses_ or vcrpy_. If that is not possible, make it
   possible to easily disable the tests using Internet access, e.g. via a pytest_
-  marker.  Use pytest-socket_ to verify that your tests work offline. This
+  marker. Use pytest-socket_ to verify that your tests work offline. This
   often makes your own test workflows faster and more reliable as well.
 
 - Make your tests work without a specialized setup, or perform the necessary

From 0eb407c94d61a253cfe5a89fb0868ed0e4eb9d02 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sat, 1 Feb 2025 16:28:51 +0100
Subject: [PATCH 552/733] Make the point of reusing source distribution lighter

Split the reuse of source distribution into two parts: the easier part
of building a wheel from sdist (which is what build tool does),
and the harder part of using it in all workflows. For the latter,
suggest it's fine to let downstreams worry about that.
---
 source/discussions/downstream-packaging.rst | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index ec6b782d3..5ec53a354 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -115,12 +115,16 @@ source archive for downstream use, for example by attaching it to a GitHub
 release. Alternatively, large files, such as test data, can be split into
 separate archives.
 
-A good idea is to **use your source distribution in the release workflow**.
-That is, build it first, then unpack it and perform all the remaining steps
-using the unpacked distribution rather than the Git repository — run tests,
-build documentation, build wheels. This ensures that it is well-tested,
-and reduces the risk that some users would hit build failures or install
-an incomplete package.
+A good idea is to use your source distribution in the release workflow.
+For example, the :ref:`build` tool does exactly that — it first builds a source
+distribution, and then uses it to build a wheel. This ensures that the source
+distribution actually works, and that it won't accidentally install fewer files
+than the official wheels.
+
+Ideally, use the source distribution also run tests, build documentation,
+and so on, or add specific tests to make sure that all necessary files were
+actually included. Understandably, this requires more effort, so it's fine
+not do that — downstream packagers will report any missing files promptly.
 
 
 .. _no-internet-access-in-builds:

From 94743f973b2b68af2c3d16614e8aa4ab4edc52c4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sat, 1 Feb 2025 16:45:34 +0100
Subject: [PATCH 553/733] Clarify the Internet part

Clarify the "do not use the Internet" part to make it clearer that we're
talking about backend actions, and custom build scripts in particular.
We're not talking of Python dependencies that are fetched and installed
by frontends.  Also, reflow the text to be more logical.
---
 source/discussions/downstream-packaging.rst | 40 +++++++++++++--------
 1 file changed, 26 insertions(+), 14 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 5ec53a354..67ed491bf 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -136,9 +136,12 @@ Why?
 ~~~~
 
 Downstream builds are frequently done in sandboxed environments that cannot
-access the Internet. Even if this is not the case, and assuming that you took
-sufficient care to properly authenticate downloads, using the Internet
-is discouraged for a number of reasons:
+access the Internet. The package sources are unpacked into this environment,
+and all the necessary dependencies are installed.
+
+Even if this is not the case, and assuming that you took sufficient care to
+properly authenticate downloads, using the Internet is discouraged for a number
+of reasons:
 
 - The Internet connection may be unstable (e.g. due to poor reception)
   or suffer from temporary problems that could cause the process to fail
@@ -159,22 +162,31 @@ is discouraged for a number of reasons:
 How?
 ~~~~
 
-Your source distribution should either include all the files needed
-for the package to build, or allow provisioning them externally. Ideally,
-it should not even attempt to access the Internet at all, unless explicitly
-requested to. If that is not possible to achieve, the next best thing
-is to provide an opt-out switch to disable all Internet access.
+If the package is implementing any custom build *backend* actions that use
+the Internet, for example by automatically downloading vendored dependencies
+or fetching Git submodules, its source distribution should either include all
+of these files or allow provisioning them externally, and the Internet must not
+be used if the files are already present.
+
+Note that this point does not apply to Python dependencies that are specified
+in the package metadata, and are fetched during the build and installation
+process by *frontends* (such as :ref:`build` or :ref:`pip`). Downstreams use
+frontends that use local provisioning for Python dependencies.
 
-When such a switch is used, the build process should fail if some
-of the required files are missing, rather than try to fetch them automatically.
-This could be done e.g. by checking whether a ``NO_NETWORK`` environment
-variable is set to a non-empty value. Please also remember that if you are
-fetching remote resources, you must *verify their authenticity* (usually against
-a hash), to protect against the file being substituted by a malicious party.
+Ideally, custom build scripts should not even attempt to access the Internet
+at all, unless explicitly requested to. If any resources are missing and need
+to be fetched, they should ask the user for permission first. If that is not
+feasible, the next best thing is to provide an opt-out switch to disable
+all Internet access. This could be done e.g. by checking whether
+a ``NO_NETWORK`` environment variable is set to a non-empty value.
 
 Since downstreams frequently also run tests and build documentation, the above
 should ideally extend to these processes as well.
 
+Please also remember that if you are fetching remote resources, you absolutely
+must *verify their authenticity* (usually against a hash), to protect against
+the file being substituted by a malicious party.
+
 
 .. _support-system-dependencies-in-builds:
 

From 704d1a575d0950d6bedd9722dcf73b439c325c89 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sat, 1 Feb 2025 19:38:29 +0000
Subject: [PATCH 554/733] Apply suggestions from code review

Co-authored-by: Jelle Zijlstra 
---
 source/discussions/downstream-packaging.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 67ed491bf..118d04a4c 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -121,7 +121,7 @@ distribution, and then uses it to build a wheel. This ensures that the source
 distribution actually works, and that it won't accidentally install fewer files
 than the official wheels.
 
-Ideally, use the source distribution also run tests, build documentation,
+Ideally, also use the source distribution to run tests, build documentation,
 and so on, or add specific tests to make sure that all necessary files were
 actually included. Understandably, this requires more effort, so it's fine
 not do that — downstream packagers will report any missing files promptly.
@@ -271,7 +271,7 @@ message rather than fall back to a vendored version. This gives the packager
 the opportunity to notice their mistake and a chance to consciously decide
 how to solve it.
 
-Note that it is reasonable for upstream projects to leave *testing* of building with
+It is reasonable for upstream projects to leave *testing* of building with
 system dependencies to their downstream repackagers. The goal of these guidelines
 is to facilitate more effective collaboration between upstream projects and downstream
 repackagers, not to suggest upstream projects take on tasks that downstream repackagers

From e5966091ec6981157255f1a4651d05e7c9f5d7f7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sat, 1 Feb 2025 20:57:23 +0100
Subject: [PATCH 555/733] Remove duplicate paragraph

---
 source/discussions/downstream-packaging.rst | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 118d04a4c..e29cf08fe 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -276,11 +276,6 @@ system dependencies to their downstream repackagers. The goal of these guideline
 is to facilitate more effective collaboration between upstream projects and downstream
 repackagers, not to suggest upstream projects take on tasks that downstream repackagers
 are better equipped to handle.
-Note that it is reasonable for upstream projects to leave *testing* of building with
-system dependencies to their downstream repackagers. The goal of these guidelines
-is to facilitate more effective collaboration between upstream projects and downstream
-repackagers, not to suggest upstream projects take on tasks that downstream repackagers
-are better equipped to handle.
 
 .. _support-downstream-testing:
 

From 169281d98494cc662ae0b00243d454dc394ec2b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sat, 1 Feb 2025 20:57:35 +0100
Subject: [PATCH 556/733] Clarify source distributions

Clarify that "source distributions" generally refer to the files
published on PyPI, and when we are referring to publishing them
elsewhere.  While at it, expand on the size/fallback argument,
and mention that some projects install tests as part of the Python
package.
---
 source/discussions/downstream-packaging.rst | 27 +++++++++++++++------
 1 file changed, 20 insertions(+), 7 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index e29cf08fe..6e69ca4af 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -94,7 +94,7 @@ a few important reasons to provide a static archive file instead:
 How?
 ~~~~
 
-Ideally, **a source distribution archive should include all the files
+Ideally, **a source distribution archive published on PyPI should include all the files
 from the package's Git repository** that are necessary to build the package
 itself, run its test suite, build and install its documentation, and any other
 files that may be useful to end users, such as shell completions, editor
@@ -108,12 +108,22 @@ the files listing these dependencies (for example, ``requirements*.txt`` files)
 should also be included, to help downstreams determine the needed dependencies,
 and check for changes in them.
 
-Some projects are concerned about increasing the size of source distributions,
-or do not wish Python packaging tools to fall back to source distributions
-automatically. In these cases, a good compromise may be to publish a separate
-source archive for downstream use, for example by attaching it to a GitHub
-release. Alternatively, large files, such as test data, can be split into
-separate archives.
+Some projects have concerns related to Python package managers using source
+distributions from PyPI. They do not wish to increase their size with files
+that are not used by these tools, or they do not wish to publish source
+distributions at all, as they enable a problematic or outright nonfunctional
+fallback to building the particular project from source. In these cases, a good
+compromise may be to publish a separate source archive for downstream use
+elsewhere, for example by attaching it to a GitHub release. Alternatively,
+large files, such as test data, can be split into separate archives.
+
+On the other hand, some projects (NumPy_, for instance) decide to install tests
+in their Python packages. This has the added advantage of permitting users to
+run tests after installing them, for example to check for regressions
+after upgrading a dependency. Yet another approach is to split tests or test
+data into a separate Python package. Such an approach was taken by
+the cryptography_ project, with the large test vectors being split
+to cryptography-vectors_ package.
 
 A good idea is to use your source distribution in the release workflow.
 For example, the :ref:`build` tool does exactly that — it first builds a source
@@ -459,3 +469,6 @@ as well. Some specific suggestions are:
 .. _pytest-rerunfailures: https://pypi.org/project/pytest-rerunfailures/
 .. _pytest-timeout: https://pypi.org/project/pytest-timeout/
 .. _Django: https://www.djangoproject.com/
+.. _NumPy: https://numpy.org/
+.. _cryptography: https://pypi.org/project/cryptography/
+.. _cryptography-vectors: https://pypi.org/project/cryptography-vectors/

From bb8ac35a866e807823770e4effab785cdb39f444 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sat, 1 Feb 2025 20:58:38 +0100
Subject: [PATCH 557/733] Add non-reproducibility argument for changing
 resources

---
 source/discussions/downstream-packaging.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 6e69ca4af..5fbab130f 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -161,6 +161,8 @@ of reasons:
   unavailable, making the build no longer possible. This is especially
   problematic when someone needs to build an old package version.
 
+- The remote resources may change, making the build not reproducible.
+
 - Accessing remote servers poses a privacy issue and a potential
   security issue, as it exposes information about the system building
   the package.

From addf891979a8600e75a111568b04cdf058087b5b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sun, 2 Feb 2025 14:51:50 +0100
Subject: [PATCH 558/733] Mention removing duplication of patches and
 inconsistency

---
 source/discussions/downstream-packaging.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 5fbab130f..3a08cf2a7 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -24,6 +24,9 @@ follow which help make downstream packaging *significantly* easier
 Note that this is not an all-or-nothing proposal — anything that upstream
 maintainers can do is useful, even if it's only a small part. Downstream
 maintainers are also willing to prepare patches to resolve these issues.
+Having these patches merged can be very helpful, since it removes the need
+for different downstreams to carry and keep rebasing the same patches,
+and the risk of applying inconsistent solutions to the same problem.
 
 Establishing a good relationship between software maintainers and downstream
 packagers can bring mutual benefits. Downstreams are often willing to share

From 8a3a56c4e4d9f030962ca3b5fb89704ebd302ffc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sun, 2 Feb 2025 14:52:10 +0100
Subject: [PATCH 559/733] Reword installing tests to make it clearer

---
 source/discussions/downstream-packaging.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 3a08cf2a7..723b3fe75 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -120,8 +120,8 @@ compromise may be to publish a separate source archive for downstream use
 elsewhere, for example by attaching it to a GitHub release. Alternatively,
 large files, such as test data, can be split into separate archives.
 
-On the other hand, some projects (NumPy_, for instance) decide to install tests
-in their Python packages. This has the added advantage of permitting users to
+On the other hand, some projects (NumPy_, for instance) decide to include tests
+in their installed packages. This has the added advantage of permitting users to
 run tests after installing them, for example to check for regressions
 after upgrading a dependency. Yet another approach is to split tests or test
 data into a separate Python package. Such an approach was taken by

From 58eaf854f6b53dff449d3bf93bef8f70854428df Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sun, 2 Feb 2025 14:52:28 +0100
Subject: [PATCH 560/733] Give an example of "catastrophic failure"

---
 source/discussions/downstream-packaging.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index 723b3fe75..d25845e47 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -266,7 +266,8 @@ In particular:
   same library being loaded in the same process (for example, attempting to
   import two Python packages that link to different versions of the same library).
   This sometimes works without incident, but it can also lead to anything from library
-  loading errors, to subtle runtime bugs, to catastrophic system failures.
+  loading errors, to subtle runtime bugs, to catastrophic failures (like suddenly
+  crashing and losing data).
 
 - Last but not least, static linking and vendoring results in duplication,
   and may increase the use of both disk space and memory.

From 54c2002d5f9dd6fca7069568782cfd2ea346954c Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Tue, 4 Feb 2025 21:18:09 +0100
Subject: [PATCH 561/733] simple-repository-api: bump, explain api-version

Signed-off-by: William Woodruff 
---
 source/specifications/simple-repository-api.rst | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
index 9ec8e4bf2..a96e4e7a8 100644
--- a/source/specifications/simple-repository-api.rst
+++ b/source/specifications/simple-repository-api.rst
@@ -101,6 +101,10 @@ In addition to the above, the following constraints are placed on the API:
   the file's provenance can be found at that URL. This URL **MUST** represent
   a `secure origin `_.
 
+  .. note::
+
+    The ``data-provenance`` attribute was added with API version 1.3.
+
   .. note::
 
     The format of the linked provenance is defined in :ref:`index-hosted-attestations`.
@@ -213,7 +217,7 @@ specification `.
 
 This would end up looking like::
 
-  
+  
 
 When interpreting the repository version:
 
@@ -405,7 +409,7 @@ As an example:
 
     {
       "meta": {
-        "api-version": "1.0"
+        "api-version": "1.3"
       },
       "projects": [
         {"name": "Frob"},
@@ -509,13 +513,17 @@ Each individual file dictionary has the following keys:
   associated provenance, with the same rules as ``data-provenance`` in the
   :ref:`base HTML API specification `.
 
+  .. note::
+
+    The ``provenance`` field was added with API version 1.3.
+
 As an example:
 
 .. code-block:: json
 
     {
       "meta": {
-        "api-version": "1.0"
+        "api-version": "1.3"
       },
       "name": "holygrail",
       "files": [

From 620404673b387f45be3c4ab51720ec21bcda6671 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee 
Date: Wed, 5 Feb 2025 09:46:06 +0800
Subject: [PATCH 562/733] Document iOS, Android and macOS platform tag schemes.

---
 .../platform-compatibility-tags.rst           | 67 +++++++++++++++++--
 1 file changed, 63 insertions(+), 4 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 3679cf4ad..08ea9e4ce 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -109,8 +109,8 @@ subset of Linux platforms, and allows building wheels tagged with the
 ``manylinux`` platform tag which can be used across most common Linux
 distributions.
 
-The current standard is the future-proof ``manylinux_x_y`` standard. It defines
-tags of the form ``manylinux_x_y_arch``, where ``x`` and ``y`` are glibc major
+The current standard is the future-proof ``manylinux__`` standard. It defines
+tags of the form ``manylinux___``, where ``x`` and ``y`` are glibc major
 and minor versions supported (e.g. ``manylinux_2_24_xxx`` should work on any
 distro using glibc 2.24+), and ``arch`` is the architecture, matching the value
 of :py:func:`sysconfig.get_platform()` on the system as in the "simple" form above.
@@ -151,7 +151,7 @@ auditwheel  ``>=1.0.0``     ``>=2.0.0``        ``>=3.0.0``        ``>=3.3.0`` [#
 
 The ``musllinux`` family of tags is similar to ``manylinux``, but for Linux
 platforms that use the musl_ libc rather than glibc (a prime example being Alpine
-Linux). The schema is ``musllinux_x_y_arch``, supporting musl ``x.y`` and higher
+Linux). The schema is ``musllinux___``, supporting musl ``x.y`` and higher
 on the architecture ``arch``.
 
 The musl version values can be obtained by executing the musl libc shared
@@ -189,6 +189,64 @@ There are currently two possible ways to find the musl library’s location that
 Python interpreter is running on, either with the system ldd_ command, or by
 parsing the ``PT_INTERP`` section’s value from the executable’s ELF_ header.
 
+.. _macos:
+
+macOS
+-----
+
+macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical
+artefact of Apple's official macOS naming scheme). The schema for compatibility
+tags is ``macosx___``, indicating that the wheel is compatible with
+macOS ``x.y`` or later on the architecture ``arch``. The version number always
+includes a major and minor version, even if Apple's official version numbering
+only refers to the major value. For example, a ``macosx_11_0_arm64`` indicates
+compatibility with macOS 11 or later, on arm64 (i.e., Apple Silicon) hardware.
+
+Recent macOS binaries distributed on Python.org are compiled with a minimum
+macOS compatibility version of 11.0, as macOS 11 (Big Sur) was the first release
+to support the ARM64 Apple Silicon architecture. Python binaries obtained from
+other sources may have a different compatibility version.
+
+macOS also supports the use of a combined, or "fat" architecture specification.
+For example, specifying an architecture of ``universal2`` indicates that
+binaries support *both* x86_64 *and* arm64.
+
+.. _android:
+
+android
+-------
+
+Android uses the schema ``android__``, indicating compatibility with
+Android SDK ``sdk`` or later, on the architecture ``arch``. Android makes no
+distinction between physical devices and emulated devices.
+
+Note that this tag schema uses the *SDK* version, not the Android OS version
+number. The Android release known publicly as Android 12 (code named "Snow
+Cone") uses SDK 31 or 32, depending on the specific Android version in use.
+Android's release documentation contains the `full list of Android versions and
+their corresponding SDK versions
+`__.
+
+By default, Python 3.13 is compiled using SDK 24 (i.e, Android 7); Python 3.14
+uses SDK 27 (i.e, Android 8.1).
+
+.. _ios:
+
+iOS
+---
+
+iOS uses the schema ``ios____``, indicating compatibility with
+iOS ``x.y`` or later, on the ``arch`` architecture, using the ``sdk`` SDK. The
+version number always includes a major and minor version, even if Apple's
+official version numbering only refers to the major value.
+
+The iOS platform has two SDKs: ``iphoneos`` for physical devices; and
+``iphonesimulator`` for simulated devices. These SDKs have the same API surface,
+but are incompatible at the binary level, even if they are running on the same
+architecture. Code compiled for an arm64 simulator will not run on an arm64
+device.
+
+By default, Python is compiled with a minimum iOS compatibility version of 13.0.
 
 Use
 ===
@@ -339,7 +397,8 @@ History
 - November 2019: The ``manylinux_x_y`` perennial tag was approved through
   :pep:`600`.
 - April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`.
-
+- December 2023: The tags for iOS were approved through :pep:`730`.
+- March 2024: The tags for Android were approved through :pep:`738`.
 
 
 .. _musl: https://musl.libc.org

From 0347e3f8c3b58f06159a52da2364ad1d9e580bca Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee 
Date: Wed, 5 Feb 2025 11:27:17 +0800
Subject: [PATCH 563/733] Add explicit details about supported architectures.

---
 source/specifications/platform-compatibility-tags.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 08ea9e4ce..6146aa86f 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -227,6 +227,12 @@ Android's release documentation contains the `full list of Android versions and
 their corresponding SDK versions
 `__.
 
+There are 4 supported architectures:
+* ``armeabi_v7a``
+* ``arm64_v8a``
+* ``x86``
+* ``x86_64``
+
 By default, Python 3.13 is compiled using SDK 24 (i.e, Android 7); Python 3.14
 uses SDK 27 (i.e, Android 8.1).
 
@@ -246,6 +252,9 @@ but are incompatible at the binary level, even if they are running on the same
 architecture. Code compiled for an arm64 simulator will not run on an arm64
 device.
 
+The ``iphonesimulator`` SDK supports 2 architectures: ``arm64`` and ``x86_64``.
+The ``iphoneos`` SDK only supports the ``arm64`` architecture.
+
 By default, Python is compiled with a minimum iOS compatibility version of 13.0.
 
 Use

From 4ad0c82ce969deac613ebc67319410c2b5c3a155 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee 
Date: Wed, 5 Feb 2025 13:44:56 +0800
Subject: [PATCH 564/733] Clarified details around macOS version compatibility.

---
 source/specifications/platform-compatibility-tags.rst | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 6146aa86f..17c51647f 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -202,15 +202,13 @@ includes a major and minor version, even if Apple's official version numbering
 only refers to the major value. For example, a ``macosx_11_0_arm64`` indicates
 compatibility with macOS 11 or later, on arm64 (i.e., Apple Silicon) hardware.
 
-Recent macOS binaries distributed on Python.org are compiled with a minimum
-macOS compatibility version of 11.0, as macOS 11 (Big Sur) was the first release
-to support the ARM64 Apple Silicon architecture. Python binaries obtained from
-other sources may have a different compatibility version.
-
 macOS also supports the use of a combined, or "fat" architecture specification.
 For example, specifying an architecture of ``universal2`` indicates that
 binaries support *both* x86_64 *and* arm64.
 
+The minimum supported macOS version may also be constrained by architecture. For
+example, macOS 11 (Big Sur) was the first release to support arm64.
+
 .. _android:
 
 android

From ac29cb8f701ee37568b9b457c37a9ce7a10867f2 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee 
Date: Wed, 5 Feb 2025 13:59:50 +0800
Subject: [PATCH 565/733] Additional note about macOS architecture constraints.

---
 source/specifications/platform-compatibility-tags.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 17c51647f..6a25fa6ab 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -207,7 +207,9 @@ For example, specifying an architecture of ``universal2`` indicates that
 binaries support *both* x86_64 *and* arm64.
 
 The minimum supported macOS version may also be constrained by architecture. For
-example, macOS 11 (Big Sur) was the first release to support arm64.
+example, macOS 11 (Big Sur) was the first release to support arm64. These
+additional constraints are enforced transparently by the macOS compilation
+toolchain when building a ``universal2`` binary.
 
 .. _android:
 

From 70698ad90b058a9d02494b46a6e685ce1cb65378 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns?= 
Date: Wed, 5 Feb 2025 16:28:19 +0000
Subject: [PATCH 566/733] specifications: add build-details.json (PEP 739)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Filipe Laíns 
---
 .github/CODEOWNERS                            |   4 +
 requirements.txt                              |   1 +
 source/conf.py                                |   2 +
 .../examples/build-details-v1.0.json          |  51 ++++
 source/specifications/build-details/index.rst |  52 ++++
 source/specifications/build-details/v1.0.rst  |  18 ++
 source/specifications/index.rst               |   1 +
 .../schemas/build-details-v1.0.schema.json    | 261 ++++++++++++++++++
 .../section-python-description-formats.rst    |   8 +
 9 files changed, 398 insertions(+)
 create mode 100644 source/specifications/build-details/examples/build-details-v1.0.json
 create mode 100644 source/specifications/build-details/index.rst
 create mode 100644 source/specifications/build-details/v1.0.rst
 create mode 100644 source/specifications/schemas/build-details-v1.0.schema.json
 create mode 100644 source/specifications/section-python-description-formats.rst

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 2d3e69fe8..ecd85064f 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -1,2 +1,6 @@
 source/guides/github-actions-ci-cd-sample/* @webknjaz
 source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @webknjaz
+
+# build-details.json
+source/specifications/build-details/ @FFY00
+source/specifications/specs/build-details-*.json @FFY00
diff --git a/requirements.txt b/requirements.txt
index a3269a025..5c710c86b 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -4,3 +4,4 @@ sphinx-autobuild==2021.3.14
 sphinx-inline-tabs==2023.4.21
 sphinx-copybutton==0.5.2
 sphinx-toolbox==3.5.0
+sphinx-jsonschema==1.19.1
diff --git a/source/conf.py b/source/conf.py
index c73dabdf2..317c89dbf 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -28,6 +28,7 @@
     "sphinx_inline_tabs",
     "sphinx_copybutton",
     "sphinx_toolbox.collapse",
+    "sphinx-jsonschema",
 ]
 
 nitpicky = True
@@ -128,6 +129,7 @@
 
 linkcheck_ignore = [
     "http://localhost:\\d+",
+    "https://packaging.python.org/en/latest/specifications/schemas/*",
     "https://test.pypi.org/project/example-package-YOUR-USERNAME-HERE",
     "https://pypi.org/manage/*",
     "https://test.pypi.org/manage/*",
diff --git a/source/specifications/build-details/examples/build-details-v1.0.json b/source/specifications/build-details/examples/build-details-v1.0.json
new file mode 100644
index 000000000..dd08b230f
--- /dev/null
+++ b/source/specifications/build-details/examples/build-details-v1.0.json
@@ -0,0 +1,51 @@
+{
+  "schema_version": "1.0",
+  "base_prefix": "/usr",
+  "base_interpreter": "/usr/bin/python",
+  "platform": "linux-x86_64",
+  "language": {
+    "version": "3.14",
+    "version_info": {
+      "major": 3,
+      "minor": 14,
+      "micro": 0,
+      "releaselevel": "alpha",
+      "serial": 0
+    }
+  },
+  "implementation": {
+    "name": "cpython",
+    "version": {
+      "major": 3,
+      "minor": 14,
+      "micro": 0,
+      "releaselevel": "alpha",
+      "serial": 0
+    },
+    "hexversion": 51249312,
+    "cache_tag": "cpython-314",
+    "_multiarch": "x86_64-linux-gnu"
+  },
+  "abi": {
+    "flags": ["t", "d"],
+    "extension_suffix": ".cpython-314-x86_64-linux-gnu.so",
+    "stable_abi_suffix": ".abi3.so"
+  },
+  "suffixes": {
+    "source": [".py"],
+    "bytecode": [".pyc"],
+    "optimized_bytecode": [".pyc"],
+    "debug_bytecode": [".pyc"],
+    "extensions": [".cpython-314-x86_64-linux-gnu.so", ".abi3.so", ".so"]
+  },
+  "libpython": {
+    "dynamic": "/usr/lib/libpython3.14.so.1.0",
+    "dynamic_stableabi": "/usr/lib/libpython3.so",
+    "static": "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a",
+    "link_extensions": true
+  },
+  "c_api": {
+    "headers": "/usr/include/python3.14",
+    "pkgconfig_path": "/usr/lib/pkgconfig"
+  }
+}
diff --git a/source/specifications/build-details/index.rst b/source/specifications/build-details/index.rst
new file mode 100644
index 000000000..bda4e0ba4
--- /dev/null
+++ b/source/specifications/build-details/index.rst
@@ -0,0 +1,52 @@
+.. _build-details:
+
+======================
+``build-details.json``
+======================
+
+.. toctree::
+   :hidden:
+
+   v1.0 
+
+
+The ``build-details.json`` file is a standardized file format that provides
+build-specfic information of a Python installation, such as its version,
+extension ABI details, and other information that is specific to that particular
+build of Python.
+
+Starting from Python 3.14, a ``build-details.json`` file is installed in the
+platform-independent standard library directory (``stdlib``, eg.
+``/usr/lib/python3.14/build-details.json``).
+
+Please refer to the :ref:`latest version ` for its
+specification.
+
+..
+   Update to point to the latest version!
+
+.. literalinclude:: examples/build-details-v1.0.json
+   :caption: Example
+   :language: json
+   :linenos:
+
+
+Changelog
+---------
+
+..
+   Order in decreasing order.
+
+v1.0
+~~~~
+
+.. list-table::
+
+    * - Specification
+      - :ref:`build-details-v1.0`
+
+    * - Schema
+      - https://packaging.python.org/en/latest/specifications/schemas/python-build-info-v1.0.schema.json
+
+
+- Initial version, introduced by :pep:`739`.
diff --git a/source/specifications/build-details/v1.0.rst b/source/specifications/build-details/v1.0.rst
new file mode 100644
index 000000000..cfe902e1e
--- /dev/null
+++ b/source/specifications/build-details/v1.0.rst
@@ -0,0 +1,18 @@
+.. _build-details-v1.0:
+
+===========================
+``build-details.json`` v1.0
+===========================
+
+
+Specification
+-------------
+
+.. jsonschema:: ../schemas/build-details-v1.0.schema.json
+    :lift_title: false
+
+
+Example
+-------
+
+.. literalinclude:: examples/build-details-v1.0.json
diff --git a/source/specifications/index.rst b/source/specifications/index.rst
index c8d2a3bed..c69605927 100644
--- a/source/specifications/index.rst
+++ b/source/specifications/index.rst
@@ -15,3 +15,4 @@ and for proposing new ones, is documented on
    section-installation-metadata
    section-distribution-formats
    section-package-indices
+   section-python-description-formats
diff --git a/source/specifications/schemas/build-details-v1.0.schema.json b/source/specifications/schemas/build-details-v1.0.schema.json
new file mode 100644
index 000000000..b088431b5
--- /dev/null
+++ b/source/specifications/schemas/build-details-v1.0.schema.json
@@ -0,0 +1,261 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://packaging.python.org/en/latest/specifications/schemas/python-build-info-v1.0.schema.json",
+  "type": "object",
+  "title": "build-details.json — a static description file with build details of Python installations",
+  "required": [
+    "schema_version",
+    "base_prefix",
+    "platform",
+    "language",
+    "implementation"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Schema version.\n\nThis is a string following the format ``.``, where ```` and ```` are unpaded numbers and represent the **major** and **minor** components of the version. Versions may be arithmetically compared by intrepreting the version string as a decimal number.\n\nFor this specification version, this value is constant and **MUST** be ``1.0``.\n\nFuture versions of this schema **MUST** use a higher version number. Future versions of this schema **MUST NOT** use the same **major** version component as other schema version unless its specification is deemed backwards-compatible with them — it can't change, or extend, any parts of the current specification in such a way as the semantics of the interpreted data differ, or that data valid under the new specification is invalid under the older specification, with the exception of additional properties (errors caused by ``additionalProperties``).",
+      "const": "1.0"
+    },
+    "base_prefix": {
+      "type": "string",
+      "description": "Base prefix of the Python installation.\n\nEither an absolute path, or a path relative to directory where this file is contained.",
+      "examples": [
+        "/usr",
+        "../.."
+      ]
+    },
+    "base_interpreter": {
+        "type": "string",
+        "description": "The path to the Python interprer of the base installation.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the installation provides an interpreter executable.",
+        "examples": [
+          "/usr/bin/python",
+          "bin/python"
+        ]
+    },
+    "platform": {
+      "type": "string",
+      "description": "System platform string.\n\nThis field **SHOULD** be equivalent to ``sysconfig.get_platform()``.",
+      "examples": [
+        "linux-x86_64"
+      ]
+    },
+    "language": {
+      "type": "object",
+      "description": "Object containing details related to the Python language specification.",
+      "required": [
+        "version"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "version": {
+          "type": "string",
+          "description": "String representation the Python language version — a version string consisting only of the *major* and *minor* components.\n\nThis field **SHOULD** be equivalent to ``sysconfig.get_python_version()``.",
+          "examples": ["3.14"]
+        },
+        "version_info": {
+          "type": "object",
+          "description": "Object in the format of :py:data:`sys.version_info`.\n\nThis section **SHOULD** be equivalent to :py:data:`sys.version_info`.",
+          "required": ["major", "minor", "micro", "releaselevel", "serial"],
+          "additionalProperties": false,
+          "examples": [
+            {
+              "major": 3,
+              "minor": 14,
+              "micro": 1,
+              "releaselevel": "final",
+              "serial": 0
+            }
+          ],
+          "properties": {
+            "major": {
+              "type": "number"
+            },
+            "minor": {
+              "type": "number"
+            },
+            "micro": {
+              "type": "number"
+            },
+            "releaselevel": {
+              "type": "string",
+              "enum": ["alpha", "beta", "candidate", "final"]
+            },
+            "serial": {
+              "type": "number"
+            }
+          }
+        }
+      }
+    },
+    "implementation": {
+      "type": "object",
+      "description": "Object containing details related to Python implementation.\n\nThis section **SHOULD** be equivalent to :py:data:`sys.implementation`. It follows specification defined in PEP 421, meaning that on top of the required keys, implementation-specific keys can also exist, but must be prefixed with an underscore.",
+      "required": [
+        "name",
+        "version",
+        "hexversion",
+        "cache_tag"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Lower-case name of the Python implementation.",
+          "examples": ["cpython", "pypy"]
+        },
+        "version": {
+          "type": "object",
+          "description": "Object in the format of :py:data:`sys.version_info`, containing the implementation version.",
+          "required": ["major", "minor", "micro", "releaselevel", "serial"],
+          "additionalProperties": false,
+          "examples": [
+            {
+              "major": 3,
+              "minor": 14,
+              "micro": 1,
+              "releaselevel": "final",
+              "serial": 0
+            },
+            {
+              "major": 7,
+              "minor": 3,
+              "micro": 16,
+              "releaselevel": "final",
+              "serial": 0
+            }
+          ],
+          "properties": {
+            "major": {
+              "type": "number"
+            },
+            "minor": {
+              "type": "number"
+            },
+            "micro": {
+              "type": "number"
+            },
+            "releaselevel": {
+              "type": "string",
+              "enum": ["alpha", "beta", "candidate", "final"]
+            },
+            "serial": {
+              "type": "number"
+            }
+          }
+        }
+      }
+    },
+    "abi": {
+      "type": "object",
+      "description": "Object containing details related to ABI.",
+      "required": [
+        "flags"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "flags": {
+          "type": "array",
+          "description": "Build configuration flags, used to calculate the extension suffix.\n\nThe flags **MUST** be defined in the order they appear on the extension suffix.",
+          "additionalProperties": true,
+          "examples": [
+            ["t", "d"]
+          ]
+        },
+        "extension_suffix": {
+          "type": "string",
+          "description": "Suffix used for extensions built against the current implementation version.\n\nThis field **MUST** be present if the Python implementation supports extensions, otherwise this entry will be missing.",
+          "examples": [
+            ".cpython-314-x86_64-linux-gnu.so"
+          ]
+        },
+        "stable_abi_suffix": {
+          "type": "string",
+          "description": "Suffix used for extensions built against the stable ABI.\n\nThis field **MUST** be present if the Python implementation has a stable ABI extension suffix, otherwise this entry will be missing.",
+          "examples": [
+            ".abi3.so"
+          ]
+        }
+      }
+    },
+    "suffixes": {
+      "type": "object",
+      "description": "Valid module suffixes grouped by type.\n\nThis section **MUST** be present if the Python installation supports importing external files, and it **SHOULD** be equivalent to the ``importlib.machinery.*_SUFFIXES`` attributes.\n\nAdditionally, if a Python implementation provides extension kinds other than the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-section for them.",
+      "examples": [
+        {
+          "source": [".py"],
+          "bytecode": [".pyc"],
+          "optimized_bytecode": [".pyc"],
+          "debug_bytecode": [".pyc"],
+          "extensions": [".cpython-313-x86_64-linux-gnu.so", ".abi3.so", ".so"]
+        }
+      ]
+    },
+    "libpython": {
+      "type": "object",
+      "description": "Object containing details related to the ``libpython`` library.\n\nThis section **MUST** by present if Python installation provides a ``libpython`` library, otherwise this section will be missing.",
+      "additionalProperties": false,
+      "properties": {
+        "dynamic": {
+          "type": "string",
+          "description": "The path to the dynamic ``libpython`` library.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing.",
+          "examples": [
+            "/usr/lib/libpython3.14.so.1.0",
+            "lib/libpython3.14.so.1.0"
+          ]
+        },
+        "dynamic_stableabi": {
+          "type": "string",
+          "description": "The path to the dynamic ``libpython`` library for the stable ABI.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python installation provides a dynamic ``libpython`` library targeting the Stable ABI, otherwise this entry will be missing.\n\nIf this key is present ``dynamic`` **MUST** also be set.",
+          "examples": [
+            "/usr/lib/libpython3.so",
+            "lib/libpython3.so"
+          ]
+        },
+        "static": {
+          "type": "string",
+          "description": "The path to the static ``libpython`` library.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python installation provides a static ``libpython`` library, otherwise this entry will be missing.",
+          "examples": [
+            "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a",
+            "lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a"
+          ]
+        },
+        "link_extensions": {
+          "type": "boolean",
+          "description": "Should extensions built against a dynamic ``libpython`` link to it?\n\nThis field **MUST** be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing."
+        }
+      }
+    },
+    "c_api": {
+      "type": "object",
+      "description": "Object containing details related to the Python C API.\n\nThis section **MUST** be present if the Python implementation provides a C API, otherwise this section will be missing.",
+      "required": [
+        "headers"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "headers": {
+          "type": "string",
+          "description": "The path to the C API headers.\n\nEither an absolute path, or a path relative to ``base_prefix``.",
+          "examples": [
+            "/usr/include/python3.14",
+            "include/python3.14"
+          ]
+        },
+        "pkgconfig_path": {
+          "type": "string",
+          "description": "The path to the pkg-config definition files.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python implementation provides pkg-config definition files, otherwise this section will be missing.",
+          "examples": [
+            "/usr/lib/pkgconfig",
+            "lib/pkgconfig"
+          ]
+        }
+      }
+    },
+    "arbitrary_data": {
+      "type": "object",
+      "description": "Object containing extra arbitrary data.\n\nThis is meant to be used as an escape-hatch, to include any relevant data that is not covered by this specification. Implementations may choose what data to provide in this section.",
+      "additionalProperties": true
+    }
+  }
+}
diff --git a/source/specifications/section-python-description-formats.rst b/source/specifications/section-python-description-formats.rst
new file mode 100644
index 000000000..5a56c3968
--- /dev/null
+++ b/source/specifications/section-python-description-formats.rst
@@ -0,0 +1,8 @@
+==========================
+Python Description Formats
+==========================
+
+.. toctree::
+   :titlesonly:
+
+   build-details/index

From 8e89d1553e55959ee9e403eb2b3f23a8eca7adeb Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee 
Date: Thu, 6 Feb 2025 08:27:58 +0800
Subject: [PATCH 567/733] Clarify the Android schema definition

Co-authored-by: Malcolm Smith 
---
 .../platform-compatibility-tags.rst              | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 6a25fa6ab..2415f03de 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -216,18 +216,20 @@ toolchain when building a ``universal2`` binary.
 android
 -------
 
-Android uses the schema ``android__``, indicating compatibility with
-Android SDK ``sdk`` or later, on the architecture ``arch``. Android makes no
+Android uses the schema ``android__``, indicating compatibility
+with the given Android API level or later, on the given ABI. Android makes no
 distinction between physical devices and emulated devices.
 
-Note that this tag schema uses the *SDK* version, not the Android OS version
-number. The Android release known publicly as Android 12 (code named "Snow
-Cone") uses SDK 31 or 32, depending on the specific Android version in use.
+Note that this tag schema uses the API level, which is a positive integer, not
+the user-facing Android version. The release known as Android 12 (code named "Snow
+Cone") uses API level 31 or 32, depending on the specific Android version in use.
 Android's release documentation contains the `full list of Android versions and
-their corresponding SDK versions
+their corresponding API levels
 `__.
 
-There are 4 supported architectures:
+There are 4 `supported ABIs `__. 
+Normalized according to the rules above, they are:
+
 * ``armeabi_v7a``
 * ``arm64_v8a``
 * ``x86``

From 84010c1fc70058e130bddb29a34654b9ca157b12 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 6 Feb 2025 00:28:05 +0000
Subject: [PATCH 568/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/specifications/platform-compatibility-tags.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 2415f03de..f67c29c5e 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -227,7 +227,7 @@ Android's release documentation contains the `full list of Android versions and
 their corresponding API levels
 `__.
 
-There are 4 `supported ABIs `__. 
+There are 4 `supported ABIs `__.
 Normalized according to the rules above, they are:
 
 * ``armeabi_v7a``

From 608a6bbb69afe74d9637a96725aa908dac281117 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee 
Date: Thu, 6 Feb 2025 07:55:57 +0800
Subject: [PATCH 569/733] Use the file role for tags to allow for variable
 markup.

---
 source/specifications/platform-compatibility-tags.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index f67c29c5e..5487cc796 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -109,8 +109,8 @@ subset of Linux platforms, and allows building wheels tagged with the
 ``manylinux`` platform tag which can be used across most common Linux
 distributions.
 
-The current standard is the future-proof ``manylinux__`` standard. It defines
-tags of the form ``manylinux___``, where ``x`` and ``y`` are glibc major
+The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. It defines
+tags of the form :file:`manylinux_{x}_{y}_{arch}`, where ``x`` and ``y`` are glibc major
 and minor versions supported (e.g. ``manylinux_2_24_xxx`` should work on any
 distro using glibc 2.24+), and ``arch`` is the architecture, matching the value
 of :py:func:`sysconfig.get_platform()` on the system as in the "simple" form above.
@@ -151,7 +151,7 @@ auditwheel  ``>=1.0.0``     ``>=2.0.0``        ``>=3.0.0``        ``>=3.3.0`` [#
 
 The ``musllinux`` family of tags is similar to ``manylinux``, but for Linux
 platforms that use the musl_ libc rather than glibc (a prime example being Alpine
-Linux). The schema is ``musllinux___``, supporting musl ``x.y`` and higher
+Linux). The schema is :file:`musllinux_{x}_{y}_{arch}``, supporting musl ``x.y`` and higher
 on the architecture ``arch``.
 
 The musl version values can be obtained by executing the musl libc shared
@@ -196,7 +196,7 @@ macOS
 
 macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical
 artefact of Apple's official macOS naming scheme). The schema for compatibility
-tags is ``macosx___``, indicating that the wheel is compatible with
+tags is :file:`macosx_{x}_{y}_{arch}``, indicating that the wheel is compatible with
 macOS ``x.y`` or later on the architecture ``arch``. The version number always
 includes a major and minor version, even if Apple's official version numbering
 only refers to the major value. For example, a ``macosx_11_0_arm64`` indicates
@@ -243,7 +243,7 @@ uses SDK 27 (i.e, Android 8.1).
 iOS
 ---
 
-iOS uses the schema ``ios____``, indicating compatibility with
+iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating compatibility with
 iOS ``x.y`` or later, on the ``arch`` architecture, using the ``sdk`` SDK. The
 version number always includes a major and minor version, even if Apple's
 official version numbering only refers to the major value.

From 77ab2013751c8de1941e47706590fc9ac2fedb0f Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee 
Date: Thu, 6 Feb 2025 08:40:17 +0800
Subject: [PATCH 570/733] Clarify macOS version number and arch specifications.

---
 .../platform-compatibility-tags.rst           | 38 ++++++++++++++-----
 1 file changed, 28 insertions(+), 10 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 5487cc796..82f491487 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -196,20 +196,38 @@ macOS
 
 macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical
 artefact of Apple's official macOS naming scheme). The schema for compatibility
-tags is :file:`macosx_{x}_{y}_{arch}``, indicating that the wheel is compatible with
-macOS ``x.y`` or later on the architecture ``arch``. The version number always
-includes a major and minor version, even if Apple's official version numbering
-only refers to the major value. For example, a ``macosx_11_0_arm64`` indicates
-compatibility with macOS 11 or later, on arm64 (i.e., Apple Silicon) hardware.
-
-macOS also supports the use of a combined, or "fat" architecture specification.
-For example, specifying an architecture of ``universal2`` indicates that
-binaries support *both* x86_64 *and* arm64.
+tags is :file:`macosx_{x}_{y}_{arch}``, indicating that the wheel is compatible
+with macOS ``x.y`` or later on the architecture ``arch``.
+
+The value of ``x`` and ``y`` correspond to the major and minor version number of
+the macOS release, respectively. They must both be positive integers, with the
+``x`` value being ``>= 10``. The version number always includes a major *and*
+minor version, even if Apple's official version numbering only refers to
+the major value. For example, a ``macosx_11_0_arm64`` indicates compatibility
+with macOS 11 or later.
+
+macOS binaries can be compiled for a single architecture, or can include support
+for multiple architectures in the same binary (sometimes called "fat" binaries).
+To indicate support for a single architecture, the value of ``arch`` must match
+the value of :py:func:`sysconfig.get_platform()` on the system. To indicate
+support multiple architectures, the ``arch`` tag should be an identifier from
+the following list that describes the set of supported architectures:
+
+============== ========================================
+``arch``       Architectures supported
+============== ========================================
+``universal2`` ``arm64``, ``x86-64``
+``universal``  ``ppc64``, ``i386``, ``x86-64``
+``intel``      ``i386``, ``x86-64``
+``fat``        ``ppc``, ``ppc64``, ``i386``, ``x86-64``
+``fat32``      ``ppc``, ``i386``
+``fat64``      ``ppc64``, ``x86-64``
+============== ========================================
 
 The minimum supported macOS version may also be constrained by architecture. For
 example, macOS 11 (Big Sur) was the first release to support arm64. These
 additional constraints are enforced transparently by the macOS compilation
-toolchain when building a ``universal2`` binary.
+toolchain when building binaries that support multiple architectures.
 
 .. _android:
 

From 37625a372720a92a692a0294c177896209ab662f Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee 
Date: Thu, 6 Feb 2025 08:44:51 +0800
Subject: [PATCH 571/733] Clarify the Android specification.

---
 .../platform-compatibility-tags.rst           | 20 ++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 82f491487..4b18cc7c3 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -231,18 +231,18 @@ toolchain when building binaries that support multiple architectures.
 
 .. _android:
 
-android
+Android
 -------
 
-Android uses the schema ``android__``, indicating compatibility
+Android uses the schema :file:`android_{api_level}_{abi}`, indicating compatibility
 with the given Android API level or later, on the given ABI. Android makes no
 distinction between physical devices and emulated devices.
 
-Note that this tag schema uses the API level, which is a positive integer, not
-the user-facing Android version. The release known as Android 12 (code named "Snow
-Cone") uses API level 31 or 32, depending on the specific Android version in use.
-Android's release documentation contains the `full list of Android versions and
-their corresponding API levels
+The API level should be a positive integer. Note that this value is the API
+level, and *not* the user-facing Android version. The release known as Android
+12 (code named "Snow Cone") uses API level 31 or 32, depending on the specific
+Android version in use. Android's release documentation contains the `full list
+of Android versions and their corresponding API levels
 `__.
 
 There are 4 `supported ABIs `__.
@@ -253,8 +253,10 @@ Normalized according to the rules above, they are:
 * ``x86``
 * ``x86_64``
 
-By default, Python 3.13 is compiled using SDK 24 (i.e, Android 7); Python 3.14
-uses SDK 27 (i.e, Android 8.1).
+Virtually all current physical devices use one of the ARM architectures. ``x86``
+and ``x86_64`` are supported for use in the emulator. ``x86`` has not been
+supported as a development platform since 2020, and no new emulator images have
+been released since then.
 
 .. _ios:
 

From 1f36a155264cd2e9322d4b99ce8ebd0fae83410f Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee 
Date: Thu, 6 Feb 2025 09:12:23 +0800
Subject: [PATCH 572/733] Clarify iOS specification.

---
 .../platform-compatibility-tags.rst           | 49 ++++++++++++-------
 1 file changed, 30 insertions(+), 19 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 4b18cc7c3..99b7cdffe 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -209,19 +209,19 @@ with macOS 11 or later.
 macOS binaries can be compiled for a single architecture, or can include support
 for multiple architectures in the same binary (sometimes called "fat" binaries).
 To indicate support for a single architecture, the value of ``arch`` must match
-the value of :py:func:`sysconfig.get_platform()` on the system. To indicate
+the value of :py:func:`platform.machine()` on the system. To indicate
 support multiple architectures, the ``arch`` tag should be an identifier from
 the following list that describes the set of supported architectures:
 
 ============== ========================================
 ``arch``       Architectures supported
 ============== ========================================
-``universal2`` ``arm64``, ``x86-64``
-``universal``  ``ppc64``, ``i386``, ``x86-64``
-``intel``      ``i386``, ``x86-64``
-``fat``        ``ppc``, ``ppc64``, ``i386``, ``x86-64``
+``universal2`` ``arm64``, ``x86_64``
+``universal``  ``ppc64``, ``i386``, ``x86_64``
+``intel``      ``i386``, ``x86_64``
+``fat``        ``ppc``, ``ppc64``, ``i386``, ``x86_64``
 ``fat32``      ``ppc``, ``i386``
-``fat64``      ``ppc64``, ``x86-64``
+``fat64``      ``ppc64``, ``x86_64``
 ============== ========================================
 
 The minimum supported macOS version may also be constrained by architecture. For
@@ -264,20 +264,31 @@ iOS
 ---
 
 iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating compatibility with
-iOS ``x.y`` or later, on the ``arch`` architecture, using the ``sdk`` SDK. The
-version number always includes a major and minor version, even if Apple's
-official version numbering only refers to the major value.
+iOS ``x.y`` or later, on the ``arch`` architecture, using the ``sdk`` SDK.
 
-The iOS platform has two SDKs: ``iphoneos`` for physical devices; and
-``iphonesimulator`` for simulated devices. These SDKs have the same API surface,
-but are incompatible at the binary level, even if they are running on the same
-architecture. Code compiled for an arm64 simulator will not run on an arm64
-device.
-
-The ``iphonesimulator`` SDK supports 2 architectures: ``arm64`` and ``x86_64``.
-The ``iphoneos`` SDK only supports the ``arm64`` architecture.
-
-By default, Python is compiled with a minimum iOS compatibility version of 13.0.
+The value of ``x`` and ``y`` correspond to the major and minor version number of
+the iOS release, respectively. They must both be positive integers. The version
+number always includes a major *and* minor version, even if Apple's official
+version numbering only refers to the major value. For example, a
+``ios_13_0_arm64_iphonesimulator`` indicates compatibility with iOS 13 or later.
+
+The value of ``arch`` must match the value of :py:func:`platform.machine()` on
+the system.
+
+The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or
+``iphonesimulator`` (for device simulators). These SDKs have the same API
+surface, but are incompatible at the binary level, even if they are running on
+the same CPU architecture. Code compiled for an arm64 simulator will not run on
+an arm64 device.
+
+The combination of :file:`{arch}_{sdk}` is referred to as the "multiarch". There
+are three possible values for multiarch:
+
+* ``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every
+  iOS device manufactured since ~2015;
+* ``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS
+  hardware; and
+* ``x86_64_iphonesimulator``, for simulators running on x86_64 hardware.
 
 Use
 ===

From 90638f828194d1fbc2dd251850078f738be21de1 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee 
Date: Thu, 6 Feb 2025 12:10:40 +0800
Subject: [PATCH 573/733] Update macOS tag table to use canonical values.

---
 source/specifications/platform-compatibility-tags.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 99b7cdffe..8c4697d27 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -217,10 +217,10 @@ the following list that describes the set of supported architectures:
 ``arch``       Architectures supported
 ============== ========================================
 ``universal2`` ``arm64``, ``x86_64``
-``universal``  ``ppc64``, ``i386``, ``x86_64``
+``universal``  ``i386``, ``ppc``, ``ppc64``, ``x86_64``
 ``intel``      ``i386``, ``x86_64``
-``fat``        ``ppc``, ``ppc64``, ``i386``, ``x86_64``
-``fat32``      ``ppc``, ``i386``
+``fat``        ``i386``, ``ppc``
+``fat3``       ``i386``, ``ppc``, ``x86_64``
 ``fat64``      ``ppc64``, ``x86_64``
 ============== ========================================
 

From caf1140041f66daaaaf00fde118dbad7cbf36fc2 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Thu, 6 Feb 2025 14:03:18 -0500
Subject: [PATCH 574/733] simple-repository-api: clean up, add API history

Signed-off-by: William Woodruff 
---
 .../specifications/simple-repository-api.rst  | 151 +++++++++---------
 1 file changed, 79 insertions(+), 72 deletions(-)

diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
index a96e4e7a8..e05e3854a 100644
--- a/source/specifications/simple-repository-api.rst
+++ b/source/specifications/simple-repository-api.rst
@@ -5,6 +5,11 @@
 Simple repository API
 =====================
 
+The keywords "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**",
+"**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**MAY**",
+and "**OPTIONAL**"" in this document are to be interpreted as described in
+:rfc:`2119`.
+
 The interface for querying available package versions and
 retrieving packages from an index server comes in two forms:
 HTML and JSON.
@@ -28,7 +33,9 @@ Within a repository, the root URL (``/`` for this spec which represents the base
 URL) **MUST** be a valid HTML5 page with a single anchor element per project in
 the repository. The text of the anchor tag **MUST** be the name of
 the project and the href attribute **MUST** link to the URL for that particular
-project. As an example::
+project. As an example:
+
+.. code-block:: html
 
    
    
@@ -89,7 +96,9 @@ In addition to the above, the following constraints are placed on the API:
   link. This exposes the :ref:`core-metadata-requires-python` metadata field
   for the corresponding release. Where this is present, installer tools
   **SHOULD** ignore the download when installing to a Python version that
-  doesn't satisfy the requirement. For example::
+  doesn't satisfy the requirement. For example:
+
+  .. code-block:: html
 
       ...
 
@@ -209,13 +218,15 @@ Versioning PyPI's Simple API
 
 This spec proposes the inclusion of a meta tag on the responses of every
 successful request to a simple API page, which contains a name attribute
-of "pypi:repository-version", and a content that is a :ref:`version specifiers
+of ``pypi:repository-version``, and a content that is a :ref:`version specifiers
 specification ` compatible
 version number, which is further constrained to ONLY be Major.Minor, and
 none of the additional features supported by :ref:`the version specifiers
 specification `.
 
-This would end up looking like::
+This would end up looking like:
+
+.. code-block:: html
 
   
 
@@ -241,10 +252,18 @@ is included to disambiguate with future versions (e.g. a hypothetical
 simple api v2 that lived at /v2/, but which would be confusing if the
 repository-version was set to a version >= 2).
 
-This spec sets the current API version to "1.0", and expects that
-future specs that further evolve the simple API will increment the
-minor version number.
+API Version History
+-------------------
+
+This section contains only an abbreviated history of changes,
+as marked by the API version number. For a full history of changes including
+changes made before API versioning, see :ref:`History `.
 
+- API version 1.0: Initial version of the API, declared with :pep:`629`.
+- API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-time`` metadata
+  to the JSON serialization, declared with :pep:`700`.
+- API version 1.2: Added repository "tracks" metadata, declared with :pep:`708`.
+- API version 1.3: Added provenance metadata, declared with :pep:`740`.
 
 Clients
 -------
@@ -393,6 +412,8 @@ spec:
 * All requirements of :ref:`the base HTML API specification
   ` that are not HTML specific still apply.
 
+* Keys (at any level) with a leading underscore are reserved as private for
+  index server use. No future standard will assign a meaning to any such key.
 
 Project List
 ~~~~~~~~~~~~
@@ -446,11 +467,34 @@ The format of this URL is ``//`` where the ```` is replaced by
 name for that project, so a project named "Silly_Walk" would
 have a URL like ``/silly-walk/``.
 
-This URL must respond with a JSON encoded dictionary that has three keys:
+This URL must respond with a JSON encoded dictionary that has four keys:
 
 - ``name``: The normalized name of the project.
 - ``files``: A list of dictionaries, each one representing an individual file.
 - ``meta``: The general response metadata as `described earlier `__.
+- ``versions``: A list of version strings specifying all of the project versions
+  uploaded for this project. The value of ``versions`` is logically a set,
+  and as such may not contain duplicates, and the order of the versions is
+  not significant.
+
+  .. note::
+
+    All of the files listed in the ``files`` key MUST be associated with one of the
+    versions in the ``versions`` key. The ``versions`` key MAY contain versions with
+    no associated files (to represent versions with no files uploaded, if the server
+    has such a concept).
+
+  .. note::
+
+    Because servers may hold "legacy" data from before the adoption of
+    :ref:`the version specifiers specification (VSS) `, version
+    strings currently cannot be required to be valid VSS versions, and therefore
+    cannot be assumed to be orderable using the VSS rules. However, servers **SHOULD**
+    use normalized VSS versions where possible.
+
+  .. note::
+
+    The ``versions`` key was added with API version 1.1.
 
 Each individual file dictionary has the following keys:
 
@@ -508,6 +552,25 @@ Each individual file dictionary has the following keys:
   and is a truthy value, then it **SHOULD** be interpreted as indicating that the
   file pointed to by the ``url`` field has been "Yanked" as per :ref:`the API
   yank specification `.
+- ``size``: A **mandatory** key. It **MUST** contain an integer which is the file size in bytes.
+
+  .. note::
+
+    The ``size`` key was added with API version 1.1.
+
+- ``upload-time``: An **optional** key that, if present, **MUST** contain a valid
+  ISO 8601 date/time string in the format ``yyyy-mm-ddThh:mm:ss.ffffffZ``
+  which represents the time the file was uploaded to the index.
+
+  As indicated by the ``Z`` suffix, the upload time **MUST** use the UTC timezone.
+  The fractional seconds part of the timestamp (the ``.ffffff`` part) is optional,
+  and if present may contain up to 6 digits of precision. If a server does not record
+  upload time information for a file, it **MAY** omit the ``upload-time`` key.
+
+  .. note::
+
+    The ``upload-time`` key was added with API version 1.1.
+
 - ``provenance``: An **optional** key which, if present **MUST** be either a JSON
   string or ``null``. If not ``null``, it **MUST** be a URL to the file's
   associated provenance, with the same rules as ``data-provenance`` in the
@@ -532,7 +595,8 @@ As an example:
           "url": "https://example.com/files/holygrail-1.0.tar.gz",
           "hashes": {"sha256": "...", "blake2b": "..."},
           "requires-python": ">=3.7",
-          "yanked": "Had a vulnerability"
+          "yanked": "Had a vulnerability",
+          "size": 123456
         },
         {
           "filename": "holygrail-1.0-py3-none-any.whl",
@@ -540,9 +604,11 @@ As an example:
           "hashes": {"sha256": "...", "blake2b": "..."},
           "requires-python": ">=3.7",
           "dist-info-metadata": true,
-          "provenance": "https://example.com/files/holygrail-1.0-py3-none-any.whl.provenance"
+          "provenance": "https://example.com/files/holygrail-1.0-py3-none-any.whl.provenance",
+          "size": 1337
         }
-      ]
+      ],
+      "versions": ["1.0"]
     }
 
 
@@ -889,71 +955,10 @@ It is recommended that clients:
 - Check the ``Content-Type`` of the response and ensure it matches something
   that you were expecting.
 
-Additional Fields for the Simple API for Package Indexes
-========================================================
-
-This specification defines version 1.1 of the simple repository API. For the
-HTML version of the API, there is no change from version 1.0. For the JSON
-version of the API, the following changes are made:
-
-- The ``api-version`` must specify version 1.1 or later.
-- A new ``versions`` key is added at the top level.
-- Two new "file information" keys, ``size`` and ``upload-time``, are added to
-  the ``files`` data.
-- Keys (at any level) with a leading underscore are reserved as private for
-  index server use. No future standard will assign a meaning to any such key.
-
-The ``versions`` and ``size`` keys are mandatory. The ``upload-time`` key is
-optional.
-
-Versions
---------
-
-An additional key, ``versions`` MUST be present at the top level, in addition to
-the keys ``name``, ``files`` and ``meta`` defined in :ref:`the JSON API
-specification `. This key MUST
-contain a list of version strings specifying all of the project versions uploaded
-for this project. The value is logically a set, and as such may not contain
-duplicates, and the order of the values is not significant.
-
-All of the files listed in the ``files`` key MUST be associated with one of the
-versions in the ``versions`` key. The ``versions`` key MAY contain versions with
-no associated files (to represent versions with no files uploaded, if the server
-has such a concept).
-
-Note that because servers may hold "legacy" data from before the adoption of
-:ref:`the version specifiers specification (VSS) `, version
-strings currently cannot be required to be valid VSS versions, and therefore
-cannot be assumed to be orderable using the VSS rules. However, servers SHOULD
-use normalised VSS versions where
-possible.
-
-
-Additional file information
----------------------------
-
-Two new keys are added to the ``files`` key.
-
-- ``size``: This field is mandatory. It MUST contain an integer which is the
-  file size in bytes.
-- ``upload-time``: This field is optional. If present, it MUST contain a valid
-  ISO 8601 date/time string, in the format ``yyyy-mm-ddThh:mm:ss.ffffffZ``,
-  which represents the time the file was uploaded to the index. As indicated by
-  the ``Z`` suffix, the upload time MUST use the UTC timezone. The fractional
-  seconds part of the timestamp (the ``.ffffff`` part) is optional, and if
-  present may contain up to 6 digits of precision. If a server does not record
-  upload time information for a file, it MAY omit the ``upload-time`` key.
 
 Rename dist-info-metadata in the Simple API
 ===========================================
 
-
-The keywords "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**",
-"**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**MAY**",
-and "**OPTIONAL**"" in this document are to be interpreted as described in
-:rfc:`RFC 2119 <2119>`.
-
-
 Servers
 -------
 
@@ -992,6 +997,8 @@ if it is present. They
 **MAY** optionally use the legacy ``dist-info-metadata`` key if it is present
 but ``core-metadata`` is not.
 
+.. _simple-repository-history:
+
 History
 =======
 

From 48052a05260b37b9e2e92fbdfc9960de0754c88a Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee 
Date: Fri, 7 Feb 2025 11:30:44 +0800
Subject: [PATCH 575/733] Minor tweaks from code review.

Co-authored-by: Malcolm Smith 
---
 source/specifications/platform-compatibility-tags.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 8c4697d27..45746c4ba 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -196,14 +196,14 @@ macOS
 
 macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical
 artefact of Apple's official macOS naming scheme). The schema for compatibility
-tags is :file:`macosx_{x}_{y}_{arch}``, indicating that the wheel is compatible
+tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the wheel is compatible
 with macOS ``x.y`` or later on the architecture ``arch``.
 
-The value of ``x`` and ``y`` correspond to the major and minor version number of
+The values of ``x`` and ``y`` correspond to the major and minor version number of
 the macOS release, respectively. They must both be positive integers, with the
 ``x`` value being ``>= 10``. The version number always includes a major *and*
 minor version, even if Apple's official version numbering only refers to
-the major value. For example, a ``macosx_11_0_arm64`` indicates compatibility
+the major value. For example, ``macosx_11_0_arm64`` indicates compatibility
 with macOS 11 or later.
 
 macOS binaries can be compiled for a single architecture, or can include support
@@ -238,8 +238,8 @@ Android uses the schema :file:`android_{api_level}_{abi}`, indicating compatibil
 with the given Android API level or later, on the given ABI. Android makes no
 distinction between physical devices and emulated devices.
 
-The API level should be a positive integer. Note that this value is the API
-level, and *not* the user-facing Android version. The release known as Android
+The API level should be a positive integer. This is *not* the same thing as
+the user-facing Android version. For example, the release known as Android
 12 (code named "Snow Cone") uses API level 31 or 32, depending on the specific
 Android version in use. Android's release documentation contains the `full list
 of Android versions and their corresponding API levels

From 2d26d3afecb7ff062ff9146fc37fe488a1109222 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee 
Date: Fri, 7 Feb 2025 11:39:04 +0800
Subject: [PATCH 576/733] Clarified android tagging markup, and added an
 example.

---
 source/specifications/platform-compatibility-tags.rst | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 45746c4ba..d617323d4 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -234,9 +234,11 @@ toolchain when building binaries that support multiple architectures.
 Android
 -------
 
-Android uses the schema :file:`android_{api_level}_{abi}`, indicating compatibility
-with the given Android API level or later, on the given ABI. Android makes no
-distinction between physical devices and emulated devices.
+Android uses the schema :file:`android_{apilevel}_{abi}`, indicating
+compatibility with the given Android API level or later, on the given ABI. For
+example, ``android_27_arm64_v8a`` indicates support for API level 27 or later,
+on ``arm64_v8a`` devices. Android makes no distinction between physical devices
+and emulated devices.
 
 The API level should be a positive integer. This is *not* the same thing as
 the user-facing Android version. For example, the release known as Android

From 61bdcafaeb042c37a13443d79744213d39bf6e5d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns=20=F0=9F=87=B5=F0=9F=87=B8?=
 
Date: Mon, 10 Feb 2025 18:08:40 +0000
Subject: [PATCH 577/733] Update source/specifications/build-details/index.rst

Co-authored-by: Zanie Blue 
---
 source/specifications/build-details/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/build-details/index.rst b/source/specifications/build-details/index.rst
index bda4e0ba4..369b74f20 100644
--- a/source/specifications/build-details/index.rst
+++ b/source/specifications/build-details/index.rst
@@ -16,7 +16,7 @@ extension ABI details, and other information that is specific to that particular
 build of Python.
 
 Starting from Python 3.14, a ``build-details.json`` file is installed in the
-platform-independent standard library directory (``stdlib``, eg.
+platform-independent standard library directory (``stdlib``, e.g.
 ``/usr/lib/python3.14/build-details.json``).
 
 Please refer to the :ref:`latest version ` for its

From 68d342c0fbcd32233c4ea53af9fc29c280473669 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Mon, 10 Feb 2025 13:50:57 -0500
Subject: [PATCH 578/733] simple-repository-api: clean up PEP 658/PEP 714 bits

Signed-off-by: William Woodruff 
---
 .../specifications/simple-repository-api.rst  | 76 ++++++++-----------
 1 file changed, 33 insertions(+), 43 deletions(-)

diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
index e05e3854a..d18c425db 100644
--- a/source/specifications/simple-repository-api.rst
+++ b/source/specifications/simple-repository-api.rst
@@ -88,6 +88,26 @@ In addition to the above, the following constraints are placed on the API:
   associated signature, the signature would be located at
   ``/packages/HolyGrail-1.0.tar.gz.asc``.
 
+* A repository **MAY** include a ``data-core-metadata`` attribute on a file
+  link.
+
+  The repository **SHOULD** provide the hash of the Core Metadata file as the
+  ``data-core-metadata`` attribute's value using the syntax
+  ``=``, where ```` is the lower cased name of
+  the hash function used, and ```` is the hex encoded digest. The
+  repository **MAY** use ``true`` as the attribute's value if a hash is unavailable.
+
+* A repository **MAY** include a ``data-dist-info-metadata`` attribute on a
+  file link.
+
+  Index clients **MAY** consume this key if present, as a legacy fallback
+  for ``data-core-metadata``.
+
+  .. important::
+
+    ``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to
+    ``data-core-metadata`` with :pep:`714`.
+
 * A repository **MAY** include a ``data-gpg-sig`` attribute on a file link with
   a value of either ``true`` or ``false`` to indicate whether or not there is a
   GPG signature. Repositories that do this **SHOULD** include it on every link.
@@ -523,7 +543,7 @@ Each individual file dictionary has the following keys:
   Unlike ``data-requires-python`` in :ref:`the base HTML API specification
   `, the ``requires-python`` key does not
   require any special escaping other than anything JSON does naturally.
-- ``dist-info-metadata``: An **optional** key that indicates
+- ``core-metadata``: An **optional** key that indicates
   that metadata for this file is available, via the same location as specified in
   :ref:`the API metadata file specification
   ` (``{file_url}.metadata``). Where this
@@ -541,11 +561,23 @@ Each individual file dictionary has the following keys:
 
   It is recommended that servers make the hashes of the metadata file available if
   possible.
+
+- ``dist-info-metadata``: An **optional**, deprecated alias for ``core-metadata``.
+
+  Index clients **MAY** consume this key if present, as a legacy fallback
+  for ``core-metadata``.
+
+  .. important::
+
+    ``dist-info-metadata`` was standardized with :pep:`658` and renamed to
+    ``core-metadata`` with :pep:`714`.
+
 - ``gpg-sig``: An **optional** key that acts a boolean to indicate if the file has
   an associated GPG signature or not. The URL for the signature file follows what
   is specified in :ref:`the base HTML API specification
   ` (``{file_url}.asc``). If this key does not exist, then
   the signature may or may not exist.
+
 - ``yanked``: An **optional** key which may be either a boolean to indicate if the
   file has been yanked, or a non empty, but otherwise arbitrary, string to indicate
   that a file has been yanked with a specific reason. If the ``yanked`` key is present
@@ -955,48 +987,6 @@ It is recommended that clients:
 - Check the ``Content-Type`` of the response and ensure it matches something
   that you were expecting.
 
-
-Rename dist-info-metadata in the Simple API
-===========================================
-
-Servers
--------
-
-The :ref:`the API metadata file specification
-` metadata, when used in the HTML
-representation of the Simple API,
-**MUST** be emitted using the attribute name ``data-core-metadata``, with the
-supported values remaining the same.
-
-The :ref:`the API metadata file specification
-` metadata, when used in the :ref:`the
-JSON API specification ` JSON representation of the
-Simple API, **MUST** be emitted using the key ``core-metadata``, with the
-supported values remaining the same.
-
-To support clients that used the previous key names, the HTML representation
-**MAY** also be emitted using the ``data-dist-info-metadata``, and if it does
-so it **MUST** match the value of ``data-core-metadata``.
-
-
-
-Clients
--------
-
-Clients consuming any of the HTML representations of the Simple API **MUST**
-read the :ref:`the API metadata file specification
-` metadata from the key
-``data-core-metadata`` if it is
-present. They **MAY** optionally use the legacy ``data-dist-info-metadata`` if
-it is present but ``data-core-metadata`` is not.
-
-Clients consuming the JSON representation of the Simple API **MUST** read the
-:ref:`the API metadata file specification
-` metadata from the key ``core-metadata``
-if it is present. They
-**MAY** optionally use the legacy ``dist-info-metadata`` key if it is present
-but ``core-metadata`` is not.
-
 .. _simple-repository-history:
 
 History

From 8a67950de7ef72c6b10ea85f63d280dc71d8af85 Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Mon, 17 Feb 2025 10:55:02 +0100
Subject: [PATCH 579/733] Fix the reference to License-File core metadata field

---
 source/specifications/pyproject-toml.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index c82fdd936..802f50959 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -252,7 +252,7 @@ The table subkeys of the ``license`` key are deprecated.
 
 - TOML_ type: array of strings
 - Corresponding :ref:`core metadata ` field:
-  :ref:`License-Expression `
+  :ref:`License-File `
 
 An array specifying paths in the project source tree relative to the project
 root directory (i.e. directory containing :file:`pyproject.toml` or legacy project

From faf4c7d882ef2be310d5dc46d54ca666aa18821c Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Mon, 17 Feb 2025 11:52:21 +0100
Subject: [PATCH 580/733] Document the legacy way of declaring pyproject.toml
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 .../licensing-examples-and-user-scenarios.rst |  4 ++
 source/guides/writing-pyproject-toml.rst      | 41 ++++++++++-
 source/tutorials/packaging-projects.rst       | 70 +++++++++++++------
 3 files changed, 92 insertions(+), 23 deletions(-)

diff --git a/source/guides/licensing-examples-and-user-scenarios.rst b/source/guides/licensing-examples-and-user-scenarios.rst
index 5b05d97ea..ae0066581 100644
--- a/source/guides/licensing-examples-and-user-scenarios.rst
+++ b/source/guides/licensing-examples-and-user-scenarios.rst
@@ -10,6 +10,10 @@ Licensing examples and user scenarios
 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
+trying to apply the newer guidelines.
+As of February 2025, :doc:`setuptools `
+and :ref:`flit ` don't support :pep:`639` yet.
 
 
 Licensing Examples
diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index f65ab28da..cfde063aa 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -325,6 +325,15 @@ You can also specify the format explicitly, like this:
 ``license``
 -----------
 
+:pep:`639` (accepted in August 2024) has changed the way the ``license`` field
+is declared. Make sure your preferred build backend supports :pep:`639` before
+trying to apply the newer guidelines.
+As of February 2025, :doc:`setuptools `
+and :ref:`flit ` don't support :pep:`639` yet.
+
+:pep:`639` license declaration
+''''''''''''''''''''''''''''''
+
 This is a valid :term:`SPDX license expression ` consisting
 of one or more :term:`license identifiers `.
 The full license list is available at the
@@ -352,10 +361,40 @@ The custom identifiers must follow the SPDX specification,
     [project]
     license = "LicenseRef-My-Custom-License"
 
+Legacy license declaration
+''''''''''''''''''''''''''
+
+This can take two forms. You can put your license in a file, typically
+:file:`LICENSE` or :file:`LICENSE.txt`, and link that file here:
+
+.. code-block:: toml
+
+    [project]
+    license = {file = "LICENSE"}
+
+or you can write the name of the license:
+
+.. code-block:: toml
+
+    [project]
+    license = {text = "MIT License"}
+
+If you are using a standard, well-known license, it is not necessary to use this
+field. Instead, you should use one of the :ref:`classifiers` starting with ``License
+::``. (As a general rule, it is a good idea to use a standard, well-known
+license, both to avoid confusion and because some organizations avoid software
+whose license is unapproved.)
+
 
 ``license-files``
 -----------------
 
+:pep:`639` (accepted in August 2024) has introduced the ``license-files`` field.
+Make sure your preferred build backend supports :pep:`639` before declaring the
+field.
+As of February 2025, :doc:`setuptools `
+and :ref:`flit ` don't support :pep:`639` yet.
+
 This is a list of license files and files containing other legal
 information you want to distribute with your package.
 
@@ -529,7 +568,7 @@ A full example
    ]
    description = "Lovely Spam! Wonderful Spam!"
    readme = "README.rst"
-   license = "MIT"
+   license = "MIT"  # or license = {file = "LICENSE.txt"} for legacy declaration
    license-files = ["LICEN[CS]E.*"]
    keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
    classifiers = [
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 9357fdfa2..8992fffb0 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -200,27 +200,52 @@ to include your username; this ensures that you have a unique
 package name that doesn't conflict with packages uploaded by other people
 following this tutorial.
 
-.. code-block:: toml
-
-    [project]
-    name = "example_package_YOUR_USERNAME_HERE"
-    version = "0.0.1"
-    authors = [
-      { name="Example Author", email="author@example.com" },
-    ]
-    description = "A small example package"
-    readme = "README.md"
-    requires-python = ">=3.8"
-    classifiers = [
-        "Programming Language :: Python :: 3",
-        "Operating System :: OS Independent",
-    ]
-    license = "MIT"
-    license-files = ["LICEN[CS]E*"]
-
-    [project.urls]
-    Homepage = "https://github.com/pypa/sampleproject"
-    Issues = "https://github.com/pypa/sampleproject/issues"
+.. tab:: hatchling/pdm
+
+  .. code-block:: toml
+
+      [project]
+      name = "example_package_YOUR_USERNAME_HERE"
+      version = "0.0.1"
+      authors = [
+        { name="Example Author", email="author@example.com" },
+      ]
+      description = "A small example package"
+      readme = "README.md"
+      requires-python = ">=3.8"
+      classifiers = [
+          "Programming Language :: Python :: 3",
+          "Operating System :: OS Independent",
+      ]
+      license = "MIT"
+      license-files = ["LICEN[CS]E*"]
+
+      [project.urls]
+      Homepage = "https://github.com/pypa/sampleproject"
+      Issues = "https://github.com/pypa/sampleproject/issues"
+
+.. tab:: setuptools/flit
+
+  .. code-block:: toml
+
+      [project]
+      name = "example_package_YOUR_USERNAME_HERE"
+      version = "0.0.1"
+      authors = [
+        { name="Example Author", email="author@example.com" },
+      ]
+      description = "A small example package"
+      readme = "README.md"
+      requires-python = ">=3.8"
+      classifiers = [
+          "Programming Language :: Python :: 3",
+          "Operating System :: OS Independent",
+          "License :: OSI Approved :: MIT License",
+      ]
+
+      [project.urls]
+      Homepage = "https://github.com/pypa/sampleproject"
+      Issues = "https://github.com/pypa/sampleproject/issues"
 
 - ``name`` is the *distribution name* of your package. This can be any name as
   long as it only contains letters, numbers, ``.``, ``_`` , and ``-``. It also
@@ -249,9 +274,10 @@ following this tutorial.
   your package will work on. For a complete list of classifiers, see
   https://pypi.org/classifiers/.
 - ``license`` is the :term:`SPDX license expression ` of
-  your package.
+  your package. Not supported by all the build backends yet.
 - ``license-files`` is the list of glob paths to the license files,
   relative to the directory where :file:`pyproject.toml` is located.
+  Not supported by all the build backends yet.
 - ``urls`` lets you list any number of extra links to show on PyPI.
   Generally this could be to the source, documentation, issue trackers, etc.
 

From 2a94f3ae763798cc195fc90bca928765025cf7f7 Mon Sep 17 00:00:00 2001
From: Marc Mueller <30130371+cdce8p@users.noreply.github.com>
Date: Tue, 18 Feb 2025 14:57:31 +0100
Subject: [PATCH 581/733] Add anchor links for license and license-files

---
 source/guides/writing-pyproject-toml.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index cfde063aa..f77b83b7f 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -322,6 +322,8 @@ You can also specify the format explicitly, like this:
    readme = {file = "README.txt", content-type = "text/x-rst"}
 
 
+.. _license:
+
 ``license``
 -----------
 
@@ -386,6 +388,8 @@ license, both to avoid confusion and because some organizations avoid software
 whose license is unapproved.)
 
 
+.. _license-files:
+
 ``license-files``
 -----------------
 

From 76aaf7919aaad728d094a8990943217def9fcaf4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= 
Date: Sat, 22 Feb 2025 12:12:26 +0100
Subject: [PATCH 582/733] Indicate that some distributions require building
 from sources

---
 source/discussions/downstream-packaging.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst
index d25845e47..3f4795fa8 100644
--- a/source/discussions/downstream-packaging.rst
+++ b/source/discussions/downstream-packaging.rst
@@ -54,9 +54,10 @@ Why?
 ~~~~
 
 The vast majority of downstream packagers prefer to build packages from source,
-rather than use the upstream-provided binary packages. This is also true
-of pure Python packages that provide universal wheels. The reasons for using
-source distributions may include:
+rather than use the upstream-provided binary packages. In some cases, using
+sources is actually required for the package to be included in the distribution.
+This is also true of pure Python packages that provide universal wheels.
+The reasons for using source distributions may include:
 
 - Being able to audit the source code of all packages.
 

From dadfc521d7d9f6022d77376d06c4b028a482fdef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns=20=F0=9F=87=B5=F0=9F=87=B8?=
 
Date: Thu, 27 Feb 2025 18:01:55 +0000
Subject: [PATCH 583/733] Update source/specifications/build-details/index.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/specifications/build-details/index.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/specifications/build-details/index.rst b/source/specifications/build-details/index.rst
index 369b74f20..5da5a7f03 100644
--- a/source/specifications/build-details/index.rst
+++ b/source/specifications/build-details/index.rst
@@ -1,8 +1,8 @@
 .. _build-details:
 
-======================
-``build-details.json``
-======================
+==========================
+:file:`build-details.json`
+==========================
 
 .. toctree::
    :hidden:

From 9a188f226a6f0fc5f849108585fb7269d560b8fd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns?= 
Date: Thu, 27 Feb 2025 18:05:03 +0000
Subject: [PATCH 584/733] Fix linkcheck_ignore regex
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Filipe Laíns 
---
 source/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/conf.py b/source/conf.py
index 317c89dbf..e10132578 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -129,7 +129,7 @@
 
 linkcheck_ignore = [
     "http://localhost:\\d+",
-    "https://packaging.python.org/en/latest/specifications/schemas/*",
+    "https://packaging.python.org/en/latest/specifications/schemas/.*",
     "https://test.pypi.org/project/example-package-YOUR-USERNAME-HERE",
     "https://pypi.org/manage/*",
     "https://test.pypi.org/manage/*",

From 0a5fbefc3e460f7a4b9405bb066ed35045bcbeb1 Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri 
Date: Tue, 11 Mar 2025 11:57:26 +0000
Subject: [PATCH 585/733] Extract glob specification to a separated document
 and add reference implementation

---
 source/specifications/glob-patterns.rst       | 115 ++++++++++++++++++
 source/specifications/pyproject-toml.rst      |  31 +----
 .../section-distribution-metadata.rst         |   1 +
 3 files changed, 121 insertions(+), 26 deletions(-)
 create mode 100644 source/specifications/glob-patterns.rst

diff --git a/source/specifications/glob-patterns.rst b/source/specifications/glob-patterns.rst
new file mode 100644
index 000000000..abdb15b0f
--- /dev/null
+++ b/source/specifications/glob-patterns.rst
@@ -0,0 +1,115 @@
+=================
+``glob`` patterns
+=================
+
+Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files
+`, accept certain types of *glob patterns*
+to match a given string containing wildcards and character ranges against
+files and directories. This specification defines which patterns are acceptable
+and how they should be handled.
+
+
+Valid glob patterns
+===================
+
+For PyPA purposes, a *valid glob pattern* MUST be a string matched against
+filesystem entries as specified below:
+
+- Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots (``.``)
+  MUST be matched verbatim.
+
+- Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]``
+  containing only the verbatim matched characters MUST be supported.
+  Within ``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``,
+  order based on Unicode code points).
+  Hyphens at the start or end are matched literally.
+
+- Path delimiters MUST be the forward slash character (``/``).
+
+- Patterns always refer to *relative paths*,
+  e.g., when used in :file:`pyproject.toml`, patterns should always be
+  relative to the directory containing that file.
+  Therefore the leading slash character MUST NOT be used.
+
+- Parent directory indicators (``..``) MUST NOT be used.
+
+Any characters or character sequences not covered by this specification are
+invalid. Projects MUST NOT use such values.
+Tools consuming glob patterns SHOULD reject invalid values with an error.
+
+Literal paths (e.g. :file:`LICENSE`) are valid globs which means they
+can also be defined.
+
+Tools consuming glob patterns:
+
+- MUST treat each value as a glob pattern, and MUST raise an error if the
+  pattern contains invalid glob syntax.
+- MUST raise an error if any individual user-specified pattern does not match
+  at least one file.
+
+Examples of valid glob patterns:
+
+.. code-block:: python
+
+   "LICEN[CS]E*"
+   "AUTHORS*"
+   "licenses/LICENSE.MIT"
+   "licenses/LICENSE.CC0"
+   "LICENSE.txt"
+   "licenses/*"
+
+Examples of invalid glob patterns:
+
+.. code-block:: python
+
+   "..\LICENSE.MIT"
+   # .. must not be used.
+   # \ is an invalid path delimiter, / must be used.
+
+   "LICEN{CSE*"
+   # the { character is not allowed
+
+
+Reference implementation in Python
+==================================
+
+It is possible to defer the majority of the pattern matching against the file
+system to the :mod:`glob` module in Python's standard library. It is necessary
+however to perform additional validations.
+
+The code below is as a simple reference implementation:
+
+.. code-block:: python
+
+   import os
+   import re
+   from glob import glob
+
+
+   def find_pattern(pattern: str) -> list[str]:
+       """
+       >>> find_pattern("/LICENSE.MIT")
+       Traceback (most recent call last):
+       ...
+       ValueError: Pattern '/LICENSE.MIT' should be relative...
+       >>> find_pattern("../LICENSE.MIT")
+       Traceback (most recent call last):
+       ...
+       ValueError: Pattern '../LICENSE.MIT' cannot contain '..'...
+       >>> find_pattern("LICEN{CSE*")
+       Traceback (most recent call last):
+       ...
+       ValueError: Pattern 'LICEN{CSE*' contains invalid characters...
+       """
+       if ".." in pattern:
+           raise ValueError(f"Pattern {pattern!r} cannot contain '..'")
+       if pattern.startswith((os.sep, "/")) or ":\\" in pattern:
+           raise ValueError(
+               f"Pattern {pattern!r} should be relative and must not start with '/'"
+           )
+       if re.match(r'^[\w\-\.\/\*\?\[\]]+$', pattern) is None:
+           raise ValueError(f"Pattern '{pattern}' contains invalid characters.")
+       found = glob(pattern, recursive=True)
+       if not found:
+           raise ValueError(f"Pattern '{pattern}' did not match any files.")
+       return found
diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 802f50959..25cf75bc8 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -247,6 +247,8 @@ Tools SHOULD validate and perform case normalization of the expression.
 The table subkeys of the ``license`` key are deprecated.
 
 
+.. _pyproject-toml-license-files:
+
 ``license-files``
 -----------------
 
@@ -260,43 +262,20 @@ configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.)
 to file(s) containing licenses and other legal notices to be
 distributed with the package.
 
-The strings MUST contain valid glob patterns, as specified below:
-
-- Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots (``.``)
-  MUST be matched verbatim.
-
-- Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]``
-  containing only the verbatim matched characters MUST be supported.
-  Within ``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``,
-  order based on Unicode code points).
-  Hyphens at the start or end are matched literally.
+The strings MUST contain valid glob patterns, as specified in
+:doc:`/specifications/glob-patterns`.
 
-- Path delimiters MUST be the forward slash character (``/``).
-  Patterns are relative to the directory containing :file:`pyproject.toml`,
-  therefore the leading slash character MUST NOT be used.
-
-- Parent directory indicators (``..``) MUST NOT be used.
-
-Any characters or character sequences not covered by this specification are
-invalid. Projects MUST NOT use such values.
-Tools consuming this field SHOULD reject invalid values with an error.
+Patterns are relative to the directory containing :file:`pyproject.toml`,
 
 Tools MUST assume that license file content is valid UTF-8 encoded text,
 and SHOULD validate this and raise an error if it is not.
 
-Literal paths (e.g. :file:`LICENSE`) are valid globs which means they
-can also be defined.
-
 Build tools:
 
-- MUST treat each value as a glob pattern, and MUST raise an error if the
-  pattern contains invalid glob syntax.
 - MUST include all files matched by a listed pattern in all distribution
   archives.
 - MUST list each matched file path under a License-File field in the
   Core Metadata.
-- MUST raise an error if any individual user-specified pattern does not match
-  at least one file.
 
 If the ``license-files`` key is present and
 is set to a value of an empty array, then tools MUST NOT include any
diff --git a/source/specifications/section-distribution-metadata.rst b/source/specifications/section-distribution-metadata.rst
index af7c1c3e6..4f3a67777 100644
--- a/source/specifications/section-distribution-metadata.rst
+++ b/source/specifications/section-distribution-metadata.rst
@@ -14,3 +14,4 @@ Package Distribution Metadata
    inline-script-metadata
    platform-compatibility-tags
    well-known-project-urls
+   glob-patterns

From a81a2d00f7ec46a7587d77b39bbf13de2aca36c1 Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri 
Date: Fri, 21 Mar 2025 12:17:30 +0000
Subject: [PATCH 586/733] Allow referencing/linking to individual fields in
 pyproject.toml

---
 source/specifications/pyproject-toml.rst | 31 +++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 25cf75bc8..1adf9e686 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -149,6 +149,8 @@ The complete list of keys allowed in the ``[project]`` table are:
 - ``version``
 
 
+.. _pyproject-toml-name:
+
 ``name``
 --------
 
@@ -161,6 +163,9 @@ The name of the project.
 Tools SHOULD :ref:`normalize ` this name, as soon
 as it is read for internal consistency.
 
+
+.. _pyproject-toml-version:
+
 ``version``
 -----------
 
@@ -174,6 +179,8 @@ The version of the project, as defined in the
 Users SHOULD prefer to specify already-normalized versions.
 
 
+.. _pyproject-toml-description:
+
 ``description``
 ---------------
 
@@ -185,6 +192,8 @@ The summary description of the project in one line. Tools MAY error
 if this includes multiple lines.
 
 
+.. _pyproject-toml-readme:
+
 ``readme``
 ----------
 
@@ -224,6 +233,8 @@ as supported by the :ref:`core metadata `. Otherwise
 tools MUST raise an error for unsupported content-types.
 
 
+.. _pyproject-toml-requires-python:
+
 ``requires-python``
 -------------------
 
@@ -234,6 +245,8 @@ tools MUST raise an error for unsupported content-types.
 The Python version requirements of the project.
 
 
+.. _pyproject-toml-license:
+
 ``license``
 -----------
 
@@ -285,6 +298,9 @@ license files. For example they can choose not to include any files or use
 their own logic to discover the appropriate files in the distribution.
 
 
+.. _pyproject-toml-authors:
+.. _pyproject-toml-maintainers:
+
 ``authors``/``maintainers``
 ---------------------------
 
@@ -327,6 +343,8 @@ follows:
 4. Multiple values should be separated by commas.
 
 
+.. _pyproject-toml-keywords:
+
 ``keywords``
 ------------
 
@@ -337,6 +355,8 @@ follows:
 The keywords for the project.
 
 
+.. _pyproject-toml-classifiers:
+
 ``classifiers``
 ---------------
 
@@ -353,6 +373,8 @@ Build tools MAY raise an error if both the ``license`` string value
 classifiers are used.
 
 
+.. _pyproject-toml-urls:
+
 ``urls``
 --------
 
@@ -365,6 +387,10 @@ URL itself. See :ref:`well-known-project-urls` for normalization rules
 and well-known rules when processing metadata for presentation.
 
 
+.. _pyproject-toml-scripts:
+.. _pyproject-toml-gui-scripts:
+.. _pyproject-toml-entry-points:
+
 Entry points
 ------------
 
@@ -395,6 +421,9 @@ be ambiguous in the face of ``[project.scripts]`` and
 ``[project.gui-scripts]``, respectively.
 
 
+.. _pyproject-toml-dependencies:
+.. _pyproject-toml-optional-dependencies:
+
 ``dependencies``/``optional-dependencies``
 ------------------------------------------
 
@@ -422,7 +451,7 @@ matching :ref:`Provides-Extra `
 metadata.
 
 
-
+.. _pyproject-toml-dynamic:
 .. _declaring-project-metadata-dynamic:
 
 ``dynamic``

From 59b55cf05a7bd89c452b544fa6bebff631d15617 Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Wed, 26 Mar 2025 13:57:51 +0100
Subject: [PATCH 587/733] Specify the valid SPDX license expressions (closes
 #1828)

---
 source/specifications/core-metadata.rst       |  4 +-
 source/specifications/license-expression.rst  | 56 +++++++++++++++++++
 source/specifications/pyproject-toml.rst      |  4 +-
 .../section-distribution-metadata.rst         |  1 +
 4 files changed, 62 insertions(+), 3 deletions(-)
 create mode 100644 source/specifications/license-expression.rst

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 2129be541..39ee7c4cd 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -468,8 +468,8 @@ License-Expression
 .. versionadded:: 2.4
 
 Text string that is a valid SPDX
-`license expression `__
-as `defined in PEP 639 `__.
+:term:`license expression `,
+as specified in :doc:`/specifications/license-expression`.
 
 Examples::
 
diff --git a/source/specifications/license-expression.rst b/source/specifications/license-expression.rst
new file mode 100644
index 000000000..50860b7aa
--- /dev/null
+++ b/source/specifications/license-expression.rst
@@ -0,0 +1,56 @@
+==================
+License Expression
+==================
+
+:pep:`639` defined a new :ref:`pyproject.toml's license `
+value and added a corresponding :ref:`core metadata License-Expression field
+`.
+This specification defines which license expressions are acceptable.
+
+
+Specification
+=============
+
+License can be defined as a text string that is a valid SPDX
+:term:`license expression `,
+as documented in the `SPDX specification `__,
+either Version 2.2 or a later compatible version.
+
+A license expression can use the following license identifiers:
+
+- Any SPDX-listed license short-form identifiers that are published in
+  the `SPDX License List `__,
+  version 3.17 or any later compatible version.
+
+- The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is
+  a unique string containing letters, numbers, ``.`` and/or ``-``,
+  to identify licenses that are not included in the SPDX license list.
+  The custom identifiers must follow the SPDX specification,
+  `clause 10.1 `__ of the given specification version.
+
+
+Examples of valid license expressions:
+
+.. code-block:: yaml
+
+    MIT
+    BSD-3-Clause
+    MIT AND (Apache-2.0 OR BSD-2-Clause)
+    MIT OR GPL-2.0-or-later OR (FSFUL AND BSD-2-Clause)
+    GPL-3.0-only WITH Classpath-Exception-2.0 OR BSD-3-Clause
+    LicenseRef-Special-License OR CC0-1.0 OR Unlicense
+    LicenseRef-Proprietary
+
+
+Examples of invalid license expressions:
+
+.. code-block:: yaml
+
+    Use-it-after-midnight  # No `LicenseRef` prefix
+    Apache-2.0 OR 2-BSD-Clause  # 2-BSD-Clause is not a valid SPDX identifier
+    LicenseRef-License with spaces  # spaces are not allowed
+    LicenseRef-License_with_underscores  # underscore are not allowed
+
+.. _spdxcustom: https://spdx.github.io/spdx-spec/v2.2.2/other-licensing-information-detected/
+.. _spdxlist: https://spdx.org/licenses/
+.. _spdxpression: https://spdx.github.io/spdx-spec/v2.2.2/SPDX-license-expressions/
diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 1adf9e686..9af16582f 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -254,7 +254,9 @@ The Python version requirements of the project.
 - Corresponding :ref:`core metadata ` field:
   :ref:`License-Expression `
 
-Text string that is a valid SPDX license expression as defined in :pep:`639`.
+Text string that is a valid SPDX
+:term:`license expression `,
+as specified in :doc:`/specifications/license-expression`.
 Tools SHOULD validate and perform case normalization of the expression.
 
 The table subkeys of the ``license`` key are deprecated.
diff --git a/source/specifications/section-distribution-metadata.rst b/source/specifications/section-distribution-metadata.rst
index 4f3a67777..551e6b730 100644
--- a/source/specifications/section-distribution-metadata.rst
+++ b/source/specifications/section-distribution-metadata.rst
@@ -15,3 +15,4 @@ Package Distribution Metadata
    platform-compatibility-tags
    well-known-project-urls
    glob-patterns
+   license-expression

From 28e262b43f28c9fc1cd8f3625e245a32217fcb02 Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Wed, 26 Mar 2025 13:58:20 +0100
Subject: [PATCH 588/733] Document legacy pyproject.toml license specification

Cleary mark it as legacy and replaced by PEP 639.
---
 source/specifications/pyproject-toml.rst | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 9af16582f..321a63a81 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -259,8 +259,21 @@ Text string that is a valid SPDX
 as specified in :doc:`/specifications/license-expression`.
 Tools SHOULD validate and perform case normalization of the expression.
 
-The table subkeys of the ``license`` key are deprecated.
+Legacy specification
+''''''''''''''''''''
 
+- TOML_ type: table
+- Corresponding :ref:`core metadata ` field:
+  :ref:`License `
+
+The table may have one of two keys. The ``file`` key has a string
+value that is a file path relative to ``pyproject.toml`` to the file
+which contains the license for the project. Tools MUST assume the
+file's encoding is UTF-8. The ``text`` key has a string value which is
+the license of the project.  These keys are mutually exclusive, so a
+tool MUST raise an error if the metadata specifies both keys.
+
+The table subkeys were deprecated by :pep:`639` in favor of the string value.
 
 .. _pyproject-toml-license-files:
 

From 3ccd14f0422e455fda75bec3e8680113eba59b47 Mon Sep 17 00:00:00 2001
From: Karolina Surma <33810531+befeleme@users.noreply.github.com>
Date: Wed, 26 Mar 2025 15:42:50 +0100
Subject: [PATCH 589/733] Update source/specifications/pyproject-toml.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/specifications/pyproject-toml.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 321a63a81..4ce9b7484 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -267,7 +267,7 @@ Legacy specification
   :ref:`License `
 
 The table may have one of two keys. The ``file`` key has a string
-value that is a file path relative to ``pyproject.toml`` to the file
+value that is a file path relative to :file:`pyproject.toml` to the file
 which contains the license for the project. Tools MUST assume the
 file's encoding is UTF-8. The ``text`` key has a string value which is
 the license of the project.  These keys are mutually exclusive, so a

From 1415b22466bf489397404ec3473d00aaa4df513a Mon Sep 17 00:00:00 2001
From: Martin Fischer 
Date: Thu, 27 Mar 2025 06:13:22 +0100
Subject: [PATCH 590/733] refactor: include build system tabs from shared file
 instead of duplicating them

---
 source/guides/writing-pyproject-toml.rst | 33 +-----------------------
 source/shared/build-backend-tabs.rst     | 33 ++++++++++++++++++++++++
 source/tutorials/packaging-projects.rst  | 33 +-----------------------
 3 files changed, 35 insertions(+), 64 deletions(-)
 create mode 100644 source/shared/build-backend-tabs.rst

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index f77b83b7f..03b402084 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -56,38 +56,7 @@ Usually, you'll just copy what your build backend's documentation
 suggests (after :ref:`choosing your build backend `).
 Here are the values for some common build backends:
 
-.. tab:: Hatchling
-
-    .. code-block:: toml
-
-        [build-system]
-        requires = ["hatchling"]
-        build-backend = "hatchling.build"
-
-.. tab:: setuptools
-
-    .. code-block:: toml
-
-        [build-system]
-        requires = ["setuptools >= 61.0"]
-        build-backend = "setuptools.build_meta"
-
-.. tab:: Flit
-
-    .. code-block:: toml
-
-        [build-system]
-        requires = ["flit_core >= 3.4"]
-        build-backend = "flit_core.buildapi"
-
-.. tab:: PDM
-
-    .. code-block:: toml
-
-        [build-system]
-        requires = ["pdm-backend"]
-        build-backend = "pdm.backend"
-
+.. include:: ../shared/build-backend-tabs.rst
 
 
 Static vs. dynamic metadata
diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
new file mode 100644
index 000000000..7177317be
--- /dev/null
+++ b/source/shared/build-backend-tabs.rst
@@ -0,0 +1,33 @@
+.. (comment) This file is included in guides/writing-pyproject-toml.rst and tutorials/packaging-projects.rst.
+
+.. tab:: Hatchling
+
+    .. code-block:: toml
+
+        [build-system]
+        requires = ["hatchling"]
+        build-backend = "hatchling.build"
+
+.. tab:: setuptools
+
+    .. code-block:: toml
+
+        [build-system]
+        requires = ["setuptools >= 61.0"]
+        build-backend = "setuptools.build_meta"
+
+.. tab:: Flit
+
+    .. code-block:: toml
+
+        [build-system]
+        requires = ["flit_core >= 3.4"]
+        build-backend = "flit_core.buildapi"
+
+.. tab:: PDM
+
+    .. code-block:: toml
+
+        [build-system]
+        requires = ["pdm-backend"]
+        build-backend = "pdm.backend"
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 8992fffb0..2888fef89 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -136,38 +136,7 @@ The :file:`pyproject.toml` tells :term:`build frontend ` tools l
 examples for common build backends, but check your backend's own documentation
 for more details.
 
-.. tab:: Hatchling
-
-    .. code-block:: toml
-
-        [build-system]
-        requires = ["hatchling"]
-        build-backend = "hatchling.build"
-
-.. tab:: setuptools
-
-    .. code-block:: toml
-
-        [build-system]
-        requires = ["setuptools>=61.0"]
-        build-backend = "setuptools.build_meta"
-
-.. tab:: Flit
-
-    .. code-block:: toml
-
-        [build-system]
-        requires = ["flit_core>=3.4"]
-        build-backend = "flit_core.buildapi"
-
-.. tab:: PDM
-
-    .. code-block:: toml
-
-        [build-system]
-        requires = ["pdm-backend"]
-        build-backend = "pdm.backend"
-
+.. include:: ../shared/build-backend-tabs.rst
 
 The ``requires`` key is a list of packages that are needed to build your package.
 The :term:`frontend ` should install them automatically when building your package.

From 6d0b21a4d9362bc0ca635aef15ec354852a78fce Mon Sep 17 00:00:00 2001
From: Martin Fischer 
Date: Tue, 25 Mar 2025 08:12:03 +0100
Subject: [PATCH 591/733] Latest setuptools and flit now support PEP 639

This updates the now outdated notes added in
faf4c7d882ef2be310d5dc46d54ca666aa18821c.

Closes #1831.
---
 .../licensing-examples-and-user-scenarios.rst |  2 -
 source/guides/writing-pyproject-toml.rst      | 88 +++++++++----------
 source/shared/build-backend-tabs.rst          |  9 +-
 source/tutorials/packaging-projects.rst       | 72 +++++----------
 4 files changed, 73 insertions(+), 98 deletions(-)

diff --git a/source/guides/licensing-examples-and-user-scenarios.rst b/source/guides/licensing-examples-and-user-scenarios.rst
index ae0066581..2c25ddfb0 100644
--- a/source/guides/licensing-examples-and-user-scenarios.rst
+++ b/source/guides/licensing-examples-and-user-scenarios.rst
@@ -12,8 +12,6 @@ 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
 trying to apply the newer guidelines.
-As of February 2025, :doc:`setuptools `
-and :ref:`flit ` don't support :pep:`639` yet.
 
 
 Licensing Examples
diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 03b402084..318fe0d51 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -291,22 +291,43 @@ You can also specify the format explicitly, like this:
    readme = {file = "README.txt", content-type = "text/x-rst"}
 
 
-.. _license:
+.. _license-and-license-files:
 
-``license``
------------
+``license`` and ``license-files``
+---------------------------------
+
+As per :pep:`639` licenses should be declared with two fields:
+
+- ``license`` is an :term:`SPDX license expression ` consisting
+  of one or more :term:`license identifiers `.
+- ``license-files`` is a list of license file glob patterns.
+
+A previous PEP had specified ``license`` to be a table with a ``file`` or a
+``text`` key, this format is now deprecated. Most :term:`build backends` now support the new format as shown in the following table.
+
+.. list-table:: build backend versions that introduced :pep:`639` support
+   :header-rows: 1
 
-:pep:`639` (accepted in August 2024) has changed the way the ``license`` field
-is declared. Make sure your preferred build backend supports :pep:`639` before
-trying to apply the newer guidelines.
-As of February 2025, :doc:`setuptools `
-and :ref:`flit ` don't support :pep:`639` yet.
+   * - hatchling
+     - setuptools
+     - flit-core [#flit-core-pep639]_
+     - pdm-backend
+     - poetry-core
+   * - 1.27.0
+     - 77.0.3
+     - 3.12
+     - 2.4.0
+     - `not yet `_
 
-:pep:`639` license declaration
-''''''''''''''''''''''''''''''
 
-This is a valid :term:`SPDX license expression ` consisting
-of one or more :term:`license identifiers `.
+.. _license:
+
+``license``
+'''''''''''
+
+The new format for ``license`` is a valid :term:`SPDX license expression `
+consisting of one or more :term:`license identifiers `.
 The full license list is available at the
 `SPDX license list page `_. The supported list version is
 3.17 or any later compatible one.
@@ -318,6 +339,11 @@ The full license list is available at the
     # or
     license = "MIT AND (Apache-2.0 OR BSD-2-Clause)"
 
+.. note:: If you get a build error that ``license`` should be a dict/table,
+   your build backend doesn't yet support the new format. See the
+   `above section `_ for more context.
+   The now deprecated format is `described in PEP 621 `__.
+
 As a general rule, it is a good idea to use a standard, well-known
 license, both to avoid confusion and because some organizations avoid software
 whose license is unapproved.
@@ -332,41 +358,11 @@ The custom identifiers must follow the SPDX specification,
     [project]
     license = "LicenseRef-My-Custom-License"
 
-Legacy license declaration
-''''''''''''''''''''''''''
-
-This can take two forms. You can put your license in a file, typically
-:file:`LICENSE` or :file:`LICENSE.txt`, and link that file here:
-
-.. code-block:: toml
-
-    [project]
-    license = {file = "LICENSE"}
-
-or you can write the name of the license:
-
-.. code-block:: toml
-
-    [project]
-    license = {text = "MIT License"}
-
-If you are using a standard, well-known license, it is not necessary to use this
-field. Instead, you should use one of the :ref:`classifiers` starting with ``License
-::``. (As a general rule, it is a good idea to use a standard, well-known
-license, both to avoid confusion and because some organizations avoid software
-whose license is unapproved.)
-
 
 .. _license-files:
 
 ``license-files``
------------------
-
-:pep:`639` (accepted in August 2024) has introduced the ``license-files`` field.
-Make sure your preferred build backend supports :pep:`639` before declaring the
-field.
-As of February 2025, :doc:`setuptools `
-and :ref:`flit ` don't support :pep:`639` yet.
+'''''''''''''''''
 
 This is a list of license files and files containing other legal
 information you want to distribute with your package.
@@ -541,7 +537,7 @@ A full example
    ]
    description = "Lovely Spam! Wonderful Spam!"
    readme = "README.rst"
-   license = "MIT"  # or license = {file = "LICENSE.txt"} for legacy declaration
+   license = "MIT"
    license-files = ["LICEN[CS]E.*"]
    keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
    classifiers = [
@@ -579,6 +575,9 @@ A full example
    like ``requires-python = "<= 3.10"`` here. `This blog post `_
    contains some information regarding possible problems.
 
+.. [#flit-core-pep639] flit-core `does not yet `_ support WITH in SPDX license expressions.
+
+.. _flit-issue-735: https://github.com/pypa/flit/issues/735
 .. _gfm: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
 .. _setuptools: https://setuptools.pypa.io
 .. _poetry: https://python-poetry.org
@@ -586,6 +585,7 @@ A full example
 .. _pypi-search-pip: https://pypi.org/search?q=pip
 .. _classifier-list: https://pypi.org/classifiers
 .. _requires-python-blog-post: https://iscinumpy.dev/post/bound-version-constraints/#pinning-the-python-version-is-special
+.. _poetry-pep639-issue: https://github.com/python-poetry/poetry/issues/9670
 .. _pytest: https://pytest.org
 .. _pygments: https://pygments.org
 .. _rest: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index 7177317be..0e5bd6190 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -1,11 +1,12 @@
 .. (comment) This file is included in guides/writing-pyproject-toml.rst and tutorials/packaging-projects.rst.
+.. The minimum versions here are the versions that introduced support for PEP 639.
 
 .. tab:: Hatchling
 
     .. code-block:: toml
 
         [build-system]
-        requires = ["hatchling"]
+        requires = ["hatchling >= 1.26"]
         build-backend = "hatchling.build"
 
 .. tab:: setuptools
@@ -13,7 +14,7 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["setuptools >= 61.0"]
+        requires = ["setuptools >= 77.0.3"]
         build-backend = "setuptools.build_meta"
 
 .. tab:: Flit
@@ -21,7 +22,7 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["flit_core >= 3.4"]
+        requires = ["flit_core >= 3.12.0"]
         build-backend = "flit_core.buildapi"
 
 .. tab:: PDM
@@ -29,5 +30,5 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["pdm-backend"]
+        requires = ["pdm-backend >= 2.4.0"]
         build-backend = "pdm.backend"
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 2888fef89..6d0a95d5c 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -144,6 +144,8 @@ Frontends usually run builds in isolated environments, so omitting dependencies
 here may cause build-time errors.
 This should always include your backend's package, and might have other build-time
 dependencies.
+The minimum version specified in the above code block is the one that introduced support
+for :ref:`the new license metadata `.
 
 The ``build-backend`` key is the name of the Python object that frontends will use
 to perform the build.
@@ -169,52 +171,27 @@ to include your username; this ensures that you have a unique
 package name that doesn't conflict with packages uploaded by other people
 following this tutorial.
 
-.. tab:: hatchling/pdm
-
-  .. code-block:: toml
-
-      [project]
-      name = "example_package_YOUR_USERNAME_HERE"
-      version = "0.0.1"
-      authors = [
-        { name="Example Author", email="author@example.com" },
-      ]
-      description = "A small example package"
-      readme = "README.md"
-      requires-python = ">=3.8"
-      classifiers = [
-          "Programming Language :: Python :: 3",
-          "Operating System :: OS Independent",
-      ]
-      license = "MIT"
-      license-files = ["LICEN[CS]E*"]
-
-      [project.urls]
-      Homepage = "https://github.com/pypa/sampleproject"
-      Issues = "https://github.com/pypa/sampleproject/issues"
-
-.. tab:: setuptools/flit
-
-  .. code-block:: toml
-
-      [project]
-      name = "example_package_YOUR_USERNAME_HERE"
-      version = "0.0.1"
-      authors = [
-        { name="Example Author", email="author@example.com" },
-      ]
-      description = "A small example package"
-      readme = "README.md"
-      requires-python = ">=3.8"
-      classifiers = [
-          "Programming Language :: Python :: 3",
-          "Operating System :: OS Independent",
-          "License :: OSI Approved :: MIT License",
-      ]
-
-      [project.urls]
-      Homepage = "https://github.com/pypa/sampleproject"
-      Issues = "https://github.com/pypa/sampleproject/issues"
+.. code-block:: toml
+
+    [project]
+    name = "example_package_YOUR_USERNAME_HERE"
+    version = "0.0.1"
+    authors = [
+      { name="Example Author", email="author@example.com" },
+    ]
+    description = "A small example package"
+    readme = "README.md"
+    requires-python = ">=3.8"
+    classifiers = [
+        "Programming Language :: Python :: 3",
+        "Operating System :: OS Independent",
+    ]
+    license = "MIT"
+    license-files = ["LICEN[CS]E*"]
+
+    [project.urls]
+    Homepage = "https://github.com/pypa/sampleproject"
+    Issues = "https://github.com/pypa/sampleproject/issues"
 
 - ``name`` is the *distribution name* of your package. This can be any name as
   long as it only contains letters, numbers, ``.``, ``_`` , and ``-``. It also
@@ -243,10 +220,9 @@ following this tutorial.
   your package will work on. For a complete list of classifiers, see
   https://pypi.org/classifiers/.
 - ``license`` is the :term:`SPDX license expression ` of
-  your package. Not supported by all the build backends yet.
+  your package.
 - ``license-files`` is the list of glob paths to the license files,
   relative to the directory where :file:`pyproject.toml` is located.
-  Not supported by all the build backends yet.
 - ``urls`` lets you list any number of extra links to show on PyPI.
   Generally this could be to the source, documentation, issue trackers, etc.
 

From 8a64c523640afe3791419687c6a59feeed1f7c6e Mon Sep 17 00:00:00 2001
From: Martin Fischer 
Date: Sat, 29 Mar 2025 06:37:51 +0100
Subject: [PATCH 592/733] Add <4 to require as recommended by Flit docs

As per https://flit.pypa.io/en/stable/pyproject_toml.html#build-system-section:

> For now, all packages should specify <4, so they won't be
> impacted by changes in the next major version.
---
 source/shared/build-backend-tabs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index 0e5bd6190..7fc3a61da 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -22,7 +22,7 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["flit_core >= 3.12.0"]
+        requires = ["flit_core >= 3.12.0, <4"]
         build-backend = "flit_core.buildapi"
 
 .. tab:: PDM

From ef7502a2e58855d06ef3f5cc320b17992a15bd16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns?= 
Date: Sun, 30 Mar 2025 12:52:56 +0100
Subject: [PATCH 593/733] Set html_extra_path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Filipe Laíns 
---
 source/conf.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/source/conf.py b/source/conf.py
index e10132578..b4565afe4 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -83,6 +83,10 @@
     # https://plausible.io/packaging.python.org
     html_js_files.extend(_metrics_js_files)
 
+html_extra_path = [
+    "specifications/schemas",
+]
+
 # -- Options for HTML help output ------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-help-output
 

From 76a2f55024e4188eb65ac71996af8a0824488acb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns?= 
Date: Sun, 30 Mar 2025 12:53:25 +0100
Subject: [PATCH 594/733] Fix schema ID
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Filipe Laíns 
---
 source/specifications/schemas/build-details-v1.0.schema.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/schemas/build-details-v1.0.schema.json b/source/specifications/schemas/build-details-v1.0.schema.json
index b088431b5..9954ddab7 100644
--- a/source/specifications/schemas/build-details-v1.0.schema.json
+++ b/source/specifications/schemas/build-details-v1.0.schema.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://packaging.python.org/en/latest/specifications/schemas/python-build-info-v1.0.schema.json",
+  "$id": "https://packaging.python.org/en/latest/specifications/schemas/build-details-v1.0.schema.json",
   "type": "object",
   "title": "build-details.json — a static description file with build details of Python installations",
   "required": [

From 7b72c11d5409a7262ac94ad4ae275ef3619af2eb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns?= 
Date: Sun, 30 Mar 2025 12:53:40 +0100
Subject: [PATCH 595/733] Use download role for schema
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Filipe Laíns 
---
 source/specifications/build-details/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/build-details/index.rst b/source/specifications/build-details/index.rst
index 5da5a7f03..1d4470aef 100644
--- a/source/specifications/build-details/index.rst
+++ b/source/specifications/build-details/index.rst
@@ -46,7 +46,7 @@ v1.0
       - :ref:`build-details-v1.0`
 
     * - Schema
-      - https://packaging.python.org/en/latest/specifications/schemas/python-build-info-v1.0.schema.json
+      - :download:`https://packaging.python.org/en/latest/specifications/schemas/build-details-v1.0.schema.json <../schemas/build-details-v1.0.schema.json>`
 
 
 - Initial version, introduced by :pep:`739`.

From 486e6842e7c17522293f1f43a871bc18b4e1582e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns?= 
Date: Thu, 3 Apr 2025 03:49:38 +0100
Subject: [PATCH 596/733] specifications: fix build-details-v1.0.schema.json
 location
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Filipe Laíns 
---
 .../specifications/schemas/build-details-v1.0.schema.json       | 0
 source/conf.py                                                  | 2 +-
 source/specifications/build-details/index.rst                   | 2 +-
 source/specifications/build-details/v1.0.rst                    | 2 +-
 4 files changed, 3 insertions(+), 3 deletions(-)
 rename {source => extra}/specifications/schemas/build-details-v1.0.schema.json (100%)

diff --git a/source/specifications/schemas/build-details-v1.0.schema.json b/extra/specifications/schemas/build-details-v1.0.schema.json
similarity index 100%
rename from source/specifications/schemas/build-details-v1.0.schema.json
rename to extra/specifications/schemas/build-details-v1.0.schema.json
diff --git a/source/conf.py b/source/conf.py
index b4565afe4..b0c468df7 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -84,7 +84,7 @@
     html_js_files.extend(_metrics_js_files)
 
 html_extra_path = [
-    "specifications/schemas",
+    "../extra",
 ]
 
 # -- Options for HTML help output ------------------------------------------------------
diff --git a/source/specifications/build-details/index.rst b/source/specifications/build-details/index.rst
index 1d4470aef..0cd5b5fe5 100644
--- a/source/specifications/build-details/index.rst
+++ b/source/specifications/build-details/index.rst
@@ -46,7 +46,7 @@ v1.0
       - :ref:`build-details-v1.0`
 
     * - Schema
-      - :download:`https://packaging.python.org/en/latest/specifications/schemas/build-details-v1.0.schema.json <../schemas/build-details-v1.0.schema.json>`
+      - https://packaging.python.org/en/latest/specifications/schemas/build-details-v1.0.schema.json
 
 
 - Initial version, introduced by :pep:`739`.
diff --git a/source/specifications/build-details/v1.0.rst b/source/specifications/build-details/v1.0.rst
index cfe902e1e..3a8cfe277 100644
--- a/source/specifications/build-details/v1.0.rst
+++ b/source/specifications/build-details/v1.0.rst
@@ -8,7 +8,7 @@
 Specification
 -------------
 
-.. jsonschema:: ../schemas/build-details-v1.0.schema.json
+.. jsonschema:: ../../../extra/specifications/schemas/build-details-v1.0.schema.json
     :lift_title: false
 
 

From 5413e625561c719e2ac15b8c9c0313141524d73e Mon Sep 17 00:00:00 2001
From: Ee Durbin 
Date: Tue, 8 Apr 2025 03:16:27 -0400
Subject: [PATCH 597/733] Add psfhosted plausbile instance to analytics

I'm evaluating the self-hosted option on the psf infrastructure.
---
 source/conf.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/source/conf.py b/source/conf.py
index b0c468df7..b3ebd0502 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -75,7 +75,11 @@
     (
         "https://plausible.io/js/script.js",
         {"data-domain": "packaging.python.org", "defer": "defer"},
-    )
+    ),
+    (
+        "https://analytics.python.org/js/script.js",
+        {"data-domain": "packaging.python.org", "defer": "defer"},
+    ),
 ]
 html_js_files = []
 if RTD_CANONICAL_BUILD:

From 11de88c7397fb99781ba090fad148c665607ddc1 Mon Sep 17 00:00:00 2001
From: Douglas Silva 
Date: Mon, 14 Apr 2025 10:44:54 -0300
Subject: [PATCH 598/733] Update packaging-projects.rst: set requires-python to
 3.9

See https://github.com/pypa/packaging.python.org/issues/1845
---
 source/tutorials/packaging-projects.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index 6d0a95d5c..f2c0851ba 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -181,7 +181,7 @@ following this tutorial.
     ]
     description = "A small example package"
     readme = "README.md"
-    requires-python = ">=3.8"
+    requires-python = ">=3.9"
     classifiers = [
         "Programming Language :: Python :: 3",
         "Operating System :: OS Independent",

From b8cfd1cf129d0648260126740d7c6aa4905f8cbf Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Mon, 14 Apr 2025 16:26:36 -0700
Subject: [PATCH 599/733] Add PEP 751

---
 .../specifications/dependency-specifiers.rst  |  53 +-
 source/specifications/index.rst               |   1 +
 source/specifications/pylock-toml.rst         | 772 ++++++++++++++++++
 .../section-reproducible-environments.rst     |   8 +
 4 files changed, 823 insertions(+), 11 deletions(-)
 create mode 100644 source/specifications/pylock-toml.rst
 create mode 100644 source/specifications/section-reproducible-environments.rst

diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index 06897da27..332dbe6e7 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -87,7 +87,7 @@ environments::
                      'platform_system' | 'platform_version' |
                      'platform_machine' | 'platform_python_implementation' |
                      'implementation_name' | 'implementation_version' |
-                     'extra' # ONLY when defined by a containing layer
+                     'extra' | 'extras' | 'dependency_groups' # ONLY when defined by a containing layer
                      )
     marker_var    = wsp* (env_var | python_str)
     marker_expr   = marker_var marker_op marker_var
@@ -196,15 +196,16 @@ safely evaluate it without running arbitrary code that could become a security
 vulnerability. Markers were first standardised in :pep:`345`. This document
 fixes some issues that were observed in the design described in :pep:`426`.
 
-Comparisons in marker expressions are typed by the comparison operator.  The
- operators that are not in  perform the same as they
-do for strings in Python. The  operators use the version comparison
-rules of the :ref:`Version specifier specification `
-when those are defined (that is when both sides have a valid
-version specifier). If there is no defined behaviour of this specification
-and the operator exists in Python, then the operator falls back to
-the Python behaviour. Otherwise an error should be raised. e.g. the following
-will result in  errors::
+Comparisons in marker expressions are typed by the comparison operator and the
+type of the marker value. The  operators that are not in
+ perform the same as they do for strings or sets in Python based on
+whether the marker value is a string or set itself. The  operators
+use the version comparison rules of the
+:ref:`Version specifier specification ` when those are
+defined (that is when both sides have a valid version specifier). If there is no
+defined behaviour of this specification and the operator exists in Python, then
+the operator falls back to the Python behaviour for the types involved.
+Otherwise an error should be raised. e.g. the following will result in errors::
 
     "dog" ~= "fred"
     python_version ~= "surprise"
@@ -235,52 +236,80 @@ no current specification for this. Regardless, outside of a context where this
 special handling is taking place, the "extra" variable should result in an
 error like all other unknown variables.
 
+The "extras" and "dependency_groups" variables are also special. They are used
+to specify any requested extras or dependency groups when installing from a lock
+file. Outside of the context of lock files, these two variables should result in
+an error like all other unknown variables.
+
 .. list-table::
    :header-rows: 1
 
    * - Marker
      - Python equivalent
+     - Type
      - Sample values
    * - ``os_name``
      - :py:data:`os.name`
+     - String
      - ``posix``, ``java``
    * - ``sys_platform``
      - :py:data:`sys.platform`
+     - String
      - ``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that "linux"
        is from Python3 and "linux2" from Python2)
    * - ``platform_machine``
      - :py:func:`platform.machine()`
+     - String
      - ``x86_64``
    * - ``platform_python_implementation``
      - :py:func:`platform.python_implementation()`
+     - String
      - ``CPython``, ``Jython``
    * - ``platform_release``
      - :py:func:`platform.release()`
+     - String
      - ``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``
    * - ``platform_system``
      - :py:func:`platform.system()`
+     - String
      - ``Linux``, ``Windows``, ``Java``
    * - ``platform_version``
      - :py:func:`platform.version()`
+     - String
      - ``#1 SMP Fri Apr 25 13:07:35 EDT 2014``
        ``Java HotSpot(TM) 64-Bit Server VM, 25.51-b03, Oracle Corporation``
        ``Darwin Kernel Version 14.5.0: Wed Jul 29 02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``
    * - ``python_version``
      - ``'.'.join(platform.python_version_tuple()[:2])``
+     - Version
      - ``3.4``, ``2.7``
    * - ``python_full_version``
      - :py:func:`platform.python_version()`
+     - Version
      - ``3.4.0``, ``3.5.0b1``
    * - ``implementation_name``
      - :py:data:`sys.implementation.name `
+     - String
      - ``cpython``
    * - ``implementation_version``
      - see definition below
+     - Version
      - ``3.4.0``, ``3.5.0b1``
    * - ``extra``
      - An error except when defined by the context interpreting the
        specification.
+     - String
      - ``test``
+   * - ``extras``
+     - An error except when defined by the context interpreting the
+       specification.
+     - Set of strings
+     - ``{"test"}``
+   * - ``dependency_groups``
+     - An error except when defined by the context interpreting the
+       specification.
+     - Set of strings
+     - ``{"test"}``
 
 The ``implementation_version`` marker variable is derived from
 :py:data:`sys.implementation.version `:
@@ -330,7 +359,7 @@ The complete parsley grammar::
                      'platform_system' | 'platform_version' |
                      'platform_machine' | 'platform_python_implementation' |
                      'implementation_name' | 'implementation_version' |
-                     'extra' # ONLY when defined by a containing layer
+                     'extra' | 'extras' | 'dependency_groups' # ONLY when defined by a containing layer
                      ):varname -> lookup(varname)
     marker_var    = wsp* (env_var | python_str)
     marker_expr   = marker_var:l marker_op:o marker_var:r -> (o, l, r)
@@ -495,6 +524,8 @@ History
 - June 2024: The definition of ``version_many`` was changed to allow trailing
   commas, matching with the behavior of the Python implementation that has been
   in use since late 2022.
+- April 2025: Added ``extras`` and ``dependency_groups`` for lock-file-spec_ as
+  approved through :pep:`751`.
 
 
 References
diff --git a/source/specifications/index.rst b/source/specifications/index.rst
index c69605927..68d95ab98 100644
--- a/source/specifications/index.rst
+++ b/source/specifications/index.rst
@@ -16,3 +16,4 @@ and for proposing new ones, is documented on
    section-distribution-formats
    section-package-indices
    section-python-description-formats
+   section-reproducible-environments
diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
new file mode 100644
index 000000000..700aac3a4
--- /dev/null
+++ b/source/specifications/pylock-toml.rst
@@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-files:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- Record the file format version that the file adheres to.
+- This PEP specifies the initial version -- and only valid value until future
+  updates to the standard change it -- as ``"1.0"``.
+- If a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras ` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- An array containing all packages that *may* be installed.
+- Packages MAY be listed multiple times with varying data, but all packages to
+  be installed MUST narrow down to a single entry at install time.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized `.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist ` or
+  :ref:`wheels ` are specified).
+- The version MUST NOT be included when it cannot be guaranteed to be consistent
+  with the code used (i.e. when a
+  :ref:`source tree ` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker `
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree ` it
+  contains.
+- Tools MAY choose to not support version control systems, both from a locking
+  and/or installation perspective.
+- Tools MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference `.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The path to the local directory of the source tree.
+- If a relative path is used it MUST be relative to the location of this file.
+- If the path is relative it MAY use POSIX-style path separators explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The branch/tag/ref/commit/revision/etc. that the user requested.
+- This is purely informational and to facilitate writing the
+  :ref:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The exact commit/revision number that is to be installed.
+- If the VCS supports commit-hash based revision identifiers, such a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree ` where
+  the project root of the project is (e.g. the location of the
+  ``pyproject.toml`` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree ` it
+  contains.
+- Tools MAY choose to not support local directories, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference `.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference `.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the ``[tool]`` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via ``[tool]``).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
+
+
+``[tool]``
+==========
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- See ``packages.tool``.
+
+
+-------
+Example
+-------
+
+.. code-block:: TOML
+
+  lock-version = '1.0'
+  environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+  requires-python = '==3.12'
+  created-by = 'mousebender'
+
+  [[packages]]
+  name = 'attrs'
+  version = '25.1.0'
+  requires-python = '>=3.8'
+  wheels = [
+    {name = 'attrs-25.1.0-py3-none-any.whl', upload-time = 2025-01-25T11:30:10.164985+00:00, url = 'https://files.pythonhosted.org/packages/fc/30/d4986a882011f9df997a55e6becd864812ccfcd821d64aac8570ee39f719/attrs-25.1.0-py3-none-any.whl', size = 63152, hashes = {sha256 = 'c75a69e28a550a7e93789579c22aa26b0f5b83b75dc4e08fe092980051e1090a'}},
+  ]
+  [[packages.attestation-identities]]
+  environment = 'release-pypi'
+  kind = 'GitHub'
+  repository = 'python-attrs/attrs'
+  workflow = 'pypi-package.yml'
+
+  [[packages]]
+  name = 'cattrs'
+  version = '24.1.2'
+  requires-python = '>=3.8'
+  dependencies = [
+      {name = 'attrs'},
+  ]
+  wheels = [
+    {name = 'cattrs-24.1.2-py3-none-any.whl', upload-time = 2024-09-22T14:58:34.812643+00:00, url = 'https://files.pythonhosted.org/packages/c8/d5/867e75361fc45f6de75fe277dd085627a9db5ebb511a87f27dc1396b5351/cattrs-24.1.2-py3-none-any.whl', size = 66446, hashes = {sha256 = '67c7495b760168d931a10233f979b28dc04daf853b30752246f4f8471c6d68d0'}},
+  ]
+
+  [[packages]]
+  name = 'numpy'
+  version = '2.2.3'
+  requires-python = '>=3.10'
+  wheels = [
+    {name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl', upload-time = 2025-02-13T16:51:21.821880+00:00, url = 'https://files.pythonhosted.org/packages/42/6e/55580a538116d16ae7c9aa17d4edd56e83f42126cb1dfe7a684da7925d2c/numpy-2.2.3-cp312-cp312-win_amd64.whl', size = 12626357, hashes = {sha256 = '83807d445817326b4bcdaaaf8e8e9f1753da04341eceec705c001ff342002e5d'}},
+    {name = 'numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', upload-time = 2025-02-13T16:50:00.079662+00:00, url = 'https://files.pythonhosted.org/packages/39/04/78d2e7402fb479d893953fb78fa7045f7deb635ec095b6b4f0260223091a/numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', size = 16116679, hashes = {sha256 = '3b787adbf04b0db1967798dba8da1af07e387908ed1553a0d6e74c084d1ceafe'}},
+  ]
+
+  [tool.mousebender]
+  command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
+  run-on = 2025-03-06T12:28:57.760769
+
+
+------------
+Installation
+------------
+
+The following outlines the steps to be taken to install from a lock file
+(while the requirements are prescriptive, the general steps and order are
+a suggestion):
+
+#. Gather the extras and dependency groups to install and set ``extras`` and
+   ``dependency_groups`` for marker evaluation, respectively.
+
+   #. ``extras`` SHOULD be set to the empty set by default.
+   #. ``dependency_groups`` SHOULD be the set created from ``default-groups`` by
+      default.
+
+#. Check if the metadata version specified by ``lock-version`` is supported;
+   an error or warning MUST be raised as appropriate.
+#. If ``requires-python`` is specified, check that the environment being
+   installed for meets the requirement; an error MUST be raised if it is not
+   met.
+#. If ``environments`` is specified, check that at least one of the environment
+   marker expressions is satisfied; an error MUST be raised if no expression is
+   satisfied.
+#. For each package listed in ``[[packages]]``:
+
+   #. If ``marker`` is specified, check if it is satisfied; if it isn't,
+      skip to the next package.
+   #. If ``requires-python`` is specified, check if it is satisfied; an error
+      MUST be raised if it isn't.
+   #. Check that no other conflicting instance of the package has been slated to
+      be installed; an error about the ambiguity MUST be raised otherwise.
+   #. Check that the source of the package is specified appropriately (i.e.
+      there are no conflicting sources in the package entry);
+      an error MUST be raised if any issues are found.
+   #. Add the package to the set of packages to install.
+
+#. For each package to be installed:
+
+   - If ``vcs`` is set:
+
+     #. Clone the repository to the commit ID specified in ``commit-id``.
+     #. Build the package, respecting ``subdirectory``.
+     #. Install.
+
+   - Else if ``directory`` is set:
+
+     #. Build the package, respecting ``subdirectory``.
+     #. Install.
+
+   - Else if ``archive`` is set:
+
+     #. Get the file.
+     #. Validate the file size and hash.
+     #. Build the package, respecting ``subdirectory``.
+     #. Install.
+
+   - Else if there are entries for ``wheels``:
+
+     #. Look for the appropriate wheel file based on ``name``; if one is not
+        found then move on to ``sdist`` or an error MUST be raised about a
+        lack of source for the project.
+     #. Get the file:
+
+        - If ``path`` is set, use it.
+        - If ``url`` is set, try to use it; optionally tools MAY use
+          ``packages.index`` or some tool-specific mechanism to download the
+          selected wheel file (tools MUST NOT try to change what wheel file to
+          download based on what's available; what file to install should be
+          determined in an offline fashion for reproducibility).
+
+     #. Validate the file size and hash.
+     #. Install.
+
+   - Else if no ``wheel`` file is found or ``sdist`` is solely set:
+
+     #. Get the file.
+
+        - If ``path`` is set, use it.
+        - If ``url`` is set, try to use it; tools MAY use
+          ``packages.index`` or some tool-specific mechanism to download the
+          file.
+
+     #. Validate the file size and hash.
+     #. Build the package.
+     #. Install.
+
+
+-------
+History
+-------
+
+- April 2025: Initial version, approved via :pep:`751`.
+
+
+.. _Content-Length: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length
+.. _Dependabot: https://docs.github.com/en/code-security/dependabot
+.. _HEAD: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
+.. _PDM: https://pypi.org/project/pdm/
+.. _pip-tools: https://pypi.org/project/pip-tools/
+.. _Poetry: https://python-poetry.org/
+.. _requirements file:
+.. _requirements files: https://pip.pypa.io/en/stable/reference/requirements-file-format/
+.. _software bill of materials: https://www.cisa.gov/sbom
+.. _TOML: https://toml.io/
+.. _uv: https://github.com/astral-sh/uv
diff --git a/source/specifications/section-reproducible-environments.rst b/source/specifications/section-reproducible-environments.rst
new file mode 100644
index 000000000..1f83f3673
--- /dev/null
+++ b/source/specifications/section-reproducible-environments.rst
@@ -0,0 +1,8 @@
+=========================
+Reproducible Environments
+=========================
+
+.. toctree::
+   :titlesonly:
+
+   pylock-toml

From e06f55b0d8edeba0705a58db0e9f477f786dd394 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Mon, 14 Apr 2025 16:32:43 -0700
Subject: [PATCH 600/733] Fix a reference

---
 source/specifications/pylock-toml.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
index 700aac3a4..c214f4c18 100644
--- a/source/specifications/pylock-toml.rst
+++ b/source/specifications/pylock-toml.rst
@@ -1,5 +1,5 @@
 .. _pylock-toml-spec:
-.. _lock-files:
+.. _lock-files-spec:
 
 =============================
 ``pylock.toml`` Specification

From effb0611f926b6ae7eea678f767d3fb137e40e87 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Mon, 14 Apr 2025 16:34:17 -0700
Subject: [PATCH 601/733] Fix a reference (again)

---
 source/specifications/pylock-toml.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
index c214f4c18..75449e4d1 100644
--- a/source/specifications/pylock-toml.rst
+++ b/source/specifications/pylock-toml.rst
@@ -1,5 +1,5 @@
 .. _pylock-toml-spec:
-.. _lock-files-spec:
+.. _lock-file-spec:
 
 =============================
 ``pylock.toml`` Specification

From 8db327530dadfe3e28da0e4f3bfb227589eee2d8 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Mon, 14 Apr 2025 16:36:05 -0700
Subject: [PATCH 602/733] Use a reference arrpropriately

---
 source/specifications/dependency-specifiers.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index 332dbe6e7..c8701b795 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -524,8 +524,8 @@ History
 - June 2024: The definition of ``version_many`` was changed to allow trailing
   commas, matching with the behavior of the Python implementation that has been
   in use since late 2022.
-- April 2025: Added ``extras`` and ``dependency_groups`` for lock-file-spec_ as
-  approved through :pep:`751`.
+- April 2025: Added ``extras`` and ``dependency_groups`` for
+  :ref:`lock-file-spec` as approved through :pep:`751`.
 
 
 References

From 0750cbef78336297bc2b21a2da0898e9d6c83bc1 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Tue, 15 Apr 2025 12:46:54 -0700
Subject: [PATCH 603/733] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Filipe Laíns 🇵🇸 
---
 .../specifications/dependency-specifiers.rst  |   6 +-
 source/specifications/pylock-toml.rst         | 111 +++++++++++++-----
 2 files changed, 84 insertions(+), 33 deletions(-)

diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index c8701b795..62731ffbb 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -281,11 +281,11 @@ an error like all other unknown variables.
        ``Darwin Kernel Version 14.5.0: Wed Jul 29 02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``
    * - ``python_version``
      - ``'.'.join(platform.python_version_tuple()[:2])``
-     - Version
+     - :ref:`Version `
      - ``3.4``, ``2.7``
    * - ``python_full_version``
      - :py:func:`platform.python_version()`
-     - Version
+     - :ref:`Version `
      - ``3.4.0``, ``3.5.0b1``
    * - ``implementation_name``
      - :py:data:`sys.implementation.name `
@@ -293,7 +293,7 @@ an error like all other unknown variables.
      - ``cpython``
    * - ``implementation_version``
      - see definition below
-     - Version
+     - :ref:`Version `
      - ``3.4.0``, ``3.5.0b1``
    * - ``extra``
      - An error except when defined by the context interpreting the
diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
index 75449e4d1..24347a95c 100644
--- a/source/specifications/pylock-toml.rst
+++ b/source/specifications/pylock-toml.rst
@@ -60,6 +60,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 .. File details
 
+.. _pylock-lock-version:
 ``lock-version``
 ================
 
@@ -74,6 +75,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 - If a tool doesn't support a major version, it MUST raise an error.
 
 
+.. _pylock-environments:
 ``environments``
 ================
 
@@ -86,6 +88,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   understanding.
 
 
+.. _pylock-requires-python:
 ``requires-python``
 ===================
 
@@ -97,6 +100,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   (i.e. the minimum viable Python version for the lock file).
 
 
+.. _pylock-extras:
 ``extras``
 ==========
 
@@ -115,6 +119,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   lock file is, in effect, multi-use even if it only looks to be single-use.
 
 
+.. _pylock-dependency-groups:
 ``dependency-groups``
 =====================
 
@@ -134,6 +139,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   is, in effect, multi-use even if it only looks to be single-use.
 
 
+.. _pylock-default-groups:
 ``default-groups``
 ==================
 
@@ -142,13 +148,14 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 - **Inspiration**: Poetry_, PDM_
 - The name of synthetic dependency groups to represent what should be installed
   by default (e.g. what ``project.dependencies`` implicitly represents).
-- Meant to be used in situations where ``packages.marker`` necessitates such a
+- Meant to be used in situations where :ref:`pylock-packages.marker` necessitates such a
   group to exist.
-- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+- The groups listed by this key SHOULD NOT be listed in :ref:`pylock-dependency-groups` as
   the groups are not meant to be directly exposed to users by name but instead
   via an installer's UI.
 
 
+.. _pylock-created-by:
 ``created-by``
 ==============
 
@@ -156,12 +163,13 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 - **Required?**: yes
 - **Inspiration**: Tools with their name in their lock file name
 - Records the name of the tool used to create the lock file.
-- Tools MAY use the ``[tool]`` table to record enough details that it can be
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it can be
   inferred what inputs were used to create the lock file.
 - Tools SHOULD record the normalized name of the tool if it is available as a
   Python package to facilitate finding the tool.
 
 
+.. _pylock-packages:
 ``[[packages]]``
 ================
 
@@ -175,6 +183,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 .. Identification
 
+.. _pylock-packages-name:
 ``packages.name``
 -----------------
 
@@ -184,6 +193,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 - The name of the package :ref:`normalized `.
 
 
+.. _pylock-packages-version:
 ``packages.version``
 --------------------
 
@@ -202,6 +212,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 .. Requirements
 
+.. _pylock-packages-marker:
 ``packages.marker``
 -------------------
 
@@ -213,6 +224,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   which specify when the package should be installed.
 
 
+.. _pylock-packages-requires-python:
 ``packages.requires-python``
 ----------------------------
 
@@ -223,13 +235,14 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   for the package.
 
 
+.. _pylock-packages-dependencies:
 ``[[packages.dependencies]]``
 -----------------------------
 
 - **Type**: array of tables
 - **Required?**: no
 - **Inspiration**: PDM_, Poetry_, uv_
-- Records the other entries in ``[[packages]]`` which are direct dependencies of
+- Records the other entries in :ref:`pylock-packages` which are direct dependencies of
   this package.
 - Each entry is a table which contains the minimum information required to tell
   which other package entry it corresponds to where doing a key-by-key
@@ -243,6 +256,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 .. Source
 
+.. _pylock-packages-vcs:
 ``[packages.vcs]``
 -------------------
 
@@ -262,6 +276,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   :ref:`direct URL reference `.
 
 
+.. _pylock-packages-vcs-type:
 ``packages.vcs.type``
 ''''''''''''''''''''''
 
@@ -272,15 +287,17 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 - The type of version control system used.
 
 
+.. _pylock-packages-vcs-url:
 ``packages.vcs.url``
 '''''''''''''''''''''
 
 - **Type**: string
 - **Required?**: if ``path`` is not specified
 - **Inspiration**: :ref:`direct-url-data-structure-vcs`
-- The URL to the source tree.
+- The URL_ to the source tree.
 
 
+.. _pylock-packages-vcs-path:
 ``packages.vcs.path``
 ''''''''''''''''''''''
 
@@ -293,6 +310,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   for portability.
 
 
+.. _pylock-packages-vcs-requested-revision:
 ``packages.vcs.requested-revision``
 ''''''''''''''''''''''''''''''''''''
 
@@ -305,6 +323,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   the repository.
 
 
+.. _pylock-packages-vcs-commit-id:
 ``packages.vcs.commit-id``
 '''''''''''''''''''''''''''
 
@@ -312,11 +331,12 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 - **Required?**: yes
 - **Inspiration**: :ref:`direct-url-data-structure-vcs`
 - The exact commit/revision number that is to be installed.
-- If the VCS supports commit-hash based revision identifiers, such a commit-hash
-  MUST be used as the commit ID in order to reference an immutable version of
+- If the VCS supports commit-hash based revision identifiers, such a commit-hash,
+  it MUST be used as the commit ID in order to reference an immutable version of
   the source code.
 
 
+.. _pylock-packages-vcs-subdirectory:
 ``packages.vcs.subdirectory``
 ''''''''''''''''''''''''''''''
 
@@ -330,12 +350,13 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 - The path MUST be relative to the root of the source tree structure.
 
 
+.. _pylock-packages-directory:
 ``[packages.directory]``
 -------------------------
 
 - **Type**: table
-- **Required?**: no; mutually-exclusive with ``packages.vcs``,
-  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and :ref:`pylock-packages.wheels`
 - **Inspiration**: :ref:`direct-url-data-structure-local-directory`
 - Record the local directory details for the
   :ref:`source tree ` it
@@ -347,6 +368,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   :ref:`direct URL reference `.
 
 
+.. _pylock-packages-directory-path:
 ``packages.directory.path``
 ''''''''''''''''''''''''''''
 
@@ -359,6 +381,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   portability.
 
 
+.. _pylock-packages-directory-editable:
 ``packages.directory.editable``
 ''''''''''''''''''''''''''''''''
 
@@ -373,12 +396,14 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   production where it would be treated at read-only).
 
 
+.. _pylock-packages-directory-subdirectory:
 ``packages.directory.subdirectory``
 ''''''''''''''''''''''''''''''''''''
 
 See ``packages.vcs.subdirectory``.
 
 
+.. _pylock-packages-archive:
 ``[packages.archive]``
 -----------------------
 
@@ -395,18 +420,21 @@ See ``packages.vcs.subdirectory``.
   :ref:`direct URL reference `.
 
 
+.. _pylock-packages-archive-url:
 ``packages.archive.url``
 '''''''''''''''''''''''''
 
-See ``packages.vcs.url``.
+See :ref:`pylock-packages-vcs-url`.
 
 
+.. _pylock-packages-archive-path:
 ``packages.archive.path``
 ''''''''''''''''''''''''''
 
-See ``packages.vcs.path``.
+See :ref:`pylock-packages-vcs-path`.
 
 
+.. _pylock-packages-archive-size:
 ``packages.archive.size``
 ''''''''''''''''''''''''''
 
@@ -418,6 +446,7 @@ See ``packages.vcs.path``.
   size is available via the Content-Length_ header from a HEAD_ HTTP request).
 
 
+.. _pylock-packages-archive-upload-time:
 ``packages.archive.upload-time``
 ''''''''''''''''''''''''''''''''
 
@@ -428,6 +457,7 @@ See ``packages.vcs.path``.
 - The date and time MUST be recorded in UTC.
 
 
+.. _pylock-packages-archive-hashes:
 ``[packages.archive.hashes]``
 ''''''''''''''''''''''''''''''
 
@@ -443,12 +473,14 @@ See ``packages.vcs.path``.
   recommended.
 
 
+.. _pylock-packages-archive-subdirectory:
 ``packages.archive.subdirectory``
 ''''''''''''''''''''''''''''''''''
 
-See ``packages.vcs.subdirectory``.
+See :ref:`pylock-packages-vcs-subdirectory`.
 
 
+.. _pylock-packages-index:
 ``packages.index``
 ------------------
 
@@ -464,12 +496,13 @@ See ``packages.vcs.subdirectory``.
   file is no longer valid (e.g. returns a 404 HTTP error code).
 
 
+.. _pylock-packages-sdist:
 ``[packages.sdist]``
 --------------------
 
 - **Type**: table
-- **Required?**: no; mutually-exclusive with ``packages.vcs``,
-  ``packages.directory``, and ``packages.archive``
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
 - **Inspiration**: uv_
 - Details of a :ref:`source-distribution-format-sdist` for the
   package.
@@ -478,53 +511,60 @@ See ``packages.vcs.subdirectory``.
 - Tools SHOULD provide a way for users to opt in/out of using sdist files.
 
 
+.. _pylock-packages-sdist-name:
 ``packages.sdist.name``
 '''''''''''''''''''''''
 
 - **Type**: string
-- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+- **Required?**: no, not when the last component of :ref:`pylock-sdist-path`/ :ref:`pylock-sdist-url` would be
   the same value
 - **Inspiration**: PDM_, Poetry_, uv_
 - The file name of the :ref:`source-distribution-format-sdist` file.
 
 
+.. _pylock-packages-sdist-upload-time:
 ``packages.sdist.upload-time``
 ''''''''''''''''''''''''''''''
 
-See ``packages.archive.upload-time``.
+See :ref:`pylock-packages-archive-upload-time`.
 
 
+.. _pylock-packages-sdist-url:
 ``packages.sdist.url``
 ''''''''''''''''''''''
 
-See ``packages.archive.url``.
+See :ref:`pylock-packages-archive-url`.
 
 
+.. _pylock-packages-sdist-path:
 ``packages.sdist.path``
 '''''''''''''''''''''''
 
-See ``packages.archive.path``.
+See :ref:`pylock-packages-archive-path`.
 
 
+.. _pylock-packages-sdist-size:
 ``packages.sdist.size``
 '''''''''''''''''''''''
 
-See ``packages.archive.size``.
+See :ref:`pylock-packages-archive-size`.
 
 
+.. _pylock-packages-sdist-hashes:
 ``packages.sdist.hashes``
 '''''''''''''''''''''''''
 
-See ``packages.archive.hashes``.
+See :ref:`pylock-packages-archive-hashes`.
 
 
 
+.. _pylock-packages-wheels:
 ``[[packages.wheels]]``
 -----------------------
 
 - **Type**: array of tables
-- **Required?**: no; mutually-exclusive with ``packages.vcs``,
-  ``packages.directory``, and ``packages.archive``
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
 - **Inspiration**: PDM_, Poetry_, uv_
 - For recording the wheel files as specified by
   :ref:`  binary-distribution-format` for the package.
@@ -532,46 +572,53 @@ See ``packages.archive.hashes``.
   perspective.
 
 
+.. _pylock-packages-wheels-name:
 ``packages.wheels.name``
 ''''''''''''''''''''''''
 
 - **Type**: string
-- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+- **Required?**: no, not when the last component of :ref:`pylock-wheels-path`/ :ref:`pylock-wheels-url` would be
   the same value
 - **Inspiration**: PDM_, Poetry_, uv_
 - The file name of the :ref:`  binary-distribution-format` file.
 
 
+.. _pylock-packages-wheels-upload-time:
 ``packages.wheels.upload-time``
 '''''''''''''''''''''''''''''''
 
-See ``packages.archive.upload-time``.
+See :ref:`pylock-packages-archive-upload-time`.
 
 
+.. _pylock-packages-wheels-url:
 ``packages.wheels.url``
 '''''''''''''''''''''''
 
-See ``packages.archive.url``.
+See :ref:`pylock-packages-archive-url`.
 
 
+.. _pylock-packages-wheels-path:
 ``packages.wheels.path``
 ''''''''''''''''''''''''
 
-See ``packages.archive.path``.
+See :ref:`pylock-packages-archive-path`.
 
 
+.. _pylock-packages-wheels-size:
 ``packages.wheels.size``
 ''''''''''''''''''''''''
 
-See ``packages.archive.size``.
+See :ref:`pylock-packages-archive-size`.
 
 
+.. _pylock-packages-wheels-hashes:
 ``packages.wheels.hashes``
 ''''''''''''''''''''''''''
 
-See ``packages.archive.hashes``.
+See :ref:`pylock-packages-archive-hashes`.
 
 
+.. _pylock-packages-attestation-identities:
 ``[[packages.attestation-identities]]``
 ---------------------------------------
 
@@ -585,6 +632,7 @@ See ``packages.archive.hashes``.
   :ref:`  index-hosted-attestations`.
 
 
+.. _pylock-packages-attestation-identities-kind:
 ``packages.attestation-identities.kind``
 ''''''''''''''''''''''''''''''''''''''''
 
@@ -594,6 +642,7 @@ See ``packages.archive.hashes``.
 - The unique identity of the Trusted Publisher.
 
 
+.. _pylock-packages.tool:
 ``[packages.tool]``
 -------------------
 
@@ -602,18 +651,19 @@ See ``packages.archive.hashes``.
 - **Inspiration**: :ref:`  pyproject-tool-table`
 - Similar usage as that of the ``[tool]`` table from the
   :ref:`  pyproject-toml-spec`, but at the package version level instead
-  of at the lock file level (which is also available via ``[tool]``).
+  of at the lock file level (which is also available via :ref:`pylock-tool`).
 - Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
   installation).
 
 
+.. _pylock-tool:
 ``[tool]``
 ==========
 
 - **Type**: table
 - **Required?**: no
 - **Inspiration**: :ref:`  pyproject-tool-table`
-- See ``packages.tool``.
+- See :ref:`pylock-packages-tool`.
 
 
 -------
@@ -770,3 +820,4 @@ History
 .. _software bill of materials: https://www.cisa.gov/sbom
 .. _TOML: https://toml.io/
 .. _uv: https://github.com/astral-sh/uv
+.. _URL: https://url.spec.whatwg.org/

From 2f1dc98c3b8231513408681b4c1ef6d3d45ca687 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Tue, 15 Apr 2025 12:48:20 -0700
Subject: [PATCH 604/733] Update source/specifications/pylock-toml.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Filipe Laíns 🇵🇸 
---
 source/specifications/pylock-toml.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
index 24347a95c..3418976fc 100644
--- a/source/specifications/pylock-toml.rst
+++ b/source/specifications/pylock-toml.rst
@@ -821,3 +821,4 @@ History
 .. _TOML: https://toml.io/
 .. _uv: https://github.com/astral-sh/uv
 .. _URL: https://url.spec.whatwg.org/
+.. _URL: https://url.spec.whatwg.org/

From 5f4d218b9dc90c17d19b995467825df77d93956e Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Tue, 15 Apr 2025 12:50:17 -0700
Subject: [PATCH 605/733] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Filipe Laíns 🇵🇸 
---
 source/specifications/pylock-toml.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
index 3418976fc..7fe04898c 100644
--- a/source/specifications/pylock-toml.rst
+++ b/source/specifications/pylock-toml.rst
@@ -480,6 +480,7 @@ See :ref:`pylock-packages-vcs-path`.
 See :ref:`pylock-packages-vcs-subdirectory`.
 
 
+.. _pylock-packages-index:
 .. _pylock-packages-index:
 ``packages.index``
 ------------------
@@ -496,6 +497,7 @@ See :ref:`pylock-packages-vcs-subdirectory`.
   file is no longer valid (e.g. returns a 404 HTTP error code).
 
 
+.. _pylock-packages-sdist:
 .. _pylock-packages-sdist:
 ``[packages.sdist]``
 --------------------
@@ -511,6 +513,7 @@ See :ref:`pylock-packages-vcs-subdirectory`.
 - Tools SHOULD provide a way for users to opt in/out of using sdist files.
 
 
+.. _pylock-packages-sdist-name:
 .. _pylock-packages-sdist-name:
 ``packages.sdist.name``
 '''''''''''''''''''''''
@@ -522,6 +525,7 @@ See :ref:`pylock-packages-vcs-subdirectory`.
 - The file name of the :ref:`source-distribution-format-sdist` file.
 
 
+.. _pylock-packages-sdist-upload-time:
 .. _pylock-packages-sdist-upload-time:
 ``packages.sdist.upload-time``
 ''''''''''''''''''''''''''''''
@@ -529,6 +533,7 @@ See :ref:`pylock-packages-vcs-subdirectory`.
 See :ref:`pylock-packages-archive-upload-time`.
 
 
+.. _pylock-packages-sdist-url:
 .. _pylock-packages-sdist-url:
 ``packages.sdist.url``
 ''''''''''''''''''''''
@@ -536,6 +541,7 @@ See :ref:`pylock-packages-archive-upload-time`.
 See :ref:`pylock-packages-archive-url`.
 
 
+.. _pylock-packages-sdist-path:
 .. _pylock-packages-sdist-path:
 ``packages.sdist.path``
 '''''''''''''''''''''''
@@ -543,6 +549,7 @@ See :ref:`pylock-packages-archive-url`.
 See :ref:`pylock-packages-archive-path`.
 
 
+.. _pylock-packages-sdist-size:
 .. _pylock-packages-sdist-size:
 ``packages.sdist.size``
 '''''''''''''''''''''''
@@ -550,6 +557,7 @@ See :ref:`pylock-packages-archive-path`.
 See :ref:`pylock-packages-archive-size`.
 
 
+.. _pylock-packages-sdist-hashes:
 .. _pylock-packages-sdist-hashes:
 ``packages.sdist.hashes``
 '''''''''''''''''''''''''
@@ -558,6 +566,7 @@ See :ref:`pylock-packages-archive-hashes`.
 
 
 
+.. _pylock-packages-wheels:
 .. _pylock-packages-wheels:
 ``[[packages.wheels]]``
 -----------------------
@@ -572,6 +581,7 @@ See :ref:`pylock-packages-archive-hashes`.
   perspective.
 
 
+.. _pylock-packages-wheels-name:
 .. _pylock-packages-wheels-name:
 ``packages.wheels.name``
 ''''''''''''''''''''''''
@@ -583,6 +593,7 @@ See :ref:`pylock-packages-archive-hashes`.
 - The file name of the :ref:`  binary-distribution-format` file.
 
 
+.. _pylock-packages-wheels-upload-time:
 .. _pylock-packages-wheels-upload-time:
 ``packages.wheels.upload-time``
 '''''''''''''''''''''''''''''''
@@ -590,6 +601,7 @@ See :ref:`pylock-packages-archive-hashes`.
 See :ref:`pylock-packages-archive-upload-time`.
 
 
+.. _pylock-packages-wheels-url:
 .. _pylock-packages-wheels-url:
 ``packages.wheels.url``
 '''''''''''''''''''''''
@@ -597,6 +609,7 @@ See :ref:`pylock-packages-archive-upload-time`.
 See :ref:`pylock-packages-archive-url`.
 
 
+.. _pylock-packages-wheels-path:
 .. _pylock-packages-wheels-path:
 ``packages.wheels.path``
 ''''''''''''''''''''''''
@@ -604,6 +617,7 @@ See :ref:`pylock-packages-archive-url`.
 See :ref:`pylock-packages-archive-path`.
 
 
+.. _pylock-packages-wheels-size:
 .. _pylock-packages-wheels-size:
 ``packages.wheels.size``
 ''''''''''''''''''''''''
@@ -611,6 +625,7 @@ See :ref:`pylock-packages-archive-path`.
 See :ref:`pylock-packages-archive-size`.
 
 
+.. _pylock-packages-wheels-hashes:
 .. _pylock-packages-wheels-hashes:
 ``packages.wheels.hashes``
 ''''''''''''''''''''''''''
@@ -618,6 +633,7 @@ See :ref:`pylock-packages-archive-size`.
 See :ref:`pylock-packages-archive-hashes`.
 
 
+.. _pylock-packages-attestation-identities:
 .. _pylock-packages-attestation-identities:
 ``[[packages.attestation-identities]]``
 ---------------------------------------
@@ -632,6 +648,7 @@ See :ref:`pylock-packages-archive-hashes`.
   :ref:`  index-hosted-attestations`.
 
 
+.. _pylock-packages-attestation-identities-kind:
 .. _pylock-packages-attestation-identities-kind:
 ``packages.attestation-identities.kind``
 ''''''''''''''''''''''''''''''''''''''''
@@ -642,6 +659,7 @@ See :ref:`pylock-packages-archive-hashes`.
 - The unique identity of the Trusted Publisher.
 
 
+.. _pylock-packages.tool:
 .. _pylock-packages.tool:
 ``[packages.tool]``
 -------------------
@@ -656,6 +674,7 @@ See :ref:`pylock-packages-archive-hashes`.
   installation).
 
 
+.. _pylock-tool:
 .. _pylock-tool:
 ``[tool]``
 ==========

From 740354d7f996655fdeb003ab9325a9b012d0a20b Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Tue, 15 Apr 2025 13:36:30 -0700
Subject: [PATCH 606/733] Fix and add more references

---
 source/specifications/pylock-toml.rst | 249 +++++++++++++++-----------
 1 file changed, 149 insertions(+), 100 deletions(-)

diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
index 7fe04898c..66eb92a14 100644
--- a/source/specifications/pylock-toml.rst
+++ b/source/specifications/pylock-toml.rst
@@ -61,6 +61,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. File details
 
 .. _pylock-lock-version:
+
 ``lock-version``
 ================
 
@@ -76,6 +77,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 
 .. _pylock-environments:
+
 ``environments``
 ================
 
@@ -89,6 +91,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 
 .. _pylock-requires-python:
+
 ``requires-python``
 ===================
 
@@ -101,6 +104,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 
 .. _pylock-extras:
+
 ``extras``
 ==========
 
@@ -114,12 +118,15 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   file).
 - Tools supporting extras MUST also support dependency groups.
 - Tools should explicitly set this key to an empty array to signal that the
-  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
-  file had no ``[project.optional-dependencies]`` table), signalling that the
-  lock file is, in effect, multi-use even if it only looks to be single-use.
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml ` file had no
+  :ref:`[project.optional-dependencies] `
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
 
 
 .. _pylock-dependency-groups:
+
 ``dependency-groups``
 =====================
 
@@ -134,12 +141,14 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   file).
 - Tools supporting dependency groups MUST also support extras.
 - Tools SHOULD explicitly set this key to an empty array to signal that the
-  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
-  file had no ``[dependency-groups]`` table), signalling that the lock file
-  is, in effect, multi-use even if it only looks to be single-use.
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml ` file had no
+  :ref:`[dependency-groups] ` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
 
 
 .. _pylock-default-groups:
+
 ``default-groups``
 ==================
 
@@ -147,15 +156,18 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 - **Required?**: no; defaults to ``[]``
 - **Inspiration**: Poetry_, PDM_
 - The name of synthetic dependency groups to represent what should be installed
-  by default (e.g. what ``project.dependencies`` implicitly represents).
-- Meant to be used in situations where :ref:`pylock-packages.marker` necessitates such a
-  group to exist.
-- The groups listed by this key SHOULD NOT be listed in :ref:`pylock-dependency-groups` as
-  the groups are not meant to be directly exposed to users by name but instead
-  via an installer's UI.
+  by default (e.g. what
+  :ref:`[project.dependencies] ` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
 
 
 .. _pylock-created-by:
+
 ``created-by``
 ==============
 
@@ -163,13 +175,14 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 - **Required?**: yes
 - **Inspiration**: Tools with their name in their lock file name
 - Records the name of the tool used to create the lock file.
-- Tools MAY use the :ref:`pylock-tool` table to record enough details that it can be
-  inferred what inputs were used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
 - Tools SHOULD record the normalized name of the tool if it is available as a
   Python package to facilitate finding the tool.
 
 
 .. _pylock-packages:
+
 ``[[packages]]``
 ================
 
@@ -184,6 +197,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. Identification
 
 .. _pylock-packages-name:
+
 ``packages.name``
 -----------------
 
@@ -194,6 +208,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 
 .. _pylock-packages-version:
+
 ``packages.version``
 --------------------
 
@@ -206,13 +221,13 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   :ref:`wheels ` are specified).
 - The version MUST NOT be included when it cannot be guaranteed to be consistent
   with the code used (i.e. when a
-  :ref:`source tree ` is
-  used).
+  :ref:`source tree ` is used).
 
 
 .. Requirements
 
 .. _pylock-packages-marker:
+
 ``packages.marker``
 -------------------
 
@@ -225,6 +240,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 
 .. _pylock-packages-requires-python:
+
 ``packages.requires-python``
 ----------------------------
 
@@ -236,14 +252,15 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 
 .. _pylock-packages-dependencies:
+
 ``[[packages.dependencies]]``
 -----------------------------
 
 - **Type**: array of tables
 - **Required?**: no
 - **Inspiration**: PDM_, Poetry_, uv_
-- Records the other entries in :ref:`pylock-packages` which are direct dependencies of
-  this package.
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
 - Each entry is a table which contains the minimum information required to tell
   which other package entry it corresponds to where doing a key-by-key
   comparison would find the appropriate package with no ambiguity (e.g. if there
@@ -257,12 +274,14 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. Source
 
 .. _pylock-packages-vcs:
+
 ``[packages.vcs]``
 -------------------
 
 - **Type**: table
-- **Required?**: no; mutually-exclusive with ``packages.directory``,
-  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
 - **Inspiration**: :ref:`direct-url-data-structure`
 - Record the version control system details for the
   :ref:`source tree ` it
@@ -277,6 +296,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 
 .. _pylock-packages-vcs-type:
+
 ``packages.vcs.type``
 ''''''''''''''''''''''
 
@@ -288,21 +308,23 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 
 .. _pylock-packages-vcs-url:
+
 ``packages.vcs.url``
 '''''''''''''''''''''
 
 - **Type**: string
-- **Required?**: if ``path`` is not specified
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
 - **Inspiration**: :ref:`direct-url-data-structure-vcs`
 - The URL_ to the source tree.
 
 
 .. _pylock-packages-vcs-path:
+
 ``packages.vcs.path``
 ''''''''''''''''''''''
 
 - **Type**: string
-- **Required?**: if ``url`` is not specified
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
 - **Inspiration**: :ref:`direct-url-data-structure-vcs`
 - The path to the local directory of the source tree.
 - If a relative path is used it MUST be relative to the location of this file.
@@ -311,6 +333,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 
 .. _pylock-packages-vcs-requested-revision:
+
 ``packages.vcs.requested-revision``
 ''''''''''''''''''''''''''''''''''''
 
@@ -324,6 +347,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 
 .. _pylock-packages-vcs-commit-id:
+
 ``packages.vcs.commit-id``
 '''''''''''''''''''''''''''
 
@@ -331,12 +355,13 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 - **Required?**: yes
 - **Inspiration**: :ref:`direct-url-data-structure-vcs`
 - The exact commit/revision number that is to be installed.
-- If the VCS supports commit-hash based revision identifiers, such a commit-hash,
-  it MUST be used as the commit ID in order to reference an immutable version of
-  the source code.
+- If the VCS supports commit-hash based revision identifiers, such a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
 
 
 .. _pylock-packages-vcs-subdirectory:
+
 ``packages.vcs.subdirectory``
 ''''''''''''''''''''''''''''''
 
@@ -346,17 +371,19 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 - The subdirectory within the
   :ref:`source tree ` where
   the project root of the project is (e.g. the location of the
-  ``pyproject.toml`` file).
+  :ref:`pyproject.toml ` file).
 - The path MUST be relative to the root of the source tree structure.
 
 
 .. _pylock-packages-directory:
+
 ``[packages.directory]``
 -------------------------
 
 - **Type**: table
 - **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
-  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and :ref:`pylock-packages.wheels`
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
 - **Inspiration**: :ref:`direct-url-data-structure-local-directory`
 - Record the local directory details for the
   :ref:`source tree ` it
@@ -369,6 +396,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 
 .. _pylock-packages-directory-path:
+
 ``packages.directory.path``
 ''''''''''''''''''''''''''''
 
@@ -382,6 +410,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 
 .. _pylock-packages-directory-editable:
+
 ``packages.directory.editable``
 ''''''''''''''''''''''''''''''''
 
@@ -397,13 +426,15 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 
 
 .. _pylock-packages-directory-subdirectory:
+
 ``packages.directory.subdirectory``
 ''''''''''''''''''''''''''''''''''''
 
-See ``packages.vcs.subdirectory``.
+See :ref:`pylock-packages-vcs-subdirectory`.
 
 
 .. _pylock-packages-archive:
+
 ``[packages.archive]``
 -----------------------
 
@@ -421,6 +452,7 @@ See ``packages.vcs.subdirectory``.
 
 
 .. _pylock-packages-archive-url:
+
 ``packages.archive.url``
 '''''''''''''''''''''''''
 
@@ -428,6 +460,7 @@ See :ref:`pylock-packages-vcs-url`.
 
 
 .. _pylock-packages-archive-path:
+
 ``packages.archive.path``
 ''''''''''''''''''''''''''
 
@@ -435,6 +468,7 @@ See :ref:`pylock-packages-vcs-path`.
 
 
 .. _pylock-packages-archive-size:
+
 ``packages.archive.size``
 ''''''''''''''''''''''''''
 
@@ -447,6 +481,7 @@ See :ref:`pylock-packages-vcs-path`.
 
 
 .. _pylock-packages-archive-upload-time:
+
 ``packages.archive.upload-time``
 ''''''''''''''''''''''''''''''''
 
@@ -458,6 +493,7 @@ See :ref:`pylock-packages-vcs-path`.
 
 
 .. _pylock-packages-archive-hashes:
+
 ``[packages.archive.hashes]``
 ''''''''''''''''''''''''''''''
 
@@ -474,6 +510,7 @@ See :ref:`pylock-packages-vcs-path`.
 
 
 .. _pylock-packages-archive-subdirectory:
+
 ``packages.archive.subdirectory``
 ''''''''''''''''''''''''''''''''''
 
@@ -481,7 +518,7 @@ See :ref:`pylock-packages-vcs-subdirectory`.
 
 
 .. _pylock-packages-index:
-.. _pylock-packages-index:
+
 ``packages.index``
 ------------------
 
@@ -498,7 +535,7 @@ See :ref:`pylock-packages-vcs-subdirectory`.
 
 
 .. _pylock-packages-sdist:
-.. _pylock-packages-sdist:
+
 ``[packages.sdist]``
 --------------------
 
@@ -514,19 +551,20 @@ See :ref:`pylock-packages-vcs-subdirectory`.
 
 
 .. _pylock-packages-sdist-name:
-.. _pylock-packages-sdist-name:
+
 ``packages.sdist.name``
 '''''''''''''''''''''''
 
 - **Type**: string
-- **Required?**: no, not when the last component of :ref:`pylock-sdist-path`/ :ref:`pylock-sdist-url` would be
+- **Required?**: no, not when the last component of
+  :ref:`pylock-packages-sdist-path`/ :ref:`pylock-packages-sdist-url` would be
   the same value
 - **Inspiration**: PDM_, Poetry_, uv_
 - The file name of the :ref:`source-distribution-format-sdist` file.
 
 
 .. _pylock-packages-sdist-upload-time:
-.. _pylock-packages-sdist-upload-time:
+
 ``packages.sdist.upload-time``
 ''''''''''''''''''''''''''''''
 
@@ -534,7 +572,7 @@ See :ref:`pylock-packages-archive-upload-time`.
 
 
 .. _pylock-packages-sdist-url:
-.. _pylock-packages-sdist-url:
+
 ``packages.sdist.url``
 ''''''''''''''''''''''
 
@@ -542,7 +580,7 @@ See :ref:`pylock-packages-archive-url`.
 
 
 .. _pylock-packages-sdist-path:
-.. _pylock-packages-sdist-path:
+
 ``packages.sdist.path``
 '''''''''''''''''''''''
 
@@ -550,7 +588,7 @@ See :ref:`pylock-packages-archive-path`.
 
 
 .. _pylock-packages-sdist-size:
-.. _pylock-packages-sdist-size:
+
 ``packages.sdist.size``
 '''''''''''''''''''''''
 
@@ -558,7 +596,7 @@ See :ref:`pylock-packages-archive-size`.
 
 
 .. _pylock-packages-sdist-hashes:
-.. _pylock-packages-sdist-hashes:
+
 ``packages.sdist.hashes``
 '''''''''''''''''''''''''
 
@@ -567,7 +605,7 @@ See :ref:`pylock-packages-archive-hashes`.
 
 
 .. _pylock-packages-wheels:
-.. _pylock-packages-wheels:
+
 ``[[packages.wheels]]``
 -----------------------
 
@@ -582,19 +620,20 @@ See :ref:`pylock-packages-archive-hashes`.
 
 
 .. _pylock-packages-wheels-name:
-.. _pylock-packages-wheels-name:
+
 ``packages.wheels.name``
 ''''''''''''''''''''''''
 
 - **Type**: string
-- **Required?**: no, not when the last component of :ref:`pylock-wheels-path`/ :ref:`pylock-wheels-url` would be
+- **Required?**: no, not when the last component of
+  :ref:`pylock-packages-wheels-path`/ :ref:`pylock-packages-wheels-url` would be
   the same value
 - **Inspiration**: PDM_, Poetry_, uv_
-- The file name of the :ref:`  binary-distribution-format` file.
+- The file name of the :ref:`binary-distribution-format` file.
 
 
 .. _pylock-packages-wheels-upload-time:
-.. _pylock-packages-wheels-upload-time:
+
 ``packages.wheels.upload-time``
 '''''''''''''''''''''''''''''''
 
@@ -602,7 +641,7 @@ See :ref:`pylock-packages-archive-upload-time`.
 
 
 .. _pylock-packages-wheels-url:
-.. _pylock-packages-wheels-url:
+
 ``packages.wheels.url``
 '''''''''''''''''''''''
 
@@ -610,7 +649,7 @@ See :ref:`pylock-packages-archive-url`.
 
 
 .. _pylock-packages-wheels-path:
-.. _pylock-packages-wheels-path:
+
 ``packages.wheels.path``
 ''''''''''''''''''''''''
 
@@ -618,7 +657,7 @@ See :ref:`pylock-packages-archive-path`.
 
 
 .. _pylock-packages-wheels-size:
-.. _pylock-packages-wheels-size:
+
 ``packages.wheels.size``
 ''''''''''''''''''''''''
 
@@ -626,7 +665,7 @@ See :ref:`pylock-packages-archive-size`.
 
 
 .. _pylock-packages-wheels-hashes:
-.. _pylock-packages-wheels-hashes:
+
 ``packages.wheels.hashes``
 ''''''''''''''''''''''''''
 
@@ -634,7 +673,7 @@ See :ref:`pylock-packages-archive-hashes`.
 
 
 .. _pylock-packages-attestation-identities:
-.. _pylock-packages-attestation-identities:
+
 ``[[packages.attestation-identities]]``
 ---------------------------------------
 
@@ -649,7 +688,7 @@ See :ref:`pylock-packages-archive-hashes`.
 
 
 .. _pylock-packages-attestation-identities-kind:
-.. _pylock-packages-attestation-identities-kind:
+
 ``packages.attestation-identities.kind``
 ''''''''''''''''''''''''''''''''''''''''
 
@@ -659,15 +698,15 @@ See :ref:`pylock-packages-archive-hashes`.
 - The unique identity of the Trusted Publisher.
 
 
-.. _pylock-packages.tool:
-.. _pylock-packages.tool:
+.. _pylock-packages-tool:
+
 ``[packages.tool]``
 -------------------
 
 - **Type**: table
 - **Required?**: no
 - **Inspiration**: :ref:`  pyproject-tool-table`
-- Similar usage as that of the ``[tool]`` table from the
+- Similar usage as that of the :ref:`pylock-tool` table from the
   :ref:`  pyproject-toml-spec`, but at the package version level instead
   of at the lock file level (which is also available via :ref:`pylock-tool`).
 - Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
@@ -675,13 +714,13 @@ See :ref:`pylock-packages-archive-hashes`.
 
 
 .. _pylock-tool:
-.. _pylock-tool:
+
 ``[tool]``
 ==========
 
 - **Type**: table
 - **Required?**: no
-- **Inspiration**: :ref:`  pyproject-tool-table`
+- **Inspiration**: :ref:`pyproject-tool-table`
 - See :ref:`pylock-packages-tool`.
 
 
@@ -746,23 +785,23 @@ a suggestion):
    ``dependency_groups`` for marker evaluation, respectively.
 
    #. ``extras`` SHOULD be set to the empty set by default.
-   #. ``dependency_groups`` SHOULD be the set created from ``default-groups`` by
-      default.
-
-#. Check if the metadata version specified by ``lock-version`` is supported;
-   an error or warning MUST be raised as appropriate.
-#. If ``requires-python`` is specified, check that the environment being
-   installed for meets the requirement; an error MUST be raised if it is not
-   met.
-#. If ``environments`` is specified, check that at least one of the environment
-   marker expressions is satisfied; an error MUST be raised if no expression is
-   satisfied.
-#. For each package listed in ``[[packages]]``:
-
-   #. If ``marker`` is specified, check if it is satisfied; if it isn't,
-      skip to the next package.
-   #. If ``requires-python`` is specified, check if it is satisfied; an error
-      MUST be raised if it isn't.
+   #. ``dependency_groups`` SHOULD be the set created from
+      :ref:`pylock-default-groups` by default.
+
+#. Check if the metadata version specified by :ref:`pylock-lock-version` is
+   supported; an error or warning MUST be raised as appropriate.
+#. If :ref:`pylock-requires-python` is specified, check that the environment
+   being installed for meets the requirement; an error MUST be raised if it is
+   not met.
+#. If :ref:`pylock-environments` is specified, check that at least one of the
+   environment marker expressions is satisfied; an error MUST be raised if no
+   expression is satisfied.
+#. For each package listed in :ref:`pylock-packages`:
+
+   #. If :ref:`pylock-packages-marker` is specified, check if it is satisfied;
+      if it isn't, skip to the next package.
+   #. If :ref:`pylock-packages-requires-python` is specified, check if it is
+      satisfied; an error MUST be raised if it isn't.
    #. Check that no other conflicting instance of the package has been slated to
       be installed; an error about the ambiguity MUST be raised otherwise.
    #. Check that the source of the package is specified appropriately (i.e.
@@ -772,53 +811,63 @@ a suggestion):
 
 #. For each package to be installed:
 
-   - If ``vcs`` is set:
+   - If :ref:`pylock-packages-vcs` is set:
 
-     #. Clone the repository to the commit ID specified in ``commit-id``.
-     #. Build the package, respecting ``subdirectory``.
-     #. Install.
+     #. Clone the repository to the commit ID specified in
+        :ref:`pylock-packages-vcs-commit-id`.
+     #. :ref:`Build ` the package,
+        respecting :ref:`pylock-packages-vcs-subdirectory`.
+     #. :ref:`Install `.
 
-   - Else if ``directory`` is set:
+   - Else if :ref:`pylock-packages-directory` is set:
 
-     #. Build the package, respecting ``subdirectory``.
-     #. Install.
+     #. :ref:`Build ` the package,
+        respecting :ref:`pylock-packages-directory-subdirectory`.
+     #. :ref:`Install `.
 
-   - Else if ``archive`` is set:
+   - Else if :ref:`pylock-packages-archive` is set:
 
      #. Get the file.
-     #. Validate the file size and hash.
-     #. Build the package, respecting ``subdirectory``.
-     #. Install.
+     #. Validate using :ref:`pylock-packages-archive-size` and
+        :ref:`pylock-packages-archive-hashes`.
+     #. :ref:`Build ` the package,
+        respecting :ref:`pylock-packages-archive-subdirectory`.
+     #. :ref:`Install `.
 
-   - Else if there are entries for ``wheels``:
+   - Else if there are entries for :ref:`pylock-packages-wheels`:
 
-     #. Look for the appropriate wheel file based on ``name``; if one is not
-        found then move on to ``sdist`` or an error MUST be raised about a
+     #. Look for the appropriate wheel file based on
+        :ref:`pylock-packages-wheels-name`; if one is not found then move on to
+        :ref:`pylock-packages-sdist` or an error MUST be raised about a
         lack of source for the project.
      #. Get the file:
 
-        - If ``path`` is set, use it.
-        - If ``url`` is set, try to use it; optionally tools MAY use
-          ``packages.index`` or some tool-specific mechanism to download the
-          selected wheel file (tools MUST NOT try to change what wheel file to
-          download based on what's available; what file to install should be
-          determined in an offline fashion for reproducibility).
+        - If :ref:`pylock-packages-wheels-path` is set, use it.
+        - Else if :ref:`pylock-packages-wheels-url` is set, try to use it;
+          optionally tools MAY use :ref:`pylock-packages-index` or some
+          tool-specific mechanism to download the selected wheel file (tools
+          MUST NOT try to change what wheel file to download based on what's
+          available; what file to install should be determined in an offline
+          fashion for reproducibility).
 
-     #. Validate the file size and hash.
-     #. Install.
+     #. Validate using :ref:`pylock-packages-wheels-size` and
+        :ref:`pylock-packages-wheels-hashes`.
+     #. :ref:`Install `.
 
-   - Else if no ``wheel`` file is found or ``sdist`` is solely set:
+   - Else if no :ref:`pylock-packages-wheels` file is found or
+     :ref:`pylock-packages-sdist` is solely set:
 
      #. Get the file.
 
-        - If ``path`` is set, use it.
-        - If ``url`` is set, try to use it; tools MAY use
-          ``packages.index`` or some tool-specific mechanism to download the
-          file.
+        - If :ref:`pylock-packages-sdist-path` is set, use it.
+        - Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools
+          MAY use :ref:`pylock-packages-index` or some tool-specific mechanism
+          to download the file.
 
-     #. Validate the file size and hash.
-     #. Build the package.
-     #. Install.
+     #. Validate using :ref:`pylock-packages-sdist-size` and
+        :ref:`pylock-packages-sdist-hashes`.
+     #. :ref:`Build ` the package.
+     #. :ref:`Install `.
 
 
 -------

From 95f181f26423a24ae9cf1810dfd96160f84d0d09 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Wed, 16 Apr 2025 13:36:03 -0700
Subject: [PATCH 607/733] Move `pylock.toml` example to an external file Along
 the way, ignore a troublesome URL that's slowing down link checking
 significantly.

---
 source/conf.py                                |  1 +
 source/specifications/pylock-toml.rst         | 48 +--------------
 .../pylock-toml/pylock.example.toml           | 60 +++++++++++++++++++
 3 files changed, 64 insertions(+), 45 deletions(-)
 create mode 100644 source/specifications/pylock-toml/pylock.example.toml

diff --git a/source/conf.py b/source/conf.py
index b3ebd0502..321d07f2b 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -149,6 +149,7 @@
     "https://stackoverflow.com/*",
     "https://pyscaffold.org/*",
     "https://anaconda.org",
+    "https://www.cisa.gov/sbom",
 ]
 linkcheck_retries = 5
 # Ignore anchors for common targets when we know they likely won't be found
diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
index 66eb92a14..3208874ed 100644
--- a/source/specifications/pylock-toml.rst
+++ b/source/specifications/pylock-toml.rst
@@ -728,49 +728,7 @@ See :ref:`pylock-packages-archive-hashes`.
 Example
 -------
 
-.. code-block:: TOML
-
-  lock-version = '1.0'
-  environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
-  requires-python = '==3.12'
-  created-by = 'mousebender'
-
-  [[packages]]
-  name = 'attrs'
-  version = '25.1.0'
-  requires-python = '>=3.8'
-  wheels = [
-    {name = 'attrs-25.1.0-py3-none-any.whl', upload-time = 2025-01-25T11:30:10.164985+00:00, url = 'https://files.pythonhosted.org/packages/fc/30/d4986a882011f9df997a55e6becd864812ccfcd821d64aac8570ee39f719/attrs-25.1.0-py3-none-any.whl', size = 63152, hashes = {sha256 = 'c75a69e28a550a7e93789579c22aa26b0f5b83b75dc4e08fe092980051e1090a'}},
-  ]
-  [[packages.attestation-identities]]
-  environment = 'release-pypi'
-  kind = 'GitHub'
-  repository = 'python-attrs/attrs'
-  workflow = 'pypi-package.yml'
-
-  [[packages]]
-  name = 'cattrs'
-  version = '24.1.2'
-  requires-python = '>=3.8'
-  dependencies = [
-      {name = 'attrs'},
-  ]
-  wheels = [
-    {name = 'cattrs-24.1.2-py3-none-any.whl', upload-time = 2024-09-22T14:58:34.812643+00:00, url = 'https://files.pythonhosted.org/packages/c8/d5/867e75361fc45f6de75fe277dd085627a9db5ebb511a87f27dc1396b5351/cattrs-24.1.2-py3-none-any.whl', size = 66446, hashes = {sha256 = '67c7495b760168d931a10233f979b28dc04daf853b30752246f4f8471c6d68d0'}},
-  ]
-
-  [[packages]]
-  name = 'numpy'
-  version = '2.2.3'
-  requires-python = '>=3.10'
-  wheels = [
-    {name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl', upload-time = 2025-02-13T16:51:21.821880+00:00, url = 'https://files.pythonhosted.org/packages/42/6e/55580a538116d16ae7c9aa17d4edd56e83f42126cb1dfe7a684da7925d2c/numpy-2.2.3-cp312-cp312-win_amd64.whl', size = 12626357, hashes = {sha256 = '83807d445817326b4bcdaaaf8e8e9f1753da04341eceec705c001ff342002e5d'}},
-    {name = 'numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', upload-time = 2025-02-13T16:50:00.079662+00:00, url = 'https://files.pythonhosted.org/packages/39/04/78d2e7402fb479d893953fb78fa7045f7deb635ec095b6b4f0260223091a/numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', size = 16116679, hashes = {sha256 = '3b787adbf04b0db1967798dba8da1af07e387908ed1553a0d6e74c084d1ceafe'}},
-  ]
-
-  [tool.mousebender]
-  command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
-  run-on = 2025-03-06T12:28:57.760769
+.. literalinclude:: pylock-toml/pylock.example.toml
 
 
 ------------
@@ -882,11 +840,11 @@ History
 .. _HEAD: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
 .. _PDM: https://pypi.org/project/pdm/
 .. _pip-tools: https://pypi.org/project/pip-tools/
-.. _Poetry: https://python-poetry.org/
+.. _Poetry: https://pypi.org/project/poetry/
 .. _requirements file:
 .. _requirements files: https://pip.pypa.io/en/stable/reference/requirements-file-format/
 .. _software bill of materials: https://www.cisa.gov/sbom
 .. _TOML: https://toml.io/
-.. _uv: https://github.com/astral-sh/uv
+.. _uv: https://pypi.org/project/uv/
 .. _URL: https://url.spec.whatwg.org/
 .. _URL: https://url.spec.whatwg.org/
diff --git a/source/specifications/pylock-toml/pylock.example.toml b/source/specifications/pylock-toml/pylock.example.toml
new file mode 100644
index 000000000..60982f1d3
--- /dev/null
+++ b/source/specifications/pylock-toml/pylock.example.toml
@@ -0,0 +1,60 @@
+lock-version = '1.0'
+environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+requires-python = '==3.12'
+created-by = 'mousebender'
+
+[[packages]]
+name = 'attrs'
+version = '25.1.0'
+requires-python = '>=3.8'
+
+    [[packages.wheels]]
+    name = 'attrs-25.1.0-py3-none-any.whl'
+    upload-time = 2025-01-25T11:30:10.164985+00:00
+    url = 'https://files.pythonhosted.org/packages/fc/30/d4986a882011f9df997a55e6becd864812ccfcd821d64aac8570ee39f719/attrs-25.1.0-py3-none-any.whl'
+    size = 63152
+    hashes = {sha256 = 'c75a69e28a550a7e93789579c22aa26b0f5b83b75dc4e08fe092980051e1090a'}
+
+    [[packages.attestation-identities]]
+    environment = 'release-pypi'
+    kind = 'GitHub'
+    repository = 'python-attrs/attrs'
+    workflow = 'pypi-package.yml'
+
+[[packages]]
+name = 'cattrs'
+version = '24.1.2'
+requires-python = '>=3.8'
+dependencies = [
+    {name = 'attrs'},
+]
+
+    [[packages.wheels]]
+    name = 'cattrs-24.1.2-py3-none-any.whl'
+    upload-time = 2024-09-22T14:58:34.812643+00:00
+    url = 'https://files.pythonhosted.org/packages/c8/d5/867e75361fc45f6de75fe277dd085627a9db5ebb511a87f27dc1396b5351/cattrs-24.1.2-py3-none-any.whl'
+    size = 66446
+    hashes = {sha256 = '67c7495b760168d931a10233f979b28dc04daf853b30752246f4f8471c6d68d0'}
+
+[[packages]]
+name = 'numpy'
+version = '2.2.3'
+requires-python = '>=3.10'
+
+    [[packages.wheels]]
+    name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl'
+    upload-time = 2025-02-13T16:51:21.821880+00:00
+    url = 'https://files.pythonhosted.org/packages/42/6e/55580a538116d16ae7c9aa17d4edd56e83f42126cb1dfe7a684da7925d2c/numpy-2.2.3-cp312-cp312-win_amd64.whl'
+    size = 12626357
+    hashes = {sha256 = '83807d445817326b4bcdaaaf8e8e9f1753da04341eceec705c001ff342002e5d'}
+
+    [[packages.wheels]]
+    name = 'numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl'
+    upload-time = 2025-02-13T16:50:00.079662+00:00
+    url = 'https://files.pythonhosted.org/packages/39/04/78d2e7402fb479d893953fb78fa7045f7deb635ec095b6b4f0260223091a/numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl'
+    size = 16116679
+    hashes = {sha256 = '3b787adbf04b0db1967798dba8da1af07e387908ed1553a0d6e74c084d1ceafe'}
+
+[tool.mousebender]
+command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
+run-on = 2025-03-06T12:28:57.760769

From b63bf5a83f847e19ff376aa3db0fa4249ec83a5c Mon Sep 17 00:00:00 2001
From: Ee Durbin 
Date: Thu, 17 Apr 2025 13:45:16 -0400
Subject: [PATCH 608/733] remove plausible.io

we're going to be migrating to self-hosted plausbile entirely now.

drop plausible.io script, and enable outbound links
---
 source/conf.py | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index b3ebd0502..bda71103a 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -73,11 +73,7 @@
 
 _metrics_js_files = [
     (
-        "https://plausible.io/js/script.js",
-        {"data-domain": "packaging.python.org", "defer": "defer"},
-    ),
-    (
-        "https://analytics.python.org/js/script.js",
+        "https://analytics.python.org/js/script.outbound-links.js",
         {"data-domain": "packaging.python.org", "defer": "defer"},
     ),
 ]

From 5fcf8fad9aee32c083198e7fbb0730f641dce790 Mon Sep 17 00:00:00 2001
From: shenxianpeng 
Date: Mon, 21 Apr 2025 16:03:30 +0300
Subject: [PATCH 609/733] docs: fix installing-packages.rst

---
 source/tutorials/installing-packages.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
index 817148d06..afe51c941 100644
--- a/source/tutorials/installing-packages.rst
+++ b/source/tutorials/installing-packages.rst
@@ -228,8 +228,8 @@ Currently, there are two common tools for creating Python virtual environments:
   (Python versions prior to 3.12 also installed :ref:`setuptools`).
 * :ref:`virtualenv` needs to be installed separately, but supports Python 2.7+
   and Python 3.3+, and :ref:`pip`, :ref:`setuptools` and :ref:`wheel` are
-  always installed into created virtual environments by default (regardless of
-  Python version).
+  installed into created virtual environments by default. Note that ``setuptools`` is no longer 
+  included by default starting with Python 3.12 (and ``virtualenv`` follows this behavior).
 
 The basic usage is like so:
 

From 77d04bf0880fb6fad515ebbb9d9200fba29bac22 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 21 Apr 2025 13:05:04 +0000
Subject: [PATCH 610/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/tutorials/installing-packages.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
index afe51c941..3a9aa23bb 100644
--- a/source/tutorials/installing-packages.rst
+++ b/source/tutorials/installing-packages.rst
@@ -228,7 +228,7 @@ Currently, there are two common tools for creating Python virtual environments:
   (Python versions prior to 3.12 also installed :ref:`setuptools`).
 * :ref:`virtualenv` needs to be installed separately, but supports Python 2.7+
   and Python 3.3+, and :ref:`pip`, :ref:`setuptools` and :ref:`wheel` are
-  installed into created virtual environments by default. Note that ``setuptools`` is no longer 
+  installed into created virtual environments by default. Note that ``setuptools`` is no longer
   included by default starting with Python 3.12 (and ``virtualenv`` follows this behavior).
 
 The basic usage is like so:

From 4bb1a536de94bbe89b4eb86bc424e8595f6115d7 Mon Sep 17 00:00:00 2001
From: Seth Michael Larson 
Date: Thu, 24 Apr 2025 07:51:52 -0500
Subject: [PATCH 611/733] Add PEP 770 to specifications

---
 .../binary-distribution-format.rst            | 20 +++++++++++++++++++
 .../recording-installed-packages.rst          | 12 ++++++++++-
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index 4d94e1052..38d80163e 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -253,6 +253,20 @@ The .dist-info directory
    installation will fail if any file in the archive is not both
    mentioned and correctly hashed in RECORD.
 
+Subdirectories in :file:`.dist-info/`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Subdirectories under `.dist-info` are reserved for future use.
+The following subdirectory names under `.dist-info` are reserved for specific usage:
+
+================= ==============
+Subdirectory name PEP / Standard
+================= ==============
+``licenses``      :pep:`639`
+``license_files`` :pep:`639`
+``LICENSES``      `REUSE licensing framework `__
+``sboms``         :pep:`770`
+================= ==============
 
 The :file:`.dist-info/licenses/` directory
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -263,6 +277,12 @@ fields is specified, the :file:`.dist-info/` directory MUST contain a
 ``License-File`` fields in the :file:`METADATA` file at their respective paths
 relative to the :file:`licenses/` directory.
 
+The :file:`.dist-info/sboms/` directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+All files contained within the :file:`.dist-info/sboms` directory MUST
+be Software Bill-of-Materials (SBOM) files that describe software contained
+within the distribution archive.
 
 The .data directory
 ^^^^^^^^^^^^^^^^^^^
diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst
index 9e01ef6f1..c750fd03e 100644
--- a/source/specifications/recording-installed-packages.rst
+++ b/source/specifications/recording-installed-packages.rst
@@ -66,10 +66,11 @@ The ``METADATA`` file is mandatory.
 All other files may be omitted at the installing tool's discretion.
 Additional installer-specific files may be present.
 
-This :file:`.dist-info/` directory may contain the following directory, described in
+This :file:`.dist-info/` directory may contain the following directories, described in
 detail below:
 
 * :file:`licenses/`: contains license files.
+* :file:`sboms/`: contains Software Bill-of-Materials files (SBOMs).
 
 .. note::
 
@@ -235,6 +236,15 @@ the :file:`METADATA` file at their respective paths relative to the
 Any files in this directory MUST be copied from wheels by the install tools.
 
 
+The :file:`sboms/` subdirectory
+==================================
+
+All files contained within the :file:`.dist-info/sboms` directory MUST
+be Software Bill-of-Materials (SBOM) files that describe software contained
+within the installed package.
+Any files in this directory MUST be copied from wheels by the install tools.
+
+
 Intentionally preventing changes to installed packages
 ======================================================
 

From cd5925c5e55de12e649f533103191db9065930ff Mon Sep 17 00:00:00 2001
From: Seth Michael Larson 
Date: Thu, 24 Apr 2025 09:06:35 -0500
Subject: [PATCH 612/733] Fix reference issue

---
 source/specifications/binary-distribution-format.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index 38d80163e..f9bd4b1d5 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -256,8 +256,8 @@ The .dist-info directory
 Subdirectories in :file:`.dist-info/`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Subdirectories under `.dist-info` are reserved for future use.
-The following subdirectory names under `.dist-info` are reserved for specific usage:
+Subdirectories under :file:`.dist-info` are reserved for future use.
+The following subdirectory names under :file:`.dist-info` are reserved for specific usage:
 
 ================= ==============
 Subdirectory name PEP / Standard

From cff79d775af203ed023102fd365e31357e5ddf22 Mon Sep 17 00:00:00 2001
From: Seth Michael Larson 
Date: Sat, 26 Apr 2025 11:32:43 -0500
Subject: [PATCH 613/733] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/specifications/binary-distribution-format.rst   | 6 +++---
 source/specifications/recording-installed-packages.rst | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
index f9bd4b1d5..8bb41ab40 100644
--- a/source/specifications/binary-distribution-format.rst
+++ b/source/specifications/binary-distribution-format.rst
@@ -256,8 +256,8 @@ The .dist-info directory
 Subdirectories in :file:`.dist-info/`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Subdirectories under :file:`.dist-info` are reserved for future use.
-The following subdirectory names under :file:`.dist-info` are reserved for specific usage:
+Subdirectories under :file:`.dist-info/` are reserved for future use.
+The following subdirectory names under :file:`.dist-info/` are reserved for specific usage:
 
 ================= ==============
 Subdirectory name PEP / Standard
@@ -280,7 +280,7 @@ relative to the :file:`licenses/` directory.
 The :file:`.dist-info/sboms/` directory
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-All files contained within the :file:`.dist-info/sboms` directory MUST
+All files contained within the :file:`.dist-info/sboms/` directory MUST
 be Software Bill-of-Materials (SBOM) files that describe software contained
 within the distribution archive.
 
diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst
index c750fd03e..a689fa7fd 100644
--- a/source/specifications/recording-installed-packages.rst
+++ b/source/specifications/recording-installed-packages.rst
@@ -239,7 +239,7 @@ Any files in this directory MUST be copied from wheels by the install tools.
 The :file:`sboms/` subdirectory
 ==================================
 
-All files contained within the :file:`.dist-info/sboms` directory MUST
+All files contained within the :file:`.dist-info/sboms/` directory MUST
 be Software Bill-of-Materials (SBOM) files that describe software contained
 within the installed package.
 Any files in this directory MUST be copied from wheels by the install tools.

From b56b6c7c81fa36f9382f4ecc1b5cdfc2f05a28e3 Mon Sep 17 00:00:00 2001
From: Ned Batchelder 
Date: Thu, 1 May 2025 13:25:53 +0000
Subject: [PATCH 614/733] minor copy-editing fixes

---
 source/contribute.rst                                     | 2 +-
 source/discussions/deploying-python-applications.rst      | 2 +-
 source/discussions/pip-vs-easy-install.rst                | 2 +-
 source/discussions/versioning.rst                         | 6 +++---
 source/glossary.rst                                       | 2 +-
 source/guides/creating-command-line-tools.rst             | 8 ++++----
 .../installing-using-pip-and-virtual-environments.rst     | 2 +-
 source/index.rst                                          | 2 +-
 source/specifications/source-distribution-format.rst      | 4 ++--
 source/specifications/version-specifiers.rst              | 2 +-
 10 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/source/contribute.rst b/source/contribute.rst
index 95d127837..cf5314b8d 100644
--- a/source/contribute.rst
+++ b/source/contribute.rst
@@ -11,7 +11,7 @@ including:
 * Reviewing new contributions
 * Revising existing content
 * Writing new content
-* Translate the guide
+* Translating the guide
 
 Most of the work on the |PyPUG| takes place on the
 `project's GitHub repository`__. To get started, check out the list of
diff --git a/source/discussions/deploying-python-applications.rst b/source/discussions/deploying-python-applications.rst
index 19ecd398e..e10f36f9c 100644
--- a/source/discussions/deploying-python-applications.rst
+++ b/source/discussions/deploying-python-applications.rst
@@ -23,7 +23,7 @@ Supporting multiple hardware platforms
   For Python-only distributions, it *should* be straightforward to deploy on all
   platforms where Python can run.
 
-  For distributions with binary extensions, deployment is major headache.  Not only
+  For distributions with binary extensions, deployment is a major headache.  Not only
   must the extensions be built on all the combinations of operating system and
   hardware platform, but they must also be tested, preferably on continuous
   integration platforms.  The issues are similar to the "multiple Python
diff --git a/source/discussions/pip-vs-easy-install.rst b/source/discussions/pip-vs-easy-install.rst
index 4fa590cf3..2bb75d3be 100644
--- a/source/discussions/pip-vs-easy-install.rst
+++ b/source/discussions/pip-vs-easy-install.rst
@@ -11,7 +11,7 @@ It was notable at the time for installing :term:`packages 
 :term:`PyPI ` using requirement specifiers, and
 automatically installing dependencies.
 
-:ref:`pip` came later in 2008, as alternative to :ref:`easy_install `, although still
+:ref:`pip` came later in 2008, as an alternative to :ref:`easy_install `, although still
 largely built on top of :ref:`setuptools` components.  It was notable at the
 time for *not* installing packages as :term:`Eggs ` or from :term:`Eggs ` (but
 rather simply as 'flat' packages from :term:`sdists `_
@@ -148,7 +148,7 @@ user, as serial version numbers convey little or no information regarding API
 backwards compatibility.
 
 Combinations of the above schemes are possible. For example, a project may
-combine date based versioning with serial versioning to create a *year.serial*
+combine date-based versioning with serial versioning to create a *year.serial*
 numbering scheme that readily conveys the approximate age of a release, but
 doesn't otherwise commit to a particular release cadence within the year.
 
diff --git a/source/glossary.rst b/source/glossary.rst
index 6a592125f..73a192daa 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -291,7 +291,7 @@ Glossary
         `_, and discuss issues on the
         `distutils-sig mailing list
         `_
-	and `the Python Discourse forum `__.
+	and `the Python Discourse forum `_.
 
 
     Python Package Index (PyPI)
diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst
index 49ce0c9ed..8266fffdb 100644
--- a/source/guides/creating-command-line-tools.rst
+++ b/source/guides/creating-command-line-tools.rst
@@ -5,7 +5,7 @@ Creating and packaging command-line tools
 =========================================
 
 This guide will walk you through creating and packaging a standalone command-line application
-that can be installed with :ref:`pipx`, a tool creating and managing :term:`Python Virtual Environments `
+that can be installed with :ref:`pipx`, a tool for creating and managing :term:`Python Virtual Environments `
 and exposing the executable scripts of packages (and available manual pages) for use on the command-line.
 
 Creating the package
@@ -98,7 +98,7 @@ Now, add an empty :file:`__init__.py` file, to define the project as a regular :
 
 The file :file:`__main__.py` marks the main entry point for the application when running it via :mod:`runpy`
 (i.e. ``python -m greetings``, which works immediately with flat layout, but requires installation of the package with src layout),
-so initizalize the command-line interface here:
+so initialize the command-line interface here:
 
 .. code-block:: python
 
@@ -162,7 +162,7 @@ To just run the program without installing it permanently, use ``pipx run``, whi
 
 	$ pipx run --spec . greet --knight
 
-This syntax is a bit unpractical, however; as the name of the entry point we defined above does not match the package name,
+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).
 
 There is, however, a more practical solution to this problem, in the form of an entry point specific to ``pipx run``.
@@ -184,7 +184,7 @@ default one and run it, which makes this command possible:
 Conclusion
 ==========
 
-You know by now how to package a command-line application written in Python. A further step could be to distribute you package,
+You know by now how to package a command-line application written in Python. A further step could be to distribute your package,
 meaning uploading it to a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions at :ref:`Packaging your project`. And once you're done, don't forget to :ref:`do some research ` on how your package is received!
 
 .. _click: https://click.palletsprojects.com/
diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
index 64fdf9382..22d1840cc 100644
--- a/source/guides/installing-using-pip-and-virtual-environments.rst
+++ b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -200,7 +200,7 @@ When your virtual environment is activated, you can install packages. Use the
 Install a package
 ~~~~~~~~~~~~~~~~~
 
-For example,let's install the
+For example, let's install the
 `Requests`_ library from the :term:`Python Package Index (PyPI)`:
 
 .. tab:: Unix/macOS
diff --git a/source/index.rst b/source/index.rst
index 32f85b206..aa522c8c5 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -79,7 +79,7 @@ topics.
 Explanations and Discussions
 ============================
 
-The :doc:`discussions/index` section for in-depth explanations and discussion
+The :doc:`discussions/index` section provides in-depth explanations and discussion
 about topics, such as:
 
 * :doc:`discussions/deploying-python-applications`
diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst
index 7006511b9..9ac93be7b 100644
--- a/source/specifications/source-distribution-format.rst
+++ b/source/specifications/source-distribution-format.rst
@@ -5,7 +5,7 @@
 Source distribution format
 ==========================
 
-The current standard format of source distribution format is identified by the
+The current standard source distribution format is identified by the
 presence of a :file:`pyproject.toml` file in the distribution archive.  The layout
 of such a distribution was originally specified in :pep:`517` and is formally
 documented here.
@@ -27,7 +27,7 @@ Source trees
 
 A *source tree* is a collection of files and directories -- like a version
 control system checkout -- which contains a :file:`pyproject.toml` file that
-can be use to build a source distribution from the contained files and
+can be used to build a source distribution from the contained files and
 directories. :pep:`517` and :pep:`518` specify what is required to meet the
 definition of what :file:`pyproject.toml` must contain for something to be
 deemed a source tree.
diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index d18596ee0..1f89ce115 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -226,7 +226,7 @@ part of the ``3.3`` release series.
    form to ``X.Y.0`` when comparing it to any release segment that includes
    three components.
 
-Date based release segments are also permitted. An example of a date based
+Date-based release segments are also permitted. An example of a date-based
 release scheme using the year and month of the release::
 
     2012.4

From be0e85f74e6f8892c74c5c67f0e7dde872dfc1ee Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Fri, 2 May 2025 15:30:25 -0700
Subject: [PATCH 615/733] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/specifications/pylock-toml.rst | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
index 3208874ed..6f39af663 100644
--- a/source/specifications/pylock-toml.rst
+++ b/source/specifications/pylock-toml.rst
@@ -31,18 +31,18 @@ The expectation is that services that automatically install from lock files will
 search for:
 
 1. The lock file with the service's name and doing the default install
-2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
-3. The default install of ``pylock.toml``
+2. A multi-use :file:`pylock.toml` with a dependency group with the name of the service
+3. The default install of :file:`pylock.toml`
 
 E.g. a cloud host service named "spam" would first look for
-``pylock.spam.toml`` to install from, and if that file didn't exist then install
-from ``pylock.toml`` and look for a dependency group named "spam" to use if
+:file:`pylock.spam.toml` to install from, and if that file didn't exist then install
+from :file:`pylock.toml` and look for a dependency group named "spam" to use if
 present.
 
 The lock file(s) SHOULD be located in the directory as appropriate for the scope
-of the lock file. Locking against a single ``pyproject.toml``, for instance,
-would place the ``pylock.toml`` in the same directory. If the lock file covered
-multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+of the lock file. Locking against a single :file:`pyproject.toml`, for instance,
+would place the :file:`pylock.toml` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the :file:`pylock.toml`
 file would be in the directory that held all the projects being locked.
 
 
@@ -54,7 +54,7 @@ The format of the file is TOML_.
 
 Tools SHOULD write their lock files in a consistent way to minimize noise in
 diff output. Keys in tables -- including the top-level table -- SHOULD be
-recorded in a consistent order (if inspiration is desired, this PEP has tried to
+recorded in a consistent order (if inspiration is desired, this specification has tried to
 write down keys in a logical order). As well, tools SHOULD sort arrays in
 consistent order. Usage of inline tables SHOULD also be kept consistent.
 

From 7c3629a5b0e4e2de9b6951a0924d8db7a18aa08d Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Fri, 2 May 2025 15:56:38 -0700
Subject: [PATCH 616/733] Make section underlines not go over

---
 source/specifications/pylock-toml.rst | 32 +++++++++++++--------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
index 6f39af663..fdd3ed5a0 100644
--- a/source/specifications/pylock-toml.rst
+++ b/source/specifications/pylock-toml.rst
@@ -276,7 +276,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. _pylock-packages-vcs:
 
 ``[packages.vcs]``
--------------------
+------------------
 
 - **Type**: table
 - **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
@@ -298,7 +298,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. _pylock-packages-vcs-type:
 
 ``packages.vcs.type``
-''''''''''''''''''''''
+'''''''''''''''''''''
 
 - **Type**: string; supported values specified in
   :ref:`direct-url-data-structure-registered-vcs`
@@ -310,7 +310,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. _pylock-packages-vcs-url:
 
 ``packages.vcs.url``
-'''''''''''''''''''''
+''''''''''''''''''''
 
 - **Type**: string
 - **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
@@ -321,7 +321,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. _pylock-packages-vcs-path:
 
 ``packages.vcs.path``
-''''''''''''''''''''''
+'''''''''''''''''''''
 
 - **Type**: string
 - **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
@@ -335,7 +335,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. _pylock-packages-vcs-requested-revision:
 
 ``packages.vcs.requested-revision``
-''''''''''''''''''''''''''''''''''''
+'''''''''''''''''''''''''''''''''''
 
 - **Type**: string
 - **Required?**: no
@@ -349,7 +349,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. _pylock-packages-vcs-commit-id:
 
 ``packages.vcs.commit-id``
-'''''''''''''''''''''''''''
+''''''''''''''''''''''''''
 
 - **Type**: string
 - **Required?**: yes
@@ -363,7 +363,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. _pylock-packages-vcs-subdirectory:
 
 ``packages.vcs.subdirectory``
-''''''''''''''''''''''''''''''
+'''''''''''''''''''''''''''''
 
 - **Type**: string
 - **Required?**: no
@@ -378,7 +378,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. _pylock-packages-directory:
 
 ``[packages.directory]``
--------------------------
+------------------------
 
 - **Type**: table
 - **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
@@ -398,7 +398,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. _pylock-packages-directory-path:
 
 ``packages.directory.path``
-''''''''''''''''''''''''''''
+'''''''''''''''''''''''''''
 
 - **Type**: string
 - **Required?**: yes
@@ -412,7 +412,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. _pylock-packages-directory-editable:
 
 ``packages.directory.editable``
-''''''''''''''''''''''''''''''''
+'''''''''''''''''''''''''''''''
 
 - **Type**: boolean
 - **Required?**: no; defaults to ``false``
@@ -428,7 +428,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
 .. _pylock-packages-directory-subdirectory:
 
 ``packages.directory.subdirectory``
-''''''''''''''''''''''''''''''''''''
+'''''''''''''''''''''''''''''''''''
 
 See :ref:`pylock-packages-vcs-subdirectory`.
 
@@ -436,7 +436,7 @@ See :ref:`pylock-packages-vcs-subdirectory`.
 .. _pylock-packages-archive:
 
 ``[packages.archive]``
------------------------
+----------------------
 
 - **Type**: table
 - **Required?**: no
@@ -454,7 +454,7 @@ See :ref:`pylock-packages-vcs-subdirectory`.
 .. _pylock-packages-archive-url:
 
 ``packages.archive.url``
-'''''''''''''''''''''''''
+''''''''''''''''''''''''
 
 See :ref:`pylock-packages-vcs-url`.
 
@@ -462,7 +462,7 @@ See :ref:`pylock-packages-vcs-url`.
 .. _pylock-packages-archive-path:
 
 ``packages.archive.path``
-''''''''''''''''''''''''''
+'''''''''''''''''''''''''
 
 See :ref:`pylock-packages-vcs-path`.
 
@@ -470,7 +470,7 @@ See :ref:`pylock-packages-vcs-path`.
 .. _pylock-packages-archive-size:
 
 ``packages.archive.size``
-''''''''''''''''''''''''''
+'''''''''''''''''''''''''
 
 - **Type**: integer
 - **Required?**: no
@@ -495,7 +495,7 @@ See :ref:`pylock-packages-vcs-path`.
 .. _pylock-packages-archive-hashes:
 
 ``[packages.archive.hashes]``
-''''''''''''''''''''''''''''''
+'''''''''''''''''''''''''''''
 
 - **Type**: Table of strings
 - **Required?**: yes

From eaf53bec528cdc65fdfa61a4b02b3b3ad3e06801 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Fri, 2 May 2025 16:02:39 -0700
Subject: [PATCH 617/733] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/specifications/pylock-toml.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
index fdd3ed5a0..a25937c75 100644
--- a/source/specifications/pylock-toml.rst
+++ b/source/specifications/pylock-toml.rst
@@ -614,7 +614,7 @@ See :ref:`pylock-packages-archive-hashes`.
   :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
 - **Inspiration**: PDM_, Poetry_, uv_
 - For recording the wheel files as specified by
-  :ref:`  binary-distribution-format` for the package.
+  :ref:`binary-distribution-format` for the package.
 - Tools MUST support wheel files, both from a locking and installation
   perspective.
 
@@ -847,4 +847,3 @@ History
 .. _TOML: https://toml.io/
 .. _uv: https://pypi.org/project/uv/
 .. _URL: https://url.spec.whatwg.org/
-.. _URL: https://url.spec.whatwg.org/

From eb512bcc0900163bfdf4faedbf04ab86efb919a2 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Fri, 2 May 2025 16:06:05 -0700
Subject: [PATCH 618/733] Drop comments

---
 source/specifications/pylock-toml.rst | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
index a25937c75..d21294cf9 100644
--- a/source/specifications/pylock-toml.rst
+++ b/source/specifications/pylock-toml.rst
@@ -58,7 +58,6 @@ recorded in a consistent order (if inspiration is desired, this specification ha
 write down keys in a logical order). As well, tools SHOULD sort arrays in
 consistent order. Usage of inline tables SHOULD also be kept consistent.
 
-.. File details
 
 .. _pylock-lock-version:
 
@@ -194,8 +193,6 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   be installed MUST narrow down to a single entry at install time.
 
 
-.. Identification
-
 .. _pylock-packages-name:
 
 ``packages.name``
@@ -224,8 +221,6 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   :ref:`source tree ` is used).
 
 
-.. Requirements
-
 .. _pylock-packages-marker:
 
 ``packages.marker``
@@ -271,8 +266,6 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
   informational for auditing purposes.
 
 
-.. Source
-
 .. _pylock-packages-vcs:
 
 ``[packages.vcs]``

From 8315686281c00a0ce17c687ef091cbe5af3d6e60 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Fri, 2 May 2025 16:10:58 -0700
Subject: [PATCH 619/733] Normalize formatting

---
 source/specifications/pylock-toml/pylock.example.toml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/source/specifications/pylock-toml/pylock.example.toml b/source/specifications/pylock-toml/pylock.example.toml
index 60982f1d3..45e8731b2 100644
--- a/source/specifications/pylock-toml/pylock.example.toml
+++ b/source/specifications/pylock-toml/pylock.example.toml
@@ -1,12 +1,12 @@
 lock-version = '1.0'
 environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
-requires-python = '==3.12'
+requires-python = '== 3.12'
 created-by = 'mousebender'
 
 [[packages]]
 name = 'attrs'
 version = '25.1.0'
-requires-python = '>=3.8'
+requires-python = '>= 3.8'
 
     [[packages.wheels]]
     name = 'attrs-25.1.0-py3-none-any.whl'
@@ -24,7 +24,7 @@ requires-python = '>=3.8'
 [[packages]]
 name = 'cattrs'
 version = '24.1.2'
-requires-python = '>=3.8'
+requires-python = '>= 3.8'
 dependencies = [
     {name = 'attrs'},
 ]
@@ -39,7 +39,7 @@ dependencies = [
 [[packages]]
 name = 'numpy'
 version = '2.2.3'
-requires-python = '>=3.10'
+requires-python = '>= 3.10'
 
     [[packages.wheels]]
     name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl'

From 8a6eccf4131c3fcccbb52949e09e91b8c6c79833 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Fri, 2 May 2025 16:13:46 -0700
Subject: [PATCH 620/733] Make example or extras and dependency groups mroe
 distinct

---
 source/specifications/dependency-specifiers.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index 62731ffbb..e8e3229ff 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -299,12 +299,12 @@ an error like all other unknown variables.
      - An error except when defined by the context interpreting the
        specification.
      - String
-     - ``test``
+     - ``toml``
    * - ``extras``
      - An error except when defined by the context interpreting the
        specification.
      - Set of strings
-     - ``{"test"}``
+     - ``{"toml"}``
    * - ``dependency_groups``
      - An error except when defined by the context interpreting the
        specification.

From 1acd5e7f6489d4085947e1534d51102da60e6419 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Fri, 9 May 2025 16:16:07 -0700
Subject: [PATCH 621/733] Clarify that dev releases are considered pre-releases
 when handling them See
 https://discuss.python.org/t/are-developmental-releases-a-type-of-pre-release/81666/10
 for approval of this change.

---
 source/specifications/version-specifiers.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index d18596ee0..acb63b59e 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -343,6 +343,9 @@ post-releases::
     X.YrcN.devM      # Developmental release of a release candidate
     X.Y.postN.devM   # Developmental release of a post-release
 
+Do note that development releases are considered a type of pre-release when
+handling them.
+
 .. note::
 
    While they may be useful for continuous integration purposes, publishing
@@ -1266,3 +1269,5 @@ History
 =======
 
 - August 2014: This specification was approved through :pep:`440`.
+- May 2025: Clarify that development releases are a form of pre-release when
+  they are handled.

From 866005370d20c64e811a7b2990b2f3e9c3ae7956 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Tue, 13 May 2025 15:52:09 -0400
Subject: [PATCH 622/733] guides: remove manual Sigstore steps from publishing
 guide

These steps are superfluous now that gh-action-pypi-publish
generates and uploads PEP 740-compatible attestations by default
on its own.

(They also served a slightly different purpose than PEP 740
attestations, since they were never uploaded to PyPI and used
a different format.)

Closes #1788.

Signed-off-by: William Woodruff 
---
 .../publish-to-test-pypi.yml                  | 43 ----------------
 ...s-using-github-actions-ci-cd-workflows.rst | 51 ++++---------------
 2 files changed, 11 insertions(+), 83 deletions(-)

diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
index 7051540ef..8813a0392 100644
--- a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
+++ b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
@@ -51,49 +51,6 @@ jobs:
     - name: Publish distribution 📦 to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
 
-  github-release:
-    name: >-
-      Sign the Python 🐍 distribution 📦 with Sigstore
-      and upload them to GitHub Release
-    needs:
-    - publish-to-pypi
-    runs-on: ubuntu-latest
-
-    permissions:
-      contents: write  # IMPORTANT: mandatory for making GitHub Releases
-      id-token: write  # IMPORTANT: mandatory for sigstore
-
-    steps:
-    - name: Download all the dists
-      uses: actions/download-artifact@v4
-      with:
-        name: python-package-distributions
-        path: dist/
-    - name: Sign the dists with Sigstore
-      uses: sigstore/gh-action-sigstore-python@v3.0.0
-      with:
-        inputs: >-
-          ./dist/*.tar.gz
-          ./dist/*.whl
-    - name: Create GitHub Release
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: >-
-        gh release create
-        "$GITHUB_REF_NAME"
-        --repo "$GITHUB_REPOSITORY"
-        --notes ""
-    - name: Upload artifact signatures to GitHub Release
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      # Upload to GitHub Release using the `gh` CLI.
-      # `dist/` contains the built packages, and the
-      # sigstore-produced signatures and certificates.
-      run: >-
-        gh release upload
-        "$GITHUB_REF_NAME" dist/**
-        --repo "$GITHUB_REPOSITORY"
-
   publish-to-testpypi:
     name: Publish Python 🐍 distribution 📦 to TestPyPI
     needs:
diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
index 049fba15c..1ee562cf7 100644
--- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
+++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
@@ -21,10 +21,10 @@ for temporarily storing and downloading the source packages.
    details of building platform specific projects. If you have binary
    components, check out :ref:`cibuildwheel`'s GitHub Action examples.
 
-Configuring trusted publishing
+Configuring Trusted Publishing
 ==============================
 
-This guide relies on PyPI's `trusted publishing`_ implementation to connect
+This guide relies on PyPI's `Trusted Publishing`_ implementation to connect
 to `GitHub Actions CI/CD`_. This is recommended for security reasons, since
 the generated tokens are created for each of your projects
 individually and expire automatically. Otherwise, you'll need to generate an
@@ -36,7 +36,7 @@ Since this guide will demonstrate uploading to both
 PyPI and TestPyPI, we'll need two trusted publishers configured.
 The following steps will lead you through creating the "pending" publishers
 for your new :term:`PyPI project `.
-However it is also possible to add `trusted publishing`_ to any
+However it is also possible to add `Trusted Publishing`_ to any
 pre-existing project, if you are its owner.
 
 .. attention::
@@ -134,7 +134,7 @@ provided by GitHub Actions. This also defines a GitHub Environment
 for the job to run in its context and a URL to be displayed in GitHub's
 UI nicely. Additionally, it allows acquiring an OpenID Connect token
 that the ``pypi-publish`` actions needs to implement secretless
-trusted publishing to PyPI.
+Trusted Publishing to PyPI.
 
 .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
    :language: yaml
@@ -152,46 +152,20 @@ Finally, add the following steps at the end:
 .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
    :language: yaml
    :start-after: id-token: write
-   :end-before:  github-release:
+   :end-before:  publish-to-testpypi:
 
 This step uses the `pypa/gh-action-pypi-publish`_ GitHub
 Action: after the stored distribution package has been
 downloaded by the `download-artifact`_ action, it uploads
 the contents of the ``dist/`` folder into PyPI unconditionally.
 
-Signing the distribution packages
-=================================
-
-The following job signs the distribution packages with `Sigstore`_,
-the same artifact signing system `used to sign CPython `_.
-
-Firstly, it uses the `sigstore/gh-action-sigstore-python GitHub Action`_
-to sign the distribution packages. In the next step, an empty GitHub Release
-from the current tag is created using the ``gh`` CLI. Note this step can be further
-customised. See the `gh release documentation `_
-as a reference.
-
 .. tip::
 
-   You may need to manage your ``GITHUB_TOKEN`` permissions to
-   enable creating the GitHub Release. See the `GitHub
-   documentation `_
-   for instructions. Specifically, the token needs the
-   ``contents: write`` permission.
-
-Finally, the signed distributions are uploaded to the GitHub Release.
-
-.. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
-   :language: yaml
-   :start-at: github-release:
-   :end-before:  publish-to-testpypi
-
-
-.. note::
-
-   This is a replacement for GPG signatures, for which support has been
-   `removed from PyPI `_.
-   However, this job is not mandatory for uploading to PyPI and can be omitted.
+   Starting with version
+   `v1.11.0 `_,
+   `pypa/gh-action-pypi-publish`_ generates and uploads :pep:`740`-compatible
+   attestations for each distribution by default. No additional manual
+   signing steps are required.
 
 
 Separate workflow for publishing to TestPyPI
@@ -254,9 +228,6 @@ sure that your release pipeline remains healthy!
    https://github.com/actions/download-artifact
 .. _`upload-artifact`:
    https://github.com/actions/upload-artifact
-.. _Sigstore: https://www.sigstore.dev/
-.. _`sigstore/gh-action-sigstore-python GitHub Action`:
-   https://github.com/marketplace/actions/gh-action-sigstore-python
 .. _Secrets:
    https://docs.github.com/en/actions/reference/encrypted-secrets
-.. _trusted publishing: https://docs.pypi.org/trusted-publishers/
+.. _Trusted Publishing: https://docs.pypi.org/trusted-publishers/

From a27a095cf3f477063daf0b55619156a54dbb13d3 Mon Sep 17 00:00:00 2001
From: Wade Cheng <86323079+wade-cheng@users.noreply.github.com>
Date: Fri, 11 Apr 2025 17:55:09 -0400
Subject: [PATCH 623/733] grammar you->your

---
 source/guides/creating-command-line-tools.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst
index 49ce0c9ed..bf0354071 100644
--- a/source/guides/creating-command-line-tools.rst
+++ b/source/guides/creating-command-line-tools.rst
@@ -184,7 +184,7 @@ default one and run it, which makes this command possible:
 Conclusion
 ==========
 
-You know by now how to package a command-line application written in Python. A further step could be to distribute you package,
+You know by now how to package a command-line application written in Python. A further step could be to distribute your package,
 meaning uploading it to a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions at :ref:`Packaging your project`. And once you're done, don't forget to :ref:`do some research ` on how your package is received!
 
 .. _click: https://click.palletsprojects.com/

From 480dbb9b8cbd7f33d0c6bc89ce490aec9c80da0d Mon Sep 17 00:00:00 2001
From: Ned Batchelder 
Date: Sat, 17 May 2025 18:21:43 -0400
Subject: [PATCH 624/733] don't change the link syntax

---
 source/glossary.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index 73a192daa..6a592125f 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -291,7 +291,7 @@ Glossary
         `_, and discuss issues on the
         `distutils-sig mailing list
         `_
-	and `the Python Discourse forum `_.
+	and `the Python Discourse forum `__.
 
 
     Python Package Index (PyPI)

From c56c952fcf0fbc0c1602c68dc266468d6f3bedb3 Mon Sep 17 00:00:00 2001
From: Stephen Rosen 
Date: Mon, 19 May 2025 14:57:56 -0400
Subject: [PATCH 625/733] Add 'docs' to dependency groups example

This is a small example update based on some observed usage of
Dependency Groups. We wouldn't want to bloat the example, but many
projects are using a `docs` group and this example therefore better
exemplifies how Dependency Groups can be used to declare
isolated/separate groups.
---
 source/specifications/dependency-groups.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/source/specifications/dependency-groups.rst b/source/specifications/dependency-groups.rst
index b6a3e6fad..22e4cba0d 100644
--- a/source/specifications/dependency-groups.rst
+++ b/source/specifications/dependency-groups.rst
@@ -22,14 +22,16 @@ Specification
 Examples
 --------
 
-This is a simple table which shows a ``test`` group::
+This is a simple table which shows ``docs`` and ``test`` groups::
 
     [dependency-groups]
+    docs = ["sphinx"]
     test = ["pytest>7", "coverage"]
 
-and a similar table which defines ``test`` and ``coverage`` groups::
+and a similar table which defines ``docs``, ``test``, and ``coverage`` groups::
 
     [dependency-groups]
+    docs = ["sphinx"]
     coverage = ["coverage[toml]"]
     test = ["pytest>7", {include-group = "coverage"}]
 

From 73aea5cd2804d66adaabbea35b8f78068662aa9d Mon Sep 17 00:00:00 2001
From: Yuki Kobayashi 
Date: Mon, 26 May 2025 01:02:51 +0000
Subject: [PATCH 626/733] Fix typo

---
 source/specifications/platform-compatibility-tags.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index d617323d4..6feb18cda 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -151,7 +151,7 @@ auditwheel  ``>=1.0.0``     ``>=2.0.0``        ``>=3.0.0``        ``>=3.3.0`` [#
 
 The ``musllinux`` family of tags is similar to ``manylinux``, but for Linux
 platforms that use the musl_ libc rather than glibc (a prime example being Alpine
-Linux). The schema is :file:`musllinux_{x}_{y}_{arch}``, supporting musl ``x.y`` and higher
+Linux). The schema is :file:`musllinux_{x}_{y}_{arch}`, supporting musl ``x.y`` and higher
 on the architecture ``arch``.
 
 The musl version values can be obtained by executing the musl libc shared

From cf5953a5ff9bd5f92b90d4ff997c0ed7614b2926 Mon Sep 17 00:00:00 2001
From: Daksh Bhayana 
Date: Sun, 1 Jun 2025 18:11:31 +0530
Subject: [PATCH 627/733] Empty Commit to check CI failure


From 79793e91b8bfd5bd0327b666a3e36f0c74d47037 Mon Sep 17 00:00:00 2001
From: Daksh Bhayana 
Date: Sun, 1 Jun 2025 18:38:20 +0530
Subject: [PATCH 628/733] Added specific redhat url to linkcheck_ignore

---
 source/conf.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/source/conf.py b/source/conf.py
index d41db4957..7a05613ea 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -146,6 +146,7 @@
     "https://pyscaffold.org/*",
     "https://anaconda.org",
     "https://www.cisa.gov/sbom",
+    "https://developers.redhat.com/products/softwarecollections/overview",
 ]
 linkcheck_retries = 5
 # Ignore anchors for common targets when we know they likely won't be found

From 397de33ae16184bd8a23941c163d4c2d174c19ea Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Tue, 3 Jun 2025 10:42:15 -0400
Subject: [PATCH 629/733] specifications: clarify "sorted, set" to "sorted,
 collection"

This will hopefully clarify/eliminate a contradiction in terms
in the current specification text: the current text says
both "sorted" and "set", where "set" conventionally implies
an unordered collection.

In context that *appears* to have not been the intention,
since the context is the wheel filename encoding
and not the internal (i.e. parsed) representation
of a wheel filename's tags.

Signed-off-by: William Woodruff 
---
 source/specifications/platform-compatibility-tags.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 6feb18cda..0502c8c03 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -351,7 +351,7 @@ Compressed Tag Sets
 
 To allow for compact filenames of bdists that work with more than
 one compatibility tag triple, each tag in a filename can instead be a
-'.'-separated, sorted, set of tags.  For example, pip, a pure-Python
+'.'-separated, sorted, collection of tags.  For example, pip, a pure-Python
 package that is written to run under Python 2 and 3 with the same source
 code, could distribute a bdist with the tag ``py2.py3-none-any``.
 The full list of simple tags is::

From 2635f8c215877157ea5728a0d36948c41133a10f Mon Sep 17 00:00:00 2001
From: Ned Batchelder 
Date: Wed, 18 Jun 2025 06:52:47 -0400
Subject: [PATCH 630/733] Re-order the metadata history to be in usual
 changelog order

---
 source/specifications/core-metadata.rst | 27 ++++++++++++++-----------
 1 file changed, 15 insertions(+), 12 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 39ee7c4cd..b4667d7e1 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -921,27 +921,30 @@ Example::
 History
 =======
 
-- March 2001: Core metadata 1.0 was approved through :pep:`241`.
-- April 2003: Core metadata 1.1 was approved through :pep:`314`:
-- February 2010: Core metadata 1.2 was approved through :pep:`345`.
-- February 2018: Core metadata 2.1 was approved through :pep:`566`.
+- August 2024: Core metadata 2.4 was approved through :pep:`639`.
 
-  - Added ``Description-Content-Type`` and ``Provides-Extra``.
-  - Added canonical method for transforming metadata to JSON.
-  - Restricted the grammar of the ``Name`` field.
+  - Added the ``License-Expression`` field.
+  - Added the ``License-File`` field.
+
+- March 2022: Core metadata 2.3 was approved through :pep:`685`.
+
+  - Restricted extra names to be normalized.
 
 - October 2020: Core metadata 2.2 was approved through :pep:`643`.
 
   - Added the ``Dynamic`` field.
 
-- March 2022: Core metadata 2.3 was approved through :pep:`685`.
+- February 2018: Core metadata 2.1 was approved through :pep:`566`.
 
-  - Restricted extra names to be normalized.
+  - Added ``Description-Content-Type`` and ``Provides-Extra``.
+  - Added canonical method for transforming metadata to JSON.
+  - Restricted the grammar of the ``Name`` field.
 
-- August 2024: Core metadata 2.4 was approved through :pep:`639`.
+- February 2010: Core metadata 1.2 was approved through :pep:`345`.
 
-  - Added the ``License-Expression`` field.
-  - Added the ``License-File`` field.
+- April 2003: Core metadata 1.1 was approved through :pep:`314`:
+
+- March 2001: Core metadata 1.0 was approved through :pep:`241`.
 
 ----
 

From f714ffd068c761d0a110b2a1d5af2cff5353f2e4 Mon Sep 17 00:00:00 2001
From: Ned Batchelder 
Date: Wed, 18 Jun 2025 06:53:26 -0400
Subject: [PATCH 631/733] Mention the metadata version and date at the top of
 the metadata page

---
 source/specifications/core-metadata.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index b4667d7e1..550c6e55a 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -6,6 +6,8 @@
 Core metadata specifications
 ============================
 
+This page describes version 2.4, approved in August 2024.
+
 Fields defined in the following specification should be considered valid,
 complete and not subject to change. The required fields are:
 

From 2989d20d2fb0a7577267729500fc4b9e8efa9bcf Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Fri, 27 Jun 2025 15:59:11 -0700
Subject: [PATCH 632/733] Fix references in pylock-toml.rst

A few had spaces after the opening backtick.
---
 source/specifications/pylock-toml.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
index d21294cf9..342e608c5 100644
--- a/source/specifications/pylock-toml.rst
+++ b/source/specifications/pylock-toml.rst
@@ -672,12 +672,12 @@ See :ref:`pylock-packages-archive-hashes`.
 
 - **Type**: array of tables
 - **Required?**: no
-- **Inspiration**: :ref:`  provenance-object`
+- **Inspiration**: :ref:`provenance-object`
 - A recording of the attestations for **any** file recorded for this package.
 - If available, tools SHOULD include the attestation identities found.
 - Publisher-specific keys are to be included in the table as-is
   (i.e. top-level), following the spec at
-  :ref:`  index-hosted-attestations`.
+  :ref:`index-hosted-attestations`.
 
 
 .. _pylock-packages-attestation-identities-kind:
@@ -687,7 +687,7 @@ See :ref:`pylock-packages-archive-hashes`.
 
 - **Type**: string
 - **Required?**: yes
-- **Inspiration**: :ref:`  provenance-object`
+- **Inspiration**: :ref:`provenance-object`
 - The unique identity of the Trusted Publisher.
 
 
@@ -698,9 +698,9 @@ See :ref:`pylock-packages-archive-hashes`.
 
 - **Type**: table
 - **Required?**: no
-- **Inspiration**: :ref:`  pyproject-tool-table`
+- **Inspiration**: :ref:`pyproject-tool-table`
 - Similar usage as that of the :ref:`pylock-tool` table from the
-  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  :ref:`pyproject-toml-spec`, but at the package version level instead
   of at the lock file level (which is also available via :ref:`pylock-tool`).
 - Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
   installation).

From 19a7a03595d6f9e7e25fbd3abf6decda739b91e0 Mon Sep 17 00:00:00 2001
From: Yuki Kobayashi 
Date: Sat, 28 Jun 2025 01:14:42 +0000
Subject: [PATCH 633/733] Fix a small markup error in the contribute guide

The "Do not translate ..." part shoule be a definition list, not a blockquote, like the rest of this page.
---
 source/contribute.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/source/contribute.rst b/source/contribute.rst
index cf5314b8d..f512dd30d 100644
--- a/source/contribute.rst
+++ b/source/contribute.rst
@@ -103,7 +103,6 @@ If you are not familiar with reStructuredText (RST) syntax, please read `this gu
 before translating on Weblate.
 
 **Do not translate the text in reference directly**
-
   When translating the text in reference, please do not translate them directly.
 
   | Wrong: Translate the following text directly:

From 6b10bd2efbec7091f21973c1824db32573b4c010 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Fri, 11 Jul 2025 22:33:52 -0400
Subject: [PATCH 634/733] simple-repository-api: add PEP 792, clean up layout

---
 source/specifications/file-yanking.rst        |  92 +++++
 .../specifications/project-status-markers.rst |  89 +++++
 .../section-package-indices.rst               |   2 +
 .../specifications/simple-repository-api.rst  | 369 +++++++++---------
 4 files changed, 377 insertions(+), 175 deletions(-)
 create mode 100644 source/specifications/file-yanking.rst
 create mode 100644 source/specifications/project-status-markers.rst

diff --git a/source/specifications/file-yanking.rst b/source/specifications/file-yanking.rst
new file mode 100644
index 000000000..4ab8cd5cc
--- /dev/null
+++ b/source/specifications/file-yanking.rst
@@ -0,0 +1,92 @@
+.. _file-yanking:
+
+============
+File Yanking
+============
+
+.. note::
+
+    This specification was originally defined in
+    :pep:`592`.
+
+.. note::
+
+    :pep:`592` includes changes to the HTML and JSON index APIs.
+    These changes are documented in the :ref:`simple-repository-api`
+    under :ref:`HTML - Project Detail `
+    and :ref:`JSON - Project Detail `.
+
+Specification
+=============
+
+Links in the simple repository **MAY** have a ``data-yanked`` attribute
+which may have no value, or may have an arbitrary string as a value. The
+presence of a ``data-yanked`` attribute **SHOULD** be interpreted as
+indicating that the file pointed to by this particular link has been
+"Yanked", and should not generally be selected by an installer, except
+under specific scenarios.
+
+The value of the ``data-yanked`` attribute, if present, is an arbitrary
+string that represents the reason for why the file has been yanked. Tools
+that process the simple repository API **MAY** surface this string to
+end users.
+
+The yanked attribute is not immutable once set, and may be rescinded in
+the future (and once rescinded, may be reset as well). Thus API users
+**MUST** be able to cope with a yanked file being "unyanked" (and even
+yanked again).
+
+Installers
+----------
+
+The desirable experience for users is that once a file is yanked, when
+a human being is currently trying to directly install a yanked file, that
+it fails as if that file had been deleted. However, when a human did that
+awhile ago, and now a computer is just continuing to mechanically follow
+the original order to install the now yanked file, then it acts as if it
+had not been yanked.
+
+An installer **MUST** ignore yanked releases, if the selection constraints
+can be satisfied with a non-yanked version, and **MAY** refuse to use a
+yanked release even if it means that the request cannot be satisfied at all.
+An implementation **SHOULD** choose a policy that follows the spirit of the
+intention above, and that prevents "new" dependencies on yanked
+releases/files.
+
+What this means is left up to the specific installer, to decide how to best
+fit into the overall usage of their installer. However, there are two
+suggested approaches to take:
+
+1. Yanked files are always ignored, unless they are the only file that
+   matches a version specifier that "pins" to an exact version using
+   either ``==`` (without any modifiers that make it a range, such as
+   ``.*``) or ``===``. Matching this version specifier should otherwise
+   be done as per :ref:`the version specifiers specification
+   ` for things like local versions, zero padding,
+   etc.
+2. Yanked files are always ignored, unless they are the only file that
+   matches what a lock file (such as ``Pipfile.lock`` or ``poetry.lock``)
+   specifies to be installed. In this case, a yanked file **SHOULD** not
+   be used when creating or updating a lock file from some input file or
+   command.
+
+Regardless of the specific strategy that an installer chooses for deciding
+when to install yanked files, an installer **SHOULD** emit a warning when
+it does decide to install a yanked file. That warning **MAY** utilize the
+value of the ``data-yanked`` attribute (if it has a value) to provide more
+specific feedback to the user about why that file had been yanked.
+
+
+Mirrors
+-------
+
+Mirrors can generally treat yanked files one of two ways:
+
+1. They may choose to omit them from their simple repository API completely,
+   providing a view over the repository that shows only "active", unyanked
+   files.
+2. They may choose to include yanked files, and additionally mirror the
+   ``data-yanked`` attribute as well.
+
+Mirrors **MUST NOT** mirror a yanked file without also mirroring the
+``data-yanked`` attribute for it.
diff --git a/source/specifications/project-status-markers.rst b/source/specifications/project-status-markers.rst
new file mode 100644
index 000000000..90df74441
--- /dev/null
+++ b/source/specifications/project-status-markers.rst
@@ -0,0 +1,89 @@
+.. _project-status-markers:
+
+======================
+Project Status Markers
+======================
+
+.. note::
+
+    This specification was originally defined in
+    :pep:`792`.
+
+.. note::
+
+    :pep:`792` includes changes to the HTML and JSON index APIs.
+    These changes are documented in the :ref:`simple-repository-api`
+    under :ref:`HTML - Project Detail `
+    and :ref:`JSON - Project Detail `.
+
+Specification
+=============
+
+A project always has exactly one status. If no status is explicitly noted,
+then the project is considered to be in the ``active`` state.
+
+Indices **MAY** implement any subset of the status markers specified,
+as applicable to their needs.
+
+This standard does not prescribe *which* principals (i.e. project maintainers,
+index administrators, etc.) are allowed to set and unset which statuses.
+
+``active``
+----------
+
+Description: The project is active. This is the default status for a project.
+
+Index semantics:
+
+* The index hosting the project **MUST** allow uploads of new distributions to
+  the project.
+* The index **MUST** offer existing distributions of the project for download.
+
+Installer semantics: none.
+
+``archived``
+------------
+
+Description: The project does not expect to be updated in the future.
+
+Index semantics:
+
+* The index hosting the project **MUST NOT** allow uploads of new distributions to
+  the project.
+* The index **MUST** offer existing distributions of the project for download.
+
+Installer semantics:
+
+* Installers **MAY** produce warnings about a project's archival.
+
+``quarantined``
+---------------
+
+Description: The project is considered generally unsafe for use, e.g. due to
+malware.
+
+Index semantics:
+
+* The index hosting the project **MUST NOT** allow uploads of new distributions to
+  the project.
+* The index **MUST NOT** offer any distributions of the project for download.
+
+Installer semantics:
+
+* Installers **MAY** produce warnings about a project's quarantine, although
+  doing so is effectively moot (as the index will not offer any distributions
+  for installation).
+
+``deprecated``
+--------------
+
+Description: The project is considered obsolete, and may have been superseded
+by another project.
+
+Index semantics:
+
+* This status shares the same semantics as ``active``.
+
+Installer semantics:
+
+* Installers **MAY** produce warnings about a project's deprecation.
diff --git a/source/specifications/section-package-indices.rst b/source/specifications/section-package-indices.rst
index 73004b4d3..1fcefe6ff 100644
--- a/source/specifications/section-package-indices.rst
+++ b/source/specifications/section-package-indices.rst
@@ -7,4 +7,6 @@ Package Index Interfaces
 
    pypirc
    simple-repository-api
+   file-yanking
    index-hosted-attestations
+   project-status-markers
diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
index d18c425db..afc932e4e 100644
--- a/source/specifications/simple-repository-api.rst
+++ b/source/specifications/simple-repository-api.rst
@@ -12,12 +12,13 @@ and "**OPTIONAL**"" in this document are to be interpreted as described in
 
 The interface for querying available package versions and
 retrieving packages from an index server comes in two forms:
-HTML and JSON.
+:ref:`HTML ` and
+:ref:`JSON `.
 
 .. _simple-repository-api-base:
 
-Base HTML API
-=============
+Base API
+========
 
 A repository that implements the simple API is defined by its base URL, this is
 the top level URL that all additional URLs are below. The API is named the
@@ -28,11 +29,115 @@ the top level URL that all additional URLs are below. The API is named the
           URL (so given PyPI's URL, a URL of ``/foo/`` would be
           ``https://pypi.org/simple/foo/``.
 
+Normalized Names
+----------------
+
+This spec references the concept of a "normalized" project name. As per
+:ref:`the name normalization specification `
+the only valid characters in a name are the ASCII alphabet, ASCII numbers,
+``.``, ``-``, and ``_``. The name should be lowercased with all runs of the
+characters ``.``, ``-``, or ``_`` replaced with a single ``-`` character. This
+can be implemented in Python with the ``re`` module::
+
+   import re
+
+   def normalize(name):
+       return re.sub(r"[-_.]+", "-", name).lower()
+
+.. _simple-repository-api-versioning:
+
+Versioning PyPI's Simple API
+----------------------------
+
+This spec proposes the inclusion of a meta tag on the responses of every
+successful request to a simple API page, which contains a name attribute
+of ``pypi:repository-version``, and a content that is a :ref:`version specifiers
+specification ` compatible
+version number, which is further constrained to ONLY be Major.Minor, and
+none of the additional features supported by :ref:`the version specifiers
+specification `.
+
+This would end up looking like:
+
+.. code-block:: html
+
+  
+
+When interpreting the repository version:
+
+* Incrementing the major version is used to signal a backwards
+  incompatible change such that existing clients would no longer be
+  expected to be able to meaningfully use the API.
+* Incrementing the minor version is used to signal a backwards
+  compatible change such that existing clients would still be
+  expected to be able to meaningfully use the API.
+
+It is left up to the discretion of any future specs as to what
+specifically constitutes a backwards incompatible vs compatible change
+beyond the broad suggestion that existing clients will be able to
+"meaningfully" continue to use the API, and can include adding,
+modifying, or removing existing features.
+
+It is expectation of this spec that the major version will never be
+incremented, and any future major API evolutions would utilize a
+different mechanism for API evolution. However the major version
+is included to disambiguate with future versions (e.g. a hypothetical
+simple api v2 that lived at /v2/, but which would be confusing if the
+repository-version was set to a version >= 2).
+
+API Version History
+~~~~~~~~~~~~~~~~~~~
+
+This section contains only an abbreviated history of changes,
+as marked by the API version number. For a full history of changes including
+changes made before API versioning, see :ref:`History `.
+
+- API version 1.0: Initial version of the API, declared with :pep:`629`.
+- API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-time`` metadata
+  to the JSON serialization, declared with :pep:`700`.
+- API version 1.2: Added repository "tracks" metadata, declared with :pep:`708`.
+- API version 1.3: Added provenance metadata, declared with :pep:`740`.
+- API version 1.4: Added status markers, declared with :pep:`792`.
+
+Clients
+~~~~~~~
+
+Clients interacting with the simple API **SHOULD** introspect each
+response for the repository version, and if that data does not exist
+**MUST** assume that it is version 1.0.
+
+When encountering a major version greater than expected, clients
+**MUST** hard fail with an appropriate error message for the user.
+
+When encountering a minor version greater than expected, clients
+**SHOULD** warn users with an appropriate message.
+
+Clients **MAY** still continue to use feature detection in order to
+determine what features a repository uses.
+
+.. _simple-repository-html-serialization:
+
+HTML Serialization
+------------------
+
+.. _simple-repository-html-project-list:
+
+The following constraints apply to all HTML serialized responses described in
+this spec:
+
+* All HTML responses **MUST** be a valid HTML5 document.
+* HTML responses **MAY** contain one or more ``meta`` tags in the
+  ```` section. The semantics of these tags are defined below.
+
+Project List
+~~~~~~~~~~~~
 
 Within a repository, the root URL (``/`` for this spec which represents the base
 URL) **MUST** be a valid HTML5 page with a single anchor element per project in
-the repository. The text of the anchor tag **MUST** be the name of
-the project and the href attribute **MUST** link to the URL for that particular
+the repository.
+
+The text of each anchor tag **MUST** be the name of
+the project and the ``href`` attribute **MUST** link to the URL for that particular
 project. As an example:
 
 .. code-block:: html
@@ -45,14 +150,26 @@ project. As an example:
      
    
 
+.. _simple-repository-html-project-detail:
+
+Project Detail
+~~~~~~~~~~~~~~
+
 Below the root URL is another URL for each individual project contained within
-a repository. The format of this URL is ``//`` where the ````
-is replaced by the normalized name for that project, so a project named
-"HolyGrail" would have a URL like ``/holygrail/``. This URL must respond with
-a valid HTML5 page with a single anchor element per file for the project. The
-href attribute **MUST** be a URL that links to the location of the file for
-download, and the text of the anchor tag **MUST** match the final path
-component (the filename) of the URL. The URL **SHOULD** include a hash in the
+a repository. The format of this URL is ``//``, where the ````
+is replaced by the normalized name for that project.
+
+.. tip::
+
+   For example, a project named "HolyGrail" would have a URL like
+   ``/holygrail/``.
+
+The project detail URL must respond with a valid HTML5 page with a single
+anchor element per file for the project. The ``href`` attribute **MUST** be a
+URL that links to the location of the file for download, and the text of the
+anchor tag **MUST** match the final path component (the filename) of the URL.
+
+Each file URL **SHOULD** include a hash in the
 form of a URL fragment with the following syntax: ``#=``,
 where ```` is the lowercase name of the hash function (such as
 ``sha256``) and ```` is the hex encoded digest.
@@ -125,6 +242,22 @@ In addition to the above, the following constraints are placed on the API:
   In the attribute value, < and > have to be HTML encoded as ``<`` and
   ``>``, respectively.
 
+* A repository **MAY** include a ``data-yanked`` attribute on a file link.
+
+  The ``data-yanked`` attribute may have no value, or may have an
+  arbitrary string as a value. The presence of a ``data-yanked`` attribute
+  **SHOULD** be interpreted as indicating that the file pointed to by this
+  particular link has been "Yanked", and should not generally be selected by
+  an installer, except under specific scenarios.
+
+  The value of the ``data-yanked`` attribute, if present, is an arbitrary
+  string that represents the reason for why the file has been yanked.
+
+  .. note::
+
+    The semantics of how tools should handle yanked files is
+    described in :ref:`file-yanking`.
+
 * A repository **MAY** include a ``data-provenance`` attribute on a file link.
   The value of this attribute **MUST** be a fully qualified URL, signaling that
   the file's provenance can be found at that URL. This URL **MUST** represent
@@ -138,168 +271,22 @@ In addition to the above, the following constraints are placed on the API:
 
     The format of the linked provenance is defined in :ref:`index-hosted-attestations`.
 
-Normalized Names
-----------------
-
-This spec references the concept of a "normalized" project name. As per
-:ref:`the name normalization specification `
-the only valid characters in a name are the ASCII alphabet, ASCII numbers,
-``.``, ``-``, and ``_``. The name should be lowercased with all runs of the
-characters ``.``, ``-``, or ``_`` replaced with a single ``-`` character. This
-can be implemented in Python with the ``re`` module::
-
-   import re
-
-   def normalize(name):
-       return re.sub(r"[-_.]+", "-", name).lower()
-
-.. _simple-repository-api-yank:
-
-Adding "Yank" Support to the Simple API
-=======================================
-
-Links in the simple repository **MAY** have a ``data-yanked`` attribute
-which may have no value, or may have an arbitrary string as a value. The
-presence of a ``data-yanked`` attribute **SHOULD** be interpreted as
-indicating that the file pointed to by this particular link has been
-"Yanked", and should not generally be selected by an installer, except
-under specific scenarios.
-
-The value of the ``data-yanked`` attribute, if present, is an arbitrary
-string that represents the reason for why the file has been yanked. Tools
-that process the simple repository API **MAY** surface this string to
-end users.
-
-The yanked attribute is not immutable once set, and may be rescinded in
-the future (and once rescinded, may be reset as well). Thus API users
-**MUST** be able to cope with a yanked file being "unyanked" (and even
-yanked again).
-
-
-Installers
-----------
-
-The desirable experience for users is that once a file is yanked, when
-a human being is currently trying to directly install a yanked file, that
-it fails as if that file had been deleted. However, when a human did that
-awhile ago, and now a computer is just continuing to mechanically follow
-the original order to install the now yanked file, then it acts as if it
-had not been yanked.
-
-An installer **MUST** ignore yanked releases, if the selection constraints
-can be satisfied with a non-yanked version, and **MAY** refuse to use a
-yanked release even if it means that the request cannot be satisfied at all.
-An implementation **SHOULD** choose a policy that follows the spirit of the
-intention above, and that prevents "new" dependencies on yanked
-releases/files.
-
-What this means is left up to the specific installer, to decide how to best
-fit into the overall usage of their installer. However, there are two
-suggested approaches to take:
-
-1. Yanked files are always ignored, unless they are the only file that
-   matches a version specifier that "pins" to an exact version using
-   either ``==`` (without any modifiers that make it a range, such as
-   ``.*``) or ``===``. Matching this version specifier should otherwise
-   be done as per :ref:`the version specifiers specification
-   ` for things like local versions, zero padding,
-   etc.
-2. Yanked files are always ignored, unless they are the only file that
-   matches what a lock file (such as ``Pipfile.lock`` or ``poetry.lock``)
-   specifies to be installed. In this case, a yanked file **SHOULD** not
-   be used when creating or updating a lock file from some input file or
-   command.
-
-Regardless of the specific strategy that an installer chooses for deciding
-when to install yanked files, an installer **SHOULD** emit a warning when
-it does decide to install a yanked file. That warning **MAY** utilize the
-value of the ``data-yanked`` attribute (if it has a value) to provide more
-specific feedback to the user about why that file had been yanked.
-
-
-Mirrors
--------
-
-Mirrors can generally treat yanked files one of two ways:
-
-1. They may choose to omit them from their simple repository API completely,
-   providing a view over the repository that shows only "active", unyanked
-   files.
-2. They may choose to include yanked files, and additionally mirror the
-   ``data-yanked`` attribute as well.
-
-Mirrors **MUST NOT** mirror a yanked file without also mirroring the
-``data-yanked`` attribute for it.
-
-.. _simple-repository-api-versioning:
-
-Versioning PyPI's Simple API
-============================
-
-This spec proposes the inclusion of a meta tag on the responses of every
-successful request to a simple API page, which contains a name attribute
-of ``pypi:repository-version``, and a content that is a :ref:`version specifiers
-specification ` compatible
-version number, which is further constrained to ONLY be Major.Minor, and
-none of the additional features supported by :ref:`the version specifiers
-specification `.
-
-This would end up looking like:
-
-.. code-block:: html
-
-  
-
-When interpreting the repository version:
-
-* Incrementing the major version is used to signal a backwards
-  incompatible change such that existing clients would no longer be
-  expected to be able to meaningfully use the API.
-* Incrementing the minor version is used to signal a backwards
-  compatible change such that existing clients would still be
-  expected to be able to meaningfully use the API.
-
-It is left up to the discretion of any future specs as to what
-specifically constitutes a backwards incompatible vs compatible change
-beyond the broad suggestion that existing clients will be able to
-"meaningfully" continue to use the API, and can include adding,
-modifying, or removing existing features.
-
-It is expectation of this spec that the major version will never be
-incremented, and any future major API evolutions would utilize a
-different mechanism for API evolution. However the major version
-is included to disambiguate with future versions (e.g. a hypothetical
-simple api v2 that lived at /v2/, but which would be confusing if the
-repository-version was set to a version >= 2).
-
-API Version History
--------------------
+* A repository **MAY** include ``pypi:project-status`` and
+  ``pypi:project-status-reason`` meta tags on the response itself.
 
-This section contains only an abbreviated history of changes,
-as marked by the API version number. For a full history of changes including
-changes made before API versioning, see :ref:`History `.
+  The value of ``pypi:project-status`` **MUST** be a valid
+  project status marker, while the value of
+  ``pypi:project-status-reason`` **MUST** be an arbitrary string if present.
 
-- API version 1.0: Initial version of the API, declared with :pep:`629`.
-- API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-time`` metadata
-  to the JSON serialization, declared with :pep:`700`.
-- API version 1.2: Added repository "tracks" metadata, declared with :pep:`708`.
-- API version 1.3: Added provenance metadata, declared with :pep:`740`.
-
-Clients
--------
-
-Clients interacting with the simple API **SHOULD** introspect each
-response for the repository version, and if that data does not exist
-**MUST** assume that it is version 1.0.
+  .. note::
 
-When encountering a major version greater than expected, clients
-**MUST** hard fail with an appropriate error message for the user.
+    The set of valid project status markers and their semantics is described
+    in :ref:`project-status-markers`.
 
-When encountering a minor version greater than expected, clients
-**SHOULD** warn users with an appropriate message.
+  .. note::
 
-Clients **MAY** still continue to use feature detection in order to
-determine what features a repository uses.
+    The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags
+    were added with API version 1.4.
 
 .. _simple-repository-api-metadata-file:
 
@@ -403,8 +390,8 @@ JSON Serialization
 ------------------
 
 The URL structure from :ref:`the base HTML API specification
-` still applies, as this spec only adds an additional
-serialization format for the already existing API.
+` still applies, as this spec only adds
+an additional serialization format for the already existing API.
 
 The following constraints apply to all JSON serialized responses described in this
 spec:
@@ -435,6 +422,8 @@ spec:
 * Keys (at any level) with a leading underscore are reserved as private for
   index server use. No future standard will assign a meaning to any such key.
 
+.. _simple-repository-json-project-list:
+
 Project List
 ~~~~~~~~~~~~
 
@@ -450,7 +439,7 @@ As an example:
 
     {
       "meta": {
-        "api-version": "1.3"
+        "api-version": "1.4"
       },
       "projects": [
         {"name": "Frob"},
@@ -478,6 +467,7 @@ As an example:
   best thought of as a set, but both JSON and HTML lack the functionality to have
   sets.
 
+.. _simple-repository-json-project-detail:
 
 Project Detail
 ~~~~~~~~~~~~~~
@@ -492,6 +482,28 @@ This URL must respond with a JSON encoded dictionary that has four keys:
 - ``name``: The normalized name of the project.
 - ``files``: A list of dictionaries, each one representing an individual file.
 - ``meta``: The general response metadata as `described earlier `__.
+
+  In addition to the general response metadata, the project detail ``meta``
+  dictionary **MAY** also include the following:
+
+  - ``project-status``: If present, this **MUST** be a valid project status marker.
+
+    .. note::
+
+      The set of valid project status markers and their semantics is described
+      in :ref:`project-status-markers`.
+
+    .. note::
+
+      The ``project-status`` key was added with API version 1.4.
+
+  - ``project-status-reason``: If present, this **MUST** be an arbitrary string
+    description of the project status.
+
+    .. note::
+
+      The ``project-status-reason`` key was added with API version 1.4.
+
 - ``versions``: A list of version strings specifying all of the project versions
   uploaded for this project. The value of ``versions`` is logically a set,
   and as such may not contain duplicates, and the order of the versions is
@@ -582,8 +594,13 @@ Each individual file dictionary has the following keys:
   file has been yanked, or a non empty, but otherwise arbitrary, string to indicate
   that a file has been yanked with a specific reason. If the ``yanked`` key is present
   and is a truthy value, then it **SHOULD** be interpreted as indicating that the
-  file pointed to by the ``url`` field has been "Yanked" as per :ref:`the API
-  yank specification `.
+  file pointed to by the ``url`` field has been "Yanked".
+
+  .. note::
+
+    The semantics of how tools should handle yanked files is
+    described in :ref:`file-yanking`.
+
 - ``size``: A **mandatory** key. It **MUST** contain an integer which is the file size in bytes.
 
   .. note::
@@ -618,7 +635,8 @@ As an example:
 
     {
       "meta": {
-        "api-version": "1.3"
+        "api-version": "1.4",
+        "project-status": "active"
       },
       "name": "holygrail",
       "files": [
@@ -1006,3 +1024,4 @@ History
 * June 2023: renaming the field which provides package metadata independently
   from a package, in :pep:`714`
 * November 2024: provenance metadata in the HTML and JSON formats, in :pep:`740`
+* July 2025: project status markers in the HTML and JSON formats, in :pep:`792`

From 9a6a4358ce484d2d76b27f0cadde85b174171d5e Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Wed, 16 Jul 2025 08:41:19 +0200
Subject: [PATCH 635/733] Add uv-build to table

---
 source/guides/writing-pyproject-toml.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 318fe0d51..1d035a384 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -314,11 +314,13 @@ backend>` now support the new format as shown in the following table.
      - flit-core [#flit-core-pep639]_
      - pdm-backend
      - poetry-core
+     - uv-build
    * - 1.27.0
      - 77.0.3
      - 3.12
      - 2.4.0
      - `not yet `_
+     - 0.7.19
 
 
 .. _license:

From bfd629be54786fe443354a239b9fedfe4341477c Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Fri, 18 Jul 2025 08:58:33 +0200
Subject: [PATCH 636/733] Add uv in other places

---
 source/shared/build-backend-tabs.rst       | 8 ++++++++
 source/tutorials/managing-dependencies.rst | 2 ++
 2 files changed, 10 insertions(+)

diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index 7fc3a61da..a4c49a3b4 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -32,3 +32,11 @@
         [build-system]
         requires = ["pdm-backend >= 2.4.0"]
         build-backend = "pdm.backend"
+
+.. tab:: uv-build
+
+    .. code-block:: toml
+
+        [build-system]
+        requires = ["uv_build >= 0.8.0, <0.9.0"]
+        build-backend = "uv_build"
\ No newline at end of file
diff --git a/source/tutorials/managing-dependencies.rst b/source/tutorials/managing-dependencies.rst
index db3b82533..da12d8a91 100644
--- a/source/tutorials/managing-dependencies.rst
+++ b/source/tutorials/managing-dependencies.rst
@@ -177,3 +177,5 @@ and techniques, listed in alphabetical order, to see if one of them is a better
   structured as a distributable Python package with a valid ``pyproject.toml`` file.
   By contrast, Pipenv explicitly avoids making the assumption that the application
   being worked on will support distribution as a ``pip``-installable Python package.
+* `uv `__ for a single tool that covers the entire project
+  management workflow, including dependency management, packaging, and publishing.
\ No newline at end of file

From 4bd633068206553f8d14375223eb261b2856ac0a Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 18 Jul 2025 06:59:04 +0000
Subject: [PATCH 637/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/shared/build-backend-tabs.rst       | 2 +-
 source/tutorials/managing-dependencies.rst | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index a4c49a3b4..2c58654a8 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -39,4 +39,4 @@
 
         [build-system]
         requires = ["uv_build >= 0.8.0, <0.9.0"]
-        build-backend = "uv_build"
\ No newline at end of file
+        build-backend = "uv_build"
diff --git a/source/tutorials/managing-dependencies.rst b/source/tutorials/managing-dependencies.rst
index da12d8a91..bb67a60e3 100644
--- a/source/tutorials/managing-dependencies.rst
+++ b/source/tutorials/managing-dependencies.rst
@@ -178,4 +178,4 @@ and techniques, listed in alphabetical order, to see if one of them is a better
   By contrast, Pipenv explicitly avoids making the assumption that the application
   being worked on will support distribution as a ``pip``-installable Python package.
 * `uv `__ for a single tool that covers the entire project
-  management workflow, including dependency management, packaging, and publishing.
\ No newline at end of file
+  management workflow, including dependency management, packaging, and publishing.

From f57c5bf67535b018d93d1e970352110f0774293d Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Fri, 18 Jul 2025 09:04:49 +0200
Subject: [PATCH 638/733] Use first version that supported PEP 639

---
 source/shared/build-backend-tabs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index 2c58654a8..608fcaddd 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -38,5 +38,5 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["uv_build >= 0.8.0, <0.9.0"]
+        requires = ["uv_build >= 0.7.19, <0.9.0"]
         build-backend = "uv_build"

From 9cbbdbce133316d11272545ae8bf8394fc17cbfe Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Tue, 22 Jul 2025 13:40:55 +0200
Subject: [PATCH 639/733] Ignore linkcheck for ATLAS URL

---
 source/conf.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/source/conf.py b/source/conf.py
index 7a05613ea..21cac0e9b 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -147,6 +147,7 @@
     "https://anaconda.org",
     "https://www.cisa.gov/sbom",
     "https://developers.redhat.com/products/softwarecollections/overview",
+    "https://math-atlas.sourceforge.net/",
 ]
 linkcheck_retries = 5
 # Ignore anchors for common targets when we know they likely won't be found

From 7f675d8e701ce55924a0f8eb9f7dc995b92018e7 Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Tue, 22 Jul 2025 13:53:44 +0200
Subject: [PATCH 640/733] Fix regex

---
 source/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/conf.py b/source/conf.py
index 21cac0e9b..2995ce190 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -147,7 +147,7 @@
     "https://anaconda.org",
     "https://www.cisa.gov/sbom",
     "https://developers.redhat.com/products/softwarecollections/overview",
-    "https://math-atlas.sourceforge.net/",
+    "https://math-atlas\\.sourceforge\\.net/?",
 ]
 linkcheck_retries = 5
 # Ignore anchors for common targets when we know they likely won't be found

From fa92ece30c88874efb4611e0e679a08ad7c174e1 Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Tue, 22 Jul 2025 15:24:05 +0200
Subject: [PATCH 641/733] Quick sanity check

---
 source/guides/installing-scientific-packages.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst
index a1aeae567..152a8350c 100644
--- a/source/guides/installing-scientific-packages.rst
+++ b/source/guides/installing-scientific-packages.rst
@@ -19,8 +19,7 @@ of different levels of vectorized instructions available in modern CPUs.
 Starting with version 1.10.4 of NumPy and version 1.0.0 of SciPy, pre-built
 32-bit and 64-bit binaries in the ``wheel`` format are available for all major
 operating systems (Windows, macOS, and Linux) on PyPI. Note, however, that on
-Windows, NumPy binaries are linked against the `ATLAS
-`__ BLAS/LAPACK library, restricted to SSE2
+Windows, NumPy binaries are linked against the ATLAS BLAS/LAPACK library, restricted to SSE2
 instructions, so they may not provide optimal linear algebra performance.
 
 There are a number of alternative options for obtaining scientific Python

From 0fcbcccf4c1e6253cfa1221914e5da79e6a850f9 Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Tue, 22 Jul 2025 15:30:48 +0200
Subject: [PATCH 642/733] Verbose

---
 noxfile.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/noxfile.py b/noxfile.py
index 698e82f9d..de3106445 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -87,6 +87,7 @@ def linkcheck(session):
         "-n",
         "-W",
         "--keep-going",  # be strict
+        "-vvv",
         "source",  # where the rst files are located
         "build",  # where to put the check output
     )

From 403e8ac53f06daf832dd35a5d6b1c994ca1b6964 Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Tue, 22 Jul 2025 15:35:06 +0200
Subject: [PATCH 643/733] Revert "Quick sanity check"

This reverts commit fa92ece30c88874efb4611e0e679a08ad7c174e1.
---
 noxfile.py                                       | 1 -
 source/guides/installing-scientific-packages.rst | 3 ++-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/noxfile.py b/noxfile.py
index de3106445..698e82f9d 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -87,7 +87,6 @@ def linkcheck(session):
         "-n",
         "-W",
         "--keep-going",  # be strict
-        "-vvv",
         "source",  # where the rst files are located
         "build",  # where to put the check output
     )
diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst
index 152a8350c..a1aeae567 100644
--- a/source/guides/installing-scientific-packages.rst
+++ b/source/guides/installing-scientific-packages.rst
@@ -19,7 +19,8 @@ of different levels of vectorized instructions available in modern CPUs.
 Starting with version 1.10.4 of NumPy and version 1.0.0 of SciPy, pre-built
 32-bit and 64-bit binaries in the ``wheel`` format are available for all major
 operating systems (Windows, macOS, and Linux) on PyPI. Note, however, that on
-Windows, NumPy binaries are linked against the ATLAS BLAS/LAPACK library, restricted to SSE2
+Windows, NumPy binaries are linked against the `ATLAS
+`__ BLAS/LAPACK library, restricted to SSE2
 instructions, so they may not provide optimal linear algebra performance.
 
 There are a number of alternative options for obtaining scientific Python

From b9bb306c0069088f5f7bc18839e94f64ab71daed Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Tue, 22 Jul 2025 15:45:31 +0200
Subject: [PATCH 644/733] Fix ignores

---
 source/conf.py | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index 2995ce190..5e79a80fe 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -132,28 +132,32 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
 
 linkcheck_ignore = [
-    "http://localhost:\\d+",
-    "https://packaging.python.org/en/latest/specifications/schemas/.*",
-    "https://test.pypi.org/project/example-package-YOUR-USERNAME-HERE",
-    "https://pypi.org/manage/*",
-    "https://test.pypi.org/manage/*",
+    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/.*",
     # Temporarily ignored. Ref:
     # https://github.com/pypa/packaging.python.org/pull/1308#issuecomment-1775347690
-    "https://www.breezy-vcs.org/*",
+    r"https://www.breezy-vcs.org/.*",
     # Ignore while StackOverflow is blocking GitHub CI. Ref:
     # https://github.com/pypa/packaging.python.org/pull/1474
-    "https://stackoverflow.com/*",
-    "https://pyscaffold.org/*",
-    "https://anaconda.org",
-    "https://www.cisa.gov/sbom",
-    "https://developers.redhat.com/products/softwarecollections/overview",
-    "https://math-atlas\\.sourceforge\\.net/?",
+    r"https://stackoverflow.com/.*",
+    r"https://pyscaffold.org/.*",
+    r"https://anaconda.org",
+    r"https://www.cisa.gov/sbom",
+    r"https://developers.redhat.com/products/softwarecollections/overview",
+    r"https://math-atlas\.sourceforge\.net/?",
+    # Self-signed certificate, fails in CI
+    r"https://click\.palletsprojects\.com/.*",
+    r"https://typer\.tiangolo\.com/.*",
 ]
 linkcheck_retries = 5
 # Ignore anchors for common targets when we know they likely won't be found
 linkcheck_anchors_ignore_for_url = [
     # GitHub synthesises anchors in JavaScript, so Sphinx can't find them in the HTML
     r"https://github\.com/",
+    r"https://docs\.github\.com/",
     # While PyPI has its botscraping defenses active, Sphinx can't resolve the anchors
     # https://github.com/pypa/packaging.python.org/issues/1744
     r"https://pypi\.org/",

From 403649c5f0892f0b74e291a3dcd3338cf8e1c022 Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Tue, 22 Jul 2025 15:46:48 +0200
Subject: [PATCH 645/733] Fix regexes

---
 source/conf.py | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index 5e79a80fe..5a7e43e91 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -133,20 +133,20 @@
 
 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/.*",
+    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/.*",
     # Temporarily ignored. Ref:
     # https://github.com/pypa/packaging.python.org/pull/1308#issuecomment-1775347690
-    r"https://www.breezy-vcs.org/.*",
+    r"https://www\.breezy-vcs\.org/.*",
     # Ignore while StackOverflow is blocking GitHub CI. Ref:
     # https://github.com/pypa/packaging.python.org/pull/1474
-    r"https://stackoverflow.com/.*",
-    r"https://pyscaffold.org/.*",
-    r"https://anaconda.org",
-    r"https://www.cisa.gov/sbom",
-    r"https://developers.redhat.com/products/softwarecollections/overview",
+    r"https://stackoverflow\.com/.*",
+    r"https://pyscaffold\.org/.*",
+    r"https://anaconda\.org",
+    r"https://www\.cisa\.gov/sbom",
+    r"https://developers\.redhat\.com/products/softwarecollections/overview",
     r"https://math-atlas\.sourceforge\.net/?",
     # Self-signed certificate, fails in CI
     r"https://click\.palletsprojects\.com/.*",

From 2fb1f527789c65d558ae20bb6708887e134aed2f Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Tue, 22 Jul 2025 14:34:01 -0400
Subject: [PATCH 646/733] add an example project-status-reason

---
 source/specifications/simple-repository-api.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
index afc932e4e..f9a32bc78 100644
--- a/source/specifications/simple-repository-api.rst
+++ b/source/specifications/simple-repository-api.rst
@@ -20,7 +20,7 @@ retrieving packages from an index server comes in two forms:
 Base API
 ========
 
-A repository that implements the simple API is defined by its base URL, this is
+A repository that implements the simple API is defined by its base URL. This is
 the top level URL that all additional URLs are below. The API is named the
 "simple" repository due to the fact that PyPI's base URL is
 ``https://pypi.org/simple/``.
@@ -636,7 +636,8 @@ As an example:
     {
       "meta": {
         "api-version": "1.4",
-        "project-status": "active"
+        "project-status": "active",
+        "project-status-reason": "this project is not yet haunted"
       },
       "name": "holygrail",
       "files": [

From 3a66caf08a8668aff7c43a50dd756079bf79b7b0 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Thu, 24 Jul 2025 17:12:43 -0400
Subject: [PATCH 647/733] Update
 source/specifications/simple-repository-api.rst

Co-authored-by: Alyssa Coghlan 
---
 source/specifications/simple-repository-api.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
index f9a32bc78..4f5bb0043 100644
--- a/source/specifications/simple-repository-api.rst
+++ b/source/specifications/simple-repository-api.rst
@@ -1026,3 +1026,4 @@ History
   from a package, in :pep:`714`
 * November 2024: provenance metadata in the HTML and JSON formats, in :pep:`740`
 * July 2025: project status markers in the HTML and JSON formats, in :pep:`792`
+* July 2025: layout changes (dedicated page for file yanking, introduce concepts before API details)

From 8f7b5a833a30ea541dcfd4db7b7d42e5533cc535 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Thu, 24 Jul 2025 17:23:54 -0400
Subject: [PATCH 648/733] fix broken anchor

---
 ...stribution-releases-using-github-actions-ci-cd-workflows.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
index 1ee562cf7..e9f601e03 100644
--- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
+++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
@@ -75,7 +75,7 @@ Let's begin! 🚀
 
    .. attention::
 
-      For security reasons, you must require `manual approval `_
+      For security reasons, you must require `manual approval `_
       on each run for the ``pypi`` environment.
 
 

From 79f33bd76d31f4312faa5ab8464121651dc9c3e9 Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Thu, 31 Jul 2025 10:11:17 +0200
Subject: [PATCH 649/733] Revert unrelated changes

---
 source/conf.py | 24 +++++++++++-------------
 1 file changed, 11 insertions(+), 13 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index 5a7e43e91..8b20a28b3 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -132,23 +132,22 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
 
 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/.*",
+    "http://localhost:\\d+",
+    "https://packaging.python.org/en/latest/specifications/schemas/.*",
+    "https://test.pypi.org/project/example-package-YOUR-USERNAME-HERE",
+    "https://pypi.org/manage/*",
+    "https://test.pypi.org/manage/*",
     # Temporarily ignored. Ref:
     # https://github.com/pypa/packaging.python.org/pull/1308#issuecomment-1775347690
-    r"https://www\.breezy-vcs\.org/.*",
+    "https://www.breezy-vcs.org/*",
     # Ignore while StackOverflow is blocking GitHub CI. Ref:
     # https://github.com/pypa/packaging.python.org/pull/1474
-    r"https://stackoverflow\.com/.*",
-    r"https://pyscaffold\.org/.*",
-    r"https://anaconda\.org",
-    r"https://www\.cisa\.gov/sbom",
-    r"https://developers\.redhat\.com/products/softwarecollections/overview",
+    "https://stackoverflow.com/*",
+    "https://pyscaffold.org/*",
+    "https://anaconda.org",
+    "https://www.cisa.gov/sbom",
+    "https://developers.redhat.com/products/softwarecollections/overview",
     r"https://math-atlas\.sourceforge\.net/?",
-    # Self-signed certificate, fails in CI
     r"https://click\.palletsprojects\.com/.*",
     r"https://typer\.tiangolo\.com/.*",
 ]
@@ -157,7 +156,6 @@
 linkcheck_anchors_ignore_for_url = [
     # GitHub synthesises anchors in JavaScript, so Sphinx can't find them in the HTML
     r"https://github\.com/",
-    r"https://docs\.github\.com/",
     # While PyPI has its botscraping defenses active, Sphinx can't resolve the anchors
     # https://github.com/pypa/packaging.python.org/issues/1744
     r"https://pypi\.org/",

From c44686e6759fa75cd377bae84693928fed5bb826 Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Thu, 31 Jul 2025 10:18:15 +0200
Subject: [PATCH 650/733] Add docs.github.com

---
 source/conf.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/source/conf.py b/source/conf.py
index 8b20a28b3..961e2e0a6 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -156,6 +156,7 @@
 linkcheck_anchors_ignore_for_url = [
     # GitHub synthesises anchors in JavaScript, so Sphinx can't find them in the HTML
     r"https://github\.com/",
+    r"https://docs\.github\.com/",
     # While PyPI has its botscraping defenses active, Sphinx can't resolve the anchors
     # https://github.com/pypa/packaging.python.org/issues/1744
     r"https://pypi\.org/",

From 6e2333a3b3bec72a63789f10455c27a9e5c69c4d Mon Sep 17 00:00:00 2001
From: Clemens Brunner 
Date: Thu, 31 Jul 2025 14:58:34 +0200
Subject: [PATCH 651/733] Convert linkcheck_ignore entries to regexes

---
 source/conf.py | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index 961e2e0a6..4c6d8bea4 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -132,21 +132,21 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
 
 linkcheck_ignore = [
-    "http://localhost:\\d+",
-    "https://packaging.python.org/en/latest/specifications/schemas/.*",
-    "https://test.pypi.org/project/example-package-YOUR-USERNAME-HERE",
-    "https://pypi.org/manage/*",
-    "https://test.pypi.org/manage/*",
+    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/.*",
     # Temporarily ignored. Ref:
     # https://github.com/pypa/packaging.python.org/pull/1308#issuecomment-1775347690
-    "https://www.breezy-vcs.org/*",
+    r"https://www\.breezy-vcs\.org/.*",
     # Ignore while StackOverflow is blocking GitHub CI. Ref:
     # https://github.com/pypa/packaging.python.org/pull/1474
-    "https://stackoverflow.com/*",
-    "https://pyscaffold.org/*",
-    "https://anaconda.org",
-    "https://www.cisa.gov/sbom",
-    "https://developers.redhat.com/products/softwarecollections/overview",
+    r"https://stackoverflow\.com/.*",
+    r"https://pyscaffold\.org/.*",
+    r"https://anaconda\.org",
+    r"https://www\.cisa\.gov/sbom",
+    r"https://developers\.redhat\.com/products/softwarecollections/overview",
     r"https://math-atlas\.sourceforge\.net/?",
     r"https://click\.palletsprojects\.com/.*",
     r"https://typer\.tiangolo\.com/.*",

From 1c6736c7aefb0086b1ded32676732ad0b1072e02 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edgar=20Ram=C3=ADrez=20Mondrag=C3=B3n?=
 
Date: Sun, 3 Aug 2025 18:56:00 -0600
Subject: [PATCH 652/733] Host PyPA spec schemas in packaging.python.org/

---
 source/conf.py                                |   4 -
 source/specifications/build-details/v1.0.rst  |   2 +-
 .../direct-url-data-structure.rst             | 117 +-----
 source/specifications/index.rst               |   1 +
 .../schemas/build-details-v1.0.schema.json    |   0
 .../schemas/direct-url.schema.json            |  99 +++++
 source/specifications/schemas/index.rst       |   8 +
 .../specifications/schemas/pylock.schema.json | 345 ++++++++++++++++++
 8 files changed, 455 insertions(+), 121 deletions(-)
 rename {extra => source}/specifications/schemas/build-details-v1.0.schema.json (100%)
 create mode 100644 source/specifications/schemas/direct-url.schema.json
 create mode 100644 source/specifications/schemas/index.rst
 create mode 100644 source/specifications/schemas/pylock.schema.json

diff --git a/source/conf.py b/source/conf.py
index 4c6d8bea4..a8a040d6c 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -83,10 +83,6 @@
     # https://plausible.io/packaging.python.org
     html_js_files.extend(_metrics_js_files)
 
-html_extra_path = [
-    "../extra",
-]
-
 # -- Options for HTML help output ------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-help-output
 
diff --git a/source/specifications/build-details/v1.0.rst b/source/specifications/build-details/v1.0.rst
index 3a8cfe277..cfe902e1e 100644
--- a/source/specifications/build-details/v1.0.rst
+++ b/source/specifications/build-details/v1.0.rst
@@ -8,7 +8,7 @@
 Specification
 -------------
 
-.. jsonschema:: ../../../extra/specifications/schemas/build-details-v1.0.schema.json
+.. jsonschema:: ../schemas/build-details-v1.0.schema.json
     :lift_title: false
 
 
diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index 0d243652d..5f3af0fae 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -236,122 +236,7 @@ JSON Schema
 
 The following JSON Schema can be used to validate the contents of ``direct_url.json``:
 
-.. code-block::
-
-     {
-       "$schema": "https://json-schema.org/draft/2019-09/schema",
-       "title": "Direct URL Data",
-       "description": "Data structure that can represent URLs to python projects and distribution artifacts such as VCS source trees, local source trees, source distributions and wheels.",
-       "definitions": {
-         "URL": {
-           "type": "string",
-           "format": "uri"
-         },
-         "DirInfo": {
-           "type": "object",
-           "properties": {
-             "editable": {
-               "type": ["boolean", "null"]
-             }
-           }
-         },
-         "VCSInfo": {
-           "type": "object",
-           "properties": {
-             "vcs": {
-               "type": "string",
-               "enum": [
-                 "git",
-                 "hg",
-                 "bzr",
-                 "svn"
-               ]
-             },
-             "requested_revision": {
-               "type": "string"
-             },
-             "commit_id": {
-               "type": "string"
-             },
-             "resolved_revision": {
-               "type": "string"
-             }
-           },
-           "required": [
-             "vcs",
-             "commit_id"
-           ]
-         },
-         "ArchiveInfo": {
-           "type": "object",
-           "properties": {
-             "hash": {
-               "type": "string",
-               "pattern": "^\\w+=[a-f0-9]+$",
-               "deprecated": true
-             },
-             "hashes": {
-               "type": "object",
-               "patternProperties": {
-                 "^[a-f0-9]+$": {
-                   "type": "string"
-                 }
-               }
-             }
-           }
-         }
-       },
-       "allOf": [
-         {
-           "type": "object",
-           "properties": {
-             "url": {
-               "$ref": "#/definitions/URL"
-             }
-           },
-           "required": [
-             "url"
-           ]
-         },
-         {
-           "anyOf": [
-             {
-               "type": "object",
-               "properties": {
-                 "dir_info": {
-                   "$ref": "#/definitions/DirInfo"
-                 }
-               },
-               "required": [
-                 "dir_info"
-               ]
-             },
-             {
-               "type": "object",
-               "properties": {
-                 "vcs_info": {
-                   "$ref": "#/definitions/VCSInfo"
-                 }
-               },
-               "required": [
-                 "vcs_info"
-               ]
-             },
-             {
-               "type": "object",
-               "properties": {
-                 "archive_info": {
-                   "$ref": "#/definitions/ArchiveInfo"
-                 }
-               },
-               "required": [
-                 "archive_info"
-               ]
-             }
-           ]
-         }
-       ]
-     }
+.. literalinclude:: schemas/direct-url.schema.json
 
 Examples
 ========
diff --git a/source/specifications/index.rst b/source/specifications/index.rst
index 68d95ab98..c375654a2 100644
--- a/source/specifications/index.rst
+++ b/source/specifications/index.rst
@@ -17,3 +17,4 @@ and for proposing new ones, is documented on
    section-package-indices
    section-python-description-formats
    section-reproducible-environments
+   schemas/index.rst
diff --git a/extra/specifications/schemas/build-details-v1.0.schema.json b/source/specifications/schemas/build-details-v1.0.schema.json
similarity index 100%
rename from extra/specifications/schemas/build-details-v1.0.schema.json
rename to source/specifications/schemas/build-details-v1.0.schema.json
diff --git a/source/specifications/schemas/direct-url.schema.json b/source/specifications/schemas/direct-url.schema.json
new file mode 100644
index 000000000..d1f4c860a
--- /dev/null
+++ b/source/specifications/schemas/direct-url.schema.json
@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "$id": "https://packaging.python.org/en/latest/specifications/schemas/direct-url.schema.json",
+  "title": "Direct URL Data",
+  "description": "Data structure that can represent URLs to python projects and distribution artifacts such as VCS source trees, local source trees, source distributions and wheels.",
+  "definitions": {
+    "url": {
+      "type": "string",
+      "format": "uri"
+    },
+    "DirInfo": {
+      "type": "object",
+      "properties": {
+        "editable": {
+          "type": ["boolean", "null"]
+        }
+      }
+    },
+    "VCSInfo": {
+      "type": "object",
+      "properties": {
+        "vcs": {
+          "type": "string",
+          "enum": ["git", "hg", "bzr", "svn"]
+        },
+        "requested_revision": {
+          "type": "string"
+        },
+        "commit_id": {
+          "type": "string"
+        },
+        "resolved_revision": {
+          "type": "string"
+        }
+      },
+      "required": ["vcs", "commit_id"]
+    },
+    "ArchiveInfo": {
+      "type": "object",
+      "properties": {
+        "hash": {
+          "type": "string",
+          "pattern": "^\\w+=[a-f0-9]+$",
+          "deprecated": true
+        },
+        "hashes": {
+          "type": "object",
+          "patternProperties": {
+            "^[a-f0-9]+$": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "type": "object",
+      "properties": {
+        "url": {
+          "$ref": "#/definitions/url"
+        }
+      },
+      "required": ["url"]
+    },
+    {
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "dir_info": {
+              "$ref": "#/definitions/DirInfo"
+            }
+          },
+          "required": ["dir_info"]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "vcs_info": {
+              "$ref": "#/definitions/VCSInfo"
+            }
+          },
+          "required": ["vcs_info"]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "archive_info": {
+              "$ref": "#/definitions/ArchiveInfo"
+            }
+          },
+          "required": ["archive_info"]
+        }
+      ]
+    }
+  ]
+}
diff --git a/source/specifications/schemas/index.rst b/source/specifications/schemas/index.rst
new file mode 100644
index 000000000..a80891975
--- /dev/null
+++ b/source/specifications/schemas/index.rst
@@ -0,0 +1,8 @@
+.. _`packaging-schemas`:
+
+PyPA schemas
+############
+
+- `direct_url.json `_
+- `build-details.json `_
+- `pylock.toml `_
diff --git a/source/specifications/schemas/pylock.schema.json b/source/specifications/schemas/pylock.schema.json
new file mode 100644
index 000000000..5469111ec
--- /dev/null
+++ b/source/specifications/schemas/pylock.schema.json
@@ -0,0 +1,345 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://json.schemastore.org/pylock.json",
+  "additionalProperties": false,
+  "definitions": {
+    "tool": {
+      "type": "object",
+      "markdownDescription": "Similar usage as that of the `[tool]` table from the [pyproject.toml specification](https://packaging.python.org/en/latest/specifications/pyproject-toml/#pyproject-toml-spec), but at the package version level instead of at the lock file level (which is also available via `[tool]`).",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    },
+    "url": {
+      "type": "string",
+      "markdownDescription": "The URL to the source tree."
+    },
+    "path": {
+      "type": "string",
+      "markdownDescription": "The path to the local directory of the source tree."
+    },
+    "upload-time": {
+      "markdownDescription": "The time the file was uploaded (UTC). Must be specified as a datetime literal."
+    },
+    "size": {
+      "type": "integer",
+      "markdownDescription": "The size of the archive file."
+    },
+    "hashes": {
+      "type": "object",
+      "description": "Known hash values of the file where the key is the hash algorithm and the value is the hash value.",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "subdirectory": {
+      "type": "string",
+      "markdownDescription": "The subdirectory within the [source tree](https://packaging.python.org/en/latest/specifications/source-distribution-format/#source-distribution-format-source-tree) where the project root of the project is (e.g. the location of the `pyproject.toml` file)."
+    },
+    "vcs": {
+      "type": "object",
+      "markdownDescription": "Record the version control system details for the [source tree](https://packaging.python.org/en/latest/specifications/source-distribution-format/#source-distribution-format-source-tree) it contains.",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "markdownDescription": "The type of version control system used."
+        },
+        "url": {
+          "$ref": "#/definitions/url"
+        },
+        "path": {
+          "$ref": "#/definitions/path"
+        },
+        "requested-revision": {
+          "type": "string",
+          "markdownDescription": "The branch/tag/ref/commit/revision/etc. that the user requested."
+        },
+        "commit-id": {
+          "type": "string",
+          "markdownDescription": "The exact commit/revision number that is to be installed."
+        },
+        "subdirectory": {
+          "$ref": "#/definitions/subdirectory"
+        }
+      }
+    },
+    "directory": {
+      "type": "object",
+      "markdownDescription": "Record the local directory details for the [source tree](https://packaging.python.org/en/latest/specifications/source-distribution-format/#source-distribution-format-source-tree) it contains.",
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "markdownDescription": "The local directory where the source tree is."
+        },
+        "editable": {
+          "type": "boolean",
+          "default": false,
+          "markdownDescription": "A flag representing whether the source tree was an editable install at lock time."
+        },
+        "subdirectory": {
+          "$ref": "#/definitions/subdirectory"
+        }
+      }
+    },
+    "archive": {
+      "type": "object",
+      "additionalProperties": false,
+      "markdownDescription": "A direct reference to an archive file to install from (this can include wheels and sdists, as well as other archive formats containing a source tree).",
+      "properties": {
+        "url": {
+          "$ref": "#/definitions/url"
+        },
+        "path": {
+          "$ref": "#/definitions/path"
+        },
+        "size": {
+          "$ref": "#/definitions/size"
+        },
+        "upload-time": {
+          "$ref": "#/definitions/upload-time"
+        },
+        "hashes": {
+          "$ref": "#/definitions/hashes"
+        },
+        "subdirectory": {
+          "$ref": "#/definitions/subdirectory"
+        }
+      }
+    },
+    "sdist": {
+      "type": "object",
+      "additionalProperties": false,
+      "markdownDescription": "Details of a [source distribution file name](https://packaging.python.org/en/latest/specifications/source-distribution-format/#source-distribution-format-sdist) for the package.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "markdownDescription": "The file name of the [source distribution file name](https://packaging.python.org/en/latest/specifications/source-distribution-format/#source-distribution-format-sdist) file."
+        },
+        "upload-time": {
+          "$ref": "#/definitions/upload-time"
+        },
+        "url": {
+          "$ref": "#/definitions/url"
+        },
+        "path": {
+          "$ref": "#/definitions/path"
+        },
+        "size": {
+          "$ref": "#/definitions/size"
+        },
+        "hashes": {
+          "$ref": "#/definitions/hashes"
+        }
+      }
+    },
+    "wheels": {
+      "type": "array",
+      "markdownDescription": "For recording the wheel files as specified by [Binary distribution format](https://packaging.python.org/en/latest/specifications/binary-distribution-format/#binary-distribution-format) for the package.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "markdownDescription": "The file name of the [Binary distribution format](https://packaging.python.org/en/latest/specifications/binary-distribution-format/#binary-distribution-format) file."
+          },
+          "upload-time": {
+            "$ref": "#/definitions/upload-time"
+          },
+          "url": {
+            "$ref": "#/definitions/url"
+          },
+          "path": {
+            "$ref": "#/definitions/path"
+          },
+          "size": {
+            "$ref": "#/definitions/size"
+          },
+          "hashes": {
+            "$ref": "#/definitions/hashes"
+          }
+        }
+      }
+    },
+    "1.0": {
+      "required": ["lock-version", "created-by", "packages"],
+      "properties": {
+        "lock-version": {
+          "type": "string",
+          "enum": ["1.0"],
+          "description": "Record the file format version that the file adheres to."
+        },
+        "environments": {
+          "type": "array",
+          "markdownDescription": "A list of [environment markers](https://packaging.python.org/en/latest/specifications/dependency-specifiers/#dependency-specifiers-environment-markers) for which the lock file is considered compatible with.",
+          "items": {
+            "type": "string",
+            "description": "Environment marker"
+          }
+        },
+        "requires-python": {
+          "type": "string",
+          "markdownDescription": "Specifies the [Requires-Python](https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata-requires-python) for the minimum Python version compatible for any environment supported by the lock file (i.e. the minimum viable Python version for the lock file)."
+        },
+        "extras": {
+          "type": "array",
+          "markdownDescription": "The list of [extras](https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata-provides-extra) supported by this lock file.",
+          "default": [],
+          "items": {
+            "type": "string",
+            "description": "Extra name"
+          }
+        },
+        "dependency-groups": {
+          "type": "array",
+          "markdownDescription": "The list of [dependency groups](https://packaging.python.org/en/latest/specifications/dependency-groups/#dependency-groups) publicly supported by this lock file (i.e. dependency groups users are expected to be able to specify via a tool’s UI).",
+          "default": [],
+          "items": {
+            "type": "string",
+            "description": "Dependency group name"
+          }
+        },
+        "default-groups": {
+          "type": "array",
+          "markdownDescription": "The name of synthetic dependency groups to represent what should be installed by default (e.g. what `project.dependencies` implicitly represents).",
+          "default": [],
+          "items": {
+            "type": "string",
+            "description": "Dependency group name"
+          }
+        },
+        "created-by": {
+          "type": "string",
+          "markdownDescription": "Records the name of the tool used to create the lock file."
+        },
+        "packages": {
+          "type": "array",
+          "markdownDescription": "An array containing all packages that may be installed.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name"],
+            "allOf": [
+              {
+                "if": {
+                  "required": ["vcs"]
+                },
+                "then": {
+                  "not": {
+                    "required": ["directory", "archive", "sdist", "wheels"]
+                  }
+                }
+              },
+              {
+                "if": {
+                  "required": ["directory"]
+                },
+                "then": {
+                  "not": {
+                    "required": ["vcs", "archive", "sdist", "wheels"]
+                  }
+                }
+              },
+              {
+                "if": {
+                  "required": ["sdist"]
+                },
+                "then": {
+                  "not": {
+                    "required": ["vcs", "directory", "archive"]
+                  }
+                }
+              },
+              {
+                "if": {
+                  "required": ["wheels"]
+                },
+                "then": {
+                  "not": {
+                    "required": ["vcs", "directory", "archive"]
+                  }
+                }
+              }
+            ],
+            "properties": {
+              "name": {
+                "type": "string",
+                "markdownDescription": "The name of the package, [normalized](https://packaging.python.org/en/latest/specifications/name-normalization/#name-normalization)."
+              },
+              "version": {
+                "type": "string",
+                "description": "The version of the package."
+              },
+              "marker": {
+                "type": "string",
+                "markdownDescription": "The [environment marker](https://packaging.python.org/en/latest/specifications/dependency-specifiers/#dependency-specifiers-environment-markers) which specify when the package should be installed."
+              },
+              "requires-python": {
+                "type": "string",
+                "markdownDescription": "Holds the [version specifiers](https://packaging.python.org/en/latest/specifications/version-specifiers/#version-specifiers) for Python version compatibility for the package."
+              },
+              "dependencies": {
+                "type": "array",
+                "markdownDescription": "Records the other entries in `[[packages]]` which are direct dependencies of this package.",
+                "items": {
+                  "type": "object",
+                  "markdownDescription": "A table which contains the minimum information required to tell which other package entry it corresponds to where doing a key-by-key comparison would find the appropriate package with no ambiguity (e.g. if there are two entries for the `spam` package, then you can include the version number like `{name = \"spam\", version = \"1.0.0\"}`, or by source like `{name = \"spam\", vcs = { url = \"...\"}`).",
+                  "additionalProperties": true
+                }
+              },
+              "vcs": {
+                "$ref": "#/definitions/vcs"
+              },
+              "directory": {
+                "$ref": "#/definitions/directory"
+              },
+              "archive": {
+                "$ref": "#/definitions/archive"
+              },
+              "index": {
+                "type": "string",
+                "markdownDescription": "The base URL for the package index from [simple repository API](https://packaging.python.org/en/latest/specifications/simple-repository-api/#simple-repository-api) where the sdist and/or wheels were found (e.g. `https://pypi.org/simple/`)."
+              },
+              "sdist": {
+                "$ref": "#/definitions/sdist"
+              },
+              "wheels": {
+                "$ref": "#/definitions/wheels"
+              },
+              "attestation-identities": {
+                "type": "array",
+                "markdownDescription": "A recording of the attestations for any file recorded for this package.",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind"],
+                  "properties": {
+                    "kind": {
+                      "type": "string",
+                      "markdownDescription": "The unique identity of the Trusted Publisher."
+                    }
+                  }
+                }
+              },
+              "tool": {
+                "$ref": "#/definitions/tool"
+              }
+            }
+          }
+        },
+        "tool": {
+          "$ref": "#/definitions/tool"
+        }
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "$ref": "#/definitions/1.0"
+    }
+  ],
+  "type": "object"
+}

From afab730d8ebff66e79ec03527d3628544d17eaac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edgar=20Ram=C3=ADrez=20Mondrag=C3=B3n?=
 
Date: Sun, 3 Aug 2025 19:16:39 -0600
Subject: [PATCH 653/733] Fix broken setuptools-scm link

---
 source/discussions/setup-py-deprecated.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/setup-py-deprecated.rst b/source/discussions/setup-py-deprecated.rst
index 6bcd15b58..dbea4ed52 100644
--- a/source/discussions/setup-py-deprecated.rst
+++ b/source/discussions/setup-py-deprecated.rst
@@ -115,7 +115,7 @@ A possible replacement solution (among others) is to rely on setuptools-scm_:
 
 * ``python -m setuptools_scm``
 
-.. _setuptools-scm: https://setuptools-scm.readthedocs.io/en/latest/usage/#as-cli-tool
+.. _setuptools-scm: https://setuptools-scm.readthedocs.io/en/latest/usage.html#as-cli-tool
 
 
 Remaining commands

From daeac9dcd39f9bc3f7dcf44397b4912cd7d8559d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edgar=20Ram=C3=ADrez=20Mondrag=C3=B3n?=
 
Date: Wed, 6 Aug 2025 12:56:12 -0600
Subject: [PATCH 654/733] Update source/discussions/setup-py-deprecated.rst

Co-authored-by: Alyssa Coghlan 
---
 source/discussions/setup-py-deprecated.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/discussions/setup-py-deprecated.rst b/source/discussions/setup-py-deprecated.rst
index dbea4ed52..b13ce190b 100644
--- a/source/discussions/setup-py-deprecated.rst
+++ b/source/discussions/setup-py-deprecated.rst
@@ -115,7 +115,7 @@ A possible replacement solution (among others) is to rely on setuptools-scm_:
 
 * ``python -m setuptools_scm``
 
-.. _setuptools-scm: https://setuptools-scm.readthedocs.io/en/latest/usage.html#as-cli-tool
+.. _setuptools-scm: https://setuptools-scm.readthedocs.io/en/latest/usage#as-cli-tool
 
 
 Remaining commands

From e1f29ae1486a5f55bd61359d8bdabf24da1bced3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edgar=20Ram=C3=ADrez=20Mondrag=C3=B3n?=
 
Date: Wed, 6 Aug 2025 14:04:07 -0600
Subject: [PATCH 655/733] Link to our own copy of the schema

Co-authored-by: Alyssa Coghlan 
---
 source/specifications/schemas/pylock.schema.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/schemas/pylock.schema.json b/source/specifications/schemas/pylock.schema.json
index 5469111ec..90404e33d 100644
--- a/source/specifications/schemas/pylock.schema.json
+++ b/source/specifications/schemas/pylock.schema.json
@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://json.schemastore.org/pylock.json",
+  "$id": "https://packaging.python.org/en/latest/specifications/schemas/pylock.schema.json",
   "additionalProperties": false,
   "definitions": {
     "tool": {

From 99299e312d93875fb37575732b9968a89ecfe07c Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 7 Jul 2025 18:28:30 +0000
Subject: [PATCH 656/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/codespell-project/codespell: v2.3.0 → v2.4.1](https://github.com/codespell-project/codespell/compare/v2.3.0...v2.4.1)
- [github.com/astral-sh/ruff-pre-commit: v0.7.1 → v0.12.2](https://github.com/astral-sh/ruff-pre-commit/compare/v0.7.1...v0.12.2)
---
 .pre-commit-config.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index db8b1131a..e092c419c 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -15,7 +15,7 @@ repos:
   - id: trailing-whitespace
 
 - repo: https://github.com/codespell-project/codespell
-  rev: v2.3.0
+  rev: v2.4.1
   hooks:
   - id: codespell
     args: ["-L", "ned,ist,oder", "--skip", "*.po"]
@@ -37,7 +37,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.7.1
+  rev: v0.12.2
   hooks:
     - id: ruff
     - id: ruff-format

From 00e971710a09c835a06e1268c174b720fc0aa53a Mon Sep 17 00:00:00 2001
From: Dustin Ingram 
Date: Thu, 21 Aug 2025 17:40:45 +0000
Subject: [PATCH 657/733] Correct regex for metadata 'name' format

The current regex permits strings that end in the newline character,
which is counter to what the description for the field states ("ASCII
letters and numbers, period, underscore and hyphen").

This updates the rexex to use `\Z` instead of `$` to match at the end of
the string and exclude newline characters.
---
 source/specifications/name-normalization.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/name-normalization.rst b/source/specifications/name-normalization.rst
index ba3246b63..e295a3d11 100644
--- a/source/specifications/name-normalization.rst
+++ b/source/specifications/name-normalization.rst
@@ -17,7 +17,7 @@ underscore and hyphen. It must start and end with a letter or number.
 This means that valid project names are limited to those which match the
 following regex (run with :py:data:`re.IGNORECASE`)::
 
-    ^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$
+    ^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])\Z
 
 
 .. _name-normalization:

From fb63fa51d867197d98888d7978dba10449374b67 Mon Sep 17 00:00:00 2001
From: Dustin Ingram 
Date: Thu, 21 Aug 2025 17:53:46 +0000
Subject: [PATCH 658/733] Update regex from PEP 508 as well

---
 source/specifications/dependency-specifiers.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index 06897da27..168d966d4 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -142,7 +142,7 @@ document we limit the acceptable values for identifiers to that regex. A full
 redefinition of name may take place in a future metadata PEP. The regex (run
 with re.IGNORECASE) is::
 
-    ^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$
+    ^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])\Z
 
 .. _dependency-specifiers-extras:
 

From f86255b40639f1ed962496a465d67c16d443ce7d Mon Sep 17 00:00:00 2001
From: Dustin Ingram 
Date: Thu, 21 Aug 2025 18:33:17 +0000
Subject: [PATCH 659/733] Add history blurbs

---
 source/specifications/dependency-specifiers.rst | 3 +++
 source/specifications/name-normalization.rst    | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index e1b69ff61..d9466c26e 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -526,6 +526,9 @@ History
   in use since late 2022.
 - April 2025: Added ``extras`` and ``dependency_groups`` for
   :ref:`lock-file-spec` as approved through :pep:`751`.
+- August 2025: The suggested name validation regex was fixed to match the field
+  specification (it previously finished with ``$`` instead of ``\Z``,
+  incorrectly permitting trailing newlines)
 
 
 References
diff --git a/source/specifications/name-normalization.rst b/source/specifications/name-normalization.rst
index e295a3d11..560d956b5 100644
--- a/source/specifications/name-normalization.rst
+++ b/source/specifications/name-normalization.rst
@@ -53,3 +53,6 @@ History
   :pep:`503 <503#normalized-names>`.
 - November 2015: The specification of valid names was approved through
   :pep:`508 <508#names>`.
+- August 2025: The suggested name validation regex was fixed to match the field
+  specification (it previously finished with ``$`` instead of ``\Z``,
+  incorrectly permitting trailing newlines)

From 8290c3face8bf5d6580f07bb9892bcbb9af90b37 Mon Sep 17 00:00:00 2001
From: konstin 
Date: Mon, 25 Aug 2025 18:20:46 +0200
Subject: [PATCH 660/733] Update uv_build version automatically

In https://github.com/pypa/packaging.python.org/pull/1880, the concern was raised that the uv_build upper bound in the docs will go stale. This PR adds a GitHub Actions workflow that automatically updates the version daily with the latest uv(-build) version.

I tested this change on my fork, but I unfortunately can't test this in pypa/packaging.python.org itself.
---
 .github/workflows/cron.yml         | 26 ++++++++++++++
 scripts/update_uv_build_version.py | 56 ++++++++++++++++++++++++++++++
 2 files changed, 82 insertions(+)
 create mode 100644 scripts/update_uv_build_version.py

diff --git a/.github/workflows/cron.yml b/.github/workflows/cron.yml
index 8870bb70b..6074c3fbb 100644
--- a/.github/workflows/cron.yml
+++ b/.github/workflows/cron.yml
@@ -5,10 +5,36 @@ name: Cron
 on:
   schedule:
   - cron: "0 6 * * *"  # daily at 6am
+  workflow_dispatch:
 
 jobs:
   test:
     if: github.repository_owner == 'pypa'  # suppress noise in forks
     uses: ./.github/workflows/test.yml
 
+  update-uv-build-version:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Update uv_build version
+        id: update_script
+        run: uv run scripts/update_uv_build_version.py
+      - # If there are no changes, no pull request will be created and the action exits silently.
+        name: Create Pull Request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: Update uv_build version to ${{ steps.update_script.outputs.version }}
+          title: Update uv_build version to ${{ steps.update_script.outputs.version }}
+          body: |
+            Automated update of uv_build version bounds for uv ${{ steps.update_script.outputs.version }}.
+            
+            This PR was created automatically by the cron workflow, ping `@konstin` for problems.
+          branch: bot/update-uv-build-version
+          delete-branch: true
+
 ...
diff --git a/scripts/update_uv_build_version.py b/scripts/update_uv_build_version.py
new file mode 100644
index 000000000..f71cb821a
--- /dev/null
+++ b/scripts/update_uv_build_version.py
@@ -0,0 +1,56 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#     "httpx>=0.28.1,<0.29",
+#     "packaging>=25.0",
+# ]
+# ///
+import re
+from pathlib import Path
+
+import httpx
+from packaging.utils import parse_wheel_filename
+from packaging.version import Version
+
+
+def main():
+    response = httpx.get(
+        "https://pypi.org/simple/uv-build/",
+        headers={"Accept": "application/vnd.pypi.simple.v1+json"},
+    )
+    response.raise_for_status()
+    data = response.json()
+    current_release = None
+    for file in data["files"]:
+        if not file["filename"].endswith(".whl"):
+            continue
+        _name, version, _build, _tags = parse_wheel_filename(file["filename"])
+        if version.is_prerelease:
+            continue
+        if current_release is None or version > current_release:
+            current_release = version
+
+    [major, minor, _patch] = current_release.release
+    if major != 0:
+        raise NotImplementedError("The script needs to be updated for uv 1.x")
+    upper_bound = Version(f"{major}.{minor + 1}.{0}")
+
+    repository_root = Path(__file__).parent.parent
+    existing = repository_root.joinpath("source/shared/build-backend-tabs.rst").read_text()
+    replacement = f'requires = ["uv_build >= {current_release}, <{upper_bound}"]'
+    searcher = re.compile(re.escape('requires = ["uv_build') + ".*" + re.escape('"]'))
+    if not searcher.search(existing):
+        raise RuntimeError("Could not `uv-build` entry")
+    updated = searcher.sub(replacement, existing)
+
+    if existing != updated:
+        print("Updating source/shared/build-backend-tabs.rst")
+        Path("source/shared/build-backend-tabs.rst").write_text(updated)
+        print(f"::set-output name=version::{current_release}")
+        print(f"::set-output name=updated::true")
+    else:
+        print("Already up-to-date source/shared/build-backend-tabs.rst")
+        print(f"::set-output name=updated::false")
+
+if __name__ == '__main__':
+    main()

From a23f1a2d451339755fed3e96bf70a7cb7972378e Mon Sep 17 00:00:00 2001
From: konsti 
Date: Tue, 26 Aug 2025 11:08:09 +0200
Subject: [PATCH 661/733] Update scripts/update_uv_build_version.py
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 scripts/update_uv_build_version.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/update_uv_build_version.py b/scripts/update_uv_build_version.py
index f71cb821a..02eee3434 100644
--- a/scripts/update_uv_build_version.py
+++ b/scripts/update_uv_build_version.py
@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.12"
+# requires-python = ">= 3.12"
 # dependencies = [
 #     "httpx>=0.28.1,<0.29",
 #     "packaging>=25.0",

From 7500df28a55d361c11f971c842beaf30a97995f2 Mon Sep 17 00:00:00 2001
From: konstin 
Date: Tue, 26 Aug 2025 11:12:28 +0200
Subject: [PATCH 662/733] Review

---
 .github/workflows/cron.yml                    | 27 -------------
 .github/workflows/update-uv-build-version.yml | 39 +++++++++++++++++++
 scripts/update_uv_build_version.py            | 18 ++++++---
 3 files changed, 52 insertions(+), 32 deletions(-)
 create mode 100644 .github/workflows/update-uv-build-version.yml

diff --git a/.github/workflows/cron.yml b/.github/workflows/cron.yml
index 6074c3fbb..18a63caba 100644
--- a/.github/workflows/cron.yml
+++ b/.github/workflows/cron.yml
@@ -11,30 +11,3 @@ jobs:
   test:
     if: github.repository_owner == 'pypa'  # suppress noise in forks
     uses: ./.github/workflows/test.yml
-
-  update-uv-build-version:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-    steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
-      - name: Update uv_build version
-        id: update_script
-        run: uv run scripts/update_uv_build_version.py
-      - # If there are no changes, no pull request will be created and the action exits silently.
-        name: Create Pull Request
-        uses: peter-evans/create-pull-request@v7
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          commit-message: Update uv_build version to ${{ steps.update_script.outputs.version }}
-          title: Update uv_build version to ${{ steps.update_script.outputs.version }}
-          body: |
-            Automated update of uv_build version bounds for uv ${{ steps.update_script.outputs.version }}.
-            
-            This PR was created automatically by the cron workflow, ping `@konstin` for problems.
-          branch: bot/update-uv-build-version
-          delete-branch: true
-
-...
diff --git a/.github/workflows/update-uv-build-version.yml b/.github/workflows/update-uv-build-version.yml
new file mode 100644
index 000000000..8586ecd11
--- /dev/null
+++ b/.github/workflows/update-uv-build-version.yml
@@ -0,0 +1,39 @@
+---
+
+name: Cron
+
+on:
+  schedule:
+  - cron: "0 6 * * 1"  # mondays at 6am
+  workflow_dispatch:
+
+jobs:
+  update-uv-build-version:
+    name: Update uv_build version
+    if: github.repository_owner == 'pypa'  # suppress noise in forks
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Update uv_build version
+        id: update_script
+        run: uv run scripts/update_uv_build_version.py
+      - # If there are no changes, no pull request will be created and the action exits silently.
+        name: Create Pull Request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: Update uv_build version to ${{ steps.update_script.outputs.version }}
+          title: Update uv_build version to ${{ steps.update_script.outputs.version }}
+          body: |
+            Automated update of uv_build version bounds for uv ${{ steps.update_script.outputs.version }}.
+            
+            This PR was created automatically by the cron workflow, ping `@konstin` for problems.
+          branch: bot/update-uv-build-version
+          delete-branch: true
+
+...
diff --git a/scripts/update_uv_build_version.py b/scripts/update_uv_build_version.py
index 02eee3434..8dfd90da8 100644
--- a/scripts/update_uv_build_version.py
+++ b/scripts/update_uv_build_version.py
@@ -5,6 +5,7 @@
 #     "packaging>=25.0",
 # ]
 # ///
+import os
 import re
 from pathlib import Path
 
@@ -36,7 +37,9 @@ def main():
     upper_bound = Version(f"{major}.{minor + 1}.{0}")
 
     repository_root = Path(__file__).parent.parent
-    existing = repository_root.joinpath("source/shared/build-backend-tabs.rst").read_text()
+    existing = repository_root.joinpath(
+        "source/shared/build-backend-tabs.rst"
+    ).read_text()
     replacement = f'requires = ["uv_build >= {current_release}, <{upper_bound}"]'
     searcher = re.compile(re.escape('requires = ["uv_build') + ".*" + re.escape('"]'))
     if not searcher.search(existing):
@@ -46,11 +49,16 @@ def main():
     if existing != updated:
         print("Updating source/shared/build-backend-tabs.rst")
         Path("source/shared/build-backend-tabs.rst").write_text(updated)
-        print(f"::set-output name=version::{current_release}")
-        print(f"::set-output name=updated::true")
+        if github_output := os.environ.get("GITHUB_OUTPUT"):
+            with open(github_output, "a") as f:
+                f.write(f"version={current_release}\n")
+                f.write(f"updated=true\n")
     else:
         print("Already up-to-date source/shared/build-backend-tabs.rst")
-        print(f"::set-output name=updated::false")
+        if github_output := os.environ.get("GITHUB_OUTPUT"):
+            with open(github_output, "a") as f:
+                f.write(f"updated=false\n")
 
-if __name__ == '__main__':
+
+if __name__ == "__main__":
     main()

From 77d8c71c11a55da7c26b251b4c61cb5d0d957fd7 Mon Sep 17 00:00:00 2001
From: konstin 
Date: Tue, 26 Aug 2025 11:14:06 +0200
Subject: [PATCH 663/733] Use same `actions/checkout@v4` as zizmor job

---
 .github/workflows/update-uv-build-version.yml | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/update-uv-build-version.yml b/.github/workflows/update-uv-build-version.yml
index 8586ecd11..54f5ad211 100644
--- a/.github/workflows/update-uv-build-version.yml
+++ b/.github/workflows/update-uv-build-version.yml
@@ -16,7 +16,10 @@ jobs:
       contents: write
       pull-requests: write
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - name: Set up uv
         uses: astral-sh/setup-uv@v5
       - name: Update uv_build version

From 7df08f4ed3a9788801c99635de0ef276389c64cd Mon Sep 17 00:00:00 2001
From: konstin 
Date: Tue, 26 Aug 2025 11:17:32 +0200
Subject: [PATCH 664/733] Linters

---
 .github/workflows/update-uv-build-version.yml | 2 +-
 scripts/update_uv_build_version.py            | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/update-uv-build-version.yml b/.github/workflows/update-uv-build-version.yml
index 54f5ad211..184497047 100644
--- a/.github/workflows/update-uv-build-version.yml
+++ b/.github/workflows/update-uv-build-version.yml
@@ -34,7 +34,7 @@ jobs:
           title: Update uv_build version to ${{ steps.update_script.outputs.version }}
           body: |
             Automated update of uv_build version bounds for uv ${{ steps.update_script.outputs.version }}.
-            
+
             This PR was created automatically by the cron workflow, ping `@konstin` for problems.
           branch: bot/update-uv-build-version
           delete-branch: true
diff --git a/scripts/update_uv_build_version.py b/scripts/update_uv_build_version.py
index 8dfd90da8..816ab9061 100644
--- a/scripts/update_uv_build_version.py
+++ b/scripts/update_uv_build_version.py
@@ -52,12 +52,12 @@ def main():
         if github_output := os.environ.get("GITHUB_OUTPUT"):
             with open(github_output, "a") as f:
                 f.write(f"version={current_release}\n")
-                f.write(f"updated=true\n")
+                f.write("updated=true\n")
     else:
         print("Already up-to-date source/shared/build-backend-tabs.rst")
         if github_output := os.environ.get("GITHUB_OUTPUT"):
             with open(github_output, "a") as f:
-                f.write(f"updated=false\n")
+                f.write("updated=false\n")
 
 
 if __name__ == "__main__":

From 64977629a37b34ab04876706069a88846134cf26 Mon Sep 17 00:00:00 2001
From: konstin 
Date: Tue, 26 Aug 2025 11:18:25 +0200
Subject: [PATCH 665/733] Undo accidental cosmetic change

---
 .github/workflows/cron.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/cron.yml b/.github/workflows/cron.yml
index 18a63caba..f1eddccb5 100644
--- a/.github/workflows/cron.yml
+++ b/.github/workflows/cron.yml
@@ -11,3 +11,5 @@ jobs:
   test:
     if: github.repository_owner == 'pypa'  # suppress noise in forks
     uses: ./.github/workflows/test.yml
+
+...

From d22b3b9fa10380eb7488986586fb2199719cf3b6 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Tue, 26 Aug 2025 15:07:30 -0700
Subject: [PATCH 666/733] Clarify that the ``License-Expression`` field applies
 to the containing distribution file, not the project itself

---
 source/specifications/core-metadata.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 550c6e55a..379805df5 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -473,6 +473,9 @@ Text string that is a valid SPDX
 :term:`license expression `,
 as specified in :doc:`/specifications/license-expression`.
 
+Note that the expression in this field only applies to the **distribution** file
+containing the metadata, not the project itself or other distribution files.
+
 Examples::
 
     License-Expression: MIT
@@ -923,6 +926,9 @@ Example::
 History
 =======
 
+- August 2025: Clarified that ``License-Expression`` applies to the containing
+  distribution file and not the project itself.
+
 - August 2024: Core metadata 2.4 was approved through :pep:`639`.
 
   - Added the ``License-Expression`` field.

From 083e98617f8053ffae61ba13b806d89e69ded647 Mon Sep 17 00:00:00 2001
From: Paul Moore 
Date: Wed, 27 Aug 2025 12:20:05 +0100
Subject: [PATCH 667/733] Clarify that the Dynamic metadata field only applies
 when building from sdist

---
 source/specifications/core-metadata.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 550c6e55a..6f071233e 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -133,6 +133,18 @@ only, and indicates that the field value was calculated at wheel build time,
 and may not be the same as the value in the sdist or in other wheels for the
 project.
 
+Note in particular that if you have a wheel, you cannot assume that a field
+which is not marked as ``Dynamic`` will have the same value in other wheels, as
+some wheels are not built directly from the sdist, but are modified from
+existing wheels (the ``cibuildwheel`` tool does this, for example). Such
+modifications *could* include changing metadata (even non-dynamic metadata).
+Similarly, if you have a sdist and a wheel which you didn't build from that
+sdist, you cannnot assume that the wheel's metadata matches that of the sdist,
+even if the field is not marked as ``Dynamic``.
+
+It is advisable, but not required, that tools which modify wheel metadata add
+the modified fields to the generated wheel's ``Dynamic`` field.
+
 Full details of the semantics of ``Dynamic`` are described in :pep:`643`.
 
 .. _core-metadata-platform:
@@ -923,6 +935,10 @@ Example::
 History
 =======
 
+- August 2025: Clarified that ``Dynamic`` only affects how fields
+  must be treated when building a wheel from a sdist, not when modifying
+  a wheel.
+
 - August 2024: Core metadata 2.4 was approved through :pep:`639`.
 
   - Added the ``License-Expression`` field.

From 42d1cbbc5be1cd43e156ba04ffde970d17ed22a4 Mon Sep 17 00:00:00 2001
From: Paul Moore 
Date: Wed, 27 Aug 2025 12:25:39 +0100
Subject: [PATCH 668/733] Grr, keyboard is doubling up letters :-(

---
 source/specifications/core-metadata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 6f071233e..106922580 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -139,7 +139,7 @@ some wheels are not built directly from the sdist, but are modified from
 existing wheels (the ``cibuildwheel`` tool does this, for example). Such
 modifications *could* include changing metadata (even non-dynamic metadata).
 Similarly, if you have a sdist and a wheel which you didn't build from that
-sdist, you cannnot assume that the wheel's metadata matches that of the sdist,
+sdist, you cannot assume that the wheel's metadata matches that of the sdist,
 even if the field is not marked as ``Dynamic``.
 
 It is advisable, but not required, that tools which modify wheel metadata add

From 875b13fa27bdf28200a364220a249290654f4280 Mon Sep 17 00:00:00 2001
From: Paul Moore 
Date: Wed, 27 Aug 2025 14:37:34 +0100
Subject: [PATCH 669/733] Refer to auditwheel rather than cibuildwheel

---
 source/specifications/core-metadata.rst | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 106922580..b77243e10 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -136,11 +136,12 @@ project.
 Note in particular that if you have a wheel, you cannot assume that a field
 which is not marked as ``Dynamic`` will have the same value in other wheels, as
 some wheels are not built directly from the sdist, but are modified from
-existing wheels (the ``cibuildwheel`` tool does this, for example). Such
-modifications *could* include changing metadata (even non-dynamic metadata).
-Similarly, if you have a sdist and a wheel which you didn't build from that
-sdist, you cannot assume that the wheel's metadata matches that of the sdist,
-even if the field is not marked as ``Dynamic``.
+existing wheels (the ``auditwheel`` tool does this, for example, and it's
+commonly used when building wheels for PyPI). Such modifications *could*
+include changing metadata (even non-dynamic metadata).  Similarly, if you have
+a sdist and a wheel which you didn't build from that sdist, you cannot assume
+that the wheel's metadata matches that of the sdist, even if the field is not
+marked as ``Dynamic``.
 
 It is advisable, but not required, that tools which modify wheel metadata add
 the modified fields to the generated wheel's ``Dynamic`` field.

From 6569d5cafecf2243368446e6f1e37d91c10797a7 Mon Sep 17 00:00:00 2001
From: Paul Moore 
Date: Wed, 27 Aug 2025 15:14:50 +0100
Subject: [PATCH 670/733] Clarify prebuilt wheels

---
 source/specifications/core-metadata.rst | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index b77243e10..571a13dde 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -133,15 +133,15 @@ only, and indicates that the field value was calculated at wheel build time,
 and may not be the same as the value in the sdist or in other wheels for the
 project.
 
-Note in particular that if you have a wheel, you cannot assume that a field
-which is not marked as ``Dynamic`` will have the same value in other wheels, as
-some wheels are not built directly from the sdist, but are modified from
-existing wheels (the ``auditwheel`` tool does this, for example, and it's
-commonly used when building wheels for PyPI). Such modifications *could*
-include changing metadata (even non-dynamic metadata).  Similarly, if you have
-a sdist and a wheel which you didn't build from that sdist, you cannot assume
-that the wheel's metadata matches that of the sdist, even if the field is not
-marked as ``Dynamic``.
+Note in particular that if you have obtained a prebuilt wheel, you cannot
+assume that a field which is not marked as ``Dynamic`` will have the same value
+in other wheels, as some wheels are not built directly from the sdist, but are
+modified from existing wheels (the ``auditwheel`` tool does this, for example,
+and it's commonly used when building wheels for PyPI). Such modifications
+*could* include changing metadata (even non-dynamic metadata).  Similarly, if
+you have a sdist and a wheel which you didn't build from that sdist, you cannot
+assume that the wheel's metadata matches that of the sdist, even if the field
+is not marked as ``Dynamic``.
 
 It is advisable, but not required, that tools which modify wheel metadata add
 the modified fields to the generated wheel's ``Dynamic`` field.

From cd571af286305cf1e7114a57f13ccff729f706c5 Mon Sep 17 00:00:00 2001
From: Paul Moore 
Date: Wed, 27 Aug 2025 16:20:46 +0100
Subject: [PATCH 671/733] Remove advice for tools that modify wheels

---
 source/specifications/core-metadata.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 571a13dde..c020e1469 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -143,9 +143,6 @@ you have a sdist and a wheel which you didn't build from that sdist, you cannot
 assume that the wheel's metadata matches that of the sdist, even if the field
 is not marked as ``Dynamic``.
 
-It is advisable, but not required, that tools which modify wheel metadata add
-the modified fields to the generated wheel's ``Dynamic`` field.
-
 Full details of the semantics of ``Dynamic`` are described in :pep:`643`.
 
 .. _core-metadata-platform:

From 31d727712bb38af2513dc7f741e47f188ed96f98 Mon Sep 17 00:00:00 2001
From: konsti 
Date: Thu, 28 Aug 2025 16:51:57 +0200
Subject: [PATCH 672/733] Update .github/workflows/update-uv-build-version.yml

Co-authored-by: Alyssa Coghlan 
---
 .github/workflows/update-uv-build-version.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/update-uv-build-version.yml b/.github/workflows/update-uv-build-version.yml
index 184497047..a3cead001 100644
--- a/.github/workflows/update-uv-build-version.yml
+++ b/.github/workflows/update-uv-build-version.yml
@@ -1,6 +1,6 @@
 ---
 
-name: Cron
+name: Update uv build version
 
 on:
   schedule:

From acdb79c4e738cc1f489288219632e6b694209ac2 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Wed, 10 Sep 2025 12:04:16 -0700
Subject: [PATCH 673/733] Try to clarify where `license-expression` applies

---
 source/specifications/core-metadata.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 379805df5..c79b4e0f7 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -473,8 +473,8 @@ Text string that is a valid SPDX
 :term:`license expression `,
 as specified in :doc:`/specifications/license-expression`.
 
-Note that the expression in this field only applies to the **distribution** file
-containing the metadata, not the project itself or other distribution files.
+Note that the expression in this field only applies to the distribution file
+containing the metadata, not the project overall or other distribution files.
 
 Examples::
 

From d73c061cbaa3f1178c8cc1e0bb5bfeaea3ee64ed Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Wed, 10 Sep 2025 13:06:14 -0700
Subject: [PATCH 674/733] Clarify throughout the docs that the `license` key in
 `pyproject.toml` is for the distribution

---
 source/glossary.rst                           |  2 +-
 .../licensing-examples-and-user-scenarios.rst | 28 +++++++++----------
 source/guides/writing-pyproject-toml.rst      | 15 +++++-----
 source/tutorials/packaging-projects.rst       | 14 +++++-----
 4 files changed, 30 insertions(+), 29 deletions(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index 6a592125f..630513868 100644
--- a/source/glossary.rst
+++ b/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``,
diff --git a/source/guides/licensing-examples-and-user-scenarios.rst b/source/guides/licensing-examples-and-user-scenarios.rst
index 2c25ddfb0..9f32b6117 100644
--- a/source/guides/licensing-examples-and-user-scenarios.rst
+++ b/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 `__ 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`
@@ -311,13 +312,12 @@ software, you can construct a license expression
 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.
+In short, ``License-1 AND License-2`` mean that *both* licenses apply, 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.
 
 In your project config file, enter your license expression under
 ``license`` (``[project]`` table of :file:`pyproject.toml`),
diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 1d035a384..3a8a8e5d4 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -296,10 +296,10 @@ You can also specify the format explicitly, like this:
 ``license`` and ``license-files``
 ---------------------------------
 
-As per :pep:`639` licenses should be declared with two fields:
+As per :pep:`639`, licenses should be declared with two fields:
 
-- ``license`` is an :term:`SPDX license expression ` consisting
-  of one or more :term:`license identifiers `.
+- ``license`` is an :term:`SPDX license expression `
+  consisting of one or more :term:`license identifiers `.
 - ``license-files`` is a list of license file glob patterns.
 
 A previous PEP had specified ``license`` to be a table with a ``file`` or a
@@ -350,10 +350,11 @@ As a general rule, it is a good idea to use a standard, well-known
 license, both to avoid confusion and because some organizations avoid software
 whose license is unapproved.
 
-If your project is licensed with a license that doesn't have an existing SPDX
-identifier, you can create a custom one in format ``LicenseRef-[idstring]``.
-The custom identifiers must follow the SPDX specification,
-`clause 10.1 `_ of the version 2.2 or any later compatible one.
+If your :term:`Distribution Archive` is licensed with a license that doesn't
+have an existing SPDX identifier, you can create a custom one in format
+``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX
+specification, `clause 10.1 `_ of the version 2.2 or any later
+compatible one.
 
 .. code-block:: toml
 
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
index f2c0851ba..4f69de20b 100644
--- a/source/tutorials/packaging-projects.rst
+++ b/source/tutorials/packaging-projects.rst
@@ -220,7 +220,7 @@ following this tutorial.
   your package will work on. For a complete list of classifiers, see
   https://pypi.org/classifiers/.
 - ``license`` is the :term:`SPDX license expression ` of
-  your package.
+  your :term:`Distribution Archive` files.
 - ``license-files`` is the list of glob paths to the license files,
   relative to the directory where :file:`pyproject.toml` is located.
 - ``urls`` lets you list any number of extra links to show on PyPI.
@@ -250,12 +250,12 @@ if you'd like.
 Creating a LICENSE
 ------------------
 
-It's important for every package uploaded to the Python Package Index to include
-a license. This tells users who install your package the terms under which they
-can use your package. For help picking a license, see
-https://choosealicense.com/. Once you have chosen a license, open
-:file:`LICENSE` and enter the license text. For example, if you had chosen the
-MIT license:
+It's important for every :term:`Distribution Archive` uploaded to the Python
+Package Index to include a license. This tells users who install your
+:term:`Distribution Archive` the terms under which they can use it. For help
+picking a license, see https://choosealicense.com/. Once you have chosen a
+license, open :file:`LICENSE` and enter the license text. For example, if you
+had chosen the MIT license:
 
 .. code-block:: text
 

From ce4251e775d04f5577ad9b7a843703c3b87bd06c Mon Sep 17 00:00:00 2001
From: konstin 
Date: Mon, 15 Sep 2025 20:57:37 +0200
Subject: [PATCH 675/733] Create PR as draft

---
 .github/workflows/update-uv-build-version.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/update-uv-build-version.yml b/.github/workflows/update-uv-build-version.yml
index a3cead001..8aadc7052 100644
--- a/.github/workflows/update-uv-build-version.yml
+++ b/.github/workflows/update-uv-build-version.yml
@@ -32,6 +32,7 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           commit-message: Update uv_build version to ${{ steps.update_script.outputs.version }}
           title: Update uv_build version to ${{ steps.update_script.outputs.version }}
+          draft: true # Trigger CI by un-drafting the PR, otherwise `GITHUB_TOKEN` PRs don't trigger CI.
           body: |
             Automated update of uv_build version bounds for uv ${{ steps.update_script.outputs.version }}.
 

From 4f0a3c603d3a901bb00e1d52d639d6b1cb3aca5f Mon Sep 17 00:00:00 2001
From: Nick Coghlan 
Date: Tue, 16 Sep 2025 11:14:09 +1000
Subject: [PATCH 676/733] Vagrant link is failing CI, drop it entirely

---
 source/overview.rst | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/source/overview.rst b/source/overview.rst
index 8c68036a7..70ef2d058 100644
--- a/source/overview.rst
+++ b/source/overview.rst
@@ -339,7 +339,7 @@ originated and where the technologies below work best:
 Bringing your own kernel
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-Most operating systems support some form of classical virtualization,
+Most desktop operating systems support some form of classical virtualization,
 running applications packaged as images containing a full operating
 system of their own. Running these virtual machines, or VMs, is a
 mature approach, widespread in data center environments.
@@ -348,9 +348,13 @@ These techniques are mostly reserved for larger scale deployments in
 data centers, though certain complex applications can benefit from
 this packaging. The technologies are Python agnostic, and include:
 
-* `Vagrant `_
-* `VHD `_, `AMI `_, and :doc:`other formats `
-* `OpenStack `_ - A cloud management system in Python, with extensive VM support
+* KVM on Linux
+* Hyper-V on Windows
+* `VHD `_,
+  `AMI `_,
+  and :doc:`other formats `
+* `OpenStack `_ -
+  A cloud management system written in Python, with extensive VM support
 
 Bringing your own hardware
 ^^^^^^^^^^^^^^^^^^^^^^^^^^

From c3274274483e7638d75699678347400b18773144 Mon Sep 17 00:00:00 2001
From: Nick Coghlan 
Date: Tue, 16 Sep 2025 11:36:49 +1000
Subject: [PATCH 677/733] Avoid binary gender assumptions in example

Closes #1907
---
 source/guides/creating-command-line-tools.rst | 46 ++++++++-----------
 1 file changed, 20 insertions(+), 26 deletions(-)

diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst
index 8266fffdb..045c221b4 100644
--- a/source/guides/creating-command-line-tools.rst
+++ b/source/guides/creating-command-line-tools.rst
@@ -40,33 +40,25 @@ named after the main module:
 
 
     def greet(
-        name: Annotated[str, typer.Argument(help="The (last, if --gender is given) name of the person to greet")] = "",
-        gender: Annotated[str, typer.Option(help="The gender of the person to greet")] = "",
+        name: Annotated[str, typer.Argument(help="The (last, if --title is given) name of the person to greet")] = "",
+        title: Annotated[str, typer.Option(help="The preferred title of the person to greet")] = "",
         knight: Annotated[bool, typer.Option(help="Whether the person is a knight")] = False,
         count: Annotated[int, typer.Option(help="Number of times to greet the person")] = 1
     ):
-        greeting = "Greetings, dear "
-        masculine = gender == "masculine"
-        feminine = gender == "feminine"
-        if gender or knight:
+        greeting = "Greetings, "
+        if not name:
+            if title:
+                name = title.lower().rstrip(".")
+            else:
+                name = "friend"
+        if title or knight:
             salutation = ""
-            if knight:
+            if title:
+                salutation = title
+            elif knight:
                 salutation = "Sir "
-            elif masculine:
-                salutation = "Mr. "
-            elif feminine:
-                salutation = "Ms. "
             greeting += salutation
-            if name:
-                greeting += f"{name}!"
-            else:
-                pronoun = "her" if feminine else "his" if masculine or knight else "its"
-                greeting += f"what's-{pronoun}-name"
-        else:
-            if name:
-                greeting += f"{name}!"
-            elif not gender:
-                greeting += "friend!"
+        greeting += f"{name}!"
         for i in range(0, count):
             print(greeting)
 
@@ -145,12 +137,14 @@ Let's test it:
 
 .. code-block:: console
 
+	$ greet
+	Greetings, friend!
 	$ greet --knight Lancelot
-	Greetings, dear Sir Lancelot!
-	$ greet --gender feminine Parks
-	Greetings, dear Ms. Parks!
-	$ greet --gender masculine
-	Greetings, dear Mr. what's-his-name!
+	Greetings, Sir Lancelot!
+	$ greet --title Ms. Parks
+	Greetings, Ms. Parks!
+	$ greet --title Mr.
+	Greetings, Mr. mr!
 
 Since this example uses ``typer``, you could now also get an overview of the program's usage by calling it with
 the ``--help`` option, or configure completions via the ``--install-completion`` option.

From 332cc3086f6f1f4e9e53062914733a8a439c7102 Mon Sep 17 00:00:00 2001
From: Nick Coghlan 
Date: Tue, 16 Sep 2025 11:53:35 +1000
Subject: [PATCH 678/733] Use a more obviously gender neutral title

---
 source/guides/creating-command-line-tools.rst | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst
index 045c221b4..5e96b7da5 100644
--- a/source/guides/creating-command-line-tools.rst
+++ b/source/guides/creating-command-line-tools.rst
@@ -42,7 +42,7 @@ named after the main module:
     def greet(
         name: Annotated[str, typer.Argument(help="The (last, if --title is given) name of the person to greet")] = "",
         title: Annotated[str, typer.Option(help="The preferred title of the person to greet")] = "",
-        knight: Annotated[bool, typer.Option(help="Whether the person is a knight")] = False,
+        doctor: Annotated[bool, typer.Option(help="Whether the person is a doctor (MD or PhD)")] = False,
         count: Annotated[int, typer.Option(help="Number of times to greet the person")] = 1
     ):
         greeting = "Greetings, "
@@ -51,13 +51,10 @@ named after the main module:
                 name = title.lower().rstrip(".")
             else:
                 name = "friend"
-        if title or knight:
-            salutation = ""
-            if title:
-                salutation = title
-            elif knight:
-                salutation = "Sir "
-            greeting += salutation
+        if doctor and not title:
+            title = "Dr."
+        if title:
+            greeting += f"{title} "
         greeting += f"{name}!"
         for i in range(0, count):
             print(greeting)

From 159fc06e960d9399a43adf59abcf22d592fbbb3b Mon Sep 17 00:00:00 2001
From: Nick Coghlan 
Date: Tue, 16 Sep 2025 11:55:30 +1000
Subject: [PATCH 679/733] Update example output

---
 source/guides/creating-command-line-tools.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst
index 5e96b7da5..72e3e37ef 100644
--- a/source/guides/creating-command-line-tools.rst
+++ b/source/guides/creating-command-line-tools.rst
@@ -46,13 +46,13 @@ named after the main module:
         count: Annotated[int, typer.Option(help="Number of times to greet the person")] = 1
     ):
         greeting = "Greetings, "
+        if doctor and not title:
+            title = "Dr."
         if not name:
             if title:
                 name = title.lower().rstrip(".")
             else:
                 name = "friend"
-        if doctor and not title:
-            title = "Dr."
         if title:
             greeting += f"{title} "
         greeting += f"{name}!"
@@ -136,8 +136,8 @@ Let's test it:
 
 	$ greet
 	Greetings, friend!
-	$ greet --knight Lancelot
-	Greetings, Sir Lancelot!
+	$ greet --doctor Brennan
+	Greetings, Dr. Brennan!
 	$ greet --title Ms. Parks
 	Greetings, Ms. Parks!
 	$ greet --title Mr.
@@ -151,7 +151,7 @@ To just run the program without installing it permanently, use ``pipx run``, whi
 
 .. code-block:: console
 
-	$ pipx run --spec . greet --knight
+	$ 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).
@@ -170,7 +170,7 @@ default one and run it, which makes this command possible:
 
 .. code-block:: console
 
-    $ pipx run . --knight
+    $ pipx run . --doctor
 
 Conclusion
 ==========

From bceb2644a302db55733492e4489883699f961921 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Mon, 15 Sep 2025 21:59:01 -0400
Subject: [PATCH 680/733] ci: remove workflow_dispatch from cron.yml

Signed-off-by: William Woodruff 
---
 .github/workflows/cron.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/cron.yml b/.github/workflows/cron.yml
index f1eddccb5..8870bb70b 100644
--- a/.github/workflows/cron.yml
+++ b/.github/workflows/cron.yml
@@ -5,7 +5,6 @@ name: Cron
 on:
   schedule:
   - cron: "0 6 * * *"  # daily at 6am
-  workflow_dispatch:
 
 jobs:
   test:

From c7ffbccf513399c2cddd0dbed7183d4835429419 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Mon, 15 Sep 2025 22:06:31 -0400
Subject: [PATCH 681/733] ci: add pull_request event subtypes

Signed-off-by: William Woodruff 
---
 .github/workflows/test.yml | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 8503ca720..172fed713 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -6,12 +6,19 @@ on:
     branches-ignore:
     - gh-readonly-queue/**  # Temporary merge queue-related GH-made branches
   pull_request:
+    types:
+    - opened  # default
+    - synchronize  # default
+    - reopened  # default
+    - ready_for_review  # used in PRs created from GitHub Actions workflows
   workflow_call:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
   cancel-in-progress: true
 
+permissions: {}
+
 jobs:
   build:
     name: ${{ matrix.noxenv }}

From b036f24d6fefac29c3b95a7b8810b62117529f5c Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Mon, 15 Sep 2025 22:06:53 -0400
Subject: [PATCH 682/733] update_uv_build_version: remove unneeded format

Signed-off-by: William Woodruff 
---
 scripts/update_uv_build_version.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/update_uv_build_version.py b/scripts/update_uv_build_version.py
index 816ab9061..69fefba27 100644
--- a/scripts/update_uv_build_version.py
+++ b/scripts/update_uv_build_version.py
@@ -34,7 +34,7 @@ def main():
     [major, minor, _patch] = current_release.release
     if major != 0:
         raise NotImplementedError("The script needs to be updated for uv 1.x")
-    upper_bound = Version(f"{major}.{minor + 1}.{0}")
+    upper_bound = Version(f"{major}.{minor + 1}.0")
 
     repository_root = Path(__file__).parent.parent
     existing = repository_root.joinpath(

From 71eb39402354a259a151dd2ea837b4b90219edb4 Mon Sep 17 00:00:00 2001
From: woodruffw <3059210+woodruffw@users.noreply.github.com>
Date: Tue, 16 Sep 2025 14:15:24 +0000
Subject: [PATCH 683/733] Update uv_build version to 0.8.17

---
 source/shared/build-backend-tabs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index 608fcaddd..9efc8b0d7 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -38,5 +38,5 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["uv_build >= 0.7.19, <0.9.0"]
+        requires = ["uv_build >= 0.8.17, <0.9.0"]
         build-backend = "uv_build"

From dd267139d93bdc154629f1038b852b8178681102 Mon Sep 17 00:00:00 2001
From: Philip Mallegol-Hansen 
Date: Tue, 16 Sep 2025 13:25:53 -0700
Subject: [PATCH 684/733] Updates table to contain poetry-core version
 supporting PEP 639

---
 source/guides/writing-pyproject-toml.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst
index 1d035a384..b8be3e85d 100644
--- a/source/guides/writing-pyproject-toml.rst
+++ b/source/guides/writing-pyproject-toml.rst
@@ -319,7 +319,7 @@ backend>` now support the new format as shown in the following table.
      - 77.0.3
      - 3.12
      - 2.4.0
-     - `not yet `_
+     - 2.2.0
      - 0.7.19
 
 
@@ -587,7 +587,6 @@ A full example
 .. _pypi-search-pip: https://pypi.org/search?q=pip
 .. _classifier-list: https://pypi.org/classifiers
 .. _requires-python-blog-post: https://iscinumpy.dev/post/bound-version-constraints/#pinning-the-python-version-is-special
-.. _poetry-pep639-issue: https://github.com/python-poetry/poetry/issues/9670
 .. _pytest: https://pytest.org
 .. _pygments: https://pygments.org
 .. _rest: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

From 3669181977fc68f686eac4c29ba25564ed964abc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edgar=20Ram=C3=ADrez-Mondrag=C3=B3n?= 
Date: Sat, 13 Sep 2025 11:12:38 -0600
Subject: [PATCH 685/733] Fix links to spec schemas

---
 .../specifications/schemas/build-details-v1.0.schema.json  | 0
 .../specifications/schemas/direct-url.schema.json          | 0
 .../specifications/schemas/pylock.schema.json              | 0
 source/conf.py                                             | 7 +++++++
 source/specifications/build-details/v1.0.rst               | 2 +-
 source/specifications/direct-url-data-structure.rst        | 2 +-
 6 files changed, 9 insertions(+), 2 deletions(-)
 rename {source => extra}/specifications/schemas/build-details-v1.0.schema.json (100%)
 rename {source => extra}/specifications/schemas/direct-url.schema.json (100%)
 rename {source => extra}/specifications/schemas/pylock.schema.json (100%)

diff --git a/source/specifications/schemas/build-details-v1.0.schema.json b/extra/specifications/schemas/build-details-v1.0.schema.json
similarity index 100%
rename from source/specifications/schemas/build-details-v1.0.schema.json
rename to extra/specifications/schemas/build-details-v1.0.schema.json
diff --git a/source/specifications/schemas/direct-url.schema.json b/extra/specifications/schemas/direct-url.schema.json
similarity index 100%
rename from source/specifications/schemas/direct-url.schema.json
rename to extra/specifications/schemas/direct-url.schema.json
diff --git a/source/specifications/schemas/pylock.schema.json b/extra/specifications/schemas/pylock.schema.json
similarity index 100%
rename from source/specifications/schemas/pylock.schema.json
rename to extra/specifications/schemas/pylock.schema.json
diff --git a/source/conf.py b/source/conf.py
index a8a040d6c..3ffa98b0f 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -83,6 +83,10 @@
     # https://plausible.io/packaging.python.org
     html_js_files.extend(_metrics_js_files)
 
+html_extra_path = [
+    "../extra",
+]
+
 # -- Options for HTML help output ------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-help-output
 
@@ -157,6 +161,9 @@
     # 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
diff --git a/source/specifications/build-details/v1.0.rst b/source/specifications/build-details/v1.0.rst
index cfe902e1e..3a8cfe277 100644
--- a/source/specifications/build-details/v1.0.rst
+++ b/source/specifications/build-details/v1.0.rst
@@ -8,7 +8,7 @@
 Specification
 -------------
 
-.. jsonschema:: ../schemas/build-details-v1.0.schema.json
+.. jsonschema:: ../../../extra/specifications/schemas/build-details-v1.0.schema.json
     :lift_title: false
 
 
diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
index 5f3af0fae..a82537f0a 100644
--- a/source/specifications/direct-url-data-structure.rst
+++ b/source/specifications/direct-url-data-structure.rst
@@ -236,7 +236,7 @@ JSON Schema
 
 The following JSON Schema can be used to validate the contents of ``direct_url.json``:
 
-.. literalinclude:: schemas/direct-url.schema.json
+.. literalinclude:: ../../extra/specifications/schemas/direct-url.schema.json
 
 Examples
 ========

From 6ae0da519af5615f4f28b28d3d738755075866a3 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Wed, 10 Sep 2025 12:26:26 -0700
Subject: [PATCH 686/733] Clarify that the `license` key in `pyprojcet.toml`
 should only be set if it is consistent across all distribution files This
 change is approved at
 https://discuss.python.org/t/split-from-pep-639-expressing-project-vs-distribution-licenses-post-pep-639-mod-titled/90314/179
 .

---
 source/specifications/pyproject-toml.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 4ce9b7484..c94e78d83 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -259,6 +259,11 @@ Text string that is a valid SPDX
 as specified in :doc:`/specifications/license-expression`.
 Tools SHOULD validate and perform case normalization of the expression.
 
+This key should **only** be specified if the license expression for any
+and all distribution files generated from the ``pyproject.toml`` is the
+same as the one specified. If the license expression will differ then
+it should either be specified as dynamic or not set at all.
+
 Legacy specification
 ''''''''''''''''''''
 

From 3504230284d0802c38859fcd18f9ca59970daaec Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Wed, 10 Sep 2025 12:30:49 -0700
Subject: [PATCH 687/733] Add a history entry

---
 source/specifications/pyproject-toml.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index c94e78d83..7950bccbc 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -545,5 +545,8 @@ History
 - December 2024: The ``license`` key was redefined, the ``license-files`` key was
   added and ``License::`` classifiers were deprecated through :pep:`639`.
 
+- September 2025: Clarity that the ``license`` key applies to all distribution
+  files generated from the ``pyproject.toml`` file.
+
 
 .. _TOML: https://toml.io

From b947936259353b85c34252dc01c2e11a97762482 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Mon, 15 Sep 2025 17:09:25 +0100
Subject: [PATCH 688/733] Apply suggestion from @webknjaz
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/specifications/pyproject-toml.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 7950bccbc..4a14615b9 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -260,7 +260,7 @@ as specified in :doc:`/specifications/license-expression`.
 Tools SHOULD validate and perform case normalization of the expression.
 
 This key should **only** be specified if the license expression for any
-and all distribution files generated from the ``pyproject.toml`` is the
+and all distribution files generated from the :file:`pyproject.toml` is the
 same as the one specified. If the license expression will differ then
 it should either be specified as dynamic or not set at all.
 

From ed6f9704411531d46756ef7b49f7109aa73fd6e6 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Mon, 15 Sep 2025 17:09:31 +0100
Subject: [PATCH 689/733] Apply suggestion from @webknjaz
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 
---
 source/specifications/pyproject-toml.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 4a14615b9..3c47b9d50 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -546,7 +546,7 @@ History
   added and ``License::`` classifiers were deprecated through :pep:`639`.
 
 - September 2025: Clarity that the ``license`` key applies to all distribution
-  files generated from the ``pyproject.toml`` file.
+  files generated from the :file:`pyproject.toml` file.
 
 
 .. _TOML: https://toml.io

From 3851b070abb3ed435f1b52572593e96970eb9431 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Mon, 15 Sep 2025 17:11:00 +0100
Subject: [PATCH 690/733] Fix wording in pyproject-toml.rst license section

---
 source/specifications/pyproject-toml.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 3c47b9d50..bb0e56ff7 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -260,9 +260,10 @@ as specified in :doc:`/specifications/license-expression`.
 Tools SHOULD validate and perform case normalization of the expression.
 
 This key should **only** be specified if the license expression for any
-and all distribution files generated from the :file:`pyproject.toml` is the
-same as the one specified. If the license expression will differ then
-it should either be specified as dynamic or not set at all.
+and all distribution files created by a build backend using the
+:file:`pyproject.toml` is the same as the one specified. If the license
+expression will differ then it should either be specified as dynamic or
+not set at all.
 
 Legacy specification
 ''''''''''''''''''''

From 5a822ab5af0d305d175e5cb475bfcbcdd9497b74 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 3 Oct 2025 22:41:35 +0000
Subject: [PATCH 691/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/specifications/core-metadata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 665f8704a..42c6b9ec6 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -938,7 +938,7 @@ History
 
 - October 2025: Clarified that ``License-Expression`` applies to the containing
   distribution file and not the project itself.
-  
+
 - August 2025: Clarified that ``Dynamic`` only affects how fields
   must be treated when building a wheel from a sdist, not when modifying
   a wheel.

From 4a44bffed7f86296599e0dd5ab968343e5450654 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Fri, 3 Oct 2025 15:45:25 -0700
Subject: [PATCH 692/733] Fix formatting of license expression explanation

---
 source/guides/licensing-examples-and-user-scenarios.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/guides/licensing-examples-and-user-scenarios.rst b/source/guides/licensing-examples-and-user-scenarios.rst
index 9f32b6117..b6cdfe327 100644
--- a/source/guides/licensing-examples-and-user-scenarios.rst
+++ b/source/guides/licensing-examples-and-user-scenarios.rst
@@ -312,8 +312,8 @@ software, you can construct a license expression
 to describe the licenses involved and the relationship
 between them.
 
-In short, ``License-1 AND License-2`` mean that *both* licenses apply, or parts
-of it (for example, you included a file under another license), and
+In short, ``License-1 AND License-2`` mean that *both* licenses apply
+(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

From 465a5bfa5e8da07656e20ab46df41489c29629da Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Tue, 7 Oct 2025 09:37:57 -0700
Subject: [PATCH 693/733] Try to clarify what a "distribution archive" is

---
 source/specifications/core-metadata.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 42c6b9ec6..b6d92e6f2 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -483,8 +483,10 @@ Text string that is a valid SPDX
 :term:`license expression `,
 as specified in :doc:`/specifications/license-expression`.
 
-Note that the expression in this field only applies to the distribution file
-containing the metadata, not the project overall or other distribution files.
+Note that the expression in this field only applies to the
+:term:`Distribution Archive` containing the metadata with this field (e.g.,
+:term:`Source Distribution` or :term:`Wheel`), not the project overall or
+other files related to the project (including other distribution archives).
 
 Examples::
 

From db0173577ef2328967b06043d7cacfb6f3a536c0 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Tue, 7 Oct 2025 11:04:31 -0700
Subject: [PATCH 694/733] Add PEP 794: Import name metadata

---
 source/specifications/core-metadata.rst  | 134 ++++++++++++++++++++---
 source/specifications/pyproject-toml.rst |  96 ++++++++++++++++
 2 files changed, 213 insertions(+), 17 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index c020e1469..0ea469fd8 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -6,7 +6,7 @@
 Core metadata specifications
 ============================
 
-This page describes version 2.4, approved in August 2024.
+This page describes version 2.5, approved in September 2025.
 
 Fields defined in the following specification should be considered valid,
 complete and not subject to change. The required fields are:
@@ -50,7 +50,7 @@ Metadata-Version
 .. versionadded:: 1.0
 
 Version of the file format; legal values are "1.0", "1.1", "1.2", "2.1",
-"2.2", "2.3", and "2.4".
+"2.2", "2.3", "2.4", and "2.5".
 
 Automated tools consuming metadata SHOULD warn if ``metadata_version`` is
 greater than the highest version they support, and MUST fail if
@@ -718,6 +718,101 @@ user SHOULD be warned and the value ignored to avoid ambiguity. Tools MAY choose
 to raise an error when reading an invalid name for older metadata versions.
 
 
+.. _core-metadata-import-name:
+
+Import-Name (multiple use)
+===========================
+
+.. versionadded:: 2.5
+
+A string containing an import name that the project exclusively provides when
+installed. The specified import name MUST be a valid Python identifier or can
+be empty. The import names listed in this field MUST be importable when the
+project is installed on *some* platform for the same version of the project.
+This implies that the metadata MUST be consistent across all sdists and wheels
+for a project release.
+
+An import name MAY be followed by a semicolon and the term "private"
+(e.g. ``; private``) with any amount of whitespace surrounding the semicolon.
+This signals to tools that the import name is not part of the public API for
+the project.
+
+Projects SHOULD list all the shortest import names that are exclusively provided
+by the project. If any of the shortest names are dotted names, all intervening
+names from that name to the top-level name should also be listed appropriately
+in ``Import-Name`` and/or ``Import-Namespace``.
+
+If a project lists the same name in both ``Import-Name`` and
+``Import-Namespace``, tools MUST raise an error due to ambiguity.
+
+Tools SHOULD raise an error when two projects that are about to be installed
+list names that overlap in each other's ``Import-Name`` entries, or when a
+project has an entry in ``Import-Name`` that overlaps with another project's
+``Import-Namespace`` entries. This is to avoid projects unexpectedly shadowing
+another project's code. Tools MAY warn or raise an error when installing a
+project into a preexisting environment where there is import name overlap with
+a project that is already installed.
+
+Projects MAY have an empty ``Import-Name`` field in their metadata to represent
+a project with no import names (i.e. there are no Python modules of any kind in
+the distribution file).
+
+Since projects MAY have no ``Import-Name`` metadata (either because the
+project uses an older metadata version, or because it didn't specify any), then
+tools have no information about what names the project provides. However, in
+practice the majority of projects have their project name match what their
+import name would be. As such, it is a reasonable assumption to make that a
+project name that is normalized in some way to an import name
+(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace("-", "_")``)
+can be used if some answer is needed.
+
+Examples::
+
+    Import-Name: PIL
+    Import-Name: _private_module ; private
+    Import-Name: zope.interface
+    Import-Name:
+
+
+.. _core-metadata-import-namespace:
+
+Import-Namespace (multiple use)
+================================
+
+.. versionadded:: 2.5
+
+A string containing an import name that the project provides when installed, but
+not exclusively. The specified import name MUST be a valid Python identifier.
+This field is used for namespace packages where multiple projects can contribute
+to the same import namespace. Projects all listing the same import name in
+``Import-Namespace`` can be installed together without shadowing each other.
+
+An import name MAY be followed by a semicolon and the term "private" (e.g.
+``; private``) with any amount of whitespace surrounding the semicolon. This
+signals to tools that the import name is not part of the public API for the
+project.
+
+Projects SHOULD list all the shortest import names that are exclusively provided
+by the project. If any of the shortest names are dotted names, all intervening
+names from that name to the top-level name should also be listed appropriately
+in ``Import-Name`` and/or ``Import-Namespace``.
+
+The import names listed in this field MUST be importable when the project is
+installed on *some* platform for the same version of the project. This implies
+that the metadata MUST be consistent across all sdists and wheels for a project
+release.
+
+If a project lists the same name in both ``Import-Name`` and
+``Import-Namespace``, tools MUST raise an error due to ambiguity.
+
+Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``.
+
+Examples::
+
+    Import-Namespace: zope
+    Import-Name: _private_module ; private
+
+
 Rarely Used Fields
 ==================
 
@@ -933,34 +1028,39 @@ Example::
 History
 =======
 
-- August 2025: Clarified that ``Dynamic`` only affects how fields
-  must be treated when building a wheel from a sdist, not when modifying
-  a wheel.
+- March 2001: Core metadata 1.0 was approved through :pep:`241`.
 
-- August 2024: Core metadata 2.4 was approved through :pep:`639`.
+- April 2003: Core metadata 1.1 was approved through :pep:`314`.
 
-  - Added the ``License-Expression`` field.
-  - Added the ``License-File`` field.
+- February 2010: Core metadata 1.2 was approved through :pep:`345`.
 
-- March 2022: Core metadata 2.3 was approved through :pep:`685`.
+- February 2018: Core metadata 2.1 was approved through :pep:`566`.
 
-  - Restricted extra names to be normalized.
+  - Added ``Description-Content-Type`` and ``Provides-Extra``.
+  - Added canonical method for transforming metadata to JSON.
+  - Restricted the grammar of the ``Name`` field.
 
 - October 2020: Core metadata 2.2 was approved through :pep:`643`.
 
   - Added the ``Dynamic`` field.
 
-- February 2018: Core metadata 2.1 was approved through :pep:`566`.
+- March 2022: Core metadata 2.3 was approved through :pep:`685`.
 
-  - Added ``Description-Content-Type`` and ``Provides-Extra``.
-  - Added canonical method for transforming metadata to JSON.
-  - Restricted the grammar of the ``Name`` field.
+  - Restricted extra names to be normalized.
 
-- February 2010: Core metadata 1.2 was approved through :pep:`345`.
+- August 2024: Core metadata 2.4 was approved through :pep:`639`.
 
-- April 2003: Core metadata 1.1 was approved through :pep:`314`:
+  - Added the ``License-Expression`` field.
+  - Added the ``License-File`` field.
 
-- March 2001: Core metadata 1.0 was approved through :pep:`241`.
+- August 2025: Clarified that ``Dynamic`` only affects how fields
+  must be treated when building a wheel from a sdist, not when modifying
+  a wheel.
+
+- September 2025: Core metadata 2.5 was approved through :pep:`794`.
+
+  - Added the ``Import-Name`` field.
+  - Added the ``Import-Namespace`` field.
 
 ----
 
diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 4ce9b7484..25004dfd5 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -136,6 +136,8 @@ The complete list of keys allowed in the ``[project]`` table are:
 - ``dynamic``
 - ``entry-points``
 - ``gui-scripts``
+- ``import-names``
+- ``import-namespaces``
 - ``keywords``
 - ``license``
 - ``license-files``
@@ -466,6 +468,97 @@ matching :ref:`Provides-Extra `
 metadata.
 
 
+.. _pyproject-toml-import-names:
+
+``import-names``
+----------------
+
+- TOML_ type: array of strings
+- Corresponding :ref:`core metadata ` field:
+  :ref:`Import-Name `
+
+An array of strings specifying the import names that the project exclusively
+provides when installed. Each string MUST be a valid Python identifier or can
+be empty. An import name MAY be followed by a semicolon and the term "private"
+(e.g. ``"; private"``) with any amount of whitespace surrounding the semicolon.
+
+Projects SHOULD list all the shortest import names that are exclusively provided
+by the project. If any of the shortest names are dotted names, all intervening
+names from that name to the top-level name should also be listed appropriately
+in ``import-names`` and/or ``import-namespaces``. For instance, a project which
+is a single package named spam with multiple submodules would only list
+``project.import-names = ["spam"]``. A project that lists ``spam.bacon.eggs``
+would also need to account for ``spam`` and ``spam.bacon`` appropriately in
+``import-names`` and ``import-namespaces``. Listing all names acts as a check
+that the intent of the import names is as expected. As well, projects SHOULD
+list all import names, public or private, using the ``; private`` modifier as
+appropriate.
+
+If a project lists the same name in both ``import-names`` and
+``import-namespaces``, then tools MUST raise an error due to ambiguity.
+
+Projects MAY set ``import-names`` to an empty array to represent a project with
+no import names (i.e. there are no Python modules of any kind in the
+distribution file).
+
+Build back-ends MAY support dynamically calculating the value if the user
+declares the key in ``project.dynamic``.
+
+Examples:
+
+.. code-block:: toml
+
+   [project]
+   name = "pillow"
+   import-names = ["PIL"]
+
+.. code-block:: toml
+
+   [project]
+   name = "myproject"
+   import-names = ["mypackage", "_private_module ; private"]
+
+
+.. _pyproject-toml-import-namespaces:
+
+``import-namespaces``
+---------------------
+
+- TOML_ type: array of strings
+- Corresponding :ref:`core metadata ` field:
+  :ref:`Import-Namespace `
+
+An array of strings specifying the import names that the project provides when
+installed, but not exclusively. Each string MUST be a valid Python identifier.
+An import name MAY be followed by a semicolon and the term "private" (e.g.
+``"; private"``) with any amount of whitespace surrounding the semicolon. Note
+that unlike ``import-names``, ``import-namespaces`` CANNOT be an empty array.
+
+Projects SHOULD list all the shortest import names that are exclusively provided
+by the project. If any of the shortest names are dotted names, all intervening
+names from that name to the top-level name should also be listed appropriately
+in ``import-names`` and/or ``import-namespaces``.
+
+This field is used for namespace packages where multiple projects can contribute
+to the same import namespace. Projects all listing the same import name in
+``import-namespaces`` can be installed together without shadowing each other.
+
+If a project lists the same name in both ``import-names`` and
+``import-namespaces``, then tools MUST raise an error due to ambiguity.
+
+Build back-ends MAY support dynamically calculating the value if the user
+declares the key in ``project.dynamic``.
+
+Example:
+
+.. code-block:: toml
+
+   [project]
+   name = "zope-interface"
+   import-namespaces = ["zope"]
+   import-names = ["zope.interface"]
+
+
 .. _pyproject-toml-dynamic:
 .. _declaring-project-metadata-dynamic:
 
@@ -540,5 +633,8 @@ History
 - December 2024: The ``license`` key was redefined, the ``license-files`` key was
   added and ``License::`` classifiers were deprecated through :pep:`639`.
 
+- September 2025: The ``import-names`` and ``import-namespaces`` keys were added
+  through :pep:`794`.
+
 
 .. _TOML: https://toml.io

From 85b31ffb80b6d59f752441b07323ab00eea90eaa Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Tue, 7 Oct 2025 11:45:33 -0700
Subject: [PATCH 695/733] Fix glossary link

---
 source/specifications/core-metadata.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index b6d92e6f2..68cc4851f 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -485,8 +485,9 @@ as specified in :doc:`/specifications/license-expression`.
 
 Note that the expression in this field only applies to the
 :term:`Distribution Archive` containing the metadata with this field (e.g.,
-:term:`Source Distribution` or :term:`Wheel`), not the project overall or
-other files related to the project (including other distribution archives).
+:term:`Source Distribution ` or :term:`Wheel`),
+not the project overall or other files related to the project (including other
+distribution archives).
 
 Examples::
 

From e05eb7ac60ae9778da4073d17dcd8260efdd3261 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Wed, 8 Oct 2025 16:09:31 -0700
Subject: [PATCH 696/733] Add npmjs.com to linkcheck regex patterns

---
 source/conf.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/source/conf.py b/source/conf.py
index a8a040d6c..95f6f3421 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -146,6 +146,7 @@
     r"https://math-atlas\.sourceforge\.net/?",
     r"https://click\.palletsprojects\.com/.*",
     r"https://typer\.tiangolo\.com/.*",
+    r"https://www.npmjs.com/.*",
 ]
 linkcheck_retries = 5
 # Ignore anchors for common targets when we know they likely won't be found

From 3d1bcf33a28453b026355a0bfa55a639895d32f5 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 16 Oct 2025 22:57:31 +0000
Subject: [PATCH 697/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 source/specifications/core-metadata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 448e468c4..b49abee71 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -1067,7 +1067,7 @@ History
 
   - Added the ``Import-Name`` field.
   - Added the ``Import-Namespace`` field.
-  
+
 - October 2025: Clarified that ``License-Expression`` applies to the containing
   distribution file and not the project itself.
 

From d470a9fc70fc035f2f35854597f0ccae1501188c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=F0=9F=87=BA=F0=9F=87=A6=20Sviatoslav=20Sydorenko=20=28?=
 =?UTF-8?q?=D0=A1=D0=B2=D1=8F=D1=82=D0=BE=D1=81=D0=BB=D0=B0=D0=B2=20=D0=A1?=
 =?UTF-8?q?=D0=B8=D0=B4=D0=BE=D1=80=D0=B5=D0=BD=D0=BA=D0=BE=29?=
 
Date: Fri, 17 Oct 2025 01:36:37 +0200
Subject: [PATCH 698/733] Match RST underlines with title lengths

---
 source/specifications/core-metadata.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index b49abee71..06562e18d 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -727,7 +727,7 @@ to raise an error when reading an invalid name for older metadata versions.
 .. _core-metadata-import-name:
 
 Import-Name (multiple use)
-===========================
+==========================
 
 .. versionadded:: 2.5
 
@@ -783,7 +783,7 @@ Examples::
 .. _core-metadata-import-namespace:
 
 Import-Namespace (multiple use)
-================================
+===============================
 
 .. versionadded:: 2.5
 

From 1f731d298bc18db1e015b8e37e783ae53acd4780 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 6 Oct 2025 19:05:07 +0000
Subject: [PATCH 699/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/pre-commit/pre-commit-hooks: v5.0.0 → v6.0.0](https://github.com/pre-commit/pre-commit-hooks/compare/v5.0.0...v6.0.0)
- [github.com/astral-sh/ruff-pre-commit: v0.12.2 → v0.13.3](https://github.com/astral-sh/ruff-pre-commit/compare/v0.12.2...v0.13.3)
---
 .pre-commit-config.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index e092c419c..615970dda 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -3,7 +3,7 @@ ci:
 
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v5.0.0
+  rev: v6.0.0
   hooks:
   - id: check-added-large-files
   - id: check-case-conflict
@@ -37,7 +37,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.12.2
+  rev: v0.13.3
   hooks:
     - id: ruff
     - id: ruff-format

From 1b0bd3162a664de2ae2c0628cf3da1cc2eac58fb Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Tue, 12 Aug 2025 15:12:47 -0400
Subject: [PATCH 700/733] simple-repository-api: remove partial TUF section

Signed-off-by: William Woodruff 
---
 .../specifications/simple-repository-api.rst  | 40 -------------------
 1 file changed, 40 deletions(-)

diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
index 4f5bb0043..3b9a2ccac 100644
--- a/source/specifications/simple-repository-api.rst
+++ b/source/specifications/simple-repository-api.rst
@@ -910,46 +910,6 @@ which version+format a specific repository URL was configured for, and when maki
 a request to that server, emit an ``Accept`` header that *only* includes the correct
 content type.
 
-
-TUF Support - PEP 458
----------------------
-
-:pep:`458` requires that all API responses are hashable and that they can be uniquely
-identified by a path relative to the repository root. For a Simple API repository, the
-target path is the Root of our API (e.g. ``/simple/`` on PyPI). This creates
-challenges when accessing the API using a TUF client instead of directly using a
-standard HTTP client, as the TUF client cannot handle the fact that a target could
-have multiple different representations that all hash differently.
-
-:pep:`458` does not specify what the target path should be for the Simple API, but
-TUF requires that the target paths be "file-like", in other words, a path like
-``simple/PROJECT/`` is not acceptable, because it technically points to a
-directory.
-
-The saving grace is that the target path does not *have* to actually match the URL
-being fetched from the Simple API, and it can just be a sigil that the fetching code
-knows how to transform into the actual URL that needs to be fetched. This same thing
-can hold true for other aspects of the actual HTTP request, such as the ``Accept``
-header.
-
-Ultimately figuring out how to map a directory to a filename is out of scope for this
-spec (but it would be in scope for :pep:`458`), and this spec defers making a decision
-about how exactly to represent this inside of :pep:`458` metadata.
-
-However, it appears that the current WIP branch against pip that attempts to implement
-:pep:`458` is using a target path like ``simple/PROJECT/index.html``. This could be
-modified to include the API version and serialization format using something like
-``simple/PROJECT/vnd.pypi.simple.vN.FORMAT``. So the v1 HTML format would be
-``simple/PROJECT/vnd.pypi.simple.v1.html`` and the v1 JSON format would be
-``simple/PROJECT/vnd.pypi.simple.v1.json``.
-
-In this case, since ``text/html`` is an alias to ``application/vnd.pypi.simple.v1+html``
-when interacting through TUF, it likely will make the most sense to normalize to the
-more explicit name.
-
-Likewise the ``latest`` metaversion should not be included in the targets, only
-explicitly declared versions should be supported.
-
 Recommendations
 ---------------
 

From 71295b0302931d34a9d9f1e61a7a3ff0e8185a01 Mon Sep 17 00:00:00 2001
From: github-merge-queue
 <118344674+github-merge-queue@users.noreply.github.com>
Date: Mon, 13 Oct 2025 06:11:04 +0000
Subject: [PATCH 701/733] Update uv_build version to 0.9.2

---
 source/shared/build-backend-tabs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index 9efc8b0d7..c753563dc 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -38,5 +38,5 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["uv_build >= 0.8.17, <0.9.0"]
+        requires = ["uv_build >= 0.9.2, <0.10.0"]
         build-backend = "uv_build"

From db0ef80312ead420058be7c95f4bb63d865ce202 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Thu, 16 Oct 2025 21:30:42 -0400
Subject: [PATCH 702/733] chore(ci): address zizmor findings

This is part 1 of N. The main focus in this PR
is on unpinned references and inadvertent/unnecessary
credential persistence.

Signed-off-by: William Woodruff 
---
 .github/workflows/pr-preview-links.yml        |  2 +-
 .github/workflows/test-translations.yml       | 10 ++++++----
 .github/workflows/test.yml                    |  8 +++++---
 .github/workflows/translation.yml             |  7 ++++---
 .github/workflows/update-uv-build-version.yml |  6 +++---
 .github/workflows/zizmor.yml                  |  6 +++---
 6 files changed, 22 insertions(+), 17 deletions(-)

diff --git a/.github/workflows/pr-preview-links.yml b/.github/workflows/pr-preview-links.yml
index 90ea9cc73..291ec3ad2 100644
--- a/.github/workflows/pr-preview-links.yml
+++ b/.github/workflows/pr-preview-links.yml
@@ -17,6 +17,6 @@ jobs:
   documentation-links:
     runs-on: ubuntu-latest
     steps:
-      - uses: readthedocs/actions/preview@v1
+      - uses: readthedocs/actions/preview@b8bba1484329bda1a3abe986df7ebc80a8950333 # v1.5
         with:
           project-slug: "python-packaging-user-guide"
diff --git a/.github/workflows/test-translations.yml b/.github/workflows/test-translations.yml
index 45dc60aa3..ca6cb08f0 100644
--- a/.github/workflows/test-translations.yml
+++ b/.github/workflows/test-translations.yml
@@ -31,9 +31,10 @@ jobs:
 
     steps:
     - name: Grab the repo src
-      uses: actions/checkout@v4
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         ref: ${{ env.I18N_BRANCH }}
+        persist-credentials: false
 
     - name: List languages
       id: languages
@@ -53,12 +54,13 @@ jobs:
 
     steps:
     - name: Grab the repo src
-      uses: actions/checkout@v4
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         ref: ${{ env.I18N_BRANCH }}
+        persist-credentials: false
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
       with:
         python-version: >-
           3.10
@@ -67,7 +69,7 @@ jobs:
       run: python -m pip install --upgrade nox virtualenv sphinx-lint
 
     - name: Set Sphinx problem matcher
-      uses: sphinx-doc/github-problem-matcher@v1.0
+      uses: sphinx-doc/github-problem-matcher@1f74d6599f4a5e89a20d3c99aab4e6a70f7bda0f # v1.1
 
     - name: Build translated docs in ${{ matrix.language }}
       run: nox -s build -- -q -D language=${{ matrix.language }}
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 172fed713..1f67bad8e 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -31,10 +31,12 @@ jobs:
         - linkcheck
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
         with:
           python-version: "3.11"
           cache: 'pip'
@@ -62,6 +64,6 @@ jobs:
 
     steps:
     - name: Decide whether the needed jobs succeeded or failed
-      uses: re-actors/alls-green@release/v1
+      uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # v1.2.2
       with:
         jobs: ${{ toJSON(needs) }}
diff --git a/.github/workflows/translation.yml b/.github/workflows/translation.yml
index 7cfae2991..1a3f71487 100644
--- a/.github/workflows/translation.yml
+++ b/.github/workflows/translation.yml
@@ -19,14 +19,15 @@ jobs:
 
     steps:
     - name: Grab the repo src
-      uses: actions/checkout@v3
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         fetch-depth: 0  # To reach the common commit
+        persist-credentials: true # For `git push`
     - name: Set up git user as [bot]
       # Refs:
       # * https://github.community/t/github-actions-bot-email-address/17204/6
       # * https://github.com/actions/checkout/issues/13#issuecomment-724415212
-      uses: fregante/setup-git-user@v1.1.0
+      uses: fregante/setup-git-user@024bc0b8e177d7e77203b48dab6fb45666854b35 # v2.0.2
 
     - name: Switch to the translation source branch
       run: |
@@ -51,7 +52,7 @@ jobs:
         git merge '${{ github.event.repository.default_branch }}'
 
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
       with:
         python-version: >-
           3.10
diff --git a/.github/workflows/update-uv-build-version.yml b/.github/workflows/update-uv-build-version.yml
index 8aadc7052..d204bd391 100644
--- a/.github/workflows/update-uv-build-version.yml
+++ b/.github/workflows/update-uv-build-version.yml
@@ -17,17 +17,17 @@ jobs:
       pull-requests: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
       - name: Set up uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@3259c6206f993105e3a61b142c2d97bf4b9ef83d # v7.1.0
       - name: Update uv_build version
         id: update_script
         run: uv run scripts/update_uv_build_version.py
       - # If there are no changes, no pull request will be created and the action exits silently.
         name: Create Pull Request
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           commit-message: Update uv_build version to ${{ steps.update_script.outputs.version }}
diff --git a/.github/workflows/zizmor.yml b/.github/workflows/zizmor.yml
index d99b6473c..6c8c62f7d 100644
--- a/.github/workflows/zizmor.yml
+++ b/.github/workflows/zizmor.yml
@@ -19,12 +19,12 @@ jobs:
       actions: read
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
 
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@3259c6206f993105e3a61b142c2d97bf4b9ef83d # v7.1.0
 
       - name: Run zizmor 🌈
         run: uvx zizmor --format sarif source/guides/github-actions-ci-cd-sample/* > results.sarif
@@ -32,7 +32,7 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Upload SARIF file
-        uses: github/codeql-action/upload-sarif@v3
+        uses: github/codeql-action/upload-sarif@f443b600d91635bebf5b0d9ebc620189c0d6fba5 # v4.30.8
         with:
           sarif_file: results.sarif
           category: zizmor

From e5a97fb662b96ebc3baccbc6765e2afc6a3c5b73 Mon Sep 17 00:00:00 2001
From: William Woodruff 
Date: Thu, 16 Oct 2025 21:38:27 -0400
Subject: [PATCH 703/733] chore(ci): fix some template injections too

Signed-off-by: William Woodruff 
---
 .github/workflows/test-translations.yml | 8 ++++++--
 .github/workflows/translation.yml       | 7 ++++++-
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/test-translations.yml b/.github/workflows/test-translations.yml
index ca6cb08f0..537a8df72 100644
--- a/.github/workflows/test-translations.yml
+++ b/.github/workflows/test-translations.yml
@@ -72,7 +72,9 @@ jobs:
       uses: sphinx-doc/github-problem-matcher@1f74d6599f4a5e89a20d3c99aab4e6a70f7bda0f # v1.1
 
     - name: Build translated docs in ${{ matrix.language }}
-      run: nox -s build -- -q -D language=${{ matrix.language }}
+      run: nox -s build -- -q -D language=${LANGUAGE}
+      env:
+        LANGUAGE: ${{ matrix.language }}
 
     - name: Set Sphinx Lint problem matcher
       if: always()
@@ -80,4 +82,6 @@ jobs:
 
     - name: Lint translation file
       if: always()
-      run: sphinx-lint locales/${{ matrix.language }}/LC_MESSAGES/messages.po
+      run: sphinx-lint locales/${LANGUAGE}/LC_MESSAGES/messages.po
+      env:
+        LANGUAGE: ${{ matrix.language }}
diff --git a/.github/workflows/translation.yml b/.github/workflows/translation.yml
index 1a3f71487..67fcb5edf 100644
--- a/.github/workflows/translation.yml
+++ b/.github/workflows/translation.yml
@@ -17,6 +17,9 @@ jobs:
     runs-on: ubuntu-latest
     if: github.repository_owner == 'pypa'
 
+    permissions:
+      contents: write # to push to I18N_BRANCH
+
     steps:
     - name: Grab the repo src
       uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
@@ -49,7 +52,9 @@ jobs:
       run: |
         sh -x
 
-        git merge '${{ github.event.repository.default_branch }}'
+        git merge "${DEFAULT_BRANCH}"
+      env:
+        DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
 
     - name: Set up Python
       uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0

From 1700f858e4066beda60c1fab2650013b9a789af9 Mon Sep 17 00:00:00 2001
From: Stephen Rosen 
Date: Sat, 27 Sep 2025 00:21:18 -0500
Subject: [PATCH 704/733] Convert 'Dependency Groups' to lowercase

Outside of titles and other contexts, convert this term to lowercase.
This usage better matches other terms defined in the packaging
specifications, such as "script metadata" and "dependency specifiers".

For reference, this change was inspired by:
https://github.com/pypa/packaging.python.org/pull/1847#discussion_r2266571023
---
 source/specifications/dependency-groups.rst | 26 ++++++++++-----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/source/specifications/dependency-groups.rst b/source/specifications/dependency-groups.rst
index 22e4cba0d..a35afb475 100644
--- a/source/specifications/dependency-groups.rst
+++ b/source/specifications/dependency-groups.rst
@@ -4,15 +4,15 @@
 Dependency Groups
 =================
 
-This specification defines Dependency Groups, a mechanism for storing package
+This specification defines dependency groups, a mechanism for storing package
 requirements in ``pyproject.toml`` files such that they are not included in
 project metadata when it is built.
 
-Dependency Groups are suitable for internal development use-cases like linting
+Dependency groups are suitable for internal development use-cases like linting
 and testing, as well as for projects which are not built for distribution, like
 collections of related scripts.
 
-Fundamentally, Dependency Groups should be thought of as being a standardized
+Fundamentally, dependency groups should be thought of as being a standardized
 subset of the capabilities of ``requirements.txt`` files (which are
 ``pip``-specific).
 
@@ -38,7 +38,7 @@ and a similar table which defines ``docs``, ``test``, and ``coverage`` groups::
 The ``[dependency-groups]`` Table
 ---------------------------------
 
-Dependency Groups are defined as a table in ``pyproject.toml`` named
+Dependency groups are defined as a table in ``pyproject.toml`` named
 ``dependency-groups``. The ``dependency-groups`` table contains an arbitrary
 number of user-defined keys, each of which has, as its value, a list of
 requirements.
@@ -103,9 +103,9 @@ Package Building
 
 Build backends MUST NOT include Dependency Group data in built distributions as
 package metadata. This means that sdist ``PKG-INFO`` and wheel ``METADATA``
-files should not include referenceable fields containing Dependency Groups.
+files should not include referenceable fields containing dependency groups.
 
-It is, however, valid to use Dependency Groups in the evaluation of dynamic
+It is, however, valid to use dependency groups in the evaluation of dynamic
 metadata, and ``pyproject.toml`` files included in sdists will still contain
 ``[dependency-groups]``. However, the table's contents are not part of a built
 package's interfaces.
@@ -114,28 +114,28 @@ Installing Dependency Groups & Extras
 -------------------------------------
 
 There is no syntax or specification-defined interface for installing or
-referring to Dependency Groups. Tools are expected to provide dedicated
+referring to dependency groups. Tools are expected to provide dedicated
 interfaces for this purpose.
 
 Tools MAY choose to provide the same or similar interfaces for interacting
-with Dependency Groups as they do for managing extras. Tools authors are
+with dependency groups as they do for managing extras. Tools authors are
 advised that the specification does not forbid having an extra whose name
 matches a Dependency Group. Separately, users are advised to avoid creating
-Dependency Groups whose names match extras, and tools MAY treat such matching
+dependency groups whose names match extras, and tools MAY treat such matching
 as an error.
 
 Validation and Compatibility
 ----------------------------
 
-Tools supporting Dependency Groups may want to validate data before using it.
+Tools supporting dependency groups may want to validate data before using it.
 When implementing such validation, authors should be aware of the possibility
 of future extensions to the specification, so that they do not unnecessarily
 emit errors or warnings.
 
 Tools SHOULD error when evaluating or processing unrecognized data in
-Dependency Groups.
+dependency groups.
 
-Tools SHOULD NOT eagerly validate the contents of *all* Dependency Groups
+Tools SHOULD NOT eagerly validate the contents of *all* dependency groups
 unless they have a need to do so.
 
 This means that in the presence of the following data, most tools should allow
@@ -151,7 +151,7 @@ the ``foo`` group to be used and only error if the ``bar`` group is used:
 
     There are several known cases of tools which have good cause to be
     stricter. Linters and validators are an example, as their purpose is to
-    validate the contents of all Dependency Groups.
+    validate the contents of all dependency groups.
 
 Reference Implementation
 ========================

From c6f6be53438286173bb3d2417103a2b91bce4f2f Mon Sep 17 00:00:00 2001
From: woodruffw <3059210+woodruffw@users.noreply.github.com>
Date: Tue, 21 Oct 2025 17:54:46 +0000
Subject: [PATCH 705/733] Update uv_build version to 0.9.5

---
 source/shared/build-backend-tabs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index c753563dc..b80d92b39 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -38,5 +38,5 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["uv_build >= 0.9.2, <0.10.0"]
+        requires = ["uv_build >= 0.9.5, <0.10.0"]
         build-backend = "uv_build"

From 1b5fa563617a71b1ab9b49f959004ee1fe3bcad6 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Mon, 27 Oct 2025 14:55:37 -0700
Subject: [PATCH 706/733] Update import name guidelines to use 'SHOULD' for
 intermediate names

---
 source/specifications/core-metadata.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index 06562e18d..a43d92ff6 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -745,7 +745,7 @@ the project.
 
 Projects SHOULD list all the shortest import names that are exclusively provided
 by the project. If any of the shortest names are dotted names, all intervening
-names from that name to the top-level name should also be listed appropriately
+names from that name to the top-level name SHOULD also be listed appropriately
 in ``Import-Name`` and/or ``Import-Namespace``.
 
 If a project lists the same name in both ``Import-Name`` and
@@ -800,7 +800,7 @@ project.
 
 Projects SHOULD list all the shortest import names that are exclusively provided
 by the project. If any of the shortest names are dotted names, all intervening
-names from that name to the top-level name should also be listed appropriately
+names from that name to the top-level name SHOULD also be listed appropriately
 in ``Import-Name`` and/or ``Import-Namespace``.
 
 The import names listed in this field MUST be importable when the project is

From 4be49e6632a5987ab438d605ede1bd37c04e994c Mon Sep 17 00:00:00 2001
From: Henry Schreiner 
Date: Tue, 28 Oct 2025 10:14:08 -0400
Subject: [PATCH 707/733] fix: links to pip's pyproject.toml pages are dead
 with 25.3

Signed-off-by: Henry Schreiner 
---
 source/guides/modernize-setup-py-project.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/guides/modernize-setup-py-project.rst b/source/guides/modernize-setup-py-project.rst
index 5b6ab3c26..1f71d1973 100644
--- a/source/guides/modernize-setup-py-project.rst
+++ b/source/guides/modernize-setup-py-project.rst
@@ -67,7 +67,7 @@ For more details:
 
 * :ref:`distributing-packages`
 * :ref:`pyproject-build-system-table`
-* :doc:`pip:reference/build-system/pyproject-toml`
+* :doc:`pip:reference/build-system`
 
 
 How to handle additional build-time dependencies?
@@ -128,7 +128,7 @@ For some projects this isolation is unwanted and it can be deactivated as follow
 
 For more details:
 
-* :doc:`pip:reference/build-system/pyproject-toml`
+* :doc:`pip:reference/build-system`
 
 
 How to handle packaging metadata?
@@ -244,5 +244,5 @@ Where to read more about this?
 ==============================
 
 * :ref:`pyproject-toml-spec`
-* :doc:`pip:reference/build-system/pyproject-toml`
+* :doc:`pip:reference/build-system`
 * :doc:`setuptools:build_meta`

From 4e8a3d24f166250ce1e9249d39f644526542633c Mon Sep 17 00:00:00 2001
From: Ben Tucker 
Date: Fri, 7 Nov 2025 16:54:35 +0000
Subject: [PATCH 708/733] docs: update spec for the macOS platform tag

---
 source/specifications/platform-compatibility-tags.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index 0502c8c03..fcb317cfe 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -199,10 +199,11 @@ artefact of Apple's official macOS naming scheme). The schema for compatibility
 tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the wheel is compatible
 with macOS ``x.y`` or later on the architecture ``arch``.
 
-The values of ``x`` and ``y`` correspond to the major and minor version number of
-the macOS release, respectively. They must both be positive integers, with the
-``x`` value being ``>= 10``. The version number always includes a major *and*
-minor version, even if Apple's official version numbering only refers to
+The values of ``x`` and ``y`` correspond to the major and minor version number
+of the macOS release, respectively. They must both be positive integers, with
+the ``x`` value being either ``10 <= x <= 15``, or ``>=26`` and corresponding
+to the year of the macOS release. The version number always includes a major
+*and* minor version, even if Apple's official version numbering only refers to
 the major value. For example, ``macosx_11_0_arm64`` indicates compatibility
 with macOS 11 or later.
 

From ac13541a8e340996da605841e0ca278eb5bc2eb9 Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Sun, 9 Nov 2025 02:51:38 +0000
Subject: [PATCH 709/733] Allow errors for missing `[build-system]` table with
 no metadata

Permit installers to present an error if the working directory does not
seem like a location that the user intended to install from.
---
 source/specifications/pyproject-toml.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst
index 74dbe34e3..48f35599e 100644
--- a/source/specifications/pyproject-toml.rst
+++ b/source/specifications/pyproject-toml.rst
@@ -61,6 +61,10 @@ table then the default values as specified above should be used.
 If the table is specified but is missing required fields then the tool
 should consider it an error.
 
+Tools may choose to present an error to the user if the file exists,
+``[build-system]`` table is missing, and there is no clear indication
+that the project should be built (e.g., no setup.py/setup.cfg or other
+build configuration files, and no ``[project]`` table).
 
 To provide a type-specific representation of the resulting data from
 the TOML file for illustrative purposes only, the following

From 82f35b5a2abcf1989574e9363cd2c3a5a6c1835f Mon Sep 17 00:00:00 2001
From: Pradyun Gedam 
Date: Sun, 9 Nov 2025 02:57:19 +0000
Subject: [PATCH 710/733] Drop warehouse's intersphinx entry

Warehouse is not referenced from these docs and their docs have moved to
mkdocs-material.
---
 source/conf.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/source/conf.py b/source/conf.py
index 95f6f3421..030a167e4 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -210,7 +210,6 @@
     "tox": ("https://tox.wiki/en/latest/", None),
     "twine": ("https://twine.readthedocs.io/en/stable/", None),
     "virtualenv": ("https://virtualenv.pypa.io/en/stable/", None),
-    "warehouse": ("https://warehouse.pypa.io/", None),
 }
 
 # -- Options for todo extension --------------------------------------------------------

From 44af965c54008fe7bdd16ce7522e1b5398041c9c Mon Sep 17 00:00:00 2001
From: github-merge-queue
 <118344674+github-merge-queue@users.noreply.github.com>
Date: Mon, 10 Nov 2025 06:11:10 +0000
Subject: [PATCH 711/733] Update uv_build version to 0.9.8

---
 source/shared/build-backend-tabs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index b80d92b39..621eb4177 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -38,5 +38,5 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["uv_build >= 0.9.5, <0.10.0"]
+        requires = ["uv_build >= 0.9.8, <0.10.0"]
         build-backend = "uv_build"

From dc58ce94e84fa8e0b99ed5031d9b723951f3e9f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns?= 
Date: Wed, 12 Nov 2025 13:45:06 +0000
Subject: [PATCH 712/733] nox: allow passing arguments to linkcheck
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Filipe Laíns 
---
 noxfile.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/noxfile.py b/noxfile.py
index 698e82f9d..484a8d39a 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -89,6 +89,7 @@ def linkcheck(session):
         "--keep-going",  # be strict
         "source",  # where the rst files are located
         "build",  # where to put the check output
+        *session.posargs,
     )
 
 

From 7a8eb853713eea644af3d5885d88c2d0e3c7390f Mon Sep 17 00:00:00 2001
From: github-merge-queue
 <118344674+github-merge-queue@users.noreply.github.com>
Date: Mon, 17 Nov 2025 06:11:01 +0000
Subject: [PATCH 713/733] Update uv_build version to 0.9.9

---
 source/shared/build-backend-tabs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index 621eb4177..23918e388 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -38,5 +38,5 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["uv_build >= 0.9.8, <0.10.0"]
+        requires = ["uv_build >= 0.9.9, <0.10.0"]
         build-backend = "uv_build"

From 761f6bdc1ebfd6885488dab57b8f4f4b9ae0ceb7 Mon Sep 17 00:00:00 2001
From: konstin 
Date: Fri, 21 Nov 2025 11:21:51 +0100
Subject: [PATCH 714/733] Document `macosx_0_{y}_{arch}` pattern

Following https://discuss.python.org/t/document-that-macos-platform-tags-use-minor-version-0-for-macos-11/104616:

 * Document that for macOS 11 and later, the platform tag is `macosx_0_{y}_{arch}`
 * Document that platform tags may change over time.
---
 .../platform-compatibility-tags.rst           | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/source/specifications/platform-compatibility-tags.rst b/source/specifications/platform-compatibility-tags.rst
index fcb317cfe..b4c14a4c0 100644
--- a/source/specifications/platform-compatibility-tags.rst
+++ b/source/specifications/platform-compatibility-tags.rst
@@ -82,6 +82,11 @@ decide how to best use the ABI tag.
 Platform Tag
 ============
 
+.. important::
+    Platform tags are dependent on the versioning of the operating system or
+    platform they represent and may change over time as the underlying platform
+    changes its versioning.
+
 Basic platform tags
 -------------------
 
@@ -199,13 +204,13 @@ artefact of Apple's official macOS naming scheme). The schema for compatibility
 tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the wheel is compatible
 with macOS ``x.y`` or later on the architecture ``arch``.
 
-The values of ``x`` and ``y`` correspond to the major and minor version number
-of the macOS release, respectively. They must both be positive integers, with
-the ``x`` value being either ``10 <= x <= 15``, or ``>=26`` and corresponding
-to the year of the macOS release. The version number always includes a major
-*and* minor version, even if Apple's official version numbering only refers to
-the major value. For example, ``macosx_11_0_arm64`` indicates compatibility
-with macOS 11 or later.
+For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` corresponds
+to the minor version number of the macOS release. For macOS 11 and higher, the
+tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds to the major
+version number of the macOS release. Following the published macOS major
+versions, the ``x`` value is either ``10 <= x <= 15``, or ``>=26`` and
+corresponding to the year of the macOS release. For example,
+``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later.
 
 macOS binaries can be compiled for a single architecture, or can include support
 for multiple architectures in the same binary (sometimes called "fat" binaries).

From 7a7d7ba624c842b224ed904cd0c7bae1dfda3f56 Mon Sep 17 00:00:00 2001
From: Damian Shaw 
Date: Sat, 22 Nov 2025 12:31:58 -0500
Subject: [PATCH 715/733] Specify arbitrary equality case insensitivity.

---
 source/specifications/version-specifiers.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index c0b544160..f620c9054 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -1016,8 +1016,9 @@ Arbitrary equality
 
 Arbitrary equality comparisons are simple string equality operations which do
 not take into account any of the semantic information such as zero padding or
-local versions. This operator also does not support prefix matching as the
-``==`` operator does.
+local versions. The comparison MUST treat ASCII letters case-insensitively, e.g.
+by lowercasing, and is unspecified for non-ASCII text. This operator also does
+not support prefix matching as the ``==`` operator does.
 
 The primary use case for arbitrary equality is to allow for specifying a
 version which cannot otherwise be represented by this specification. This operator is
@@ -1271,3 +1272,4 @@ History
 - August 2014: This specification was approved through :pep:`440`.
 - May 2025: Clarify that development releases are a form of pre-release when
   they are handled.
+- Nov 2025: Specify arbitrary equality case insensitivity.

From 5e9c85eefa28bb369c1187e61504a8c78d55a054 Mon Sep 17 00:00:00 2001
From: Stefaan Lippens 
Date: Sun, 23 Nov 2025 21:42:54 +0100
Subject: [PATCH 716/733] Rename publish-to-test-pypi.yml to
 publish-to-pypi.yml #1935

---
 ...lish-to-test-pypi.yml => publish-to-pypi.yml} |  0
 ...ases-using-github-actions-ci-cd-workflows.rst | 16 ++++++++--------
 2 files changed, 8 insertions(+), 8 deletions(-)
 rename source/guides/github-actions-ci-cd-sample/{publish-to-test-pypi.yml => publish-to-pypi.yml} (100%)

diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-pypi.yml
similarity index 100%
rename from source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
rename to source/guides/github-actions-ci-cd-sample/publish-to-pypi.yml
diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
index e9f601e03..a3d893c9f 100644
--- a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
+++ b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
@@ -87,13 +87,13 @@ Creating a workflow definition
 GitHub CI/CD workflows are declared in YAML files stored in the
 ``.github/workflows/`` directory of your repository.
 
-Let's create a ``.github/workflows/publish-to-test-pypi.yml``
+Let's create a ``.github/workflows/publish-to-pypi.yml``
 file.
 
 Start it with a meaningful name and define the event that
 should make GitHub run this workflow:
 
-.. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
+.. literalinclude:: github-actions-ci-cd-sample/publish-to-pypi.yml
    :language: yaml
    :end-before: jobs:
 
@@ -107,7 +107,7 @@ build the distribution packages.
 First, we'll define the job for building the dist packages of
 your project and storing them for later use:
 
-.. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
+.. literalinclude:: github-actions-ci-cd-sample/publish-to-pypi.yml
    :language: yaml
    :start-at: jobs:
    :end-before: Install pypa/build
@@ -119,7 +119,7 @@ And now we can build the dists from source and store them.
 In this example, we'll use the ``build`` package.
 So add this to the steps list:
 
-.. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
+.. literalinclude:: github-actions-ci-cd-sample/publish-to-pypi.yml
    :language: yaml
    :start-at: Install pypa/build
    :end-before: publish-to-pypi
@@ -136,7 +136,7 @@ UI nicely. Additionally, it allows acquiring an OpenID Connect token
 that the ``pypi-publish`` actions needs to implement secretless
 Trusted Publishing to PyPI.
 
-.. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
+.. literalinclude:: github-actions-ci-cd-sample/publish-to-pypi.yml
    :language: yaml
    :start-after: path: dist/
    :end-before: steps:
@@ -149,7 +149,7 @@ Publishing the distribution to PyPI
 
 Finally, add the following steps at the end:
 
-.. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
+.. literalinclude:: github-actions-ci-cd-sample/publish-to-pypi.yml
    :language: yaml
    :start-after: id-token: write
    :end-before:  publish-to-testpypi:
@@ -175,7 +175,7 @@ Now, repeat these steps and create another job for
 publishing to the TestPyPI package index under the ``jobs``
 section:
 
-.. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
+.. literalinclude:: github-actions-ci-cd-sample/publish-to-pypi.yml
    :language: yaml
    :start-at: publish-to-testpypi
 
@@ -191,7 +191,7 @@ This paragraph showcases the whole workflow after following the above guide.
 
 .. collapse:: Click here to display the entire GitHub Actions CI/CD workflow definition
 
-    .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
+    .. literalinclude:: github-actions-ci-cd-sample/publish-to-pypi.yml
        :language: yaml
 
 That's all, folks!

From 43060740c4109e24f8dd6902b731d9d288fc5c21 Mon Sep 17 00:00:00 2001
From: github-merge-queue
 <118344674+github-merge-queue@users.noreply.github.com>
Date: Mon, 24 Nov 2025 06:10:56 +0000
Subject: [PATCH 717/733] Update uv_build version to 0.9.11

---
 source/shared/build-backend-tabs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index 23918e388..c732ed2e9 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -38,5 +38,5 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["uv_build >= 0.9.9, <0.10.0"]
+        requires = ["uv_build >= 0.9.11, <0.10.0"]
         build-backend = "uv_build"

From 97a72c521adb07961e4766039a30bc3e0159ac09 Mon Sep 17 00:00:00 2001
From: Damian Shaw 
Date: Tue, 25 Nov 2025 14:37:04 -0500
Subject: [PATCH 718/733] Update source/specifications/version-specifiers.rst

Co-authored-by: Alyssa Coghlan 
---
 source/specifications/version-specifiers.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst
index f620c9054..13015794f 100644
--- a/source/specifications/version-specifiers.rst
+++ b/source/specifications/version-specifiers.rst
@@ -1272,4 +1272,4 @@ History
 - August 2014: This specification was approved through :pep:`440`.
 - May 2025: Clarify that development releases are a form of pre-release when
   they are handled.
-- Nov 2025: Specify arbitrary equality case insensitivity.
+- Nov 2025: Make arbitrary equality case insensitivity explicit.

From 22d9ddf8899b615ee51fe46f0cd9dff8c108bcbf Mon Sep 17 00:00:00 2001
From: Benjamin Rodenberg 
Date: Thu, 6 Nov 2025 13:18:09 +0100
Subject: [PATCH 719/733] Fix typo in creating-command-line-tools.rst

---
 source/guides/creating-command-line-tools.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/guides/creating-command-line-tools.rst b/source/guides/creating-command-line-tools.rst
index 72e3e37ef..cbe8b3bb0 100644
--- a/source/guides/creating-command-line-tools.rst
+++ b/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`:

From 870e6fe9799b8885d547dc88cc2c2b62057f3eb0 Mon Sep 17 00:00:00 2001
From: Brett Cannon 
Date: Mon, 27 Jan 2025 16:57:03 -0800
Subject: [PATCH 720/733] Fix the use of underscores when a hyphen is more
 accurate

---
 source/specifications/core-metadata.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index a43d92ff6..eb9a03ff6 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -52,9 +52,9 @@ Metadata-Version
 Version of the file format; legal values are "1.0", "1.1", "1.2", "2.1",
 "2.2", "2.3", "2.4", and "2.5".
 
-Automated tools consuming metadata SHOULD warn if ``metadata_version`` is
+Automated tools consuming metadata SHOULD warn if ``metadata-version`` is
 greater than the highest version they support, and MUST fail if
-``metadata_version`` has a greater major version than the highest
+``metadata-version`` has a greater major version than the highest
 version they support (as described in the
 :ref:`Version specifier specification `,
 the major version is the value before the first dot).

From 2ee73e02c90f7d7429e0e80120380aee759ce12e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns?= 
Date: Wed, 12 Nov 2025 13:37:02 +0000
Subject: [PATCH 721/733] Restore linkcheck for specs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Filipe Laíns 
---
 pug_sphinx_extensions/__init__.py | 76 +++++++++++++++++++++++++++++++
 source/conf.py                    | 10 ++--
 2 files changed, 82 insertions(+), 4 deletions(-)
 create mode 100644 pug_sphinx_extensions/__init__.py

diff --git a/pug_sphinx_extensions/__init__.py b/pug_sphinx_extensions/__init__.py
new file mode 100644
index 000000000..ae495bb60
--- /dev/null
+++ b/pug_sphinx_extensions/__init__.py
@@ -0,0 +1,76 @@
+import os
+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.
+    """
+    local_uri = uri
+    parsed = urllib.parse.urlparse(uri)
+    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}')
+    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,
+    }
diff --git a/source/conf.py b/source/conf.py
index d18faf662..ccb828b6e 100644
--- a/source/conf.py
+++ b/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/.*",
@@ -162,9 +167,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

From 0cef54ccf1a3cf5dc4302e66e57740f2ea046cd3 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 12 Nov 2025 14:23:22 +0000
Subject: [PATCH 722/733] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 pug_sphinx_extensions/__init__.py | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/pug_sphinx_extensions/__init__.py b/pug_sphinx_extensions/__init__.py
index ae495bb60..82abe6997 100644
--- a/pug_sphinx_extensions/__init__.py
+++ b/pug_sphinx_extensions/__init__.py
@@ -5,7 +5,7 @@
 import sphinx.util.logging
 
 
-DOMAIN = 'packaging.python.org'
+DOMAIN = "packaging.python.org"
 
 
 logger = sphinx.util.logging.getLogger(__name__)
@@ -35,14 +35,14 @@ def resolve_local_html_link(app: sphinx.application.Sphinx, url_path: str) -> st
     for entry in app.config.html_extra_path:
         candidate = (app.confdir / entry / url_path).resolve()
         if candidate.is_dir():
-            candidate = candidate / 'index.html'
+            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:
+    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
@@ -55,22 +55,22 @@ def rewrite_local_uri(app: sphinx.application.Sphinx, uri: str) -> str:
     """
     local_uri = uri
     parsed = urllib.parse.urlparse(uri)
-    if parsed.hostname == DOMAIN and parsed.path.startswith('/en/latest/'):
-        document = parsed.path.removeprefix('/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)'
+            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}')
+        logger.debug(f"Replacing linkcheck URL {uri!r} with {local_uri!r}")
     return local_uri
 
 
 def setup(app: sphinx.application.Sphinx) -> dict[str, bool]:
-    app.connect('linkcheck-process-uri', rewrite_local_uri)
+    app.connect("linkcheck-process-uri", rewrite_local_uri)
 
     return {
-        'parallel_read_safe': True,
-        'parallel_write_safe': True,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
     }

From c2fe979382110513c6515c4f7c14d6f922f76846 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns?= 
Date: Fri, 14 Nov 2025 22:41:54 +0000
Subject: [PATCH 723/733] Resolve local relative links to html_extra_path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Filipe Laíns 
---
 pug_sphinx_extensions/__init__.py | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/pug_sphinx_extensions/__init__.py b/pug_sphinx_extensions/__init__.py
index 82abe6997..00d91da3c 100644
--- a/pug_sphinx_extensions/__init__.py
+++ b/pug_sphinx_extensions/__init__.py
@@ -1,4 +1,5 @@
 import os
+import pathlib
 import urllib
 
 import sphinx.application
@@ -52,9 +53,12 @@ def resolve_local_html_link(app: sphinx.application.Sphinx, url_path: str) -> st
 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)
@@ -64,6 +68,12 @@ def rewrite_local_uri(app: sphinx.application.Sphinx, uri: str) -> str:
             "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
 
 

From 5a56b2e46ef12ff3fed57b78c79622d357c90a9e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns?= 
Date: Wed, 19 Nov 2025 12:51:42 +0000
Subject: [PATCH 724/733] Add myself to the pug_sphinx_extensions codeowners
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Filipe Laíns 
---
 .github/CODEOWNERS | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index ecd85064f..0b7c7b289 100644
--- a/.github/CODEOWNERS
+++ b/.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

From 9daa2ef1184a805e6634ab16f8bd6560cd1c5d2a Mon Sep 17 00:00:00 2001
From: Damian Shaw 
Date: Mon, 1 Dec 2025 20:30:45 -0500
Subject: [PATCH 725/733] Fix grammar for arbitrary equality comparisons in
 version specifiers

---
 source/specifications/dependency-specifiers.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index d9466c26e..99886563c 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -63,7 +63,7 @@ Versions may be specified according to the rules of the
 :ref:`Version specifier specification `. (Note:
 URI is defined in :rfc:`std-66 <3986>`)::
 
-    version_cmp   = wsp* '<' | '<=' | '!=' | '==' | '>=' | '>' | '~=' | '==='
+    version_cmp   = wsp* '<=' | '<' | '!=' | '===' | '==' | '>=' | '>' | '~='
     version       = wsp* ( letterOrDigit | '-' | '_' | '.' | '*' | '+' | '!' )+
     version_one   = version_cmp version wsp*
     version_many  = version_one (',' version_one)* (',' wsp*)?
@@ -339,7 +339,7 @@ Complete Grammar
 The complete parsley grammar::
 
     wsp           = ' ' | '\t'
-    version_cmp   = wsp* <'<=' | '<' | '!=' | '==' | '>=' | '>' | '~=' | '==='>
+    version_cmp   = wsp* <'<=' | '<' | '!=' | '===' | '==' | '>=' | '>' | '~='>
     version       = wsp* <( letterOrDigit | '-' | '_' | '.' | '*' | '+' | '!' )+>
     version_one   = version_cmp:op version:v wsp* -> (op, v)
     version_many  = version_one:v1 (',' version_one)*:v2 (',' wsp*)? -> [v1] + v2
@@ -529,6 +529,8 @@ History
 - August 2025: The suggested name validation regex was fixed to match the field
   specification (it previously finished with ``$`` instead of ``\Z``,
   incorrectly permitting trailing newlines)
+- December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary
+  equality comparisons to be parsed.
 
 
 References

From d255619f85b966d6fa7e77855a706638d51bf17a Mon Sep 17 00:00:00 2001
From: Gene Wood 
Date: Tue, 2 Dec 2025 13:23:06 -0800
Subject: [PATCH 726/733] Update versions of GitHub actions used

This updates the versions of the GitHub actions used to the current major releases.
---
 .../github-actions-ci-cd-sample/publish-to-pypi.yml    | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-pypi.yml
index 8813a0392..155f82555 100644
--- a/source/guides/github-actions-ci-cd-sample/publish-to-pypi.yml
+++ b/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/

From ad086b91742c9cc22e6db9d490fbb35646dda524 Mon Sep 17 00:00:00 2001
From: Petr Viktorin 
Date: Thu, 11 Dec 2025 16:15:57 +0100
Subject: [PATCH 727/733] Add subheading for Build backends for extension
 modules

---
 source/guides/tool-recommendations.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
index 1ba36ed61..bf8d93d5a 100644
--- a/source/guides/tool-recommendations.rst
+++ b/source/guides/tool-recommendations.rst
@@ -109,6 +109,11 @@ Do **not** use :ref:`distutils`, which is deprecated, and has been removed from
 the standard library in Python 3.12, although it still remains available from
 setuptools.
 
+.. _extension-module-tool-recommendations:
+
+Build backends for extension modules
+------------------------------------
+
 For packages with :term:`extension modules `, it is best to use
 a build system with dedicated support for the language the extension is written in,
 for example:

From 3e4b6ec014e6e722e493322b0e755c5b35facf7a Mon Sep 17 00:00:00 2001
From: github-merge-queue
 <118344674+github-merge-queue@users.noreply.github.com>
Date: Mon, 15 Dec 2025 06:12:11 +0000
Subject: [PATCH 728/733] Update uv_build version to 0.9.17

---
 source/shared/build-backend-tabs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index c732ed2e9..f81423ca1 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -38,5 +38,5 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["uv_build >= 0.9.11, <0.10.0"]
+        requires = ["uv_build >= 0.9.17, <0.10.0"]
         build-backend = "uv_build"

From 0f6ac8de0005553909725085d90cca807bd50888 Mon Sep 17 00:00:00 2001
From: Henry Schreiner 
Date: Sun, 21 Dec 2025 18:37:01 -0500
Subject: [PATCH 729/733] fix: bitbucket org gone

Signed-off-by: Henry Schreiner 
---
 source/glossary.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/glossary.rst b/source/glossary.rst
index 630513868..40c041f4c 100644
--- a/source/glossary.rst
+++ b/source/glossary.rst
@@ -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 `, host projects on `GitHub
-        `_ and `Bitbucket
-        `_, and discuss issues on the
+        `_, and discuss issues on the
         `distutils-sig mailing list
         `_
 	and `the Python Discourse forum `__.

From ca4013df271d79c79c1424a047805f92e3d8e7ed Mon Sep 17 00:00:00 2001
From: github-merge-queue
 <118344674+github-merge-queue@users.noreply.github.com>
Date: Mon, 22 Dec 2025 06:11:58 +0000
Subject: [PATCH 730/733] Update uv_build version to 0.9.18

---
 source/shared/build-backend-tabs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index f81423ca1..70f5733d0 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -38,5 +38,5 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["uv_build >= 0.9.17, <0.10.0"]
+        requires = ["uv_build >= 0.9.18, <0.10.0"]
         build-backend = "uv_build"

From 90034b530d029679155d3c7ce4ba50f8ade19aca Mon Sep 17 00:00:00 2001
From: Henry Schreiner 
Date: Mon, 22 Dec 2025 17:33:14 -0500
Subject: [PATCH 731/733] docs: fix links to Travis

Signed-off-by: Henry Schreiner 
---
 source/guides/supporting-multiple-python-versions.rst | 2 +-
 source/guides/supporting-windows-using-appveyor.rst   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/guides/supporting-multiple-python-versions.rst b/source/guides/supporting-multiple-python-versions.rst
index 8c128ed91..7e945aa53 100644
--- a/source/guides/supporting-multiple-python-versions.rst
+++ b/source/guides/supporting-multiple-python-versions.rst
@@ -62,7 +62,7 @@ of many continuous-integration systems. There are two hosted services which
 when used in conjunction provide automated testing across Linux, Mac and
 Windows:
 
-  - `Travis CI `_ provides both a Linux and a macOS
+  - `Travis CI `_ provides both a Linux and a macOS
     environment. The Linux environment is Ubuntu 12.04 LTS Server Edition 64 bit
     while the macOS is 10.9.2 at the time of writing.
   - `Appveyor `_ provides a Windows environment
diff --git a/source/guides/supporting-windows-using-appveyor.rst b/source/guides/supporting-windows-using-appveyor.rst
index 0044d8c5e..e884dd976 100644
--- a/source/guides/supporting-windows-using-appveyor.rst
+++ b/source/guides/supporting-windows-using-appveyor.rst
@@ -237,6 +237,6 @@ For reference, the SDK setup support script is listed here:
    :linenos:
 
 .. _Appveyor: https://www.appveyor.com/
-.. _Travis: https://travis-ci.org/
+.. _Travis: https://travis-ci.com/
 .. _GitHub: https://github.com
 .. _Bitbucket: https://bitbucket.org/

From b14f944a186f2b27b0a89f5a710a63cd71461bd5 Mon Sep 17 00:00:00 2001
From: github-merge-queue
 <118344674+github-merge-queue@users.noreply.github.com>
Date: Mon, 5 Jan 2026 06:13:45 +0000
Subject: [PATCH 732/733] Update uv_build version to 0.9.21

---
 source/shared/build-backend-tabs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/shared/build-backend-tabs.rst b/source/shared/build-backend-tabs.rst
index 70f5733d0..64ef0bf2f 100644
--- a/source/shared/build-backend-tabs.rst
+++ b/source/shared/build-backend-tabs.rst
@@ -38,5 +38,5 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["uv_build >= 0.9.18, <0.10.0"]
+        requires = ["uv_build >= 0.9.21, <0.10.0"]
         build-backend = "uv_build"

From 712f24a877b533bcca4a637f6a1cf165edf4fdc1 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 5 Jan 2026 18:37:47 +0000
Subject: [PATCH 733/733] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.13.3 → v0.14.10](https://github.com/astral-sh/ruff-pre-commit/compare/v0.13.3...v0.14.10)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 615970dda..47b864808 100644
--- a/.pre-commit-config.yaml
+++ b/.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