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

Author: jaraco

changelog.d/2230.change.rst

@@ -0,0 +1 @@
+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 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()