Python: discourage direct setup.py install

When invoking setup.py directly, the default behavior for 'install' is
to run the bdist_egg installation hook, which is ... actually deprecated
by setuptools. It doesn't seem to work quite right anymore.

By contrast, 'pip install' will invoke the bdist_wheel hook
instead. This leads to differences in behavior for the two approaches. I
advocate using pip in the documentation in this directory, but the
'setup.py' which has been used for quite a long time in the Python world
may deceptively appear to work at first glance.

Add an error message that will save a bit of time and frustration
that points the user towards using the supported installation
invocation.

Reported-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Beraldo Leal <bleal@redhat.com>
Message-id: 20220207213039.2278569-1-jsnow@redhat.com
Signed-off-by: John Snow <jsnow@redhat.com>

diff --git a/python/setup.py b/python/setup.py
index 2014f81b757e2d87d799e1948ffc78e835c2fa9d..c5bc45919a4d8988640a5c80cc71fe53b9dce609 100755 (executable)
--- a/python/setup.py
+++ b/python/setup.py
@@ -5,9 +5,26 @@ Copyright (c) 2020-2021 John Snow for Red Hat, Inc.
 """
 
 import setuptools
+from setuptools.command import bdist_egg
+import sys
 import pkg_resources
 
 
+class bdist_egg_guard(bdist_egg.bdist_egg):
+    """
+    Protect against bdist_egg from being executed
+
+    This prevents calling 'setup.py install' directly, as the 'install'
+    CLI option will invoke the deprecated bdist_egg hook. "pip install"
+    calls the more modern bdist_wheel hook, which is what we want.
+    """
+    def run(self):
+        sys.exit(
+            'Installation directly via setup.py is not supported.\n'
+            'Please use `pip install .` instead.'
+        )
+
+
 def main():
     """
     QEMU tooling installer
@@ -16,7 +33,7 @@ def main():
     # https://medium.com/@daveshawley/safely-using-setup-cfg-for-metadata-1babbe54c108
     pkg_resources.require('setuptools>=39.2')
 
-    setuptools.setup()
+    setuptools.setup(cmdclass={'bdist_egg': bdist_egg_guard})
 
 
 if __name__ == '__main__':