Warn the user when distutils is present to discourage this usage and direct...

Warn the user when distutils is present to discourage this usage and direct users to the recommended usage. Closes #2230.

changelog.d/2230.change.rst

+Now warn the user when setuptools is imported after distutils modules have been loaded (exempting PyPy for 3.6), directing the users of packages to import setuptools first.

setuptools/distutils_patch.py

@@ -12,10 +12,26 @@ import importlib
 import warnings
 
 
+is_pypy = '__pypy__' in sys.builtin_module_names
+
+
+def warn_distutils_present():
+    if 'distutils' not in sys.modules:
+        return
+    if is_pypy and sys.version_info < (3, 7):
+        # PyPy for 3.6 unconditionally imports distutils, so bypass the warning
+        # https://foss.heptapod.net/pypy/pypy/-/blob/be829135bc0d758997b3566062999ee8b23872b4/lib-python/3/site.py#L250
+        return
+    warnings.warn(
+        "Distutils was imported before Setuptools. This usage is discouraged "
+        "and may exhibit undesirable behaviors or errors. Please use "
+        "Setuptools' objects directly or at least import Setuptools first.")
+
+
 def clear_distutils():
     if 'distutils' not in sys.modules:
         return
-    warnings.warn("Setuptools is replacing distutils")
+    warnings.warn("Setuptools is replacing distutils.")
     mods = [name for name in sys.modules if re.match(r'distutils\b', name)]
     for name in mods:
         del sys.modules[name]
@@ -40,5 +56,6 @@ def ensure_local_distutils():
     assert '_distutils' in core.__file__, core.__file__
 
 
+warn_distutils_present()
 if enabled():
     ensure_local_distutils()