From ef0c98facac639501d2a461cf29238f5703d4c06 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 13 Oct 2023 10:17:22 +0100 Subject: [PATCH 1/4] Replace `pyproject.toml` with backend string in logs In issue 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. --- src/pip/_internal/operations/build/metadata.py | 4 +++- src/pip/_internal/operations/build/metadata_editable.py | 2 +- src/pip/_internal/operations/build/wheel.py | 2 +- src/pip/_internal/operations/build/wheel_editable.py | 2 +- 4 files changed, 6 insertions(+), 4 deletions(-) diff --git a/src/pip/_internal/operations/build/metadata.py b/src/pip/_internal/operations/build/metadata.py index c66ac354d..78b3f277e 100644 --- a/src/pip/_internal/operations/build/metadata.py +++ b/src/pip/_internal/operations/build/metadata.py @@ -29,7 +29,9 @@ def generate_metadata( # Note that BuildBackendHookCaller implements a fallback for # prepare_metadata_for_build_wheel, so we don't have to # consider the possibility that this hook doesn't exist. - runner = runner_with_spinner_message("Preparing metadata (pyproject.toml)") + runner = runner_with_spinner_message( + f"Preparing metadata ({backend.build_backend})" + ) with backend.subprocess_runner(runner): try: distinfo_dir = backend.prepare_metadata_for_build_wheel(metadata_dir) diff --git a/src/pip/_internal/operations/build/metadata_editable.py b/src/pip/_internal/operations/build/metadata_editable.py index 27c69f0d1..c95f589db 100644 --- a/src/pip/_internal/operations/build/metadata_editable.py +++ b/src/pip/_internal/operations/build/metadata_editable.py @@ -30,7 +30,7 @@ def generate_editable_metadata( # prepare_metadata_for_build_wheel/editable, so we don't have to # consider the possibility that this hook doesn't exist. runner = runner_with_spinner_message( - "Preparing editable metadata (pyproject.toml)" + f"Preparing editable metadata ({backend.build_backend})" ) with backend.subprocess_runner(runner): try: diff --git a/src/pip/_internal/operations/build/wheel.py b/src/pip/_internal/operations/build/wheel.py index 064811ad1..b1e3a01d1 100644 --- a/src/pip/_internal/operations/build/wheel.py +++ b/src/pip/_internal/operations/build/wheel.py @@ -24,7 +24,7 @@ def build_wheel_pep517( logger.debug("Destination directory: %s", tempd) runner = runner_with_spinner_message( - f"Building wheel for {name} (pyproject.toml)" + f"Building wheel for {name} ({backend.build_backend})" ) with backend.subprocess_runner(runner): wheel_name = backend.build_wheel( diff --git a/src/pip/_internal/operations/build/wheel_editable.py b/src/pip/_internal/operations/build/wheel_editable.py index 719d69dd8..7aaa08661 100644 --- a/src/pip/_internal/operations/build/wheel_editable.py +++ b/src/pip/_internal/operations/build/wheel_editable.py @@ -24,7 +24,7 @@ def build_wheel_editable( logger.debug("Destination directory: %s", tempd) runner = runner_with_spinner_message( - f"Building editable for {name} (pyproject.toml)" + f"Building editable for {name} ({backend.build_backend})" ) with backend.subprocess_runner(runner): try: From ae701fd440690c847dfbaa757d86a9a0a2befecb Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 13 Oct 2023 10:35:38 +0100 Subject: [PATCH 2/4] Add news entry --- news/12346.trivial.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 news/12346.trivial.rst diff --git a/news/12346.trivial.rst b/news/12346.trivial.rst new file mode 100644 index 000000000..c488c93b3 --- /dev/null +++ b/news/12346.trivial.rst @@ -0,0 +1 @@ +Replace confusing ``pyproject.toml`` with backend string in logs. From 36098fd9521c9675f23632e9cb35c8649b90d6bd Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 13 Oct 2023 12:39:01 +0100 Subject: [PATCH 3/4] Update docs to avoid refering to API-based builds as pyproject.toml --- docs/html/reference/build-system/index.md | 36 +++++++++++++------ .../reference/build-system/pyproject-toml.md | 5 ++- docs/html/reference/build-system/setup-py.md | 4 +-- 3 files changed, 31 insertions(+), 14 deletions(-) diff --git a/docs/html/reference/build-system/index.md b/docs/html/reference/build-system/index.md index ed43fec37..72575a7d0 100644 --- a/docs/html/reference/build-system/index.md +++ b/docs/html/reference/build-system/index.md @@ -17,7 +17,7 @@ setup-py ``` -[`pyproject.toml` based](pyproject-toml) +[*Backend API* based](pyproject-toml) : Standards-backed interface, that has explicit declaration and management of build dependencies. @@ -33,36 +33,50 @@ the build system interfaces that pip may use. ## Determining which build system interface is used -Currently, pip uses the `pyproject.toml` based build system interface, if a -`pyproject.toml` file exists. If not, the legacy build system interface is used. -The intention is to switch to using the `pyproject.toml` build system interface +Currently, pip uses the *backend API* based build system interface, in the +following scenarios: + +- if a `pyproject.toml` file exists, or +- if {pypi}`setuptools` or {pypi}`wheel` is not installed. + +Otherwise, the legacy build system interface is used. +The intention is to switch to using the *backend API* build system interface unconditionally and to drop support for the legacy build system interface at some point in the future. When performing a build, pip will mention which build system interface it is -using. Typically, this will take the form of a message like: +using. For the *backend API* based build system interface, +typically this will take the form of a message like[^2]: ```none -Building wheel for pip (pyproject.toml)... done +Building wheel for pip ()... done ``` +[^2]: Here `` is replaced with the actual value for + the given package, e.g. `Building wheel for pip (setuptools.build_meta)... done` + +For the `setup.py` based build system interface, typically this will look like +the following: + ```none Building wheel for pip (setup.py)... done ``` -The content in the brackets, refers to which build system interface is being -used. - ```{versionchanged} 21.3 The output uses "pyproject.toml" instead of "PEP 517" to refer to be -`pyproject.toml` based build system interface. +*backend API* based build system interface. +``` + +```{versionchanged} 23.X +The output uses the backend specification instead of "pyproject.toml" +to refer to be *backend API* based build system interface. ``` ## Controlling which build system interface is used The [`--use-pep517`](install_--use-pep517) flag (and corresponding environment variable: `PIP_USE_PEP517`) can be used to force all packages to build using -the `pyproject.toml` based build system interface. There is no way to force +the *backend API* based build system interface. There is no way to force the use of the legacy build system interface. (controlling-setup_requires)= diff --git a/docs/html/reference/build-system/pyproject-toml.md b/docs/html/reference/build-system/pyproject-toml.md index a42a3b8c4..f03e6afab 100644 --- a/docs/html/reference/build-system/pyproject-toml.md +++ b/docs/html/reference/build-system/pyproject-toml.md @@ -1,4 +1,4 @@ -# `pyproject.toml` +# Backend API ```{versionadded} 10.0 @@ -168,3 +168,6 @@ changes and improvements in it. - Prior to pip 18.1, build dependencies using `.pth` files are not properly supported; as a result namespace packages do not work under Python 3.2 and earlier. +- Starting from version 23.1, pip uses the fallback behaviour of + `setuptools.build_meta:__legacy__` when `wheel` or `setuptools` are not + installed. diff --git a/docs/html/reference/build-system/setup-py.md b/docs/html/reference/build-system/setup-py.md index 0103a3a6a..8c022b9f2 100644 --- a/docs/html/reference/build-system/setup-py.md +++ b/docs/html/reference/build-system/setup-py.md @@ -1,11 +1,11 @@ # `setup.py` (legacy) -Prior to the introduction of pyproject.toml-based builds (in {pep}`517` and +Prior to the introduction of *backend API* based builds (in {pep}`517` and {pep}`518`), pip had only supported installing packages using `setup.py` files that were built using {pypi}`setuptools`. The interface documented here is retained currently solely for legacy purposes, -until the migration to `pyproject.toml`-based builds can be completed. +until the migration to *backend API* based builds can be completed. ```{caution} The arguments and syntax of the various invocations of `setup.py` made by From 76cd925004e17e3585d97add202bc6a613af5a07 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 13 Oct 2023 14:03:01 +0100 Subject: [PATCH 4/4] Add news entry for docs --- news/12346.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 news/12346.doc.rst diff --git a/news/12346.doc.rst b/news/12346.doc.rst new file mode 100644 index 000000000..00895836a --- /dev/null +++ b/news/12346.doc.rst @@ -0,0 +1 @@ +Avoid referring to "backend API"-based builds as ``pyproject.toml``-based.