Include more details on failure to import `setuptools` in metadata resolution

[jakelishman]

What's the problem this feature will solve?

When building legacy packages in non-PEP-517 mode, if setuptools fails to import for any reason, the error message is "setuptools is not installed in the build environment". However, setuptools might be installed, but failed to import for other reasons, but it's hard to track down why with the particular error.

Describe the solution you'd like

Include the traceback of the triggering exception in the error message.

Alternative Solutions

Nothing much, I guess?

Additional context

For some discussion of a seemingly valid environment that can cause setuptools to fail to import, see (e.g.) pypa/setuptools#4894.

Code of Conduct

• I agree to follow the PSF Code of Conduct.

[notatallshaw]

Do you have a reproducible example? And can you provide an example of an existing error, and what you would like to see added.

[jakelishman]

Sure, here's a version somewhat extracted from a CI failure:

1. Create a new venv (any Python version, I happen to have 3.9 open atm) with pip install 'setuptools==77.0.1' 'packaging==24.1' 'wheel==0.45.1'. This is a valid environment according to declared dependencies, but interferes with setuptools' vendoring of packaging==24.2.

2. pip install [--no-use-pep517] 'pyperclip==1.9.0'. pyperclip==1.9.0 is known to cause the failure, not a package under my control. --no-use-pep517 is just being explicit about the failure path, but having setuptools and wheel in the environment is sufficient anyway.

3. The error message is something to the effect of

   Collecting pyperclip==1.9.0
     Using cached pyperclip-1.9.0.tar.gz (20 kB)
     Preparing metadata (setup.py) ... error
     error: subprocess-exited-with-error
   
     × python setup.py egg_info did not run successfully.
     │ exit code: 1
     ╰─> [1 lines of output]
         ERROR: Can not execute `setup.py` since setuptools is not available in the build environment.
         [end of output]
   
     note: This error originates from a subprocess, and is likely not a problem with pip.
   error: metadata-generation-failed
   
   × Encountered error while generating package metadata.
   ╰─> See above for output.
   
   note: This is an issue with the package mentioned above, not pip.
   hint: See above for details.

   In particular, the relevant line is:

   ERROR: Can not execute setup.py since setuptools is not available in the build environment.

4. If instead I use the same environment to python -c 'import setuptools', the error message is:

      Traceback (most recent call last):
     File "<string>", line 1, in <module>
     File "/Users/jake/tmp/venv39/lib/python3.9/site-packages/setuptools/__init__.py", line 27, in <module>
       from .dist import Distribution
     File "/Users/jake/tmp/venv39/lib/python3.9/site-packages/setuptools/dist.py", line 15, in <module>
       from packaging.licenses import canonicalize_license_expression
   ModuleNotFoundError: No module named 'packaging.licenses'

   which is a better indication of what the actual problem was.

I don't necessarily want the entire traceback to be dumped out, but the

ModuleNotFoundError: No module named 'packaging.licenses'

would have helped track down that it's not setuptools itself that's absent, but an inconsistent vendored environment.

[HelloCard]

same problom, setuptools 77.0.1, packaging 24.1

File "/root/miniconda3/lib/python3.12/site-packages/triton/__init__.py", line 8, in <module>
    from .runtime import (
  File "/root/miniconda3/lib/python3.12/site-packages/triton/runtime/__init__.py", line 1, in <module>
    from .autotuner import (Autotuner, Config, Heuristics, autotune, heuristics)
  File "/root/miniconda3/lib/python3.12/site-packages/triton/runtime/autotuner.py", line 9, in <module>
    from .jit import KernelInterface
  File "/root/miniconda3/lib/python3.12/site-packages/triton/runtime/jit.py", line 12, in <module>
    from ..runtime.driver import driver
  File "/root/miniconda3/lib/python3.12/site-packages/triton/runtime/driver.py", line 1, in <module>
    from ..backends import backends
  File "/root/miniconda3/lib/python3.12/site-packages/triton/backends/__init__.py", line 50, in <module>
    backends = _discover_backends()
               ^^^^^^^^^^^^^^^^^^^^
  File "/root/miniconda3/lib/python3.12/site-packages/triton/backends/__init__.py", line 44, in _discover_backends
    driver = _load_module(name, os.path.join(root, name, 'driver.py'))
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/root/miniconda3/lib/python3.12/site-packages/triton/backends/__init__.py", line 12, in _load_module
    spec.loader.exec_module(module)
  File "/root/miniconda3/lib/python3.12/site-packages/triton/backends/nvidia/driver.py", line 7, in <module>
    from triton.runtime.build import _build
  File "/root/miniconda3/lib/python3.12/site-packages/triton/runtime/build.py", line 8, in <module>
    import setuptools
  File "/root/miniconda3/lib/python3.12/site-packages/setuptools/__init__.py", line 27, in <module>
    from .dist import Distribution
  File "/root/miniconda3/lib/python3.12/site-packages/setuptools/dist.py", line 15, in <module>
    from packaging.licenses import canonicalize_license_expression
ModuleNotFoundError: No module named 'packaging.licenses'

[eli-schwartz]

pip/src/pip/_internal/utils/setuptools_build.py

Lines 8 to 28 in 0285e1a

	_SETUPTOOLS_SHIM = textwrap.dedent(
	"""
	exec(compile('''
	# This is <pip-setuptools-caller> -- a caller that pip uses to run setup.py
	#
	# - It imports setuptools before invoking setup.py, to enable projects that directly
	# import from `distutils.core` to work with newer packaging standards.
	# - It provides a clear error message when setuptools is not installed.
	# - It sets `sys.argv[0]` to the underlying `setup.py`, when invoking `setup.py` so
	# 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
	try:
	import setuptools
	except ImportError as error:
	print(
	"ERROR: Can not execute `setup.py` since setuptools is not available in "
	"the build environment.",
	file=sys.stderr,

This message seems:

• a bit obsolete if we assume that packages built:
  • in an isolated venv always install setuptools+wheel as a dependency
  • using --no-build-isolation will error out with: pip._vendor.pyproject_hooks._impl.BackendUnavailable: Cannot import 'setuptools.build_meta'
  • using --no-use-pep517 will error out with: --no-use-pep517 error: It is not possible to use --no-use-pep517 without setuptools and wheel installed.
• not quite robust, as it suppresses error messages instead of checking the real source of the error. It should a) use ModuleNotFoundError, not ImportError, b) check that error.name == 'setuptools'

I think that shim is quite old, and dates back from a time when the first half of that wasn't at all guaranteed, so it may make sense to just treat this as a cleanup at this point, and delete that logic entirely.