From 1ba4ec2a65745ae368d1e0ec5c692a129d92b02d Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 27 Oct 2026 12:28:37 +0000 Subject: [PATCH 1/2] Use built distribution terminology for wheels --- source/discussions/downstream-packaging.rst | 2 +- .../guides/distributing-packages-using-setuptools.rst | 2 +- .../github-actions-ci-cd-sample/publish-to-pypi.yml | 2 +- source/key_projects.rst | 8 ++++---- source/overview.rst | 8 +++++--- source/specifications/binary-distribution-format.rst | 9 ++++----- .../specifications/externally-managed-environments.rst | 2 +- source/specifications/source-distribution-format.rst | 2 +- source/specifications/version-specifiers.rst | 10 +++++----- 9 files changed, 23 insertions(+), 22 deletions(-) diff --git a/source/discussions/downstream-packaging.rst b/source/discussions/downstream-packaging.rst index 3f4795fa87..05991daf3d 100644 --- a/source/discussions/downstream-packaging.rst +++ b/source/discussions/downstream-packaging.rst @@ -54,7 +54,7 @@ Why? ~~~~ The vast majority of downstream packagers prefer to build packages from source, -rather than use the upstream-provided binary packages. In some cases, using +rather than use the upstream-provided wheels. 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: diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst index bf4227aaee..9e75104139 100644 --- a/source/guides/distributing-packages-using-setuptools.rst +++ b/source/guides/distributing-packages-using-setuptools.rst @@ -120,7 +120,7 @@ sample project `_ has removed its manifes file, since all the necessary files have been included by :ref:`setuptools` 43.0.0 and newer. -.. note:: :file:`MANIFEST.in` does not affect binary distributions such as wheels. +.. note:: :file:`MANIFEST.in` does not affect built distributions such as wheels. LICENSE.txt ~~~~~~~~~~~ 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 155f825551..00e8224097 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 @@ -21,7 +21,7 @@ jobs: pip install build --user - - name: Build a binary wheel and a source tarball + - name: Build a wheel and a source distribution run: python3 -m build - name: Store the distribution packages uses: actions/upload-artifact@v5 diff --git a/source/key_projects.rst b/source/key_projects.rst index 98e87b12d8..c26572b450 100644 --- a/source/key_projects.rst +++ b/source/key_projects.rst @@ -74,7 +74,7 @@ distlib relate to packaging and distribution of Python software. ``distlib`` implements several relevant PEPs (Python Enhancement Proposal standards) and is useful for developers of third-party packaging tools -to make and upload binary and source :term:`distributions +to make and upload built and source :term:`distributions `, achieve interoperability, resolve dependencies, manage package resources, and do other similar functions. @@ -373,9 +373,9 @@ creating :term:`wheel distributions `. Additionally, it offers its own command line utility for creating and installing wheels. See also `auditwheel `__, a tool -that package developers use to check and fix Python packages they are -making in the binary wheel format. It provides functionality to -discover dependencies, check metadata for compliance, and repair the +that package developers use to check and fix wheels containing native code. +It provides functionality to discover dependencies, check metadata for +compliance, and repair the wheel and metadata to properly link and include external shared libraries in a package. diff --git a/source/overview.rst b/source/overview.rst index d7b3efdaf5..a139588d00 100644 --- a/source/overview.rst +++ b/source/overview.rst @@ -112,8 +112,10 @@ advantages for pure-Python libraries. a drop-in replacement for PIL, just by changing your project's ``install_requires`` or ``requirements.txt``. -Python binary distributions -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _python-binary-distributions: + +Python built distributions +^^^^^^^^^^^^^^^^^^^^^^^^^^ So much of Python's practical power comes from its ability to integrate with the software ecosystem, in particular libraries written @@ -126,7 +128,7 @@ compiled artifacts. In fact, Python's package installer, ``pip``, always prefers wheels because installation is always faster, so even pure-Python packages work better with wheels. -Binary distributions are best when they come with source distributions +Built distributions are best when they come with source distributions to match. Even if you don't upload wheels of your code for every operating system, by uploading the sdist, you're enabling users of other platforms to still build it for themselves. Default to diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst index a6f1418516..76a4754b47 100644 --- a/source/specifications/binary-distribution-format.rst +++ b/source/specifications/binary-distribution-format.rst @@ -2,12 +2,11 @@ .. _binary-distribution-format: -========================== -Binary distribution format -========================== +========================= +Wheel distribution format +========================= -This page specifies the binary distribution format for Python packages, -also called the wheel format. +This page specifies the wheel format for Python packages. 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 diff --git a/source/specifications/externally-managed-environments.rst b/source/specifications/externally-managed-environments.rst index 65fc14a626..eddd48f054 100644 --- a/source/specifications/externally-managed-environments.rst +++ b/source/specifications/externally-managed-environments.rst @@ -50,7 +50,7 @@ distro 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 + source or built 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. diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst index b877e87d5e..cc0a310ead 100644 --- a/source/specifications/source-distribution-format.rst +++ b/source/specifications/source-distribution-format.rst @@ -39,7 +39,7 @@ Source distribution file name The file name of a sdist was standardised in :pep:`625`. The file name must be in the form ``{name}-{version}.tar.gz``, where ``{name}`` is normalised according to -the same rules as for binary distributions (see :ref:`binary-distribution-format`), +the same rules as for wheels (see :ref:`binary-distribution-format`), and ``{version}`` is the canonicalized form of the project version (see :ref:`version-specifiers`). diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst index 75093c2e27..d843a892d2 100644 --- a/source/specifications/version-specifiers.rst +++ b/source/specifications/version-specifiers.rst @@ -19,18 +19,18 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", document are to be interpreted as described in :rfc:`2119`. "Build tools" are automated tools intended to run on development systems, -producing source and binary distribution archives. Build tools may also be +producing source and built distribution archives. Build tools may also be invoked by integration tools in order to build software distributed as -sdists rather than prebuilt binary archives. +sdists rather than built distribution 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. +systems and upload source and built distribution archives to index servers. "Installation tools" are integration tools specifically intended to run on -deployment targets, consuming source and binary distribution archives from +deployment targets, consuming source and built distribution archives from an index server or other designated location and deploying them to the target system. @@ -1112,7 +1112,7 @@ uploaded distributions. Direct references are intended as a tool for software integrators rather than publishers. Depending on the use case, some appropriate targets for a direct URL -reference may be an sdist or a wheel binary archive. The exact URLs and +reference may be an sdist or a wheel. The exact URLs and targets supported will be tool dependent. For example, a local source archive may be referenced directly:: From ac8973ada1e24c6bf4e3895918388a934c9cf84f Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 27 Oct 2026 17:11:17 +0000 Subject: [PATCH 2/2] Add new link target name alongside the old ones for backcompat --- source/overview.rst | 1 + source/specifications/binary-distribution-format.rst | 1 + 2 files changed, 2 insertions(+) diff --git a/source/overview.rst b/source/overview.rst index a139588d00..f8c9659144 100644 --- a/source/overview.rst +++ b/source/overview.rst @@ -113,6 +113,7 @@ advantages for pure-Python libraries. ``install_requires`` or ``requirements.txt``. .. _python-binary-distributions: +.. _python-built-distributions: Python built distributions ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst index 76a4754b47..b9ad485a0e 100644 --- a/source/specifications/binary-distribution-format.rst +++ b/source/specifications/binary-distribution-format.rst @@ -1,6 +1,7 @@ .. highlight:: text .. _binary-distribution-format: +.. _wheel-distribution-format: ========================= Wheel distribution format