Provide traceback on setuptools import failure in legacy paths (#13291)

In the legacy `setup.py` wrapper importer, failures to import
setuptools might not be because setuptools itself is absent, but
because it failed to import successfully.  This can currently arise (as
of `setuptools==77.0.1`) in seemingly valid environments due to
limitations in the setuptools vendoring.  This commit exposes more of
the failure up to users, to help with debugging failed environments, and
makes it possible for setuptools to expose a better error message
itself through the import system.

The above situation is more likely than setuptools being wholly
absent as the legacy code paths invoke setup.py will check that
setuptools is installed (and install setuptools in a temporary build
env. if not) beforehand.

For some more context, see pypa/setuptools#4894.

Author: jakelishman

news/13290.feature.rst

@@ -0,0 +1 @@
+Include traceback on failure to import ``setuptools`` when ``setup.py`` is being invoked directly.

src/pip/_internal/utils/setuptools_build.py

@@ -17,16 +17,17 @@
     #   setuptools doesn't think the script is `-c`. This avoids the following warning:
     #     manifest_maker: standard file '-c' not found".
     # - It generates a shim setup.py, for handling setup.cfg-only projects.
-    import os, sys, tokenize
+    import os, sys, tokenize, traceback
 
     try:
         import setuptools
-    except ImportError as error:
+    except ImportError:
         print(
-            "ERROR: Can not execute `setup.py` since setuptools is not available in "
-            "the build environment.",
+            "ERROR: Can not execute `setup.py` since setuptools failed to import in "
+            "the build environment with exception:",
             file=sys.stderr,
         )
+        traceback.print_exc()
         sys.exit(1)
 
     __file__ = %r

tests/functional/test_install_reqs.py

@@ -13,6 +13,7 @@
     _create_test_package_with_subdirectory,
     create_basic_sdist_for_package,
     create_basic_wheel_for_package,
+    make_wheel,
     need_svn,
     requirements_file,
 )
@@ -917,3 +918,26 @@ def test_config_settings_local_to_package(
     assert "--verbose" not in simple3_args
     simple2_args = simple2_sdist.args()
     assert "--verbose" not in simple2_args
+
+
+def test_nonpep517_setuptools_import_failure(script: PipTestEnvironment) -> None:
+    """Any import failures of `setuptools` should inform the user both that it's
+    not pip's fault, but also exactly what went wrong in the import."""
+    # Install a poisoned version of 'setuptools' that fails to import.
+    name = "setuptools_poisoned"
+    module = """\
+raise ImportError("this 'setuptools' was intentionally poisoned")
+"""
+    path = make_wheel(name, "0.1.0", extra_files={"setuptools.py": module}).save_to_dir(
+        script.scratch_path
+    )
+    script.pip("install", "--no-index", path)
+
+    result = script.pip_install_local("--no-use-pep517", "simple", expect_error=True)
+    nice_message = (
+        "ERROR: Can not execute `setup.py`"
+        " since setuptools failed to import in the build environment"
+    )
+    exc_message = "ImportError: this 'setuptools' was intentionally poisoned"
+    assert nice_message in result.stderr
+    assert exc_message in result.stderr