From ca4f78f54994f766957b5732a5c810015b709738 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 31 Oct 2025 16:15:08 +0100 Subject: [PATCH 01/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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 From 92e2e7f4ce892ed59e3cb9a30c8493cd483706c2 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Sat, 3 Jan 2026 16:48:23 +0100 Subject: [PATCH 12/22] Go back to "host" standard terminology (instead of "build-host") --- peps/pep-0804.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index 0159aec885f..ef3601dfe16 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -235,7 +235,7 @@ of dictionaries, in which each entry consists of: - a ``specs`` field whose value MUST be one of: - - a dictionary with three keys (``build``, ``build_host``, ``run``). The values + - a dictionary with three keys (``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). @@ -589,9 +589,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', 'build_host', 'run'], string | list[string]]`` + - ``string | list[string] | dict[Literal['build', 'host', 'run'], string | list[string]]`` - Ecosystem-specific identifiers for this package. The full form is a dictionary - that maps the categories ``build``, ``build_host`` and ``run`` to their corresponding + that maps the categories ``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. @@ -769,7 +769,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", - "build_host": "libwebp-base", + "host": "libwebp-base", "run": "libwebp" }, "urls": { @@ -784,7 +784,7 @@ for brevity, could look like: "clang", "clangxx" ], - "build_host": [ + "host": [ "clangdev" ], "run": [ @@ -907,7 +907,7 @@ plus ``meson-python`` as the build backend: build-requires = [ "dep:virtual/compiler/cxx", ] - build-host-requires = [ + host-requires = [ "dep:generic/zlib", ] @@ -922,7 +922,7 @@ following: build-requires = [ "dep:virtual/compiler/cxx", ] - build-host-requires = [ + host-requires = [ "dep:generic/zlib", ] @@ -933,7 +933,7 @@ following: "g++", "python3", ] - build-host-requires = [ + host-requires = [ "zlib1g", "zlib1g-dev", ] From 460efe3e13def74768e170aca774b85cbd8769f5 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 6 Feb 2026 00:26:50 +0100 Subject: [PATCH 13/22] Simplify complex `dict` type hints --- peps/pep-0804.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index ef3601dfe16..df34017e8c7 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -633,7 +633,7 @@ Each entry in this list is defined as a dictionary with these fields: - 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']]]`` + - ``dict`` - Commands used to install or query the given package(s). Only two keys are allowed: ``install`` (to generate install instructions) and ``query`` (to check whether a given package is already installed). Their value is a dictionary @@ -663,7 +663,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', 'syntax'], None | str | list[str]]`` + - ``dict`` - Mapping of allowed PEP440 version specifiers to the syntax used in this package manager. Three top-level keys are expected and required: From 53f35483c265590b871e457ab7cfc3450c8d6996 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 6 Feb 2026 00:30:12 +0100 Subject: [PATCH 14/22] Rearrange some "Required" columns --- peps/pep-0804.rst | 31 +++++++++---------------------- 1 file changed, 9 insertions(+), 22 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index df34017e8c7..9fbc179f7f5 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -414,24 +414,19 @@ Each entry in this list is defined as: * - Field - Type - Description - - Required - * - ``id`` + * - ``id`` (required) - ``DepURLField`` (``string`` matching regex ``^dep:.+$``) - DepURL - - True * - ``description`` - ``string`` - Free-form field to add some details about the package. Allows Markdown. - - False * - ``provides`` - ``DepURLField | list[DepURLField]`` - List of identifiers this entry connects to. Useful to annotate aliases or virtual package implementations. - - False * - ``urls`` - ``AnyUrl | list[AnyUrl] | dict[NonEmptyString, AnyUrl]`` - Hyperlinks to web locations that provide more information about the definition. - - False Known ecosystems schema ^^^^^^^^^^^^^^^^^^^^^^^ @@ -575,11 +570,9 @@ Each entry in this list is defined as: * - Field - Type - Description - - Required - * - ``id`` + * - ``id`` (required) - ``DepURLField`` (``string`` matching regex ``^dep:.+$``) - DepURL, as provided in the central registry. - - True * - ``description`` - ``string`` - Free-form field to add some details about the package. Allows Markdown. @@ -588,21 +581,20 @@ Each entry in this list is defined as: - ``AnyUrl | list[AnyUrl] | dict[NonEmptyString, AnyUrl]`` - Hyperlinks to web locations that provide more information about the definition. - False - * - ``specs`` + * - ``specs`` † - ``string | list[string] | dict[Literal['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 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. - * - ``specs_from`` + * - ``specs_from`` † - ``DepURLField`` (``string`` matching regex ``^dep:.+$``) - Take specs from another mapping entry. - - Either ``specs`` or ``specs_from`` MUST be present. * - ``extra_metadata`` - ``dict[NonEmptyString, Any]`` - Free-form key-value store for arbitrary metadata. - - False + +† One of ``specs`` and ``specs_from`` MUST be present. ``package_managers`` ~~~~~~~~~~~~~~~~~~~~ @@ -627,12 +619,10 @@ Each entry in this list is defined as a dictionary with these fields: * - Field - Type - Description - - Required - * - ``name`` + * - ``name`` (required) - ``string`` - Short identifier for this package manager (usually the command name). - - True - * - ``commands`` + * - ``commands`` (required) - ``dict`` - Commands used to install or query the given package(s). Only two keys are allowed: ``install`` (to generate install instructions) and ``query`` (to @@ -661,8 +651,7 @@ Each entry in this list is defined as a dictionary with these fields: ``install`` command SHOULD support the placeholder being replaced by multiple specifiers, ``query`` MUST only receive a single specifier per command. - - True - * - ``specifier_syntax`` + * - ``specifier_syntax`` (required) - ``dict`` - Mapping of allowed PEP440 version specifiers to the syntax used in this package manager. Three top-level keys are expected and required: @@ -701,8 +690,6 @@ Each entry in this list is defined as a dictionary with these fields: indicates that the respective types of specifiers are not supported by the package manager. - - True - Examples -------- From 24c6f952bb1de23b4437b4f4b840e44de376fa04 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 6 Feb 2026 00:31:31 +0100 Subject: [PATCH 15/22] It's schemas.py --- peps/pep-0804.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index 9fbc179f7f5..4064ce997ed 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -1212,7 +1212,7 @@ For (2), the JSON Schema is defined at `external-mapping.schema.json `__. For (3), the JSON Schema is defined at `known-ecosystems.schema.json `__. An example list can be found at `known-ecosystems.json `__. -The JSON Schemas are created with `these Pydantic models `__. +The JSON Schemas are created with `these Pydantic models `__. The reference CLI and Python API to consume the different JSON documents and ``[external]`` tables can be found in `pyproject-external `__. From 3f550e588879ee63df91b8eb580371f770df6b1b Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 6 Feb 2026 00:32:20 +0100 Subject: [PATCH 16/22] Fix debian PURL --- peps/pep-0804.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index 4064ce997ed..96bd0852e8f 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -1233,7 +1233,7 @@ Allowing ecosystem-specific variants of packages ------------------------------------------------ Some ecosystems have their own variants of known packages; e.g. Debian's -``libsymspg2-dev``. While an identifier such as ``dep:debian/libsymspg2-dev`` +``libsymspg2-dev``. While an identifier such as ``dep:deb/debian/libsymspg2-dev`` is syntactically valid, the central registry should not recognize it as a well-known identifier, preferring its ``generic`` counterpart instead. Users may still choose to use it, but tools may warn about it and suggest using the From 3a9bcae59f1f2647fb5488f59da31200b95d89c4 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 6 Feb 2026 00:50:33 +0100 Subject: [PATCH 17/22] Redistribute widths --- peps/pep-0804.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index 96bd0852e8f..92ab463b3c1 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -409,7 +409,7 @@ Each entry in this list is defined as: .. list-table:: :header-rows: 1 - :widths: 20 25 40 15 + :widths: 25 25 50 * - Field - Type @@ -565,7 +565,7 @@ Each entry in this list is defined as: .. list-table:: :header-rows: 1 - :widths: 20 25 40 15 + :widths: 25 25 50 * - Field - Type @@ -576,11 +576,9 @@ Each entry in this list is defined as: * - ``description`` - ``string`` - Free-form field to add some details about the package. Allows Markdown. - - False * - ``urls`` - ``AnyUrl | list[AnyUrl] | dict[NonEmptyString, AnyUrl]`` - Hyperlinks to web locations that provide more information about the definition. - - False * - ``specs`` † - ``string | list[string] | dict[Literal['build', 'host', 'run'], string | list[string]]`` - Ecosystem-specific identifiers for this package. The full form is a dictionary @@ -614,7 +612,7 @@ Each entry in this list is defined as a dictionary with these fields: .. list-table:: :header-rows: 1 - :widths: 20 25 40 15 + :widths: 25 25 50 * - Field - Type From 3f24658e9bfae1af6881877e165e493817530b90 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 6 Feb 2026 00:58:29 +0100 Subject: [PATCH 18/22] Move `commands` and `specifier_syntax` details to subsections --- peps/pep-0804.rst | 125 ++++++++++++++++++++++++---------------------- 1 file changed, 66 insertions(+), 59 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index 92ab463b3c1..27a7f591e98 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -612,7 +612,7 @@ Each entry in this list is defined as a dictionary with these fields: .. list-table:: :header-rows: 1 - :widths: 25 25 50 + :widths: 25 15 60 * - Field - Type @@ -622,71 +622,78 @@ Each entry in this list is defined as a dictionary with these fields: - Short identifier for this package manager (usually the command name). * - ``commands`` (required) - ``dict`` - - Commands used to install or query the given package(s). Only two keys - are allowed: ``install`` (to generate install instructions) and ``query`` (to - check whether a given package is already installed). Their value is a dictionary - with: + - Commands used to install or query the given package(s). See subsection + below for more details. + * - ``specifier_syntax`` (required) + - ``dict`` + - Mapping of allowed PEP440 version specifiers to the syntax used in this + package manager. See subsection below for more details. - - a required key ``command`` that takes a list of strings - (as expected by ``subprocess.run``). +``commands`` +"""""""""""" - - an optional ``requires_elevation`` boolean (``False`` by default) - to indicate whether the command must run with elevated permissions - (e.g. administrator on Windows, superuser on Linux and macOS). +Only two keys are allowed: ``install`` (to generate install instructions) and +``query`` (to check whether a given package is already installed). Their value +is a dictionary with: - - an enum ``multiple_specifiers`` that determines whether the command - accepts multiple package specifiers at the same time, taking one of: +- a required key ``command`` that takes a list of strings (as expected by + ``subprocess.run``). - - ``always``, default in ``install``. +- an optional ``requires_elevation`` boolean (``False`` by default) to indicate + whether the command must run with elevated permissions (e.g. administrator on + Windows, superuser on Linux and macOS). - - ``name-only``, the command only accepts multiple specifiers if they do - not contain version constraints. +- an enum ``multiple_specifiers`` that determines whether the command accepts + multiple package specifiers at the same time, taking one of: - - ``never``, default in ``query``. + - ``always``, default in ``install``. - 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 specifiers, ``query`` MUST only receive a single specifier - per command. - * - ``specifier_syntax`` (required) - - ``dict`` - - Mapping of allowed PEP440 version specifiers to the syntax used in this - package manager. Three top-level keys are expected and required: - - - ``name_only`` MUST take a list of strings as the syntax used for specifiers - that do not contain any version information; it MUST include the placeholder - ``{name}``. - - - ``exact_version`` MUST be ``None`` or a list of strings that describe - the syntax used for specifiers that only express exact version - constraints; in the latter case, the placeholders ``{name}`` - and ``{version}`` MUST be present in at least one of the strings - (although not necessary the same string for both). - - - ``version_ranges`` MUST be ``None`` or a dictionary with the - following required keys: - - - the key ``syntax`` takes a list of strings where at least one MUST - include the ``{ranges}`` placeholder (to be replaced by the - maybe-joined version constraints, as determined by the value of - ``and``). They MAY also include the ``{name}`` placeholder. - - - the keys ``equal``, ``greater_than``, ``greater_than_equal``, - ``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}``. - - - 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 - ``syntax`` template. - - When ``exact_version`` or ``version_ranges`` are set to ``None``, it - indicates that the respective types of specifiers are not supported - by the package manager. + - ``name-only``, the command only accepts multiple specifiers if they do not + contain version constraints. + + - ``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 ``install`` command SHOULD +support the placeholder being replaced by multiple specifiers, ``query`` MUST +only receive a single specifier per command. + +``specifier_syntax`` +"""""""""""""""""""" + +Three top-level keys are expected and required: + +- ``name_only`` MUST take a list of strings as the syntax used for specifiers + that do not contain any version information; it MUST include the placeholder + ``{name}``. + +- ``exact_version`` MUST be ``None`` or a list of strings that describe the + syntax used for specifiers that only express exact version constraints; in + the latter case, the placeholders ``{name}`` and ``{version}`` MUST be + present in at least one of the strings (although not necessary the same + string for both). + +- ``version_ranges`` MUST be ``None`` or a dictionary with the following + required keys: + + - the key ``syntax`` takes a list of strings where at least one MUST include + the ``{ranges}`` placeholder (to be replaced by the maybe-joined version + constraints, as determined by the value of ``and``). They MAY also include + the ``{name}`` placeholder. + + - the keys ``equal``, ``greater_than``, ``greater_than_equal``, + ``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}``. + + - 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 ``syntax`` template. + + When ``exact_version`` or ``version_ranges`` are set to ``None``, it + indicates that the respective types of specifiers are not supported by the + package manager. Examples From 15aef06bbf582df17a58467c4e5d7d71f7c569f7 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 6 Feb 2026 01:05:11 +0100 Subject: [PATCH 19/22] Prettier tables --- peps/pep-0804.rst | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index 27a7f591e98..d4edfe056d3 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -334,6 +334,7 @@ The complete filename MUST be ``{identifier}.mapping.json``. Some examples: .. list-table:: + :header-rows: 1 * - Ecosystem - Identifier @@ -372,7 +373,8 @@ The central registry is specified by the following ~~~~~~~~~~~ .. list-table:: - :widths: 25 75 + :widths: 15 85 + :stub-columns: 1 * - Type - ``string`` @@ -385,7 +387,8 @@ The central registry is specified by the following ~~~~~~~~~~~~~~~~~~ .. list-table:: - :widths: 25 75 + :widths: 15 85 + :stub-columns: 1 * - Type - ``integer`` @@ -396,7 +399,8 @@ The central registry is specified by the following ~~~~~~~~~~~~~~~ .. list-table:: - :widths: 25 75 + :widths: 15 85 + :stub-columns: 1 * - Type - ``array`` @@ -438,7 +442,8 @@ The known ecosystems list is specified by the following ~~~~~~~~~~~ .. list-table:: - :widths: 25 75 + :widths: 15 85 + :stub-columns: 1 * - Type - ``string`` @@ -451,7 +456,8 @@ The known ecosystems list is specified by the following ~~~~~~~~~~~~~~~~~~ .. list-table:: - :widths: 25 75 + :widths: 15 85 + :stub-columns: 1 * - Type - ``integer`` @@ -464,7 +470,8 @@ The known ecosystems list is specified by the following ~~~~~~~~~~~~~~ .. list-table:: - :widths: 25 75 + :widths: 15 85 + :stub-columns: 1 * - Type - ``dict`` @@ -499,7 +506,8 @@ The mappings are specified by the following ~~~~~~~~~~~ .. list-table:: - :widths: 25 75 + :widths: 15 85 + :stub-columns: 1 * - Type - ``string`` @@ -512,7 +520,8 @@ The mappings are specified by the following ~~~~~~~~~~~~~~~~~~ .. list-table:: - :widths: 25 75 + :widths: 15 85 + :stub-columns: 1 * - Type - ``integer`` @@ -525,7 +534,8 @@ The mappings are specified by the following ~~~~~~~~ .. list-table:: - :widths: 25 75 + :widths: 15 85 + :stub-columns: 1 * - Type - ``string`` @@ -538,7 +548,8 @@ The mappings are specified by the following ~~~~~~~~~~~~~~~ .. list-table:: - :widths: 25 75 + :widths: 15 85 + :stub-columns: 1 * - Type - ``string`` @@ -552,7 +563,8 @@ The mappings are specified by the following ~~~~~~~~~~~~ .. list-table:: - :widths: 25 75 + :widths: 15 85 + :stub-columns: 1 * - Type - ``array`` @@ -598,7 +610,8 @@ Each entry in this list is defined as: ~~~~~~~~~~~~~~~~~~~~ .. list-table:: - :widths: 25 75 + :widths: 15 85 + :stub-columns: 1 * - Type - ``array`` From bac156302fc44d7774497c7a8d8764c292c76308 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 6 Feb 2026 01:19:59 +0100 Subject: [PATCH 20/22] Merge Schema sections with their corresponding entries in Specifications --- peps/pep-0804.rst | 288 +++++++++++++++++++++++----------------------- 1 file changed, 141 insertions(+), 147 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index d4edfe056d3..3daed33671c 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -222,149 +222,8 @@ canonical, or which versioning scheme applies to virtual DepURLs (see Appendix B). The corresponding answers are not given in this PEP; instead we delegate that responsibility to the central registry maintainers. -Mappings --------- - -The mappings specify which ecosystem-specific identifiers provide the canonical -entries available in the central registry. A mapping mainly consists of a list -of dictionaries, in which each entry consists of: - -- an ``id`` field with the canonical DepURL. - -- an optional free form ``description`` text. - -- a ``specs`` field whose value MUST be one of: - - - a dictionary with three keys (``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). - - - for convenience, a string or a list of strings are also accepted as a - shorthand form. In this case, the identifier(s) will be used to populate - the three categories mentioned in the item above. - - - an empty list, which is understood as the ecosystem not having packages to - provide such dependency. - -- a ``specs_from`` field whose value is a DepURL from which the ``specs`` - 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 non-empty string to a URL. This is useful to link to external - resources that provide more information about the mapped packages. - -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 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. - -- ``commands`` (list of dictionaries), the commands to run to install the mapped package(s) and - 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, a non-zero exit code - MUST be returned. - -- ``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 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`` (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. - -.. 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 ----------------- - -The list of known ecosystems has two roles: - -1. Reporting the canonical URL for its mapping. -2. Assigning a unique, short identifier to each ecosystem. - -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:: - :header-rows: 1 - - * - 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 --------------- - -Three JSON Schema documents are provided to fully standardize the registries and mappings. - -Central registry schema -^^^^^^^^^^^^^^^^^^^^^^^ +Schema +^^^^^^ The central registry is specified by the following `JSON schema `__: @@ -432,8 +291,61 @@ Each entry in this list is defined as: - ``AnyUrl | list[AnyUrl] | dict[NonEmptyString, AnyUrl]`` - Hyperlinks to web locations that provide more information about the definition. -Known ecosystems schema -^^^^^^^^^^^^^^^^^^^^^^^ +Known ecosystems +---------------- + +The list of known ecosystems has two roles: + +1. Reporting the canonical URL for its mapping. +2. Assigning a unique, short identifier to each ecosystem. + +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:: + :header-rows: 1 + + * - 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 +^^^^^^ The known ecosystems list is specified by the following `JSON Schema `__: @@ -496,8 +408,90 @@ to a sub-dictionary defined as: - URL to the mapping for this ecosystem - True -Mappings schema -^^^^^^^^^^^^^^^ +Mappings +-------- + +The mappings specify which ecosystem-specific identifiers provide the canonical +entries available in the central registry. A mapping mainly consists of a list +of dictionaries, in which each entry consists of: + +- an ``id`` field with the canonical DepURL. + +- an optional free form ``description`` text. + +- a ``specs`` field whose value MUST be one of: + + - a dictionary with three keys (``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). + + - for convenience, a string or a list of strings are also accepted as a + shorthand form. In this case, the identifier(s) will be used to populate + the three categories mentioned in the item above. + + - an empty list, which is understood as the ecosystem not having packages to + provide such dependency. + +- a ``specs_from`` field whose value is a DepURL from which the ``specs`` + 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 non-empty string to a URL. This is useful to link to external + resources that provide more information about the mapped packages. + +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 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. + +- ``commands`` (list of dictionaries), the commands to run to install the mapped package(s) and + 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, a non-zero exit code + MUST be returned. + +- ``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 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`` (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. + +.. 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. + +Schema +^^^^^^ The mappings are specified by the following `JSON Schema `__: From 1381cafa25a648c4e2d8f30c54e308bd5a929422 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 6 Feb 2026 01:25:08 +0100 Subject: [PATCH 21/22] Rearrange examples --- peps/pep-0804.rst | 69 ++++++++++++++++++++++++++--------------------- 1 file changed, 39 insertions(+), 30 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index 3daed33671c..fff846e39a9 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -317,33 +317,6 @@ identifier but fallback to the name-only identifier if not found. The complete filename MUST be ``{identifier}.mapping.json``. -Some examples: - -.. list-table:: - :header-rows: 1 - - * - 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 ^^^^^^ @@ -706,8 +679,8 @@ Three top-level keys are expected and required: Examples -------- -Registry, known ecosystems and mappings -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Registry +^^^^^^^^ A simplified registry would look like this: @@ -732,6 +705,9 @@ A simplified registry would look like this: ] } +Known ecosystems +^^^^^^^^^^^^^^^^ + A minimal list of known ecosystems with a single entry would look like this: .. code-block:: js @@ -745,7 +721,37 @@ A minimal list of known ecosystems with a single entry would look like this: } } -That hypothetical conda-forge mapping (``conda-forge.mapping.json``), with only a couple entries +Some representative identifiers: + +.. list-table:: + :header-rows: 1 + + * - 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`` + +Mappings +^^^^^^^^ + +A hypothetical conda-forge mapping (``conda-forge.mapping.json``), with only a couple entries for brevity, could look like: .. code-block:: js @@ -845,6 +851,9 @@ for brevity, could look like: ] } +Practical examples +^^^^^^^^^^^^^^^^^^ + The following repository provides examples of how these schemas *could* look like in real cases. They are not meant to be prescriptive, but just illustrative of how to apply these schemas: From fbad6da31b351562aca1cc1878d8215277efbb75 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 6 Feb 2026 11:54:02 +0100 Subject: [PATCH 22/22] Remove almost-duplicate list --- peps/pep-0804.rst | 7 ------- 1 file changed, 7 deletions(-) diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst index fff846e39a9..81ad7e3e0d5 100644 --- a/peps/pep-0804.rst +++ b/peps/pep-0804.rst @@ -182,13 +182,6 @@ instead of ``apt`` as their package manager of choice to provide external depen Specification ============= -Three schemas are proposed: - -1. A central registry of known DepURLs, as introduced in PEP 725. -2. A list of known ecosystems and the canonical URL for their mappings. -3. The ecosystem-specific mappings of DepURLs to their - corresponding ecosystem specifiers, plus details of their package manager(s). - Central registry ----------------