Replace confusing pyproject.toml with backend string in logs

[abravalheri]

In #12339, it was pointed out that displaying logs like:

Preparing editable metadata (pyproject.toml): started
Preparing editable metadata (pyproject.toml): finished with status 'done'
Building editable for X (pyproject.toml): started
Building editable for X (pyproject.toml): finished with status 'done'

can be a source of confusion for users, when the package does not contain any pyproject.toml.

Since the API-based build process (described in PEP 517/660) does not actually need a pyproject.toml, I propose that a better way to communicate to the end-user this is the kind of process being used would be to show the "backend string".

If we take the logs above as example, this change would mean printing the following:

Preparing editable metadata (setuptools.build_meta:__legacy__): started
Preparing editable metadata (setuptools.build_meta:__legacy__): finished with status 'done'
Building editable for X (setuptools.build_meta:__legacy__): started
Building editable for X (setuptools.build_meta:__legacy__): finished with status 'done'

This should leave less margin of confusion, and communicate clearly for anyone trying to debug a problem what is the direction to look for.

Resolves #12339.

[abravalheri]

This is how the CLI output would look like:

# docker run --rm -it python:3.12-bullseye /bin/bash
mkdir /tmp/test
cd /tmp/test
python -m venv .venv
.venv/bin/python -m pip install -U https://github.com/abravalheri/pip/archive/refs/heads/buildapi-logs.zip
.venv/bin/python -m pip uninstall -y setuptools wheel

echo '__import__("setuptools").setup(name="test")' > setup.py

.venv/bin/python -m pip install -e .
# Obtaining file:///tmp/test
#   Installing build dependencies ... done
#   Checking if build backend supports build_editable ... done
#   Getting requirements to build editable ... done
#   Preparing editable metadata (setuptools.build_meta:__legacy__) ... done
# Building wheels for collected packages: test
#   Building editable for test (setuptools.build_meta:__legacy__) ... done
#   Created wheel for test: filename=test-0.0.0-0.editable-py3-none-any.whl size=2355 sha256=6c44c0b61504f5ef8e5eda99abaa1ffab8a2dc1599d6828912a5279383aba121
#   Stored in directory: /tmp/pip-ephem-wheel-cache-vonlmnjk/wheels/c2/df/a4/7854454926d99c1de479bd8f63b77e8cae49fc28b0a8152d04
# Successfully built test
# Installing collected packages: test
# Successfully installed test-0.0.0

.venv/bin/python -m pip install -I .
# Processing /tmp/test
#   Installing build dependencies ... done
#   Getting requirements to build wheel ... done
#   Preparing metadata (setuptools.build_meta:__legacy__) ... done
# Building wheels for collected packages: test
#   Building wheel for test (setuptools.build_meta:__legacy__) ... done
#   Created wheel for test: filename=test-0.0.0-py3-none-any.whl size=894 sha256=07a5cee46e13c1f6a3c0a5a8d42a59a38d1651fb6284085bdb1e0a7e018cbff7
#   Stored in directory: /tmp/pip-ephem-wheel-cache-hvu98_o8/wheels/c2/df/a4/7854454926d99c1de479bd8f63b77e8cae49fc28b0a8152d04
# Successfully built test
# Installing collected packages: test
# Successfully installed test-0.0.0

[pradyunsg]

This is currently used to differentiate which build-system interface it's using (i.e. via the setup.py-based model or via the pyproject.toml-based model -- https://pip.pypa.io/en/stable/reference/build-system/#determining-which-build-system-interface-is-used), so I'd prefer to keep "pyproject.toml" in the message.

That said, I like the idea of including the build-backend information in addition to the pyproject.toml interface information.

[abravalheri]

so I'd prefer to keep "pyproject.toml" in the message.

Hi @pradyunsg, the problem with keeping pyproject.toml is that it is confusing for users (see #12339), when no pyproject.toml exists.

Do you have a different suggestion other than the backend name for clarifying this aspect?

I think that calling pyproject.toml-based model is a bit misleading because the to use the APIs described PEP 517 and PEP 660, pyproject.toml does not have to exist (as pip is currently doing for certain states of the installation environment).

[pradyunsg]

the problem with keeping pyproject.toml is that it is confusing for users (see #12339), when no pyproject.toml exists.

I'd argue that I think setuptools.build_meta:__legacy__ is more confusing in more instances than this one (which doesn't mean that status quo isn't confusing as well :P).

calling pyproject.toml-based model is misleading because the process described by PEP 517 and PEP 660 does not actually require a pyproject.toml file to exist.

Hmm... that's fair. This is a hold-over from when pip would only do that when the file existed.

None the less, changing this only in the code isn't sufficient regardless, and if we want to change this, we also need to update the corresponding documentation/communication around this well.

FWIW, I picked that name based on the discussion at https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659 where no one voiced any concerns around this and it's in line with what we're doing in multiple places.

Do you have a different suggestion other than the backend name for clarifying this aspect?

At the moment, not really. This is a non-trivial situation.

I want to improve the output we present as part of the build process more generally and, with that, I'd like to add more context on why pip is performing the build in the manner that it is performing it, but that's a more future-facing thing -- something like that is more descriptive and provides a clearer mental model for end users.

[abravalheri]

None the less, changing this only in the code isn't sufficient regardless, and if we want to change this, we also need to update the corresponding documentation/communication around this well.

In 36098fd I am giving it a try to update the docs. Probably not the best change in the universe, but it is an attempt.

Please feel free to change the words... I am just attempting to change it from pyproject.toml-based to something else, but I don't really mind the exact words.

It also contains some minor updates in relation to the behaviour implemented in the latest version of pip.

[sbidoul]

Maybe we could add a __str__ method to BuildBackendHookCaller that renders pyproject.toml - {self.build_backend} unless it is the default backend, in which case it renders the same without pyproject.toml?