tools/docs: sphinx-pre-install: allow check for alternatives and bail out

The caller script may not want an automatic execution of the new
version. Add two parameters to allow showing alternatives and to
bail out if version is incompatible.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <19777bc710bf901ffbb0ad0f1bb57b18fc01b163.1758196090.git.mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
index fa12e01fc7fea31361118f4fddec090735a2346e..895220c6d4f83f82cedcfb8c18d8afa66a79770f 100755 (executable)
--- a/tools/docs/sphinx-pre-install
+++ b/tools/docs/sphinx-pre-install
@@ -254,7 +254,7 @@ class AncillaryMethods:
         return (0, 0, 0)
 
     @staticmethod
-    def find_python():
+    def find_python(min_version):
         """
         Detect if are out there any python 3.xy version newer than the
         current one.
@@ -263,21 +263,25 @@ class AncillaryMethods:
         may need to update it one day, hopefully on a distant future.
         """
         patterns = [
-            "python3.[0-9]",
             "python3.[0-9][0-9]",
+            "python3.[0-9]",
         ]
 
         # Seek for a python binary newer than MIN_PYTHON_VERSION
+        python_cmd = []
         for path in os.getenv("PATH", "").split(":"):
             for pattern in patterns:
                 for cmd in glob(os.path.join(path, pattern)):
                     if os.path.isfile(cmd) and os.access(cmd, os.X_OK):
                         version = SphinxDependencyChecker.get_python_version(cmd)
-                        if version >= MIN_PYTHON_VERSION:
-                            return cmd
+                        if version >= min_version:
+                            python_cmd.append((version, cmd))
+
+        return sorted(python_cmd, reverse=True)
 
     @staticmethod
-    def check_python():
+    def check_python(min_version, show_alternatives=False, bail_out=False,
+                     success_on_error=False):
         """
         Check if the current python binary satisfies our minimal requirement
         for Sphinx build. If not, re-run with a newer version if found.
@@ -301,18 +305,42 @@ class AncillaryMethods:
 
         python_ver = ver_str(cur_ver)
 
-        new_python_cmd = SphinxDependencyChecker.find_python()
-        if not new_python_cmd:
+        available_versions = SphinxDependencyChecker.find_python(min_version)
+        if not available_versions:
             print(f"ERROR: Python version {python_ver} is not spported anymore\n")
             print("       Can't find a new version. This script may fail")
             return
 
-        # Restart script using the newer version
         script_path = os.path.abspath(sys.argv[0])
-        args = [new_python_cmd, script_path] + sys.argv[1:]
+
+        # Check possible alternatives
+        if available_versions:
+            new_python_cmd = available_versions[0][1]
+        else:
+            new_python_cmd = None
+
+        if show_alternatives:
+            print("You could run, instead:")
+            for _, cmd in available_versions:
+                args = [cmd, script_path] + sys.argv[1:]
+
+                cmd_str = " ".join(args)
+                print(f"  {cmd_str}")
+            print()
+
+        if bail_out:
+            msg = f"Python {python_ver} not supported. Bailing out"
+            if success_on_error:
+                print(msg, file=sys.stderr)
+                sys.exit(0)
+            else:
+                sys.exit(msg)
 
         print(f"Python {python_ver} not supported. Changing to {new_python_cmd}")
 
+        # Restart script using the newer version
+        args = [new_python_cmd, script_path] + sys.argv[1:]
+
         try:
             os.execv(new_python_cmd, args)
         except OSError as e:
@@ -1612,7 +1640,7 @@ def main():
 
     checker = SphinxDependencyChecker(args)
 
-    checker.check_python()
+    checker.check_python(MIN_PYTHON_VERSION)
     checker.check_needs()
 
 # Call main if not used as module