[BUG] Confusing ModuleNotFoundError for distutils if using setuptools in CPython directory

[The-Compiler]

setuptools version

setuptools==78.1.0

Python version

Python 3.13.2

OS

Arch Linux

Additional environment information

No response

Description

I was trying to reproduce a bug in CPython involving a third-party package. I created a virtualenv to do so, but my current working directory was the CPython source tree, as I was trying to git bisect the bug.

I was greeted with:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import setuptools
  File "[...]/site-packages/setuptools/__init__.py", line 22, in <module>
    import _distutils_hack.override  # noqa: F401
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "[...]/site-packages/_distutils_hack/override.py", line 1, in <module>
    __import__('_distutils_hack').do_override()
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "[...]/site-packages/_distutils_hack/__init__.py", line 89, in do_override
    ensure_local_distutils()
    ~~~~~~~~~~~~~~~~~~~~~~^^
  File "[...]/site-packages/_distutils_hack/__init__.py", line 72, in ensure_local_distutils
    importlib.import_module('distutils')
    ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
  File "/usr/lib/python3.13/importlib/__init__.py", line 88, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'distutils'

and ended up having to debug setuptools to find the culprit:

setuptools/_distutils_hack/__init__.py

Lines 111 to 113 in 3a3144f

	def spec_for_distutils(self):
	if self.is_cpython():
	return None

setuptools/_distutils_hack/__init__.py

Lines 144 to 150 in 3a3144f

	@staticmethod
	def is_cpython():
	"""
	Suppress supplying distutils for CPython (build and tests).
	Ref #2965 and #3007.
	"""
	return os.path.isfile('pybuilddir.txt')

Context:

• [BUG] stdlib test_distutils on python3.8 runs only with SETUPTOOLS_USE_DISTUTILS=stdlib #2965
• [BUG] Having setuptools installed causes cpython stdlib build to fail #3007

Expected behavior

Ideally, a more robust way to detect CPython builds should be found. Failing that, perhaps the detection can be disabled if running in a virtualenv?

If that's also not possible, IMHO at least some sort of note/warning should be logged as currently it's impossible to see what's going on without delving into setuptools sources (and knowing about how distutils is coming from setuptools, and how custom import finders work).

How to Reproduce

This triggers as soon as a pybuilddir.txt is in the current working directory:

touch pybuilddir.txt
python3 -m venv .venv
.venv/bin/pip install setuptools
.venv/bin/python -c "import setuptools"

Output

$ touch pybuilddir.txt

$ python3 -m venv .venv

$ .venv/bin/pip install setuptools

Collecting setuptools
  Using cached setuptools-78.1.0-py3-none-any.whl.metadata (6.6 kB)
Using cached setuptools-78.1.0-py3-none-any.whl (1.3 MB)
Installing collected packages: setuptools
Successfully installed setuptools-78.1.0

[notice] A new release of pip is available: 24.3.1 -> 25.0.1
[notice] To update, run: python3 -m pip install --upgrade pip
$ .venv/bin/python -c "import setuptools"

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import setuptools
  File "/home/florian/tmp/setuptools-repro/.venv/lib/python3.13/site-packages/setuptools/__init__.py", line 22, in <module>
    import _distutils_hack.override  # noqa: F401
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/florian/tmp/setuptools-repro/.venv/lib/python3.13/site-packages/_distutils_hack/override.py", line 1, in <module>
    __import__('_distutils_hack').do_override()
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/home/florian/tmp/setuptools-repro/.venv/lib/python3.13/site-packages/_distutils_hack/__init__.py", line 89, in do_override
    ensure_local_distutils()
    ~~~~~~~~~~~~~~~~~~~~~~^^
  File "/home/florian/tmp/setuptools-repro/.venv/lib/python3.13/site-packages/_distutils_hack/__init__.py", line 72, in ensure_local_distutils
    importlib.import_module('distutils')
    ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
  File "/usr/lib/python3.13/importlib/__init__.py", line 88, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'distutils'