More robust, helpful error messaging around minimum python version.

Workaround for #119
Great opportunity for more general bazel support expressed in bazelbuild/bazel#18389

Author: cpsauer

.pre-commit-config.yaml

@@ -7,7 +7,9 @@ repos:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
     -   id: check-ast
+        exclude: ^check_python_version\.template\.py$  # Template for bazel creates syntax error
     -   id: debug-statements
+        exclude: ^check_python_version\.template\.py$  # Template for bazel creates syntax error
     -   id: mixed-line-ending
     -   id: check-case-conflict
     -   id: fix-byte-order-marker

BUILD

@@ -13,4 +13,4 @@ refresh_compile_commands(
 # Implementation:
 # If you are looking into the implementation, start with the overview in ImplementationReadme.md.
 
-exports_files(["refresh.template.py"])  # For implicit use by refresh_compile_commands.
+exports_files(["refresh.template.py", "check_python_version.template.py"])  # For implicit use by therefresh_compile_commands macro, not direct use.

ImplementationReadme.md

@@ -52,7 +52,7 @@ The `refresh_compile_commands` rule (from [`refresh_compile_commands.bzl`](./ref
 
 - [`refresh.template.py`](./refresh.template.py) is the main driver of actions. Browsing it should help you figure out where you want to go. It consists of two sections: one for calling `bazel aquery` and one for constructing the `compile_commands.json` from it. The latter does the actual reformatting of command so they're usable by `clangd`. This is more involved than you might think, but not crazy. It's easy to extend the reformatting operations applied.
   - If you're seeing failures on a new platform, weird entries in `compile_commands.json`, or wrapped compilers, this is where you should make changes to properly undo Bazel's wrapping of the command. See the "Patch command by platform" section.
-- The bazel files ([`refresh_compile_commands.bzl`](./refresh_compile_commands.bzl) and others) are just wrappings. They're less likely to require your attention.
+- The other files ([`refresh_compile_commands.bzl`](./refresh_compile_commands.bzl) and others) are just wrappings. They're less likely to require your attention, except as directed from the README or refresh.template.py.
 
 
 ## Tool Choice — Why `clangd`?

check_python_version.template.py

@@ -0,0 +1,16 @@
+"""
+Print a nice error message if the user is running too old of a version of python.
+
+Why not just put this block at the top of refresh.template.py?
+Python versions introduce constructs that don't parse in older versions, leading to an error before the version check is executed, since python parses files eagerly.
+For examples of this issue, see https://github.com/hedronvision/bazel-compile-commands-extractor/issues/119 and https://github.com/hedronvision/bazel-compile-commands-extractor/issues/95
+This seems common enough that hopefully bazel will support it someday. We've filed a request: https://github.com/bazelbuild/bazel/issues/18389
+"""
+
+import sys
+if sys.version_info < (3,6):
+    sys.exit("\n\033[31mFATAL ERROR:\033[0m Python 3.6 or later is required. Please update!")
+
+# Only import -> parse once we're sure we have the required python version
+import {to_run}
+{to_run}.main()

refresh.template.py

@@ -10,14 +10,13 @@
     - Crucially, this output is de-Bazeled; The result is a command that could be run from the workspace root directly, with no Bazel-specific requirements, environment variables, etc.
 """
 
-import sys
-if sys.version_info < (3,6):
-    sys.exit("\n\033[31mFATAL ERROR:\033[0m Python 3.6 or later is required. Please update!")
-    # 3.6 backwards compatibility required by @zhanyong-wan in https://github.com/hedronvision/bazel-compile-commands-extractor/issues/111.
-    # 3.7 backwards compatibility required by @lummax in https://github.com/hedronvision/bazel-compile-commands-extractor/pull/27.
-    # ^ Try to contact before upgrading.
-    # When adding things could be cleaner if we had a higher minimum version, please add a comment with MIN_PY=3.<v>.
-    # Similarly, when upgrading, please search for that MIN_PY= tag.
+
+# This file requires python 3.6, which is enforced by check_python_version.template.py
+# 3.6 backwards compatibility required by @zhanyong-wan in https://github.com/hedronvision/bazel-compile-commands-extractor/issues/111.
+# 3.7 backwards compatibility required by @lummax in https://github.com/hedronvision/bazel-compile-commands-extractor/pull/27.
+# ^ Try to contact before upgrading.
+# When adding things could be cleaner if we had a higher minimum version, please add a comment with MIN_PY=3.<v>.
+# Similarly, when upgrading, please search for that MIN_PY= tag.
 
 
 import concurrent.futures
@@ -32,6 +31,7 @@
 import shlex
 import shutil
 import subprocess
+import sys
 import tempfile
 import time
 import types
@@ -1049,7 +1049,7 @@ def _ensure_cwd_is_workspace_root():
     os.chdir(workspace_root)
 
 
-if __name__ == '__main__':
+def main():
     _ensure_cwd_is_workspace_root()
     _ensure_gitignore_entries_exist()
     _ensure_external_workspaces_link_exists()

refresh_compile_commands.bzl

@@ -77,13 +77,27 @@ def refresh_compile_commands(
     elif type(targets) != "dict":  # Assume they've supplied a single string/label and wrap it
         targets = {targets: ""}
 
-    # Generate runnable python script from template
+    # Create a wrapper script that prints a helpful error message if the python version is too old, generated from check_python_version.template.py
+    version_checker_script_name = name + ".check_python_version.py"
+    _check_python_version(name = version_checker_script_name, to_run = name)
+
+    # Generate the core, runnable python script from refresh.template.py
     script_name = name + ".py"
     _expand_template(name = script_name, labels_to_flags = targets, exclude_headers = exclude_headers, exclude_external_sources = exclude_external_sources, **kwargs)
-    native.py_binary(name = name, srcs = [script_name], **kwargs)
+
+    # Combine them so the wrapper calls the main script
+    native.py_binary(
+        name = name,
+        main = version_checker_script_name,
+        srcs = [
+            version_checker_script_name,
+            script_name,
+        ],
+        **kwargs
+    )
 
 def _expand_template_impl(ctx):
-    """Inject targets of interest into refresh.template.py, and set it up to be run."""
+    """Inject targets of interest--and other settings--into refresh.template.py, and set it up to be run."""
     script = ctx.actions.declare_file(ctx.attr.name)
     ctx.actions.expand_template(
         output = script,
@@ -112,3 +126,24 @@ _expand_template = rule(
     toolchains = ["@bazel_tools//tools/cpp:toolchain_type"],  # Needed for find_cpp_toolchain with --incompatible_enable_cc_toolchain_resolution
     implementation = _expand_template_impl,
 )
+
+def _check_python_version_impl(ctx):
+    """Sets up check_python_version.template.py to call {to_run}.py's main()"""
+    script = ctx.actions.declare_file(ctx.attr.name)
+    ctx.actions.expand_template(
+        output = script,
+        is_executable = True,
+        template = ctx.file._template,
+        substitutions = {
+            "{to_run}": ctx.attr.to_run,
+        },
+    )
+    return DefaultInfo(files = depset([script]))
+
+_check_python_version = rule(
+    attrs = {
+        "to_run": attr.string(mandatory = True), # Name of the python module (no .py) to import and call .main() on, should checks succeed.
+        "_template": attr.label(allow_single_file = True, default = "check_python_version.template.py"),
+    },
+    implementation = _check_python_version_impl,
+)