Copy editing

Author: zklaus

peps/pep-0780.rst

@@ -23,33 +23,31 @@ Abstract
 ========
 
 This PEP defines using ABI features as environment markers for project
-dependencies, through a new ``sys_abi_features`` environment marker.
-:pep:`508` (later moved to :ref:`packaging:dependency-specifiers`) introduced
-environment markers to specify dependencies based on rules that describe
-when the dependency should be used.
-This PEP extends the environment markers to allow specifying dependencies
-based on specific ABI features of the Python interpreter.
-For this, it defines a set of `ABI Features`_ and specifies how they are made
-available for `environment markers <pep-780-sys_abi_features_>`_ as a new
-marker variable, ``sys_abi_features``.
+dependencies, through a new ``sys_abi_features`` environment marker. :pep:`508`
+(later moved to :ref:`packaging:dependency-specifiers`) introduced environment
+markers to specify dependencies based on rules that describe when the
+dependency should be used. This PEP extends the environment markers to allow
+specifying dependencies based on specific ABI features of the Python
+interpreter. For this, it defines a set of `ABI Features`_ and specifies how
+they are made available for `environment markers <pep-780-sys_abi_features_>`_
+as a new marker variable, ``sys_abi_features``.
 
 Motivation
 ==========
 
 In 2015, :pep:`508` established environment markers to specify dependencies
-based on environment conditions.
-The development of free-threaded CPython [#python-free-threading]_
-has underlined the need for an environment marker to discriminate between
-different ABI features that the interpreter was built with.
-For example, currently there is no way to distinguish between a GIL-enabled and
-a free-threaded CPython interpreter with an environment marker. This leads to
-real world issues for the adoption of free-threading and its incremental
-rollout. When a Python package is being made compatible with free-threaded
-CPython, it also needs all its build and runtime dependencies to be compatible.
-Capturing the first version of a dependency that is compatible precisely in
-metadata is currently not possible, and increasing the minimum version of a
-dependency also for the GIL-enabled build is usually undesirable since it
-unnecessarily limits compatibility between packages.
+based on environment conditions. The development of free-threaded CPython
+[#python-free-threading]_ has underlined the need for an environment marker to
+discriminate between different ABI features that the interpreter was built
+with. For example, currently there is no way to distinguish between a
+GIL-enabled and a free-threaded CPython interpreter with an environment marker.
+This leads to real world issues for the adoption of free-threading and its
+incremental rollout. When a Python package is being made compatible with
+free-threaded CPython, it also needs all its build and runtime dependencies to
+be compatible. Capturing the first version of a dependency that is compatible
+precisely in metadata is currently not possible, and increasing the minimum
+version of a dependency also for the GIL-enabled build is usually undesirable
+since it unnecessarily limits compatibility between packages.
 
 Some concrete examples of such issues have been discussed in the `Environment
 marker for free-threading`_ Discourse thread:
@@ -96,20 +94,18 @@ Rationale
 =========
 
 The intention of this PEP is to introduce its core features with minimal impact
-on the existing ecosystem.
-The existing grammar proposed in :pep:`508` lends itself to a straightforward
-extension to include the new environment marker.
+on the existing ecosystem. The existing grammar proposed in :pep:`508` lends
+itself to a straightforward extension to include the new environment marker.
 
 A Forward Looking View on Free-Threaded Python
 ----------------------------------------------
 
-:pep:`703`, the accepted proposal for free threading, states that the
-rollout of free-threaded Python should be gradual, which has been clarified
-by the Python Steering Council in `the PEP 703 acceptance post`_ to mean a
-three stage process over multiple releases. It is therefore important to make
-sure that the mechanisms in this PEP are useable for Python interpreters where
-either free-threading or non-free-threading could be the default or the only
-option.
+:pep:`703`, the accepted proposal for free threading, states that the rollout
+of free-threaded Python should be gradual, which has been clarified by the
+Python Steering Council in `the PEP 703 acceptance post`_ to mean a three stage
+process over multiple releases. It is therefore important to make sure that the
+mechanisms in this PEP are useable for Python interpreters where either
+free-threading or non-free-threading could be the default or the only option.
 
 At the time of writing, free-threaded Python is in Phase I: experimental phase.
 In this phase, there is an acute need for the proposed environment markers to
@@ -120,11 +116,11 @@ As the number of packages with support increases, and particularly during
 Phase II: Supported-but-not-default phase, we still anticipate a strong need
 for the environment markers to help with the transition.
 
-As free-threaded Python enters into Phase III: Default phase, the need for
-the environment markers will decrease, though at this point it is not clear
-that the GIL-enabled Python will be completely phased out (it may remain
-available as a non standard build option). If it persists, the inverse need for
-the ABI feature detection may arise.
+As free-threaded Python enters into Phase III: Default phase, the need for the
+environment markers will decrease, though at this point it is not clear that
+the GIL-enabled Python will be completely phased out (it may remain available
+as a non standard build option). If it persists, the inverse need for the ABI
+feature detection may arise.
 
 Indeed, in all three phases it may be necessary for package authors to choose
 specific versions of their dependencies based on the ABI features, with a shift
@@ -160,12 +156,11 @@ distinction between free-threaded and GIL-enabled interpreters is only relevant
 for CPython 3.13 onwards, but the bitness of the interpreter is relevant for
 all interpreters.
 
-All interpreters MUST handle the following ABI features as stated.
-ABI features that are restricted to particular interpreters MUST NOT be
-provided by other interpreters.
-The features are subdivided into groups and for each group there MUST be
-exactly one feature present, except when the group is marked as optional, in
-which case there MUST be at most one feature present.
+All interpreters MUST handle the following ABI features as stated. ABI features
+that are restricted to particular interpreters MUST NOT be provided by other
+interpreters. The features are subdivided into groups and for each group there
+MUST be exactly one feature present, except when the group is marked as
+optional, in which case there MUST be at most one feature present.
 
 ``free-threading`` or ``gil-enabled`` (only CPython)
     If the Python interpreter is free-threaded, the ``free-threading`` feature
@@ -176,8 +171,8 @@ which case there MUST be at most one feature present.
 ``debug`` (only CPython, optional)
     This ABI feature is reserved for the ``--with-pydebug`` build of CPython.
     If the interpreter is a CPython interpreter with ``Py_DEBUG`` capabilities,
-    the ``debug`` feature MUST be present.
-    On POSIX systems, this corresponds to ``"d" in sys.abiflags``.
+    the ``debug`` feature MUST be present. On POSIX systems, this corresponds
+    to the Python expression ``"d" in sys.abiflags``.
 
 ``32-bit`` or ``64-bit`` (optional)
     The bitness of the interpreter, that is, whether it is a 32-bit or 64-bit
@@ -231,8 +226,8 @@ Examples
 
 Require Cython Pre-release for Free-Threaded Python
 ----------------------------------------------------
-To require a pre-release of Cython only for a free-threaded Python
-interpreter, the following dependency specification can be used::
+To require a pre-release of Cython only for a free-threaded Python interpreter,
+the following dependency specification can be used::
 
     cython >3.1.0a1; "free-threading" in sys_abi_features
     cython ==3.0.*; "free-threading" not in sys_abi_features
@@ -258,9 +253,9 @@ This is a pure extension to the existing environment markers and does not
 affect existing environment markers or dependency specifications, hence there
 are no direct backwards compatibility concerns.
 
-However, the introduction of the feature has implications for a
-number of ecosystem tools, especially those which attempt to support
-examination of data in ``pyproject.toml`` and ``requirements.txt``.
+However, the introduction of the feature has implications for a number of
+ecosystem tools, especially those which attempt to support examination of data
+in ``pyproject.toml`` and ``requirements.txt``.
 
 Audit and Update Tools
 ----------------------
@@ -269,10 +264,9 @@ A wide range of tools understand Python dependency data as expressed in
 ``requirements.txt`` files. (e.g., Dependabot, Tidelift, etc)
 
 Such tools inspect dependency data and, in some cases, offer tool-assisted or
-fully automated updates.
-It is our expectation that no such tools would support the new environment
-markers at first, and broad ecosystem support could take many months or even
-some number of years to arrive.
+fully automated updates. It is our expectation that no such tools would support
+the new environment markers at first, and broad ecosystem support could take
+many months or even some number of years to arrive.
 
 As a result, users of the new environment markers would experience a
 degradation in their workflows and tool support at the time that they start
@@ -294,11 +288,11 @@ dependencies may be specified here, just as they may be specified in
 How to Teach This
 =================
 
-The use of environment markers is well established and communicated chiefly
-in :ref:`packaging:dependency-specifiers`.
-The new environment marker can be introduced in the same document.
-Additionally, both for package authors and users, free-threading specific
-guidance can be provided at the `Python free-threading guide`_.
+The use of environment markers is well established and communicated chiefly in
+:ref:`packaging:dependency-specifiers`. The new environment marker can be
+introduced in the same document. Additionally, both for package authors and
+users, free-threading specific guidance can be provided at the
+`Python free-threading guide`_.
 
 Reference Implementation
 ========================
@@ -311,8 +305,8 @@ of the ``packaging`` library at `Environment markers for ABI features
 also available.
 
 Since ``pip`` uses a vendored copy of ``packaging`` internally, we also provide
-`a patched version of pip`__, which replaces the vendored ``packaging`` with the
-reference implementation linked above.
+`a patched version of pip`__, which replaces the vendored ``packaging`` with
+the reference implementation linked above.
 
 __ https://github.com/zklaus/pip/tree/env-marker-free-threading
 
@@ -349,16 +343,15 @@ Other Tooling
 -------------
 The reference implementation is based on the ``packaging`` library and ``pip``.
 We have confirmed that this allows for building and installing packages with
-several build backends.
-It is possible that other tools should be added to the reference
-implementation.
+several build backends. It is possible that other tools should be added to the
+reference implementation.
 
 
 Footnotes
 =========
 
-.. [#python-free-threading] Python experimental support for free threading
-   is available in Python 3.13 and later. For more information, see `Python
+.. [#python-free-threading] Python experimental support for free threading is
+   available in Python 3.13 and later. For more information, see `Python
    experimental support for free threading`_.
 
 .. [#bitness] While there are some related environment markers available, such
@@ -377,9 +370,9 @@ Footnotes
 Acknowledgements
 ================
 
-Thanks to Filipe Laíns for the suggestion of the ``abi_features`` attribute
-and to Stephen Rosen for the Backwards Compatibility section of :pep:`735`,
-which served as a template for the corresponding section in this PEP.
+Thanks to Filipe Laíns for the suggestion of the ``abi_features`` attribute and
+to Stephen Rosen for the Backwards Compatibility section of :pep:`735`, which
+served as a template for the corresponding section in this PEP.
 
 Copyright
 =========