Fix some typos and polish some details

Author: jaimergp

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,23 +72,23 @@ RPM-based distributions, like Fedora, can use a `rule-based implementation
 <https://discuss.python.org/t/wanting-a-singular-packaging-tool-vision/21141/117>`__
 (``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 <https://docs.fedoraproject.org/en-US/packaging-guidelines/Python/#_naming>`__.
 
 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 <https://www.debian.org/doc/packaging-manuals/python-policy/#module-package-names>`__.
 
 Gentoo follows a similar approach to naming Python packages, using the ``dev-python/``
 category and some `well-specified rules <https://projects.gentoo.org/python/guide/package-maintenance.html>`__.
 
 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 <https://github.com/regro/cf-graph-countyfair/tree/master/mappings/pypi>`__.
@@ -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 <https://github.com/jaimergp/external-metadata-mappings/blob/main/scripts/lint-mapping-entries.py>`__),
+(see example at `external-metadata-mappings
+<https://github.com/jaimergp/external-metadata-mappings/blob/main/scripts/lint-mapping-entries.py>`__),
 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,15 +1197,15 @@ 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.
 
 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