From 6f692c00c1cb96e166f104d2657b630a1579b7e6 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Wed, 2 Oct 2024 16:47:38 -0700 Subject: [PATCH] Reword the intro to the specifications section, and other improvements --- peps/pep-0759.rst | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/peps/pep-0759.rst b/peps/pep-0759.rst index 7fea965deb1..810f4d19247 100644 --- a/peps/pep-0759.rst +++ b/peps/pep-0759.rst @@ -158,11 +158,12 @@ This PEP proposes an approach that favors such operational simplicity. Specification ============= -A new type of uploadable file is defined, called a "RIM" (i.e. ``.rim``) file, so named to -evoke the image of a wheel with the tire removed, and backronymed to "Remote Installable -Metadata" files. ``.rim`` files are easily derivable from wheels, and the process of -turning a wheel into a ``.rim`` is outlined below. The file name format exactly matches -the `wheel file naming format`_ specification, except that RIM files use the suffix +A new type of uploadable file is defined, called a "RIM" (i.e. ``.rim``), or "Remote +Installable Metadata" file. The name evokes the image of a wheel with the tire removed, +and emphasizes that ``.rim`` files are easily derived from ``.whl`` files. The process of +turning a ``.whl`` into a ``.rim`` is :ref:`outlined below `. The file name +format exactly matches the :ref:`wheel file naming format +` specification, except that RIM files use the suffix ``.rim``. This means that all the tags used to discriminate ``.whl`` files also distinguish between different ``.rim`` files, and thus can be used during dependency resolution steps, exactly as ``.whl`` files are today. In this respect, ``.whl`` and @@ -182,12 +183,13 @@ This is a JSON file contains containing the following keys: This is the file format version, which for this PEP **MUST** be ``1.0``. ``owner`` This **MUST** name the PyPI organization owner of this externally hosted file, for - reasons which will be described in detail below. + reasons which will be described in :ref:`detail below `. ``uri`` This is a single URL naming the location of the physical ``.whl`` file hosted on an external site. This URL **MUST** use the ``https`` scheme. ``size`` - This is an integer value describing the size in bytes of the physical ``.whl`` file. + This is an integer value describing the size in bytes of the physical ``.whl`` file on + the remote host. ``hashes`` This is a dictionary of the format described in :pep:`694`, used to capture both the :pep:`694#upload-each-file` of the physical ``.whl`` file, with the same @@ -247,6 +249,8 @@ repository version`_ is not necessary. Since ``.rim`` files are essentially chan to the upload API, package resolvers and package installers can continue to function with the APIs they've always supported. +.. _resiliency: + External hosting resiliency =========================== @@ -303,6 +307,8 @@ provide a useful error message to the end user: downloaded. Please contact support@foo.example.com for help. Do not report this to the PyPI administrators. +.. _dismounting: + Dismounting wheels ================== @@ -456,7 +462,6 @@ This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. .. _`exception request support tickets`: https://github.com/pypi/support/issues?q=is%3Aissue+is%3Aclosed+file+limit+request -.. _`wheel file naming format`: https://packaging.python.org/en/latest/specifications/binary-distribution-format/#file-format .. _`allowed`: https://packaging.python.org/en/latest/specifications/binary-distribution-format/#the-dist-info-directory .. _`signed wheel file format`: https://packaging.python.org/en/latest/specifications/binary-distribution-format/#signed-wheel-files .. _`simple repository API`: https://packaging.python.org/en/latest/specifications/simple-repository-api/#