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

@@ -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

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"],
 )
 

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 {

gazelle/rules_python_gazelle_helper/BUILD.bazel

@@ -0,0 +1,4 @@
+exports_files(
+    srcs = glob(["*.py"]),
+    visibility = ["//python:__pkg__"],
+)

gazelle/python/__main__.py → 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")