From 72372c34541681a55de7ac24b913000d5a7dcc92 Mon Sep 17 00:00:00 2001
From: Ignas Anikevicius <240938+aignas@users.noreply.github.com>
Date: Sun, 3 Dec 2023 00:15:34 +0900
Subject: [PATCH] fix(gazelle): use Python 3.11 in tests and use absolute paths
 in helper

Before this change there was a bug in how the parsing helpers were being
used in case we were using Python 3.11 toolchain, which is using a more
strict version of the entrypoint template. This change moves the python
code to a different location to ensure that the top level package is
something more unique than just "python" and updates the non-bzlmod
tests to run under 3.11.

We also change ".bazelrc" to use explicit "__init__.py" definition to
avoid non-reproducible errors in the future.

Fixes #1589
---
 CHANGELOG.md                                           |  5 +++++
 gazelle/python/BUILD.bazel                             |  8 ++++----
 gazelle/python/python_test.go                          |  2 +-
 gazelle/rules_python_gazelle_helper/BUILD.bazel        |  4 ++++
 .../__main__.py                                        | 10 ++++++++--
 .../{python => rules_python_gazelle_helper}/parse.py   |  0
 .../std_modules.py                                     |  0
 7 files changed, 22 insertions(+), 7 deletions(-)
 create mode 100644 gazelle/rules_python_gazelle_helper/BUILD.bazel
 rename gazelle/{python => rules_python_gazelle_helper}/__main__.py (73%)
 rename gazelle/{python => rules_python_gazelle_helper}/parse.py (100%)
 rename gazelle/{python => rules_python_gazelle_helper}/std_modules.py (100%)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 04e3beb6cc..e89e3428b1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,6 +31,11 @@ A brief description of the categories of changes:
   is also available under bzlmod as
   `pip.parse(experimental_requirement_cycles={})`.
 
+### Fixed
+
+* (gazelle) The gazelle plugin helper was not working with Python toolchains 3.11
+  and above due to a bug in the helper entrypoint import paths.
+
 [0.XX.0]: https://github.com/bazelbuild/rules_python/releases/tag/0.XX.0
 
 ## [0.27.0] - 2023-11-16
diff --git a/gazelle/python/BUILD.bazel b/gazelle/python/BUILD.bazel
index e993a14f22..5f2bb622ee 100644
--- a/gazelle/python/BUILD.bazel
+++ b/gazelle/python/BUILD.bazel
@@ -40,11 +40,11 @@ go_library(
 py_binary(
     name = "helper",
     srcs = [
-        "__main__.py",
-        "parse.py",
-        "std_modules.py",
+        "//rules_python_gazelle_helper:__main__.py",
+        "//rules_python_gazelle_helper:parse.py",
+        "//rules_python_gazelle_helper:std_modules.py",
     ],
-    main = "__main__.py",
+    main = "//rules_python_gazelle_helper:__main__.py",
     visibility = ["//visibility:public"],
 )
 
diff --git a/gazelle/python/python_test.go b/gazelle/python/python_test.go
index 74bd85bce6..617b3f858e 100644
--- a/gazelle/python/python_test.go
+++ b/gazelle/python/python_test.go
@@ -162,7 +162,7 @@ func testPath(t *testing.T, name string, files []bazel.RunfileEntry) {
 		cmd.Dir = workspaceRoot
 		helperScript, err := runfiles.Rlocation("rules_python_gazelle_plugin/python/helper")
 		if err != nil {
-			t.Fatalf("failed to initialize Python heler: %v", err)
+			t.Fatalf("failed to initialize Python helper: %v", err)
 		}
 		cmd.Env = append(os.Environ(), "GAZELLE_PYTHON_HELPER="+helperScript)
 		if err := cmd.Run(); err != nil {
diff --git a/gazelle/rules_python_gazelle_helper/BUILD.bazel b/gazelle/rules_python_gazelle_helper/BUILD.bazel
new file mode 100644
index 0000000000..ffb51d9a46
--- /dev/null
+++ b/gazelle/rules_python_gazelle_helper/BUILD.bazel
@@ -0,0 +1,4 @@
+exports_files(
+    srcs = glob(["*.py"]),
+    visibility = ["//python:__pkg__"],
+)
diff --git a/gazelle/python/__main__.py b/gazelle/rules_python_gazelle_helper/__main__.py
similarity index 73%
rename from gazelle/python/__main__.py
rename to gazelle/rules_python_gazelle_helper/__main__.py
index 2f5a4a16ca..125708f864 100644
--- a/gazelle/python/__main__.py
+++ b/gazelle/rules_python_gazelle_helper/__main__.py
@@ -16,10 +16,16 @@
 # STDIN receives parse requests, one per line. It outputs the parsed modules and
 # comments from all the files from each request.
 
-import parse
-import std_modules
 import sys
 
+# NOTE @aignas 2023-12-02: Use absolute imports with respect to WORKSPACE root.
+# With Python versions other than 3.11 doing import parse import std_modules
+# works fine, but with 3.11 we need to use absolute import paths, which could be
+# due to differences in the bootstrap template in 3.11, which is more strict.
+#
+# We are also using a unique name to avoid any name clashes
+from rules_python_gazelle_helper import parse, std_modules
+
 if __name__ == "__main__":
     if len(sys.argv) < 2:
         sys.exit("Please provide subcommand, either print or std_modules")
diff --git a/gazelle/python/parse.py b/gazelle/rules_python_gazelle_helper/parse.py
similarity index 100%
rename from gazelle/python/parse.py
rename to gazelle/rules_python_gazelle_helper/parse.py
diff --git a/gazelle/python/std_modules.py b/gazelle/rules_python_gazelle_helper/std_modules.py
similarity index 100%
rename from gazelle/python/std_modules.py
rename to gazelle/rules_python_gazelle_helper/std_modules.py