setuptools 82.0.0__tar.gz → 83.0.0__tar.gz

{setuptools-82.0.0 → setuptools-83.0.0}/MANIFEST.in

@@ -3,8 +3,6 @@ recursive-include tests *.py
 recursive-include setuptools/tests *.html
 recursive-include docs *.py *.txt *.rst *.conf *.css *.css_t Makefile indexsidebar.html
 recursive-include setuptools/_vendor *
-recursive-include pkg_resources *.py *.txt
-recursive-include pkg_resources/tests/data *
 recursive-include tools *
 recursive-include newsfragments *
 include *.py

{setuptools-82.0.0 → setuptools-83.0.0}/NEWS.rst

@@ -1,3 +1,52 @@
+v83.0.0
+=======
+
+Features
+--------
+
+- Require Python 3.10 or later.
+
+
+Bugfixes
+--------
+
+- ``MANIFEST.in`` matching (via ``FileList``) is now insensitive to Unicode
+  normalization form. A pattern authored in one form (e.g. NFC, as typically
+  saved by editors) now matches a file whose name is stored on disk in another
+  (e.g. NFD, as produced by macOS APFS/HFS+). Previously an ``exclude``,
+  ``global-exclude``, ``recursive-exclude``, or ``prune`` rule could silently
+  fail to drop a non-ASCII-named file from the source distribution, publishing
+  it despite the exclusion -- see GHSA-h35f-9h28-mq5c.
+
+
+Deprecations and Removals
+-------------------------
+
+- Synced with pypa/distutils@d7633fbed including removal of dry_run support (pypa/distutils#334).
+
+
+v82.0.1
+=======
+
+Bugfixes
+--------
+
+- Fix the loading of ``launcher manifest.xml`` file. (#5047)
+- Replaced deprecated ``json.__version__`` with fixture in tests. (#5186)
+
+
+Improved Documentation
+----------------------
+
+- Add advice about how to improve predictability when installing sdists. (#5168)
+
+
+Misc
+----
+
+- #4941, #5157, #5169, #5175
+
+
 v82.0.0
 =======
 
@@ -394,6 +443,7 @@ Bugfixes
 --------
 
 - Backport CVE-47273 from 78.1.1 for Python 3.8. (#4946)
+- Reverted distutils changes that broke the monkey patching of command classes. (#4902)
 
 
 v75.3.3
@@ -786,7 +836,7 @@ Features
 
 - Added return types to typed public functions -- by :user:`Avasam`
 
-  Marked `pkg_resources` as ``py.typed`` -- by :user:`Avasam` (#4409)
+  Marked ``pkg_resources`` as ``py.typed`` -- by :user:`Avasam` (#4409)
 
 
 Misc
@@ -920,7 +970,7 @@ Features
 - Improved `AttributeError` error message if ``pkg_resources.EntryPoint.require`` is called without extras or distribution
   Gracefully "do nothing" when trying to activate a ``pkg_resources.Distribution`` with a `None` location, rather than raising a `TypeError`
   -- by :user:`Avasam` (#4262)
-- Typed the dynamically defined variables from `pkg_resources` -- by :user:`Avasam` (#4267)
+- Typed the dynamically defined variables from ``pkg_resources`` -- by :user:`Avasam` (#4267)
 - Modernized and refactored VCS handling in package_index. (#4332)
 
 
@@ -1050,8 +1100,8 @@ Features
 Bugfixes
 --------
 
-- Clarify some `pkg_resources` methods return `bytes`, not `str`. Also return an empty `bytes` in ``EmptyProvider._get`` -- by :user:`Avasam` (#4243)
-- Return an empty `list` by default in ``pkg_resources.ResourceManager.cleanup_resources`` -- by :user:`Avasam` (#4244)
+- Clarify some ``pkg_resources`` methods return ``bytes``, not ``str``. Also return an empty ``bytes`` in ``EmptyProvider._get`` -- by :user:`Avasam` (#4243)
+- Return an empty ``list`` by default in ``pkg_resources.ResourceManager.cleanup_resources`` -- by :user:`Avasam` (#4244)
 - Made ``pkg_resoursces.NullProvider``'s ``has_metadata`` and ``metadata_isdir`` methods return actual booleans like all other Providers. -- by :user:`Avasam` (#4254)
 
 
@@ -1084,7 +1134,7 @@ Features
 --------
 
 - Updated and removed obsolete Python < 3.8 code and comments. -- by :user:`Avasam` (#4096)
-- Updated `pkg_resources` to use stdlib `importlib.machinery` instead of ``importlib_machinery`` -- by :user:`Avasam` (#4097)
+- Updated ``pkg_resources`` to use stdlib ``importlib.machinery`` instead of ``importlib_machinery`` -- by :user:`Avasam` (#4097)
 
 
 Bugfixes

{setuptools-82.0.0/setuptools.egg-info → setuptools-83.0.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: setuptools
-Version: 82.0.0
-Summary: Easily download, build, install, upgrade, and uninstall Python packages
+Version: 83.0.0
+Summary: Most extensible Python build backend with support for C/C++ extension modules
 Author-email: Python Packaging Authority <distutils-sig@python.org>
 License-Expression: MIT
 Project-URL: Source, https://github.com/pypa/setuptools
@@ -16,7 +16,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Archiving :: Packaging
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: Utilities
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Provides-Extra: test
@@ -63,19 +63,18 @@ Requires-Dist: jaraco.text>=3.7; extra == "core"
 Requires-Dist: importlib_metadata>=6; python_version < "3.10" and extra == "core"
 Requires-Dist: tomli>=2.0.1; python_version < "3.11" and extra == "core"
 Requires-Dist: wheel>=0.43.0; extra == "core"
-Requires-Dist: platformdirs>=4.2.2; extra == "core"
 Requires-Dist: jaraco.functools>=4; extra == "core"
 Requires-Dist: more_itertools; extra == "core"
 Provides-Extra: check
-Requires-Dist: pytest-checkdocs>=2.4; extra == "check"
+Requires-Dist: pytest-checkdocs>=2.14; extra == "check"
 Requires-Dist: pytest-ruff>=0.2.1; sys_platform != "cygwin" and extra == "check"
 Requires-Dist: ruff>=0.13.0; sys_platform != "cygwin" and extra == "check"
 Provides-Extra: cover
 Requires-Dist: pytest-cov; extra == "cover"
 Provides-Extra: enabler
-Requires-Dist: pytest-enabler>=2.2; extra == "enabler"
+Requires-Dist: pytest-enabler>=3.4; extra == "enabler"
 Provides-Extra: type
-Requires-Dist: pytest-mypy; extra == "type"
+Requires-Dist: pytest-mypy>=1.0.1; platform_python_implementation != "PyPy" and extra == "type"
 Requires-Dist: mypy==1.18.*; extra == "type"
 Requires-Dist: importlib_metadata>=7.0.2; python_version < "3.10" and extra == "type"
 Requires-Dist: jaraco.develop>=7.21; sys_platform != "cygwin" and extra == "type"
@@ -97,7 +96,7 @@ Dynamic: license-file
 .. |docs-badge| image:: https://img.shields.io/readthedocs/setuptools/latest.svg
    :target: https://setuptools.pypa.io
 
-.. |skeleton-badge| image:: https://img.shields.io/badge/skeleton-2025-informational
+.. |skeleton-badge| image:: https://img.shields.io/badge/skeleton-2026-informational
    :target: https://blog.jaraco.com/skeleton
 
 .. |codecov-badge| image:: https://img.shields.io/codecov/c/github/pypa/setuptools/master.svg?logo=codecov&logoColor=white

{setuptools-82.0.0 → setuptools-83.0.0}/README.rst

@@ -14,7 +14,7 @@
 .. |docs-badge| image:: https://img.shields.io/readthedocs/setuptools/latest.svg
    :target: https://setuptools.pypa.io
 
-.. |skeleton-badge| image:: https://img.shields.io/badge/skeleton-2025-informational
+.. |skeleton-badge| image:: https://img.shields.io/badge/skeleton-2026-informational
    :target: https://blog.jaraco.com/skeleton
 
 .. |codecov-badge| image:: https://img.shields.io/codecov/c/github/pypa/setuptools/master.svg?logo=codecov&logoColor=white

{setuptools-82.0.0 → setuptools-83.0.0}/conftest.py

@@ -32,7 +32,6 @@ collect_ignore = [
     'setuptools/tests/mod_with_constant.py',
     'setuptools/_distutils',
     '_distutils_hack',
-    'pkg_resources/tests/data',
     'setuptools/_vendor',
     'setuptools/config/_validate_pyproject',
     'setuptools/modified.py',

{setuptools-82.0.0 → setuptools-83.0.0}/docs/conf.py

@@ -146,6 +146,7 @@ extensions += ['sphinx_reredirects']
 redirects = {
     "userguide/keywords": "/deprecated/changed_keywords.html",
     "userguide/commands": "/deprecated/commands.html",
+    "pkg_resources": "/deprecated/pkg_resources.html",
 }
 
 # Add support for inline tabs
@@ -238,8 +239,8 @@ favicons = [
 ]
 
 intersphinx_mapping.update({
-    'pip': ('https://pip.pypa.io/en/latest', None),
-    'build': ('https://build.pypa.io/en/latest', None),
+    'pip': ('https://pip.pypa.io/en/stable', None),
+    'build': ('https://build.pypa.io/en/stable', None),
     'PyPUG': ('https://packaging.python.org/en/latest', None),
     'pytest': ('https://docs.pytest.org/en/stable', None),
     'packaging': ('https://packaging.pypa.io/en/latest', None),

{setuptools-82.0.0 → setuptools-83.0.0}/docs/deprecated/distutils/apiref.rst

@@ -361,7 +361,7 @@ This module provides the following functions.
    are not given.
 
 
-.. function:: new_compiler(plat=None, compiler=None, verbose=False, dry_run=False, force=False)
+.. function:: new_compiler(plat=None, compiler=None, verbose=False, force=False)
 
    Factory function to generate an instance of some CCompiler subclass for the
    supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg.
@@ -383,7 +383,7 @@ This module provides the following functions.
    to :command:`build`, :command:`build_ext`, :command:`build_clib`).
 
 
-.. class:: CCompiler([verbose=False, dry_run=False, force=False])
+.. class:: CCompiler([verbose=False, force=False])
 
    The abstract base class :class:`CCompiler` defines the interface that  must be
    implemented by real compiler classes.  The class also has  some utility methods
@@ -398,8 +398,7 @@ This module provides the following functions.
    or per-link basis.
 
    The constructor for each subclass creates an instance of the Compiler object.
-   Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the
-   steps) and *force* (rebuild everything, regardless of dependencies). All of
+   Flags are *verbose* (show verbose output) and *force* (rebuild everything, regardless of dependencies). All of
    these flags default to ``0`` (off). Note that you probably don't want to
    instantiate :class:`CCompiler` or one of its subclasses directly - use the
    :func:`distutils.CCompiler.new_compiler` factory function instead.
@@ -755,8 +754,7 @@ This module provides the following functions.
    .. method:: CCompiler.execute(func, args[, msg=None, level=1])
 
       Invokes :func:`distutils.util.execute`. This method invokes a  Python function
-      *func* with the given arguments *args*, after  logging and taking into account
-      the *dry_run* flag.
+      *func* with the given arguments *args*, after logging.
 
 
    .. method:: CCompiler.spawn(cmd)
@@ -884,7 +882,7 @@ This module provides a few functions for creating archive files, such as
 tarballs or zipfiles.
 
 
-.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=False, dry_run=False])
+.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=False])
 
    Create an archive file (eg. ``zip`` or ``tar``).  *base_name*  is the name of
    the file to create, minus any format-specific extension;  *format* is the
@@ -900,7 +898,7 @@ tarballs or zipfiles.
       Added support for the ``xztar`` format.
 
 
-.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=False, dry_run=False])
+.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=False])
 
    'Create an (optional compressed) archive as a tar file from all files in and
    under *base_dir*. *compress* must be ``'gzip'`` (the default),
@@ -915,7 +913,7 @@ tarballs or zipfiles.
       Added support for the ``xz`` compression.
 
 
-.. function:: make_zipfile(base_name, base_dir[, verbose=False, dry_run=False])
+.. function:: make_zipfile(base_name, base_dir[, verbose=False])
 
    Create a zip file from all files in and under *base_dir*.  The output zip file
    will be named *base_name* + :file:`.zip`.  Uses either the  :mod:`zipfile` Python
@@ -978,7 +976,7 @@ This module provides functions for operating on directories and trees of
 directories.
 
 
-.. function:: mkpath(name[, mode=0o777, verbose=False, dry_run=False])
+.. function:: mkpath(name[, mode=0o777, verbose=False])
 
    Create a directory and any missing ancestor directories.  If the directory
    already exists (or if *name* is the empty string, which means the current
@@ -989,17 +987,17 @@ directories.
    directories actually created.
 
 
-.. function:: create_tree(base_dir, files[, mode=0o777, verbose=False, dry_run=False])
+.. function:: create_tree(base_dir, files[, mode=0o777, verbose=False])
 
    Create all the empty directories under *base_dir* needed to put *files* there.
    *base_dir* is just the name of a directory which doesn't necessarily exist
    yet; *files* is a list of filenames to be interpreted relative to *base_dir*.
    *base_dir* + the directory portion of every file in *files* will be created if
-   it doesn't already exist.  *mode*, *verbose* and *dry_run* flags  are as for
+   it doesn't already exist.  *mode* and *verbose* flags  are as for
    :func:`mkpath`.
 
 
-.. function:: copy_tree(src, dst[, preserve_mode=True, preserve_times=True, preserve_symlinks=False, update=False, verbose=False, dry_run=False])
+.. function:: copy_tree(src, dst[, preserve_mode=True, preserve_times=True, preserve_symlinks=False, update=False, verbose=False])
 
    Copy an entire directory tree *src* to a new location *dst*.  Both *src* and
    *dst* must be directory names.  If *src* is not a directory, raise
@@ -1007,7 +1005,7 @@ directories.
    :func:`mkpath`.  The end result of the  copy is that every file in *src* is
    copied to *dst*, and  directories under *src* are recursively copied to *dst*.
    Return the list of files that were copied or might have been copied, using their
-   output name. The return value is unaffected by *update* or *dry_run*: it is
+   output name. The return value is unaffected by *update*: it is
    simply the list of all files under *src*, with the names changed to be under
    *dst*.
 
@@ -1026,7 +1024,7 @@ directories.
    .. versionchanged:: 3.3.1
       NFS files are ignored.
 
-.. function:: remove_tree(directory[, verbose=False, dry_run=False])
+.. function:: remove_tree(directory[, verbose=False])
 
    Recursively remove *directory* and all files and directories underneath it. Any
    errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
@@ -1043,7 +1041,7 @@ directories.
 This module contains some utility functions for operating on individual files.
 
 
-.. function:: copy_file(src, dst[, preserve_mode=True, preserve_times=True, update=False, link=None, verbose=False, dry_run=False])
+.. function:: copy_file(src, dst[, preserve_mode=True, preserve_times=True, update=False, link=None, verbose=False])
 
    Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there
    with the same name; otherwise, it must be a filename. (If the file exists, it
@@ -1062,8 +1060,7 @@ This module contains some utility functions for operating on individual files.
    contents.
 
    Return a tuple ``(dest_name, copied)``: *dest_name* is the actual  name of the
-   output file, and *copied* is true if the file was copied  (or would have been
-   copied, if *dry_run* true).
+   output file, and *copied* is true if the file was copied.
 
    .. % XXX if the destination file already exists, we clobber it if
    .. % copying, but blow up if linking.  Hmmm.  And I don't know what
@@ -1073,7 +1070,7 @@ This module contains some utility functions for operating on individual files.
    .. % (not update) and (src newer than dst)).
 
 
-.. function:: move_file(src, dst[, verbose, dry_run])
+.. function:: move_file(src, dst[, verbose])
 
    Move file *src* to *dst*. If *dst* is a directory, the file will be moved into
    it with the same name; otherwise, *src* is just renamed to *dst*.  Returns the
@@ -1216,12 +1213,12 @@ other utility module.
    .. % Should probably be moved into the standard library.
 
 
-.. function:: execute(func, args[, msg=None, verbose=False, dry_run=False])
+.. function:: execute(func, args[, msg=None, verbose=False])
 
    Perform some action that affects the outside world (for instance, writing to the
-   filesystem).  Such actions are special because they are disabled by the
-   *dry_run* flag.  This method takes  care of all that bureaucracy for you; all
-   you have to do is supply the function to call and an argument tuple for it (to
+   filesystem). Historically, such actions were special because they could be disabled
+   by a *dry_run* flag. This method takes care of all that bureaucracy;
+   simply supply the function to call and an argument tuple for it (to
    embody the "external action" being performed), and an optional message to print.
 
 
@@ -1234,7 +1231,7 @@ other utility module.
    :exc:`ValueError` if *val*  is anything else.
 
 
-.. function:: byte_compile(py_files[, optimize=0, force=False, prefix=None, base_dir=None, verbose=True, dry_run=False, direct=None])
+.. function:: byte_compile(py_files[, optimize=0, force=False, prefix=None, base_dir=None, verbose=True, direct=None])
 
    Byte-compile a collection of Python source files to :file:`.pyc` files in a
    :file:`__pycache__` subdirectory (see :pep:`3147` and :pep:`488`).
@@ -1254,9 +1251,6 @@ other utility module.
    stripped).  You can supply either or both (or neither) of *prefix* and
    *base_dir*, as you wish.
 
-   If *dry_run* is true, doesn't actually do anything that would affect the
-   filesystem.
-
    Byte-compilation is either done directly in this interpreter process with the
    standard :mod:`py_compile` module, or indirectly by writing a temporary script
    and executing it.  Normally, you should let :func:`byte_compile` figure out to

{setuptools-82.0.0 → setuptools-83.0.0}/docs/deprecated/index.rst

@@ -23,3 +23,13 @@ objectives.
     distutils-legacy
     functionalities
     commands
+    pkg_resources
+
+Notes for Consumers of Packages Built with Setuptools
+=====================================================
+
+
+.. toctree::
+   :maxdepth: 1
+
+   sdist-reproducibility

{setuptools-82.0.0/docs → setuptools-83.0.0/docs/deprecated}/pkg_resources.rst

@@ -2,7 +2,54 @@
 Package Discovery and Resource Access using ``pkg_resources``
 =============================================================
 
-The ``pkg_resources`` module distributed with ``setuptools`` provides an API
+.. attention:: **This documentation is retained solely for historical purposes**
+
+   ``pkg_resources`` has long been **discouraged** due to architectural
+   limitations that led to persistent performance issues.
+   These limitations were inherent to its design (e.g. importing on startup,
+   scanning the entire environment for metadata, and eager, global
+   working‑set management) and could not be corrected.
+
+   .. version-deprecated:: v67.5.0
+      ``pkg_resources`` issued official deprecation warnings as early as
+      ``setuptools`` **v67.5.0**.
+
+   .. version-removed:: v82.0.0
+      ``pkg_resources`` is no longer maintained, no longer used internally by
+      ``setuptools``, and is no longer included in current
+      distributions/installations as of ``setuptools`` **v82.0.0**.
+
+   Projects must migrate away from ``pkg_resources``. The recommended
+   replacements are:
+
+   * Resource access: use :mod:`importlib.resources`
+     (or its backport :pypi:`importlib_resources`).
+   * Distribution metadata & entry points: use :mod:`importlib.metadata`
+     (or its backport :pypi:`importlib_metadata`).
+   * Requirement and version parsing: use :pypi:`packaging`.
+     This includes parsing and evaluating ``extras`` and markers via
+     ``packaging.requirements.Requirement`` and ``packaging.markers.Marker``.
+     Note that automatic installation or detection of extras is not provided;
+     projects requiring that behaviour must implement it themselves using
+     a combination of ``packaging``, ``importlib.metadata`` and other tools
+     as building blocks.
+   * Coexistence of multiple versions of a package: please consider using a different
+     approach, as this functionality is not supported by Python itself.
+     Alternatives include isolated environments and orchestration tools
+     (:mod:`venv`, :pypi:`tox`, :pypi:`nox`, etc.).
+   * Handling of ``.egg`` distributions: please consider using a different
+     approach, as the ``.egg`` and ``easy_install`` mechanisms have also been
+     discontinued.
+     Please use currently supported packaging formats
+     (see :external+PyPUG:doc:`specifications/section-distribution-formats`)
+     and build/installation workflows (see :pep:`517`).
+
+   **Note:** The following documentation may no longer accurately describe the
+   behaviour of the distributed package and has been frozen at the last
+   ``setuptools`` release that still contained ``pkg_resources``.
+
+
+The ``pkg_resources`` module provides an API
 for Python libraries to access their resource files, and for extensible
 applications and frameworks to automatically discover plugins.  It also
 provides runtime support for using C extensions that are inside zipfile-format
@@ -10,15 +57,6 @@ eggs, support for merging packages that have separately-distributed modules or
 subpackages, and APIs for managing Python's current "working set" of active
 packages.
 
-.. attention::
-   Use of ``pkg_resources`` is deprecated in favor of
-   :mod:`importlib.resources`, :mod:`importlib.metadata`
-   and their backports (:pypi:`importlib_resources`, :pypi:`importlib_metadata`).
-   Some useful APIs are also provided by :pypi:`packaging` (e.g. requirements
-   and version parsing).
-   Users should refrain from new usage of ``pkg_resources`` and
-   should work to port to importlib-based solutions.
-
 
 --------
 Overview

setuptools-83.0.0/docs/deprecated/sdist-reproducibility.rst

@@ -0,0 +1,202 @@
+===========================================================================================
+Drawbacks of installing source distributions (``sdist``) and how to improve reproducibility
+===========================================================================================
+
+
+.. admonition:: Scope and audience
+
+   This page contains relevant information for **package consumers** (people
+   installing third-party projects that may have been built with Setuptools).
+   It explains why installing from :external+PyPUG:term:`Source Distributions
+   <Source Distribution (or "sdist")>` can be less predictable than installing
+   from :external+PyPUG:term:`wheels <Wheel>`, and contains tips on how to improve
+   **installation-time** reproducibility. It does **not** describe how to build
+   packages with Setuptools, nor is it a statement of policy about what
+   publishers must do [#publishing]_.
+
+
+The ``sdist`` format was one of the first packaging formats to be created by the
+Python community (predating the advent of ``wheel``). Although very
+useful today to distribute and share Python libraries and applications,
+``sdist``\s are notoriously difficult to work with in circumstances that
+require high build reproducibility and tolerance to disruptions.
+
+This guide reviews the concept of ``sdist``, highlights its potential uses
+and drawbacks and explores potential practices to improve build reproducibility
+when relying on ``sdist``\s.
+
+
+What is an ``sdist``?
+=====================
+
+You can read more about the ``sdist`` format and its ``wheel`` counterpart in
+:external+PyPUG:doc:`discussions/package-formats`, but for the sake of this
+document an ``sdist`` can be considered a simple ``.tar.gz`` archive that
+contains all the files necessary to build a Python project that later will be
+installed in the end-user's environment.
+
+The most defining characteristic of the ``sdist`` format is its
+platform-independence, as the distributions do not include binary executable files.
+This format is very flexible and, although usually composed by a simple copy
+of the source code files with some extra metadata files added, it can also include
+platform-independent code automatically generated during the build
+phase [#examples]_.
+
+
+When is an ``sdist`` useful?
+============================
+
+Sometimes it can be tricky to distribute Python packages that contain binary
+extensions, especially when they are built for platforms that do not define a
+cross-version stable ABI_.
+Moreover package indexes like PyPI_ may restrict their offer to a handful of
+well-known platforms.
+Finally, for certain edge cases, the build process may require machine specific
+parameters.
+
+In this context, distributing code via ``sdist``\s becomes a valuable fallback.
+It allows users in other platforms to access the source code
+and attempt to recompile the extensions locally.
+
+
+What are the drawbacks of an ``sdist``?
+=======================================
+
+Despite their usefulness, working with ``sdist``\s can be challenging. One
+major difficulty is reconstructing a compatible build environment in which the
+``sdist`` can be processed into a ``wheel``, especially when it comes to build
+dependencies.
+
+While :pep:`518` introduced a standard for declaring build dependencies
+distributed as Python packages (e.g. via PyPI), many projects also rely on
+non-Python dependencies, such as compilers and binary system-level libraries,
+that are not declared as a standard metadata. These dependencies can vary
+significantly across systems and its installation is often not automated and
+undocumented, i.e., simply assumed to be present.
+
+Another issue is *tooling drift*: even if a project was originally buildable
+from its ``sdist``, changes in the build dependencies (e.g., updates,
+deprecations and security fixes) can break compatibility over time [#pinning]_.
+This is a natural tendency of software systems and especially true for older
+projects.
+
+Therefore, mission-critical systems and environments that cannot afford
+unforeseen/unintended interruptions should not rely on ``sdist``\s.
+If your project or product requires high reliability and minimal disruption,
+you should adapt your workflow to increase resiliency and reproducibility or
+disallow ``sdist``\s all together.
+
+
+How to improve reproducibility in your workflow and avoid ``sdist`` drawbacks?
+==============================================================================
+
+The first step to improve your workflow is to determine whether your workflow
+is directly or indirectly relying on ``sdist``\s — and to prevent them from being
+compiled on demand.
+
+Installers like ``pip`` or ``uv`` have options that help with this.
+For example, you can set the environment variable |PIP_ONLY_BINARY|_ with
+the value ``:all:``, to prevent ``sdist``\s from being installed
+(see the corresponding `uv alternative`_).
+When this setting is enabled, any installation that fails will indicate which
+packages are not available as ``wheel``\s, helping you pinpoint installations
+relying on ``sdist``\s.
+
+Once these packages are identified, the next step is to build them in
+a controlled environment.
+You can use ``pip``\'s |PIP_CONSTRAINT|_ / |PIP_BUILD_CONSTRAINT|_
+environment variables or the
+|build-constraint|_ ``uv``\'s CLI option to enforce specific versions of
+Python packages [#build-isolation]_.
+
+To further improve the consistency of OS-level tools and libraries,
+you can leverage your CI/CD provider's configuration method, for example
+`GitHub Workflows`_, `Bitbucket Pipelines`_, `GitLab CI/CD`_, Jenkins_,
+CircleCI_ or Semaphore_.
+
+Alternatively, you can use containers (e.g. docker_, nerdctl_ or podman_),
+immutable operating system distributions or package managers (e.g. `NixOS/Nix`_)
+or configuration management tools (e.g. Ansible_, chef_ or puppet_)
+to implement `Infrastructure as Code`_ (IaC) and ensure build environments
+are reproducible and version-controlled.
+
+Consider caching the resulting ``wheel``\s
+locally via |wheelhouse directories|_ or hosting them in
+*private package indexes* (such as devpi_).
+This allows you to serve pre-built distributions internally,
+which reduces reliance on external sources, improves build stability,
+and often results in faster workflows as a welcome side effect.
+
+Finally, it's important to regularly audit your pinned or cached (build)
+dependencies for known security vulnerabilities and critical bug fixes and/or
+update them accordingly.
+This can be done through an *out-of-band* workflow — such as a scheduled job
+or a monthly CI/CD pipeline — that does not interfere with your
+mission-critical or low-tolerance environments. This approach ensures that your
+systems remain secure and up to date without compromising the stability of your
+primary workflows.
+
+
+.. rubric:: Footnotes
+
+.. [#publishing]
+   The PyPA recommendation, documented in the `packaging tutorial`_, is to
+   publish both ``sdists`` and ``wheels``.
+
+.. [#examples]
+   Examples of platform-independent generated code in ``sdist``\s include
+   ``.pyx`` files transpiled into ``.c`` and Python code created from
+   ``.proto``, JSON schema or grammar files, etc.
+
+.. [#pinning]
+   Although developers can try to minimize the impact of tooling drift by
+   locking the version of build dependencies, this approach also has
+   its own drawbacks. In fact, it is very common in the Python community to
+   avoid specifying version caps. For a deeper discussion on this topic, see:
+   https://iscinumpy.dev/post/bound-version-constraints/ and
+   https://hynek.me/articles/semver-will-not-save-you/.
+
+.. [#build-isolation]
+   When a virtual environment with hand picked versions of build dependencies
+   is crafted (either manually or via tools supporting one of the
+   :external+PyPUG:doc:`specifications/pylock-toml` or
+   :external+pip:doc:`reference/requirements-file-format`), it is also possible
+   to use features like |no-isolation|_, |no-build-isolation|_ or the
+   `equivalent uv settings`_ to ensure packages are built against the currently
+   active virtual environment.
+
+
+.. _ABI: https://en.wikipedia.org/wiki/Application_binary_interface
+.. _PyPI: https://pypi.org
+.. |PIP_ONLY_BINARY| replace:: ``PIP_ONLY_BINARY``
+.. _PIP_ONLY_BINARY: https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-only-binary
+.. _uv alternative: https://docs.astral.sh/uv/reference/settings/#pip_only-binary
+.. |PIP_CONSTRAINT| replace:: ``PIP_CONSTRAINT``
+.. _PIP_CONSTRAINT: https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-c
+.. |PIP_BUILD_CONSTRAINT| replace:: ``PIP_BUILD_CONSTRAINT``
+.. _PIP_BUILD_CONSTRAINT: https://pip.pypa.io/en/stable/cli/pip_download/#cmdoption-build-constraint
+.. |build-constraint| replace:: ``--build-constraint``
+.. _build-constraint: https://docs.astral.sh/uv/concepts/projects/build/#build-constraints
+.. _GitHub Workflows: https://docs.github.com/en/actions/writing-workflows
+.. _Bitbucket Pipelines: https://www.atlassian.com/software/bitbucket/features/pipelines
+.. _GitLab CI/CD: https://docs.gitlab.com/ci/
+.. _Jenkins: https://www.jenkins.io/doc/
+.. _CircleCI: https://circleci.com
+.. _Semaphore: https://semaphore.io
+.. _docker: https://www.docker.com
+.. _nerdctl: https://github.com/containerd/nerdctl
+.. _podman: https://podman.io
+.. _NixOS/Nix: https://nixos.org
+.. _Ansible: https://docs.ansible.com
+.. _chef: https://docs.chef.io
+.. _puppet: https://www.puppet.com/docs/index.html
+.. _Infrastructure as Code: https://en.wikipedia.org/wiki/Infrastructure_as_code
+.. |wheelhouse directories| replace:: *"wheelhouse" directories*
+.. _wheelhouse directories: https://pip.pypa.io/en/stable/cli/pip_wheel/#examples
+.. _devpi: https://doc.devpi.net/
+.. |no-isolation| replace:: ``--no-isolation``
+.. _no-isolation: https://build.pypa.io/en/stable/#python--m-build---no-isolation
+.. |no-build-isolation| replace:: ``--no-build-isolation``
+.. _no-build-isolation: https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-no-build-isolation
+.. _equivalent uv settings: https://docs.astral.sh/uv/concepts/projects/config/#build-isolation
+.. _packaging tutorial: https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives