Implement diagnostic errors for build-system.requires issues

This demonstrates how the new diagnostic errors are to implement, and
how they get presented to users.

Author: pradyunsg

src/pip/_internal/exceptions.py

@@ -109,6 +109,45 @@ class UninstallationError(PipError):
     """General exception during uninstallation"""
 
 
+class MissingPyProjectBuildRequires(DiagnosticPipError):
+    """Raised when pyproject.toml has `build-system`, but no `build-system.requires`."""
+
+    reference = "missing-pyproject-build-system-requires"
+
+    def __init__(self, *, package: str) -> None:
+        super().__init__(
+            message=f"Can not process {package}",
+            context=(
+                "This package has an invalid pyproject.toml file.\n"
+                "The [build-system] table is missing the mandatory `requires` key."
+            ),
+            attention_stmt=(
+                "This is an issue with the package mentioned above, not pip."
+            ),
+            hint_stmt="See PEP 518 for the detailed specification.",
+        )
+
+
+class InvalidPyProjectBuildRequires(DiagnosticPipError):
+    """Raised when pyproject.toml an invalid `build-system.requires`."""
+
+    reference = "invalid-pyproject-build-system-requires"
+
+    def __init__(self, *, package: str, reason: str) -> None:
+        super().__init__(
+            message=f"Can not process {package}",
+            context=(
+                "This package has an invalid `build-system.requires` key in "
+                "pyproject.toml.\n"
+                f"{reason}"
+            ),
+            hint_stmt="See PEP 518 for the detailed specification.",
+            attention_stmt=(
+                "This is an issue with the package mentioned above, not pip."
+            ),
+        )
+
+
 class NoneMetadataError(PipError):
     """
     Raised when accessing "METADATA" or "PKG-INFO" metadata for a

src/pip/_internal/pyproject.py

@@ -5,7 +5,11 @@
 from pip._vendor import tomli
 from pip._vendor.packaging.requirements import InvalidRequirement, Requirement
 
-from pip._internal.exceptions import InstallationError
+from pip._internal.exceptions import (
+    InstallationError,
+    InvalidPyProjectBuildRequires,
+    MissingPyProjectBuildRequires,
+)
 
 
 def _is_list_of_str(obj: Any) -> bool:
@@ -119,47 +123,28 @@ def load_pyproject_toml(
 
     # Ensure that the build-system section in pyproject.toml conforms
     # to PEP 518.
-    error_template = (
-        "{package} has a pyproject.toml file that does not comply "
-        "with PEP 518: {reason}"
-    )
 
     # Specifying the build-system table but not the requires key is invalid
     if "requires" not in build_system:
-        raise InstallationError(
-            error_template.format(
-                package=req_name,
-                reason=(
-                    "it has a 'build-system' table but not "
-                    "'build-system.requires' which is mandatory in the table"
-                ),
-            )
-        )
+        raise MissingPyProjectBuildRequires(package=req_name)
 
     # Error out if requires is not a list of strings
     requires = build_system["requires"]
     if not _is_list_of_str(requires):
-        raise InstallationError(
-            error_template.format(
-                package=req_name,
-                reason="'build-system.requires' is not a list of strings.",
-            )
+        raise InvalidPyProjectBuildRequires(
+            package=req_name,
+            reason="It is not a list of strings.",
         )
 
     # Each requirement must be valid as per PEP 508
     for requirement in requires:
         try:
             Requirement(requirement)
-        except InvalidRequirement:
-            raise InstallationError(
-                error_template.format(
-                    package=req_name,
-                    reason=(
-                        "'build-system.requires' contains an invalid "
-                        "requirement: {!r}".format(requirement)
-                    ),
-                )
-            )
+        except InvalidRequirement as error:
+            raise InvalidPyProjectBuildRequires(
+                package=req_name,
+                reason=f"It contains an invalid requirement: {requirement!r}",
+            ) from error
 
     backend = build_system.get("build-backend")
     backend_path = build_system.get("backend-path", [])

tests/functional/test_install.py

@@ -108,7 +108,12 @@ def test_pep518_refuses_invalid_requires(script, data, common_wheels):
         expect_error=True,
     )
     assert result.returncode == 1
-    assert "does not comply with PEP 518" in result.stderr
+
+    # Ensure the relevant things are mentioned.
+    assert "PEP 518" in result.stderr
+    assert "not a list of strings" in result.stderr
+    assert "build-system.requires" in result.stderr
+    assert "pyproject.toml" in result.stderr
 
 
 def test_pep518_refuses_invalid_build_system(script, data, common_wheels):
@@ -120,7 +125,12 @@ def test_pep518_refuses_invalid_build_system(script, data, common_wheels):
         expect_error=True,
     )
     assert result.returncode == 1
-    assert "does not comply with PEP 518" in result.stderr
+
+    # Ensure the relevant things are mentioned.
+    assert "PEP 518" in result.stderr
+    assert "mandatory `requires` key" in result.stderr
+    assert "[build-system] table" in result.stderr
+    assert "pyproject.toml" in result.stderr
 
 
 def test_pep518_allows_missing_requires(script, data, common_wheels):
@@ -132,7 +142,7 @@ def test_pep518_allows_missing_requires(script, data, common_wheels):
         expect_stderr=True,
     )
     # Make sure we don't warn when this occurs.
-    assert "does not comply with PEP 518" not in result.stderr
+    assert "PEP 518" not in result.stderr
 
     # We want it to go through isolation for now.
     assert "Installing build dependencies" in result.stdout, result.stdout

tests/unit/test_pep517.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from pip._internal.exceptions import InstallationError
+from pip._internal.exceptions import InstallationError, InvalidPyProjectBuildRequires
 from pip._internal.req import InstallRequirement
 from tests.lib import TestData
 from tests.lib.path import Path
@@ -75,20 +75,24 @@ def test_disabling_pep517_invalid(shared_data: TestData, source: str, msg: str)
 def test_pep517_parsing_checks_requirements(tmpdir: Path, spec: str) -> None:
     tmpdir.joinpath("pyproject.toml").write_text(
         dedent(
+            f"""
+            [build-system]
+            requires = [{spec!r}]
+            build-backend = "foo"
             """
-        [build-system]
-        requires = [{!r}]
-        build-backend = "foo"
-        """.format(
-                spec
-            )
         )
     )
     req = InstallRequirement(None, None)
     req.source_dir = tmpdir  # make req believe it has been unpacked
 
-    with pytest.raises(InstallationError) as e:
+    with pytest.raises(InvalidPyProjectBuildRequires) as e:
         req.load_pyproject_toml()
 
-    err_msg = e.value.args[0]
-    assert "contains an invalid requirement" in err_msg
+    error = e.value
+
+    assert str(req) in error.message
+    assert error.context
+    assert "build-system.requires" in error.context
+    assert "contains an invalid requirement" in error.context
+    assert error.hint_stmt
+    assert "PEP 518" in error.hint_stmt