feat(gazelle) Allow disabling sibling module resolution

amartani · amartani · commit dc1dbf1df334 · 2025-07-18T18:37:23.000-07:00
diff --git a/gazelle/python/configure.go b/gazelle/python/configure.go
@@ -71,6 +71,7 @@ func (py *Configurer) KnownDirectives() []string {
 		pythonconfig.GeneratePyiDeps,
 		pythonconfig.ExperimentalAllowRelativeImports,
 		pythonconfig.GenerateProto,
+		pythonconfig.PythonResolveSiblingImports,
 	}
 }
 
@@ -244,6 +245,12 @@ func (py *Configurer) Configure(c *config.Config, rel string, f *rule.File) {
 				log.Fatal(err)
 			}
 			config.SetGenerateProto(v)
+		case pythonconfig.PythonResolveSiblingImports:
+			v, err := strconv.ParseBool(strings.TrimSpace(d.Value))
+			if err != nil {
+				log.Fatal(err)
+			}
+			config.SetResolveSiblingImports(v)
 		}
 	}
 
diff --git a/gazelle/python/generate.go b/gazelle/python/generate.go
@@ -259,7 +259,7 @@ func (py *Python) GenerateRules(args language.GenerateArgs) language.GenerateRes
 						fqTarget.String(), actualPyBinaryKind, err)
 					continue
 				}
-				pyBinary := newTargetBuilder(pyBinaryKind, pyBinaryTargetName, pythonProjectRoot, args.Rel, pyFileNames).
+				pyBinary := newTargetBuilder(pyBinaryKind, pyBinaryTargetName, pythonProjectRoot, args.Rel, pyFileNames, cfg.ResolveSiblingImports()).
 					addVisibility(visibility).
 					addSrc(filename).
 					addModuleDependencies(mainModules[filename]).
@@ -301,7 +301,7 @@ func (py *Python) GenerateRules(args language.GenerateArgs) language.GenerateRes
 			collisionErrors.Add(err)
 		}
 
-		pyLibrary := newTargetBuilder(pyLibraryKind, pyLibraryTargetName, pythonProjectRoot, args.Rel, pyFileNames).
+		pyLibrary := newTargetBuilder(pyLibraryKind, pyLibraryTargetName, pythonProjectRoot, args.Rel, pyFileNames, cfg.ResolveSiblingImports()).
 			addVisibility(visibility).
 			addSrcs(srcs).
 			addModuleDependencies(allDeps).
@@ -354,7 +354,7 @@ func (py *Python) GenerateRules(args language.GenerateArgs) language.GenerateRes
 			collisionErrors.Add(err)
 		}
 
-		pyBinaryTarget := newTargetBuilder(pyBinaryKind, pyBinaryTargetName, pythonProjectRoot, args.Rel, pyFileNames).
+		pyBinaryTarget := newTargetBuilder(pyBinaryKind, pyBinaryTargetName, pythonProjectRoot, args.Rel, pyFileNames, cfg.ResolveSiblingImports()).
 			setMain(pyBinaryEntrypointFilename).
 			addVisibility(visibility).
 			addSrc(pyBinaryEntrypointFilename).
@@ -387,7 +387,7 @@ func (py *Python) GenerateRules(args language.GenerateArgs) language.GenerateRes
 			collisionErrors.Add(err)
 		}
 
-		conftestTarget := newTargetBuilder(pyLibraryKind, conftestTargetname, pythonProjectRoot, args.Rel, pyFileNames).
+		conftestTarget := newTargetBuilder(pyLibraryKind, conftestTargetname, pythonProjectRoot, args.Rel, pyFileNames, cfg.ResolveSiblingImports()).
 			addSrc(conftestFilename).
 			addModuleDependencies(deps).
 			addResolvedDependencies(annotations.includeDeps).
@@ -419,7 +419,7 @@ func (py *Python) GenerateRules(args language.GenerateArgs) language.GenerateRes
 				fqTarget.String(), actualPyTestKind, err, pythonconfig.TestNamingConvention)
 			collisionErrors.Add(err)
 		}
-		return newTargetBuilder(pyTestKind, pyTestTargetName, pythonProjectRoot, args.Rel, pyFileNames).
+		return newTargetBuilder(pyTestKind, pyTestTargetName, pythonProjectRoot, args.Rel, pyFileNames, cfg.ResolveSiblingImports()).
 			addSrcs(srcs).
 			addModuleDependencies(deps).
 			addResolvedDependencies(annotations.includeDeps).
@@ -594,7 +594,7 @@ func generateProtoLibraries(args language.GenerateArgs, pythonProjectRoot string
 	// Generate a py_proto_library for each proto_library.
 	for _, protoRuleName := range protoRuleNames {
 		pyProtoLibraryName := strings.TrimSuffix(protoRuleName, "_proto") + "_py_pb2"
-		pyProtoLibrary := newTargetBuilder(pyProtoLibraryKind, pyProtoLibraryName, pythonProjectRoot, args.Rel, &emptySiblings).
+		pyProtoLibrary := newTargetBuilder(pyProtoLibraryKind, pyProtoLibraryName, pythonProjectRoot, args.Rel, &emptySiblings, false).
 			addVisibility(visibility).
 			addResolvedDependency(":" + protoRuleName).
 			generateImportsAttribute().build()
@@ -611,7 +611,7 @@ func generateProtoLibraries(args language.GenerateArgs, pythonProjectRoot string
 			continue
 		}
 
-		emptyRule := newTargetBuilder(pyProtoLibraryKind, ruleName, pythonProjectRoot, args.Rel, &emptySiblings).build()
+		emptyRule := newTargetBuilder(pyProtoLibraryKind, ruleName, pythonProjectRoot, args.Rel, &emptySiblings, false).build()
 		res.Empty = append(res.Empty, emptyRule)
 	}
 
diff --git a/gazelle/python/target.go b/gazelle/python/target.go
@@ -25,34 +25,36 @@ import (
 
 // targetBuilder builds targets to be generated by Gazelle.
 type targetBuilder struct {
-	kind              string
-	name              string
-	pythonProjectRoot string
-	bzlPackage        string
-	srcs              *treeset.Set
-	siblingSrcs       *treeset.Set
-	deps              *treeset.Set
-	resolvedDeps      *treeset.Set
-	visibility        *treeset.Set
-	main              *string
-	imports           []string
-	testonly          bool
-	annotations       *annotations
+	kind                  string
+	name                  string
+	pythonProjectRoot     string
+	bzlPackage            string
+	srcs                  *treeset.Set
+	siblingSrcs           *treeset.Set
+	deps                  *treeset.Set
+	resolvedDeps          *treeset.Set
+	visibility            *treeset.Set
+	main                  *string
+	imports               []string
+	testonly              bool
+	annotations           *annotations
+	resolveSiblingImports bool
 }
 
 // newTargetBuilder constructs a new targetBuilder.
-func newTargetBuilder(kind, name, pythonProjectRoot, bzlPackage string, siblingSrcs *treeset.Set) *targetBuilder {
+func newTargetBuilder(kind, name, pythonProjectRoot, bzlPackage string, siblingSrcs *treeset.Set, resolveSiblingImports bool) *targetBuilder {
 	return &targetBuilder{
-		kind:              kind,
-		name:              name,
-		pythonProjectRoot: pythonProjectRoot,
-		bzlPackage:        bzlPackage,
-		srcs:              treeset.NewWith(godsutils.StringComparator),
-		siblingSrcs:       siblingSrcs,
-		deps:              treeset.NewWith(moduleComparator),
-		resolvedDeps:      treeset.NewWith(godsutils.StringComparator),
-		visibility:        treeset.NewWith(godsutils.StringComparator),
-		annotations:       new(annotations),
+		kind:                  kind,
+		name:                  name,
+		pythonProjectRoot:     pythonProjectRoot,
+		bzlPackage:            bzlPackage,
+		srcs:                  treeset.NewWith(godsutils.StringComparator),
+		siblingSrcs:           siblingSrcs,
+		deps:                  treeset.NewWith(moduleComparator),
+		resolvedDeps:          treeset.NewWith(godsutils.StringComparator),
+		visibility:            treeset.NewWith(godsutils.StringComparator),
+		annotations:           new(annotations),
+		resolveSiblingImports: resolveSiblingImports,
 	}
 }
 
@@ -77,7 +79,7 @@ func (t *targetBuilder) addModuleDependency(dep Module) *targetBuilder {
 	if dep.From != "" {
 		fileName = dep.From + ".py"
 	}
-	if t.siblingSrcs.Contains(fileName) && fileName != filepath.Base(dep.Filepath) {
+	if t.resolveSiblingImports && t.siblingSrcs.Contains(fileName) && fileName != filepath.Base(dep.Filepath) {
 		// importing another module from the same package, converting to absolute imports to make
 		// dependency resolution easier
 		dep.Name = importSpecFromSrc(t.pythonProjectRoot, t.bzlPackage, fileName).Imp
@@ -138,7 +140,6 @@ func (t *targetBuilder) setAnnotations(val annotations) *targetBuilder {
 	return t
 }
 
-
 // generateImportsAttribute generates the imports attribute.
 // These are a list of import directories to be added to the PYTHONPATH. In our
 // case, the value we add is on Bazel sub-packages to be able to perform imports
diff --git a/gazelle/python/testdata/sibling_imports/README.md b/gazelle/python/testdata/sibling_imports/README.md
@@ -1,3 +1,13 @@
 # Sibling imports
 
-This test case asserts that imports from sibling modules are resolved correctly. It covers 3 different types of imports in `pkg/unit_test.py`
+This test case asserts that imports from sibling modules are resolved correctly
+when the `python_resolve_sibling_imports` directive is enabled (default
+behavior). It covers 3 different types of imports in `pkg/unit_test.py`:
+
+- `import a` - resolves to the sibling `a.py` in the same package
+- `import test_util` - resolves to the sibling `test_util.py` in the same
+  package
+- `from b import run` - resolves to the sibling `b.py` in the same package
+
+When sibling imports are enabled, we allow them to be satisfied by sibling
+modules (ie. modules in the same package).
diff --git a/gazelle/python/testdata/sibling_imports_disabled/BUILD.in b/gazelle/python/testdata/sibling_imports_disabled/BUILD.in
@@ -0,0 +1 @@
+# gazelle:python_resolve_sibling_imports false
diff --git a/gazelle/python/testdata/sibling_imports_disabled/BUILD.out b/gazelle/python/testdata/sibling_imports_disabled/BUILD.out
@@ -0,0 +1,17 @@
+load("@rules_python//python:defs.bzl", "py_library", "py_test")
+
+# gazelle:python_resolve_sibling_imports false
+
+py_library(
+    name = "sibling_imports_disabled",
+    srcs = [
+        "a.py",
+        "b.py",
+    ],
+    visibility = ["//:__subpackages__"],
+)
+
+py_test(
+    name = "test_util",
+    srcs = ["test_util.py"],
+)
diff --git a/gazelle/python/testdata/sibling_imports_disabled/README.md b/gazelle/python/testdata/sibling_imports_disabled/README.md
@@ -0,0 +1,17 @@
+# Sibling imports disabled
+
+This test case asserts that imports from sibling modules are NOT resolved as
+absolute imports when the `python_resolve_sibling_imports` directive is
+disabled. It covers 3 different types of imports in `pkg/unit_test.py`:
+
+- `import a` - resolves to the root-level `a.py` instead of the sibling
+  `pkg/a.py`
+- `import test_util` - resolves to the root-level `test_util.py` instead of
+  the sibling `pkg/test_util.py`
+- `from b import run` - resolves to the root-level `b.py` instead of the
+  sibling `pkg/b.py`
+
+When sibling imports are disabled with
+`# gazelle:python_resolve_sibling_imports false`, the imports remain as-is
+and follow standard Python resolution rules where absolute imports can't refer
+to sibling modules.
diff --git a/gazelle/python/testdata/sibling_imports_disabled/WORKSPACE b/gazelle/python/testdata/sibling_imports_disabled/WORKSPACE
@@ -0,0 +1 @@
+# This is a Bazel workspace for the Gazelle test data.
diff --git a/gazelle/python/testdata/sibling_imports_disabled/a.py b/gazelle/python/testdata/sibling_imports_disabled/a.py
@@ -0,0 +1 @@
+# Root level a.py file for testing disabled sibling imports
diff --git a/gazelle/python/testdata/sibling_imports_disabled/b.py b/gazelle/python/testdata/sibling_imports_disabled/b.py
@@ -0,0 +1,3 @@
+# Root level b.py file for testing disabled sibling imports
+def run():
+    pass
diff --git a/gazelle/python/testdata/sibling_imports_disabled/pkg/BUILD.in b/gazelle/python/testdata/sibling_imports_disabled/pkg/BUILD.in
@@ -0,0 +1 @@
+# gazelle:python_resolve_sibling_imports false
diff --git a/gazelle/python/testdata/sibling_imports_disabled/pkg/BUILD.out b/gazelle/python/testdata/sibling_imports_disabled/pkg/BUILD.out
@@ -0,0 +1,27 @@
+load("@rules_python//python:defs.bzl", "py_library", "py_test")
+
+# gazelle:python_resolve_sibling_imports false
+
+py_library(
+    name = "pkg",
+    srcs = [
+        "__init__.py",
+        "a.py",
+        "b.py",
+    ],
+    visibility = ["//:__subpackages__"],
+)
+
+py_test(
+    name = "test_util",
+    srcs = ["test_util.py"],
+)
+
+py_test(
+    name = "unit_test",
+    srcs = ["unit_test.py"],
+    deps = [
+        "//:sibling_imports_disabled",
+        "//:test_util",
+    ],
+)
diff --git a/gazelle/python/testdata/sibling_imports_disabled/pkg/__init__.py b/gazelle/python/testdata/sibling_imports_disabled/pkg/__init__.py
diff --git a/gazelle/python/testdata/sibling_imports_disabled/pkg/a.py b/gazelle/python/testdata/sibling_imports_disabled/pkg/a.py
diff --git a/gazelle/python/testdata/sibling_imports_disabled/pkg/b.py b/gazelle/python/testdata/sibling_imports_disabled/pkg/b.py
@@ -0,0 +1,2 @@
+def run():
+    pass
diff --git a/gazelle/python/testdata/sibling_imports_disabled/pkg/test_util.py b/gazelle/python/testdata/sibling_imports_disabled/pkg/test_util.py
diff --git a/gazelle/python/testdata/sibling_imports_disabled/pkg/unit_test.py b/gazelle/python/testdata/sibling_imports_disabled/pkg/unit_test.py
@@ -0,0 +1,3 @@
+import a
+import test_util
+from b import run
diff --git a/gazelle/python/testdata/sibling_imports_disabled/test.yaml b/gazelle/python/testdata/sibling_imports_disabled/test.yaml
@@ -0,0 +1 @@
+---
diff --git a/gazelle/python/testdata/sibling_imports_disabled/test_util.py b/gazelle/python/testdata/sibling_imports_disabled/test_util.py
@@ -0,0 +1 @@
+# Root level test_util.py file for testing disabled sibling imports
diff --git a/gazelle/pythonconfig/pythonconfig.go b/gazelle/pythonconfig/pythonconfig.go
@@ -101,6 +101,11 @@ const (
 	// GenerateProto represents the directive that controls whether to generate
 	// python_generate_proto targets.
 	GenerateProto = "python_generate_proto"
+	// PythonResolveSiblingImports represents the directive that controls whether
+	// sibling imports are resolved to absolute imports. When enabled, imports like
+	// "import a" from a sibling module are converted to absolute imports. When
+	// disabled, they remain as relative imports to the current package.
+	PythonResolveSiblingImports = "python_resolve_sibling_imports"
 )
 
 // GenerationModeType represents one of the generation modes for the Python
@@ -190,6 +195,7 @@ type Config struct {
 	experimentalAllowRelativeImports          bool
 	generatePyiDeps                           bool
 	generateProto                             bool
+	resolveSiblingImports                     bool
 }
 
 type LabelNormalizationType int
@@ -228,6 +234,7 @@ func New(
 		experimentalAllowRelativeImports:          false,
 		generatePyiDeps:                           false,
 		generateProto:                             false,
+		resolveSiblingImports:                     true,
 	}
 }
 
@@ -263,6 +270,7 @@ func (c *Config) NewChild() *Config {
 		experimentalAllowRelativeImports:          c.experimentalAllowRelativeImports,
 		generatePyiDeps:                           c.generatePyiDeps,
 		generateProto:                             c.generateProto,
+		resolveSiblingImports:                     c.resolveSiblingImports,
 	}
 }
 
@@ -571,6 +579,16 @@ func (c *Config) GenerateProto() bool {
 	return c.generateProto
 }
 
+// SetResolveSiblingImports sets whether sibling imports are resolved to absolute imports.
+func (c *Config) SetResolveSiblingImports(resolveSiblingImports bool) {
+	c.resolveSiblingImports = resolveSiblingImports
+}
+
+// ResolveSiblingImports returns whether sibling imports are resolved to absolute imports.
+func (c *Config) ResolveSiblingImports() bool {
+	return c.resolveSiblingImports
+}
+
 // FormatThirdPartyDependency returns a label to a third-party dependency performing all formating and normalization.
 func (c *Config) FormatThirdPartyDependency(repositoryName string, distributionName string) label.Label {
 	conventionalDistributionName := strings.ReplaceAll(c.labelConvention, distributionNameLabelConventionSubstitution, distributionName)

Original file line number	Diff line number	Diff line change
`@@ -71,6 +71,7 @@ func (py *Configurer) KnownDirectives() []string {`
`71`	`71`	`pythonconfig.GeneratePyiDeps,`
`72`	`72`	`pythonconfig.ExperimentalAllowRelativeImports,`
`73`	`73`	`pythonconfig.GenerateProto,`
	`74`	`+ pythonconfig.PythonResolveSiblingImports,`
`74`	`75`	`}`
`75`	`76`	`}`
`76`	`77`
`@@ -244,6 +245,12 @@ func (py Configurer) Configure(c config.Config, rel string, f *rule.File) {`
`244`	`245`	`log.Fatal(err)`
`245`	`246`	`}`
`246`	`247`	`config.SetGenerateProto(v)`
	`248`	`+ case pythonconfig.PythonResolveSiblingImports:`
	`249`	`+ v, err := strconv.ParseBool(strings.TrimSpace(d.Value))`
	`250`	`+ if err != nil {`
	`251`	`+ log.Fatal(err)`
	`252`	`+ }`
	`253`	`+ config.SetResolveSiblingImports(v)`
`247`	`254`	`}`
`248`	`255`	`}`
`249`	`256`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+# gazelle:python_resolve_sibling_imports false`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+# This is a Bazel workspace for the Gazelle test data.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+# Root level a.py file for testing disabled sibling imports`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Root level b.py file for testing disabled sibling imports`
	`2`	`+def run():`
	`3`	`+ pass`