[FR] Vendor distutils stubs

[Avasam]

What's the problem this feature will solve?

Type-checkers don't see distutils as available in Python 3.12+ This is already causing us much pain when it comes to type-checking, and is becoming a blocker. One of the main issue is that importing from distutils, types are seen as Any, which breaks subclassing, removes tons of type-safety, and creates nasty inconsistencies when trying to type-check <3.12 vs >=3.12.

We also get some overriding issues when type-checkers don't understand we're using an updated distutils version vendored from pypa/distutils.

As long as _distutils_hack exists, we can't have type-checkers scan the vendored version instead. (if pypa/distutils was installed like a regular package, this wouldn't be an issue either)

Describe the solution you'd like

My suggestion is to vendor distutils-stubs, reflecting the types as the modernized pypa/distutils. (concretely this means: Start with https://github.com/python/typeshed/tree/main/stdlib/distutils, then apply https://github.com/python/typeshed/tree/main/stubs/setuptools/distutils on top)

Those stubs should exist in the repo in a folder named distutils or distutils-stubs. distutils-stubs should be installed in users' site-packages when installing setuptools (this can be locked behind an extra if you have concerns for vendors)

This also means we no longer need to wait on new mypy releases to get distutils typing fixes from typeshed AND we can be more accurate to what _distutils does.

Alternative Solutions

• Make pypa/distutils a real package found in site-packages
• Change how the hack works, and always import from ._distutils in setuptools instead.

Additional context

• https://github.com/pypa/setuptools/pull/4504 (see failures for Python 3.12 and 3.13)
• https://github.com/pypa/setuptools/issues/2345#issuecomment-1627561833

Code of Conduct

• [X] I agree to follow the PSF Code of Conduct