Merge branch 'main' into remove-setuptools-wheel-upgrade

Author: ncoghlan

source/conf.py

@@ -156,6 +156,10 @@
     r"https://click\.palletsprojects\.com/.*",
     r"https://typer\.tiangolo\.com/.*",
     r"https://www.npmjs.com/.*",
+    r"https://docutils\.sourceforge\.io/.*",
+    # Temporarily ignored due to expired TLS cert.
+    # Ref: https://github.com/pypa/packaging.python.org/issues/1998
+    r"https://blog\.ganssle\.io/.*",
 ]
 linkcheck_retries = 5
 # Ignore anchors for common targets when we know they likely won't be found

source/discussions/versioning.rst

@@ -27,7 +27,7 @@ examples of version numbers [#version-examples]_:
 - 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``
+- A version with an epoch (discouraged): ``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,
@@ -46,13 +46,14 @@ 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.
-
+Finally, epochs were intended to fix the sorting order when changing the
+versioning scheme. For example, if a project was using calendar versioning, with
+versions like ``23.12``, and switched to semantic versioning, with versions like
+``1.0``, the comparison between ``1.0`` and ``23.12`` would go the wrong way. To
+correct this, the new version numbers would have an explicit epoch, as in
+``1!1.0``, in order to be treated as more recent than the old version numbers.
+However, this is discouraged, and it is preferable to use a higher version
+number that is unlikely to cause user confusion, such as ``100.0``.
 
 
 Semantic versioning vs. calendar versioning

source/glossary.rst

@@ -14,7 +14,7 @@ Glossary
 
     Build Backend
 
-        A library that takes a source tree
+        A library that takes a :term:`source tree <Project Source Tree>`
         and builds a :term:`source distribution <Source Distribution (or "sdist")>` or
         :term:`built distribution <Built Distribution>` from it.
         The build is delegated to the backend by a

source/guides/analyzing-pypi-package-downloads.rst

@@ -333,6 +333,14 @@ Usage:
 The `pandas-gbq`_ project allows for accessing query results via `Pandas`_.
 
 
+``ClickPy``
+-----------
+
+The `ClickPy`_ project provides a public application to visualize download
+statistics, with free direct SQL access to the underlying open-source
+`ClickHouse`_ database, updated daily.
+
+
 References
 ==========
 
@@ -346,3 +354,5 @@ References
 .. _google-cloud-bigquery: https://cloud.google.com/bigquery/docs/reference/libraries
 .. _pandas-gbq: https://pandas-gbq.readthedocs.io/en/latest/
 .. _Pandas: https://pandas.pydata.org/
+.. _ClickHouse: https://github.com/ClickHouse/ClickHouse
+.. _Clickpy: https://clickpy.clickhouse.com/

source/guides/multi-version-installs.rst

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

source/guides/packaging-namespace-packages.rst

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

source/guides/writing-pyproject-toml.rst

@@ -413,6 +413,7 @@ A list of PyPI classifiers that apply to your project. Check the
 
 .. code-block:: toml
 
+    [project]
     classifiers = [
       # How mature is this project? Common values are
       #   3 - Alpha

source/shared/build-backend-tabs.rst

@@ -38,5 +38,5 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["uv_build >= 0.9.26, <0.10.0"]
+        requires = ["uv_build >= 0.10.7, <0.11.0"]
         build-backend = "uv_build"

source/specifications/binary-distribution-format.rst

@@ -240,18 +240,17 @@ The .dist-info directory
    secure hashes.  Unlike PEP 376, every file except RECORD, which
    cannot contain a hash of itself, must include its hash.  The hash
    algorithm must be sha256 or better; specifically, md5 and sha1 are
-   not permitted, as signed wheel files rely on the strong hashes in
-   RECORD to validate the integrity of the archive.
+   not permitted.
 #. PEP 376's INSTALLER and REQUESTED are not included in the archive.
-#. RECORD.jws is used for digital signatures.  It is not mentioned in
-   RECORD.
-#. RECORD.p7s is allowed as a courtesy to anyone who would prefer to
-   use S/MIME signatures to secure their wheel files.  It is not
-   mentioned in RECORD.
+#. RECORD.jws and RECORD.p7s are deprecated.  Where they are still
+   used, neither RECORD.jws nor RECORD.p7s are mentioned in RECORD.
+   Build backends and other tools must not add them to wheels anymore,
+   installers should be aware that these files may still be part of
+   some wheels.
 #. During extraction, wheel installers verify all the hashes in RECORD
-   against the file contents.  Apart from RECORD and its signatures,
-   installation will fail if any file in the archive is not both
-   mentioned and correctly hashed in RECORD.
+   against the file contents.  Apart from RECORD, RECORD.jws and
+   RECORD.p7s, installation will fail if any file in the archive is not
+   both mentioned and correctly hashed in RECORD.
 
 Subdirectories in :file:`.dist-info/`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -300,52 +299,6 @@ documentation and so forth from the distribution.  During installation the
 contents of these subdirectories are moved onto their destination paths.
 
 
-Signed wheel files
-------------------
-
-Wheel files include an extended RECORD that enables digital
-signatures.  PEP 376's RECORD is altered to include a secure hash
-``digestname=urlsafe_b64encode_nopad(digest)`` (urlsafe base64
-encoding with no trailing = characters) as the second column instead
-of an md5sum.  All possible entries are hashed, including any
-generated files such as .pyc files, but not RECORD which cannot contain its
-own hash. For example::
-
-    file.py,sha256=AVTFPZpEKzuHr7OvQZmhaU3LvwKz06AJw8mT\_pNh2yI,3144
-    distribution-1.0.dist-info/RECORD,,
-
-The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in
-RECORD at all since they can only be added after RECORD is generated.
-Every other file in the archive must have a correct hash in RECORD
-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:
-
-.. code-block:: json
-
-    { "hash": "sha256=ADD-r2urObZHcxBW3Cr-vDCu5RJwT4CaRTHiFmbcIYY" }
-
-(The hash value is the same format used in RECORD.)
-
-If RECORD.p7s is used, it must contain a detached S/MIME format signature
-of RECORD.
-
-A wheel installer is not required to understand digital signatures but
-MUST verify the hashes in RECORD against the extracted file contents.
-When the installer checks file hashes against RECORD, a separate signature
-checker only needs to establish that RECORD matches the signature.
-
-See
-
-- https://datatracker.ietf.org/doc/html/rfc7515
-- https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-serialization-01
-- https://datatracker.ietf.org/doc/html/rfc7517
-- https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01
-
-
 FAQ
 ===
 
@@ -361,34 +314,6 @@ Wheel defines a .data directory.  Should I put all my data there?
     in *wheel's* ``.data`` directory.
 
 
-Why does wheel include attached signatures?
--------------------------------------------
-
-    Attached signatures are more convenient than detached signatures
-    because they travel with the archive.  Since only the individual files
-    are signed, the archive can be recompressed without invalidating
-    the signature or individual files can be verified without having
-    to download the whole archive.
-
-
-Why does wheel allow JWS signatures?
-------------------------------------
-
-    The JOSE specifications of which JWS is a part are designed to be easy
-    to implement, a feature that is also one of wheel's primary design
-    goals.  JWS yields a useful, concise pure-Python implementation.
-
-
-Why does wheel also allow S/MIME signatures?
---------------------------------------------
-
-    S/MIME signatures are allowed for users who need or want to use
-    existing public key infrastructure with wheel.
-
-    Signed packages are only a basic building block in a secure package
-    update system.  Wheel only provides the building block.
-
-
 What's the deal with "purelib" vs. "platlib"?
 ---------------------------------------------
 
@@ -465,6 +390,7 @@ History
   :pep:`639`.
 - January 2025: Clarified that name and version needs to be normalized for
   ``.dist-info`` and ``.data`` directories.
+- January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`.
 
 
 Appendix

source/specifications/pypirc.rst

@@ -10,6 +10,11 @@ indexes <Package Index>` (referred to here as "repositories"), so that you don't
 have to enter the URL, username, or password whenever you upload a package with
 :ref:`twine` or :ref:`flit`.
 
+The :file:`.pypirc` file **SHOULD** be UTF-8 encoded.
+
+Tools that read or write :file:`.pypirc` files may not function correctly
+if another character encoding is used.
+
 The format (originally defined by the :ref:`distutils` package) is:
 
 .. code-block:: ini