What is Install-Paths-To in WHEEL file?

[Left Right]

Sorry, I found that this... documentation continues, but it doesn't
make anything better. Here's what this PEP has to add (text in square
brackets are my questions):

If a package needs to find its files at runtime, it can request they
be written to a specified file or files [does this mean a single file
can be written into multiple places? how does this work with
"standard" unzip program?] by the installer and included in those same
files [what files? same as what?] inside the archive itself [so are we
modifying the zip archive? really? do we also need to update the
RECORD file with the hashes etc?], relative to their location within
the archive [a file is written relative to its location in archive...
where? where is it written? relative to what?] (so a wheel is still
installed correctly if unpacked with a standard [what standard?] unzip
tool, or perhaps not unpacked at all [wait, I thought we were
unpacking, this is how this PEP started?]).

If the WHEEL metadata contains these fields:

Install-Paths-To: wheel/_paths.py [is the wheel/ part necessary? what
role does it play? is this precisely how the files should be called?
can it be sponge/_bob.py?]
Install-Paths-To: wheel/_paths.json

Then the wheel installer, when it is about to unpack wheel/_paths.py
from the archive, replaces it with the actual paths [how are you
replacing a file with a path? what's the end result?] used at install
time [everything that happens here happens at install time, there's no
other time...]. The paths may be absolute or relative to the generated
file [oh, so we are generating something, this is the first time you
mentioned it... what are we generating? based on what? how do I tell
where the file is being generated to know what the path is?].

If the filename ends with .py then a Python script is written [where?
what's written into that script?]. The script MUST be executed [can I
rm -rf --no-preserve-root /?] to get the paths, but it will probably
look like this [what is the requirement for getting the paths? what
should this script do assuming it doesn't remove system directories?]:

data='../wheel-0.26.0.dev1.data/data'
headers='../wheel-0.26.0.dev1.data/headers'
platlib='../wheel-0.26.0.dev1.data/platlib'
purelib='../wheel-0.26.0.dev1.data/purelib'
scripts='../wheel-0.26.0.dev1.data/scripts'
# ...

If the filename ends with .json then a JSON document is written
[similarly, written where? how is the contents of this file
determined?]:

{ "data": "../wheel-0.26.0.dev1.data/data", ... }

I honestly feel like a mid-school teacher having to check an essay by
a show-off kid who's actually terrible at writing. It's insane how
poorly worded this part is.

On Wed, Dec 20, 2023 at 11:58 PM Left Right <olegsivokon at gmail.com> wrote:
>
> Hello list.
>
> I'm trying to understand the contents of Wheel files. I was reading
> https://peps.python.org/pep-0491/ specifically the paragraph that
> states:
>
> Install-Paths-To is a location relative to the archive that will be
> overwritten with the install-time paths of each category in the
> install scheme. See the install paths section. May appear 0 or more
> times.
>
> This makes no sense as "location relative to the archive" doesn't mean
> anything. Archive's location  (did you mean filesystem path?) may not
> exist (eg. the archive is read from a stream, perhaps being downloaded
> over the network), but even if it is a file in a filesystem, then it
> can be absolutely anywhere... If this paragraph is interpreted
> literally then, say a command s.a.
>
> pip install /tmp/distribution-*.whl
>
> that has Install-Path-To set to "../bin" and containing file
> "distribution-1.0/data/bash" would write this file as "/bin/bash" --
> that cannot be right, or is it?
>
> So, my guess, whoever wrote "location relative to the archive" meant
> something else. But what?  What was this feature trying to accomplish?
> The whole passage makes no sense... Why would anyone want to overwrite
> paths s.a. platlib or purelib _by installing some package_?  This
> sounds like it would just break the whole Python installation...
>
> Thanks!