From ca4f78f54994f766957b5732a5c810015b709738 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 31 Oct 2025 16:15:08 +0100 Subject: [PATCH 01/11] Fix zlib example --- peps/pep-0804.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index 239567c86d3..f137d4bcb2e 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -682,10 +682,10 @@ for brevity, could look like: "mappings": [ { "id": "dep:generic/zlib", - "description": "zlib data compression library for the next generation systems. From zlib-ng/zlib-ng.", - "specs": "zlib-ng", // Simplest form + "description": "Massively spiffy yet delicately unobtrusive compression library.", + "specs": "zlib", // Simplest form "urls": { - "feedstock": "https://github.com/conda-forge/zlib-ng-feedstock" + "feedstock": "https://github.com/conda-forge/zlib-feedstock" } }, { From a64b84c3b34965921d5e578858c9037f8f6e5a86 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Sat, 1 Nov 2025 10:07:18 +0100 Subject: [PATCH 02/11] 804: Rename `host` to `build_host` (#6) --- peps/pep-0804.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index f137d4bcb2e..274ad508973 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -230,7 +230,7 @@ of dictionaries, in which each entry consists of: - a ``specs`` field whose value MUST be one of: - - a dictionary with three keys (``build``, ``host``, ``run``). The values + - a dictionary with three keys (``build``, ``build_host``, ``run``). The values MUST be a string or list of strings representing the ecosystem-specific package identifiers as needed as build-, host- and runtime dependencies (see PEP 725 for details on these definitions). @@ -514,9 +514,9 @@ Each entry in this list is defined as: - Hyperlinks to web locations that provide more information about the definition. - False * - ``specs`` - - ``string | list[string] | dict[Literal['build', 'host', 'run'], string | list[string]]`` + - ``string | list[string] | dict[Literal['build', 'build_host', 'run'], string | list[string]]`` - Ecosystem-specific identifiers for this package. The full form is a dictionary - that maps the categories ``build``, ``host`` and ``run`` to their corresponding + that maps the categories ``build``, ``build_host`` and ``run`` to their corresponding package identifiers. As a shorthand, a single string or a list of strings can be provided, in which case will be used to populate the three categories identically. - Either ``specs`` or ``specs_from`` MUST be present. @@ -693,7 +693,7 @@ for brevity, could look like: "description": "WebP image library. libwebp-base ships libraries; libwebp ships the binaries.", "specs": { // expanded form with single spec per category "build": "libwebp", - "host": "libwebp-base", + "build_host": "libwebp-base", "run": "libwebp" }, "urls": { @@ -708,7 +708,7 @@ for brevity, could look like: "clang", "clangxx" ], - "host": [ + "build_host": [ "clangdev" ], "run": [ @@ -832,7 +832,7 @@ plus ``meson-python`` as the build backend: build-requires = [ "dep:virtual/compiler/cxx", ] - host-requires = [ + build-host-requires = [ "dep:generic/zlib", ] @@ -847,18 +847,18 @@ following: build-requires = [ "dep:virtual/compiler/cxx", ] - host-requires = [ + build-host-requires = [ "dep:generic/zlib", ] # show all external dependencies, but mapped to the autodetected ecosystem $ python -m pyproject_external show --output=mapped . [external] - build_requires = [ + build-requires = [ "g++", "python3", ] - host_requires = [ + build-host-requires = [ "zlib1g", "zlib1g-dev", ] From 6a0138ccaa20065692cc9f4d033ea95b3a607afd Mon Sep 17 00:00:00 2001 From: jaimergp Date: Mon, 3 Nov 2025 14:45:41 +0100 Subject: [PATCH 03/11] 804: Reject existing databases (#2) --- peps/pep-0804.rst | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index 274ad508973..cdec517d6f0 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -1199,7 +1199,6 @@ The reasons include: discrepancies across target ecosystems, where different versions may be available or required. - Mapping PyPI projects to repackaged counterparts in target ecosystems --------------------------------------------------------------------- @@ -1263,6 +1262,36 @@ We suggest simply checking that the provided identifiers are well-formed. Future work may choose to also enforce that the identifiers are recognized as canonical, once the central registry has matured with significant adoption. +Reusing existing databases as a central registry +------------------------------------------------ + +A cursory online search for cross-ecosystem databases of packages would reveal +different sets of results close to the needs of this proposal, but not quite there. +For example: + +- Some solutions only focus on Linux distributions or Unix systems, + like Repology_ or `pkgs.org `__. +- Other services like `Libraries.io `__ require a login. +- Other providers like `ecosyste.ms `__ are only available via APIs. +- The service `purldb `__ only focuses + on collecting concrete PURLs (which identify specific package artifacts), + instead of abstract PURLs concerned with identifying input requirements. + +The proposed mappings try to be as lightweight as possible, without +requiring the maintenance of a live server and an API. Simply a collection +of static JSON files that can be easily updated and distributed online and offline. + +If in the future a service exists providing the following features, then it would +be a strong contender for superseding this PEP: + +- Provides mappings between source DepURLs, PURLs and their repackaged counterparts. + This implies that PURLs have gained the notion of virtual packages and ergonomic + version range expressions. +- Can generate package manager instructions for a given input PURL. +- Can be distributed as local artifacts for offline consumption. +- Does not require a live server or an API. +- FOSS-licensed. + Open Issues =========== From b0e0364e58322cf8a8524e19174e0f12b194a6fc Mon Sep 17 00:00:00 2001 From: jaimergp Date: Mon, 3 Nov 2025 14:53:47 +0100 Subject: [PATCH 04/11] 804: Reject "Tracking package name changes" (#7) --- peps/pep-0804.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index cdec517d6f0..dfaf23fc4a4 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -1262,6 +1262,27 @@ We suggest simply checking that the provided identifiers are well-formed. Future work may choose to also enforce that the identifiers are recognized as canonical, once the central registry has matured with significant adoption. +Tracking package name changes +----------------------------- + +Packaging ecosystems tend to correct, extend and evolve the naming schemes used. +It is common to split what started as a monolithic build into smaller components +(e.g. avoid shipping development files to runtime-only environments, saving bandwidth). +Some practitioners also use the package name to track ABI compatibility across SONAME +changes. The reasons may be multiple and diverse, but the problem is the same: a +given upstream project name may be distributed as different names over time. + +A proposal to track these changes in the mapping suggested the inclusion of additional +date fields (such as ``valid_from`` and ``valid_to``), but the authors decided to reject +this idea. It adds complexity to the implementation, it is difficult to maintain up-to-date, +and doesn't add value to the end-user, simply serving as a historical record. + +Instead, we expect that versioned distributions maintain a separate mapping per release +(see the proposed mapping naming schemes). Rolling ecosystems should strive to keep +alias packages around, with deprecation warnings if needed and feasible. In general, we +also recommend keeping the mapping files under public version control so end-users +can refer to older versions if necessary. + Reusing existing databases as a central registry ------------------------------------------------ From 61e615e77162268a64e9c69f33f19eed14daabbb Mon Sep 17 00:00:00 2001 From: jaimergp Date: Thu, 13 Nov 2025 10:00:01 +0100 Subject: [PATCH 05/11] 804: Clarify role of `query` commands and version mappings (#3) --- peps/pep-0804.rst | 38 +++++++++++++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index dfaf23fc4a4..5b7cc4ea1bc 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -34,8 +34,7 @@ used in other ecosystems, which would allow to: - Including the needed external dependencies *with the package names used by the relevant system package manager on the user's system* in error messages emitted by Python package installers and build frontends, - as well as allowing the user to query for those names directly to obtain install - instructions. + as well as allowing the user to obtain install instructions for those packages. Packaging ecosystems like Linux distros, conda, Homebrew, Spack, and Nix need full sets of dependencies for Python packages, and have tools like pyp2rpm_ @@ -150,7 +149,7 @@ standalone tool, or as a new subcommand in any Python development workflow tool (e.g., Pip, Poetry, Hatch, PDM, uv). To this end, each ecosystem mapping can provide a list of package managers -known to be compatible, with templated instructions on how to install and query +known to be compatible, with templated instructions on how to install and query installed packages. The provided install command templates are paired with query command templates so those tools can check whether the needed packages are already present without having to attempt an install operation (which might be expensive and have unintended @@ -254,8 +253,16 @@ which package managers are available in the ecosystem and how to use them. This take a list of dictionaries, with each of them reporting the following fields: - ``name`` (string), unique identifier for this package manager. Usually, the executable name. + - ``commands`` (list of dictionaries), the commands to run to install the mapped package(s) and - check whether they are already installed. + check whether they are already installed. Two types of commands are proposed: + + - ``install``, to generate install instructions. The exit code MUST be ``0`` on success. + + - ``query``, to check whether a given package is already installed. If the package is + installed, the command MUST result in an exit code of ``0``. Otherwise, an exit code + of ``1`` SHOULD be used. + - ``specifier_syntax``: instructions on how to map a subset of PEP 440 specifiers to the target package manager. Three levels of support are offered: name-only, exact-version-only, and version-range compatibility (with per-operator translations). @@ -270,6 +277,26 @@ contain mapping documents named ``{ecosystem-identifier}.mapping.json``. The cen registry and known ecosystem documents MAY also be distributed in this directory, as ``registry.json`` and ``known-ecosystems.json``, respectively. +.. note:: + + The ``specifier_syntax`` mappings are meant to provide interoperability between + ecosystems where choosing which package version to install is possible. For + example, this is not the case in many Linux distributions, where each distro + release commits to a package version during its lifecycle (although often + with the necessary security backports). + + In these cases, the ``install`` command could be used, optimistically, in + "name-only" mode, hoping that the OS-provided version is a good fit. A more + pessimistic alternative would be to use the ``query`` command first to see if + the available version matches the project constraints, and then install the + package by name. + + Even in those cases, perfect 1:1 version matching is not always possible due to how + different ecosystems map upstream releases to repackaged versions (e.g. the epoch + had to be bumped to accommodate a change of release schema). In that regard, we do + not encode explicit mapping semantics for epochs or pre-releases. + + Known ecosystems ---------------- @@ -560,7 +587,8 @@ Each entry in this list is defined as a dictionary with these fields: * - ``commands`` - ``dict[Literal['install', 'query'], dict[Literal['command', 'requires_elevation', 'multiple_specifiers'], list[str] | bool | Literal['always', 'name-only', 'never']]]`` - Commands used to install or query the given package(s). Only two keys - are allowed: ``install`` and ``query``. Their value is a dictionary + are allowed: ``install`` (to generate install instructions) and ``query`` (to + check whether a given package is already installed). Their value is a dictionary with: - a required key ``command`` that takes a list of strings From 5aea6db9252a9058bd28e709ae754536aba7cac3 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Thu, 13 Nov 2025 10:00:13 +0100 Subject: [PATCH 06/11] 804: Clarify mapping filenames and versioning (#4) --- peps/pep-0804.rst | 59 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 48 insertions(+), 11 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index 5b7cc4ea1bc..5900fa57563 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -267,8 +267,9 @@ take a list of dictionaries, with each of them reporting the following fields: the target package manager. Three levels of support are offered: name-only, exact-version-only, and version-range compatibility (with per-operator translations). -Each mapping MUST have a canonical URL for online retrieval. These mappings -MAY also be packaged for offline distribution in each platform. The authors +Each mapping MUST have a canonical URL for online retrieval, with the +filename following the rules described in the section below. These +mappings MAY also be packaged for offline distribution in each platform. The authors recommend placing in the standard location for data artifacts in each operating system; e.g. ``$XDG_DATA_DIRS`` on Linux and others, ``~/Library/Application Support`` on macOS, and ``%LOCALAPPDATA%`` for Windows. The subdirectory identifier MUST @@ -303,15 +304,51 @@ Known ecosystems The list of known ecosystems has two roles: 1. Reporting the canonical URL for its mapping. -2. Assigning a short identifier to each ecosystem. This is the identifier - that MUST be used in the mapping filenames mentioned above so they can be - found in the local filesystem. +2. Assigning a unique, short identifier to each ecosystem. -For ecosystems corresponding to Linux distributions, the identifier MUST be the -one reported by their `os-release `__ -``ID`` parameter. For other ecosystems, it MUST be decided during the submission to -the list of known ecosystems document. It MUST only use the characters allowed in -``os-release``'s ``ID`` field, as per this regex ``[a-z0-9\-_.]+``. +Ecosystem identifiers +^^^^^^^^^^^^^^^^^^^^^ + +The identifier MUST conform to this regex: ``[a-z0-9\-_.]+(\+[a-z0-9\-_.])?``. +In other words, a first field optionally followed by a second, separated +by a ``+`` symbol. + +For ecosystems corresponding to Linux distributions, +the first field MUST correspond to the ``ID`` string as specified in the +`os-release `__ +specification. If provided, the second field MUST correspond to the +``VERSION_ID`` string if relevant. + +Since the version field is optional, tools SHOULD try to access the versioned +identifier but fallback to the name-only identifier if not found. + +The complete filename MUST be ``{identifier}.mapping.json``. + +Some examples: + +.. list-table:: + + * - Ecosystem + - Identifier + - Filename + * - Debian Bookworm + - ``debian+12`` + - ``debian+12.mapping.json`` + * - Fedora 40 + - ``fedora+40`` + - ``fedora+40.mapping.json`` + * - Ubuntu 24.04 + - ``ubuntu+24.04`` + - ``ubuntu+24.04.mapping.json`` + * - Arch Linux (rolling) + - ``arch`` + - ``arch.mapping.json`` + * - Homebrew + - ``homebrew`` + - ``homebrew.mapping.json`` + * - conda-forge + - ``conda-forge`` + - ``conda-forge.mapping.json`` Schema details -------------- @@ -432,7 +469,7 @@ The known ecosystems list is specified by the following * - Required - True -This dictionary maps non-empty string keys referring to the ecosystem identifiers +This dictionary maps non-empty string keys referring to the ecosystem *identifiers* to a sub-dictionary defined as: .. list-table:: From 15e5afba2e5679c4541c02986bd00c463023c4be Mon Sep 17 00:00:00 2001 From: jaimergp Date: Thu, 13 Nov 2025 10:00:23 +0100 Subject: [PATCH 07/11] 804: Mapping reusability and customization (#5) --- peps/pep-0804.rst | 72 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index 5900fa57563..a9441d5b416 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -1327,6 +1327,78 @@ We suggest simply checking that the provided identifiers are well-formed. Future work may choose to also enforce that the identifiers are recognized as canonical, once the central registry has matured with significant adoption. +Inheritance and cross-referenced mappings +----------------------------------------- + +A potential improvement to improve the reusability of mappings is to provide a +mechanism to inherit a parent mapping and extend it or replace it with additional +values. The authors have decided to not add this feature given the implied complexity +(e.g. URL resolution, nested dependencies, possibilities of broken resources). Instead, +the following alternatives are proposed: + +- For mapping authors, automate the generation of derived mappings via scripting and + cronjobs. For example, simple logic such as fetching the parent mapping, applying the + necesary modifications and republishing it to the target location should not result + in much maintenance burden. + +- For end-users wishing to extend a given mapping with custom overrides, client-side + tools should implement the necessary affordances to do this easily. For example, + a tool such as ``pyproject-external`` could provide the following CLI flags or + environment variables: + + - ``--use-mapping`` / ``_USE_MAPPING``: Use the given local or + remote mapping instead of the the canonical location. + + - ``--patch-mapping`` / ``_PATCH_MAPPING``: Given a local or + remote mapping, replace the matching keys in the canonical location + and append the non-matching ones. + + - ``--extend-mapping`` / ``_EXTEND_MAPPING``: Given a local + or remote mapping, append its contents to the canonical one. Assuming + the tool allows the user to pick different mapping options if more than + one is available, this option enriches the set of options without + complete overrides. + +So, for example, given a package with this ``external`` table: + +.. code-block:: toml + + [external] + build-requires = [ + "dep:virtual/compiler/c", + ] + host-requires = [ + "dep:generic/libffi", + ] + +And a target ecosystem that maps ``dep:virtual/compiler/c`` to ``gcc`` +but ``clang`` is preferred, the following mapping override could be provided: + +.. code-block:: json + + { + "$schema": "https://raw.githubusercontent.com/jaimergp/external-metadata-mappings/main/schemas/external-mapping.schema.json", + "schema_version": 1, + "name": "ecosystem override", + "description": "Mapping override for my ecosystem of choice", + "mappings": [ + { + "id": "dep:virtual/compiler/c", + "description": "Clang override", + "specs": "clang" + } + ] + } + +Then, it would be used like this: + +.. code-block:: shell + + $ python -m my-tool show \ + sdist/cryptography-46.0.2.tar.gz \ + --output install-command \ + --patch-mapping=my-override.mapping.json + Tracking package name changes ----------------------------- From 167448055ccb02d089023a5df0140e54ef3722bb Mon Sep 17 00:00:00 2001 From: jaimergp Date: Sun, 23 Nov 2025 19:15:13 +0100 Subject: [PATCH 08/11] 804: Some more details about naming guidelines for RPM and Debian ecosystems (#9) --- peps/pep-0804.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index a9441d5b416..a4e09fe971a 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -71,10 +71,17 @@ Ubuntu and CentOS in a Docker container. RPM-based distributions, like Fedora, can use a `rule-based implementation `__ (``NameConvertor``) in pyp2rpm_. The main rule is that the RPM name for a PyPI package is -``f"python-{pypi_package_name}"``. This seems to work quite well; there are a -few variants like Python version specific names, where the prefix contains the -Python major and minor version numbers (e.g. ``python311-`` instead of -``python-``). +typically ``f"python3-{pypi_package_name}"``. The rare exceptions include packages that +primarily distribute an application, which drop the prefix, (e.g., the Black formatter +is simply ``black``, not ``python3-black``), and variants for different Python versions +(e.g., in RHEL 9 ``setuptools`` can be found as ``python3-setuptools`` for Python 3.9, +but ``python3.11-setuptools`` and ``python3.12-setuptools`` are also available). More details +are available in `Fedora's packaging guidelines for Python `__. + +Debian packages typically follow a ``f"python3-{import_name}"`` naming scheme, with some +exceptions: some sub-communities have an infix (e.g., Django packages go under +``f"python3-django-*"``), and applications are often distributed by their name, with no +``python3-`` prefix. Additional details are available in `Debian's Python Policy `__. Gentoo follows a similar approach to naming Python packages, using the ``dev-python/`` category and some `well-specified rules `__. @@ -134,8 +141,7 @@ instructions for its external build dependencies (C/C++/Fortran compilers, OpenBLAS, pkg-config): - Debian/Ubuntu: ``sudo apt install -y gcc g++ gfortran libopenblas-dev liblapack-dev pkg-config python3-pip python3-dev`` -- Fedora: ``sudo dnf install gcc-gfortran python3-devel openblas-devel lapack-devel pkgconfig`` -- CentOS/RHEL: ``sudo yum install gcc-gfortran python3-devel openblas-devel lapack-devel pkgconfig`` +- Fedora/CentOS/RHEL: ``sudo dnf install gcc-gfortran python3-devel openblas-devel lapack-devel pkgconfig`` - Arch Linux: ``sudo pacman -S gcc-fortran openblas pkgconf`` - Homebrew on macOS: ``brew install gfortran openblas pkg-config`` From da7480b9fb21a05b16f434f9f57cbc385b73e93f Mon Sep 17 00:00:00 2001 From: jaimergp Date: Sun, 23 Nov 2025 19:15:51 +0100 Subject: [PATCH 09/11] 804: Address feedback in `package_managers` (#8) --- peps/pep-0804.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index a4e09fe971a..2f2e7e133bd 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -651,10 +651,10 @@ Each entry in this list is defined as a dictionary with these fields: - ``never``, default in ``query``. - Exactly one of the ``command`` items MUST include a ``{}`` placeholder, - which will be replaced by the mapped package identifier(s). The + Exactly one of the ``command`` items MUST be the ``{}`` placeholder, + which will be replaced by the mapped package specifier(s). The ``install`` command SHOULD support the placeholder being replaced by - multiple identifiers, ``query`` MUST only receive a single identifier + multiple specifiers, ``query`` MUST only receive a single specifier per command. - True * - ``specifier_syntax`` @@ -686,7 +686,7 @@ Each entry in this list is defined as a dictionary with these fields: the value MUST include the ``{version}`` placeholder, and MAY include ``{name}``. - - the key ``{and}`` takes a string used to join multiple version + - the key ``and`` takes a string used to join multiple version constraints in a single token, or ``None`` if only a single constraint can be used per token. In the latter case, the different constraints will be "exploded" into several tokens using the From 82c2587d7403868f16444939b32f0aac492ebf30 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Tue, 25 Nov 2025 09:43:35 +0100 Subject: [PATCH 10/11] Remove `not_equal` from schema (#10) --- peps/pep-0804.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index 2f2e7e133bd..2f323203a8d 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -658,7 +658,7 @@ Each entry in this list is defined as a dictionary with these fields: per command. - True * - ``specifier_syntax`` - - ``dict[Literal['name_only', 'exact_version', 'version_ranges'], None | list[str] | dict[Literal['and', 'equal', 'greater_than', 'greater_than_equal', 'less_than', 'less_than_equal', 'not_equal', 'syntax'], None | str | list[str]]`` + - ``dict[Literal['name_only', 'exact_version', 'version_ranges'], None | list[str] | dict[Literal['and', 'equal', 'greater_than', 'greater_than_equal', 'less_than', 'less_than_equal', 'syntax'], None | str | list[str]]`` - Mapping of allowed PEP440 version specifiers to the syntax used in this package manager. Three top-level keys are expected and required: @@ -681,7 +681,7 @@ Each entry in this list is defined as a dictionary with these fields: ``and``). They MAY also include the ``{name}`` placeholder. - the keys ``equal``, ``greater_than``, ``greater_than_equal``, - ``less_than``, ``less_than_equal``, and ``not_equal`` take a string + ``less_than``, and ``less_than_equal`` take a string if the operator is supported, ``None`` otherwise. In the former case, the value MUST include the ``{version}`` placeholder, and MAY include ``{name}``. @@ -832,7 +832,6 @@ for brevity, could look like: "greater_than_equal": ">={version}", "less_than": "<{version}", "less_than_equal": "<={version}", - "not_equal": "!={version}", "syntax": [ "{name}{ranges}" ] From 165e2cbe691b1fba950fc61548ec0a17585e3440 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Thu, 18 Dec 2025 11:58:36 +0100 Subject: [PATCH 11/11] Fix some typos and polish some details --- peps/pep-0804.rst | 95 ++++++++++++++++++++++++++--------------------- 1 file changed, 52 insertions(+), 43 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index 2f323203a8d..0159aec885f 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -27,14 +27,14 @@ Packages on PyPI often require build-time and runtime dependencies that are not present on PyPI. :pep:`725` introduced metadata to express such dependencies. Using concrete external dependency metadata for a Python package requires mapping the given dependency identifiers to the specifiers -used in other ecosystems, which would allow to: +used in other ecosystems, which would allow: - Enabling tools to automatically map external dependencies to packages in other packaging repositories/ecosystems, - Including the needed external dependencies *with the package names used by the relevant system package manager on the user's system* in error messages emitted by Python package installers and build frontends, - as well as allowing the user to obtain install instructions for those packages. + as well as allowing the user to obtain installation instructions for those packages. Packaging ecosystems like Linux distros, conda, Homebrew, Spack, and Nix need full sets of dependencies for Python packages, and have tools like pyp2rpm_ @@ -44,7 +44,7 @@ upstream Python packages. Before PEP 725, external dependencies were handled man because there was no metadata for this in ``pyproject.toml`` or any other standard metadata file. Enabling its automatic conversion is a key benefit of this PEP, making Python packaging easier and more reliable. In addition, the -authors envision other types of tools making use of this information; e.g., +authors envision other types of tools making use of this information; e.g. dependency analysis tools like Repology_, Dependabot_ and libraries.io_. @@ -72,14 +72,14 @@ RPM-based distributions, like Fedora, can use a `rule-based implementation `__ (``NameConvertor``) in pyp2rpm_. The main rule is that the RPM name for a PyPI package is typically ``f"python3-{pypi_package_name}"``. The rare exceptions include packages that -primarily distribute an application, which drop the prefix, (e.g., the Black formatter +primarily distribute an application, which drop the prefix, (e.g. the Black formatter is simply ``black``, not ``python3-black``), and variants for different Python versions -(e.g., in RHEL 9 ``setuptools`` can be found as ``python3-setuptools`` for Python 3.9, +(e.g. in RHEL 9 ``setuptools`` can be found as ``python3-setuptools`` for Python 3.9, but ``python3.11-setuptools`` and ``python3.12-setuptools`` are also available). More details are available in `Fedora's packaging guidelines for Python `__. Debian packages typically follow a ``f"python3-{import_name}"`` naming scheme, with some -exceptions: some sub-communities have an infix (e.g., Django packages go under +exceptions: some sub-communities have an infix (e.g. Django packages go under ``f"python3-django-*"``), and applications are often distributed by their name, with no ``python3-`` prefix. Additional details are available in `Debian's Python Policy `__. @@ -87,8 +87,8 @@ Gentoo follows a similar approach to naming Python packages, using the ``dev-pyt category and some `well-specified rules `__. Conda-forge has a more explicit name mapping, because the base names are the -same in conda-forge as on PyPI (e.g., ``numpy`` maps to ``numpy``), but there -are many exceptions because of both name collisions and renames (e.g., the PyPI +same in conda-forge as on PyPI (e.g. ``numpy`` maps to ``numpy``), but there +are many exceptions because of both name collisions and renames (e.g. the PyPI name for PyTorch is ``torch`` while in conda-forge it's ``pytorch``). There are several name mappings efforts maintained by different teams. Conda-forge's infrastructure generates one in `regro/cf-graph-countyfair `__. @@ -152,7 +152,7 @@ this could be made both more comprehensive and easier to maintain through a tool command with semantics of *"show this ecosystem's preferred package manager install command for all external dependencies"*. This may be done as a standalone tool, or as a new subcommand in any Python development workflow tool -(e.g., Pip, Poetry, Hatch, PDM, uv). +(e.g. Pip, Poetry, Hatch, PDM, uv). To this end, each ecosystem mapping can provide a list of package managers known to be compatible, with templated instructions on how to install and query installed @@ -167,7 +167,7 @@ Registry design The mapping infrastructure has been designed to present the following components and properties: - A central registry of PEP 725 identifiers (DepURLs), including at least the - well-known generic and virtual identifiers considered canonical. + well-known ``generic`` and ``virtual`` identifiers considered canonical. - A list of known ecosystems, where ecosystem maintainers can register their name mapping(s). - A standardized schema that defines how mappings should be structured. Each mapping can also provide programmatic details about how their supported package manager(s) work. @@ -237,7 +237,7 @@ of dictionaries, in which each entry consists of: - a dictionary with three keys (``build``, ``build_host``, ``run``). The values MUST be a string or list of strings representing the ecosystem-specific package - identifiers as needed as build-, host- and runtime dependencies (see PEP 725 for + identifiers as needed as build-, host- and runtime dependencies (see :pep:`725` for details on these definitions). - for convenience, a string or a list of strings are also accepted as a @@ -251,12 +251,12 @@ of dictionaries, in which each entry consists of: field will be imported. Either ``specs`` or ``specs_from`` MUST be present. - an optional ``urls`` field whose value MUST be a URL, a list of URLs, or a - dictionary that maps a string to a URL. This is useful to link to external + dictionary that maps a non-empty string to a URL. This is useful to link to external resources that provide more information about the mapped packages. -The mappings SHOULD also specify another section ``package_managers``, reporting +The mappings MUST also specify another section ``package_managers``, reporting which package managers are available in the ecosystem and how to use them. This field MUST -take a list of dictionaries, with each of them reporting the following fields: +take an empty list or a list of dictionaries, with each of them reporting the following fields: - ``name`` (string), unique identifier for this package manager. Usually, the executable name. @@ -266,21 +266,22 @@ take a list of dictionaries, with each of them reporting the following fields: - ``install``, to generate install instructions. The exit code MUST be ``0`` on success. - ``query``, to check whether a given package is already installed. If the package is - installed, the command MUST result in an exit code of ``0``. Otherwise, an exit code - of ``1`` SHOULD be used. + installed, the command MUST result in an exit code of ``0``. Otherwise, a non-zero exit code + MUST be returned. -- ``specifier_syntax``: instructions on how to map a subset of PEP 440 specifiers to - the target package manager. Three levels of support are offered: name-only, exact-version-only, - and version-range compatibility (with per-operator translations). +- ``specifier_syntax``: instructions on how to map a subset of PEP 440 specifiers (as determined + in PEP 725)to the target package manager. Three levels of support are offered: name-only, + exact-version-only, and version-range compatibility (with per-operator translations). Each mapping MUST have a canonical URL for online retrieval, with the filename following the rules described in the section below. These mappings MAY also be packaged for offline distribution in each platform. The authors -recommend placing in the standard location for data artifacts in each operating +recommend placing them in the standard location for data artifacts in each operating system; e.g. ``$XDG_DATA_DIRS`` on Linux and others, ``~/Library/Application Support`` on macOS, and ``%LOCALAPPDATA%`` for Windows. The subdirectory identifier MUST be ``external-packaging-metadata-mappings``. This data directory SHOULD only -contain mapping documents named ``{ecosystem-identifier}.mapping.json``. The central +contain mapping documents named ``{ecosystem-identifier}.mapping.json`` (see section below +for details on the construction of ecosystem identifiers). The central registry and known ecosystem documents MAY also be distributed in this directory, as ``registry.json`` and ``known-ecosystems.json``, respectively. @@ -447,7 +448,7 @@ The known ecosystems list is specified by the following * - Type - ``string`` * - Description - - URL of the mappings schema in use for the document. + - URL of the schema in use for the document. * - Required - False @@ -459,6 +460,8 @@ The known ecosystems list is specified by the following * - Type - ``integer`` + * - Description + - Version of the schema in use. * - Required - False @@ -486,7 +489,7 @@ to a sub-dictionary defined as: - Value type - Value description - Required - * - ``Literal['mapping']`` + * - ``mapping`` - ``AnyURL`` - URL to the mapping for this ecosystem - True @@ -518,6 +521,8 @@ The mappings are specified by the following * - Type - ``integer`` + * - Description + - Version of the schema in use. * - Required - False @@ -530,7 +535,7 @@ The mappings are specified by the following * - Type - ``string`` * - Description - - Name of the schema + - Name of the schema. * - Required - True @@ -541,7 +546,7 @@ The mappings are specified by the following :widths: 25 75 * - Type - - ``string | None`` + - ``string`` * - Description - Free-form field to add information this mapping. Allows Markdown. @@ -573,7 +578,7 @@ Each entry in this list is defined as: - Required * - ``id`` - ``DepURLField`` (``string`` matching regex ``^dep:.+$``) - - DepURL, as provided in the central registry + - DepURL, as provided in the central registry. - True * - ``description`` - ``string`` @@ -625,7 +630,7 @@ Each entry in this list is defined as a dictionary with these fields: - Required * - ``name`` - ``string`` - - Short identifier for this package manager (usually the command name) + - Short identifier for this package manager (usually the command name). - True * - ``commands`` - ``dict[Literal['install', 'query'], dict[Literal['command', 'requires_elevation', 'multiple_specifiers'], list[str] | bool | Literal['always', 'name-only', 'never']]]`` @@ -642,14 +647,14 @@ Each entry in this list is defined as a dictionary with these fields: (e.g. administrator on Windows, superuser on Linux and macOS). - an enum ``multiple_specifiers`` that determines whether the command - accepts multiple package specifiers at the same time, accepting one of: + accepts multiple package specifiers at the same time, taking one of: - - ``always``, default in ``install``. + - ``always``, default in ``install``. - - ``name-only``, the command only accepts multiple specifiers if they do - not contain version constraints. + - ``name-only``, the command only accepts multiple specifiers if they do + not contain version constraints. - - ``never``, default in ``query``. + - ``never``, default in ``query``. Exactly one of the ``command`` items MUST be the ``{}`` placeholder, which will be replaced by the mapped package specifier(s). The @@ -1044,9 +1049,11 @@ The ``pyproject-external`` Python API also allows users to do these operations p 'pixi' >>> external.to_dict(mapped_for=ecosystem, package_manager=package_manager) {'external': {'build_requires': ['c-compiler', 'cxx-compiler', 'python']}} - >>> external.install_command(ecosystem, package_manager=package_manager) + >>> external.install_commands(ecosystem, package_manager=package_manager) # {"command": ["pixi", "add", "{}"]} - ['pixi', 'add', 'c-compiler', 'cxx-compiler', 'python'] + [ + ['pixi', 'add', 'c-compiler', 'cxx-compiler', 'python'], + ] >>> external.query_commands(ecosystem, package_manager=package_manager) # {"command": ["pixi", "list", "{}"]} [ @@ -1117,7 +1124,7 @@ connectivity to fetch the mappings from their online sources. Instead: - they should vendor the relevant documents in the distributed packages, - or depend on prepackaged, offline distributions of these documents, -- or implement best-practices for authenticity verification of the fetched documents. +- or implement best practices for authenticity verification of the fetched documents. The install commands have the potential to modify the system configuration of the user. When available, tools should prefer creating ephemeral, isolated environments for the @@ -1153,14 +1160,16 @@ affordances like issue and pull request templates, or linting tools. Package ecosystem maintainers usage ----------------------------------- -Missing mapping entries will result in the absence tailored error messages and +Missing mapping entries will result in the absence of tailored error messages and other UX affordances for end users of the impacted ecosystems. It is thus recommended that each package ecosystem keeps their mappings up-to-date with the central registry. The key to this will be automation, like linting scripts -(see example at `external-metadata-mappings `__), +(see example at `external-metadata-mappings +`__), or periodic notifications via issues or draft submissions. -Establishing the initial mapping is likely to involve a lot of work, but ideally the maintenance on an ongoing basis effort should require smaller effort. +Establishing the initial mapping is likely to involve a lot of work, but ideally +the maintenance on an ongoing basis effort should require smaller effort. As best practices are discovered and agreed on, they should get documented in the central registry repository as learning materials for the mapping @@ -1188,7 +1197,7 @@ true if the user only relies on wheels, since the only impact will be driven by external runtime dependencies (expected to be rare), and even in those cases they need to opt-in by installing a compatible tool. -Users that do opt-in may find missing entries in for their target ecosystems, for +Users that do opt-in may find missing entries for their target ecosystems, for which they should obtain informative error messages that point to the relevant documentation sections. This will allow them to get acquainted with the nature of the issue and its potential solutions. @@ -1196,7 +1205,7 @@ of the issue and its potential solutions. We hope that this results in a subset of them reporting the missing entries, submitting a fix to the affected mapping or, if totally absent, even deciding to maintain a new one on their own. To that end, they should get familiar with -the responsibilties of mapping maintainers (discussed above). +the responsibilities of mapping maintainers (discussed above). Reference Implementation ======================== @@ -1261,7 +1270,7 @@ The reasons include: where that extra metadata can be obtained (e.g. the repository at the URL will likely include details about authorship and licensing). - These details can also be obtained from the actual target ecosystems. In some - cases this might even be preferable; e.g., for licenses, where downstream packaging + cases this might even be preferable; e.g. for licenses, where downstream packaging can actually affect it by unvendoring dependencies or adjusting optional bits. - Those details may change over the lifetime of the project, and keeping them up-to-date would increase the maintenance burden on the governance body. @@ -1342,8 +1351,8 @@ values. The authors have decided to not add this feature given the implied compl the following alternatives are proposed: - For mapping authors, automate the generation of derived mappings via scripting and - cronjobs. For example, simple logic such as fetching the parent mapping, applying the - necesary modifications and republishing it to the target location should not result + cron jobs. For example, simple logic such as fetching the parent mapping, applying the + necessary modifications and republishing it to the target location should not result in much maintenance burden. - For end-users wishing to extend a given mapping with custom overrides, client-side