feat(gazelle): Directive controlling pytest ancestor depdencies

gazelle/docs/annotations.md

@@ -116,6 +116,7 @@ deps = [
 ```
 
 
+(annotation-include-pytest-conftest)=
 ## `include_pytest_conftest`
 
 :::{versionadded} 1.6.0

gazelle/docs/directives.md

@@ -175,6 +175,11 @@ The Python-specific directives are:
   * Default: `false`
   * Allowed Values: `true`, `false`
 
+[`# gazelle:python_include_ancestor_conftest bool`](#python-include-ancestor-conftest)
+: Controls whether ancestor conftest targets are added to {bzl:obj}`py_test` target
+  dependencies.
+  * Default: `true`
+  * Allowed Values: `true`, `false`
 
 ## `python_extension`
 
@@ -720,3 +725,67 @@ previously-generated or hand-created rules.
 :::{error}
 Detailed docs are not yet written.
 :::
+
+## `python_include_ancestor_conftest`
+
+Version 1.9.0 includes a fix ({gh-pr}`3498`) for a long-standing issue
+({gh-issue}`3497`) where ancestor `conftest.py` files were not automatically
+added as dependencies of {bzl:obj}`py_test` targets.
+
+However, some people may not want this behavior (see https://xkcd.com/1172/).
+Thus the `python_include_ancestor_conftest` directive controls this behavior.
+It defaults to `true`, which causes all ancestor `conftest.py` files to be
+included as dependencies for {bzl:obj}`py_test` targets.
+
+Setting the directive to `false` reverts to the pre-1.9.0 behavior.
+
+For example, given this directory tree (not shown: intermediary `BUILD.bazel`
+files)
+
+```
+./
+├── conftest.py
+└── one/
+    ├── conftest.py
+    └── two/
+        ├── conftest.py
+        └── three/
+            ├── BUILD.bazel
+            ├── conftest.py
+            └── my_test.py
+```
+
+Gazelle will generate this target for `foo_test.py` by default:
+
+```starlark
+py_test(
+    name = "foo_test",
+    srcs = ["foo_test.py"],
+    deps = [
+        ":conftest",
+        "//:conftest",
+        "//one:conftest",
+        "//one/two:conftest",
+    ],
+)
+```
+
+But when `python_include_ancestor_conftest` is `false`, only the sibling
+`:conftest` target will be included as a dependency:
+
+:::{tip}
+The [`include_pytest_conftest` annotation](annotation-include-pytest-conftest)
+controls whether the sibling `:conftest` target is added to {bzl:obj}`py_test`
+target dependency list.
+:::
+
+```starlark
+# gazelle:python_include_ancestor_conftest false
+py_test(
+    name = "foo_test",
+    srcs = ["foo_test.py"],
+    deps = [
+        ":conftest",
+    ],
+)
+```

gazelle/python/configure.go

@@ -74,6 +74,7 @@ func (py *Configurer) KnownDirectives() []string {
 		pythonconfig.ExperimentalAllowRelativeImports,
 		pythonconfig.GenerateProto,
 		pythonconfig.PythonResolveSiblingImports,
+		pythonconfig.PythonIncludeAncestorConftest,
 	}
 }
 
@@ -261,6 +262,12 @@ func (py *Configurer) Configure(c *config.Config, rel string, f *rule.File) {
 				log.Fatal(err)
 			}
 			config.SetResolveSiblingImports(v)
+		case pythonconfig.PythonIncludeAncestorConftest:
+			v, err := strconv.ParseBool(strings.TrimSpace(d.Value))
+			if err != nil {
+				log.Fatal(err)
+			}
+			config.SetIncludeAncestorConftest(v)
 		}
 	}
 

gazelle/python/testdata/directive_python_include_ancestor_conftest/BUILD.out

@@ -0,0 +1,8 @@
+load("@rules_python//python:defs.bzl", "py_library")
+
+py_library(
+    name = "conftest",
+    testonly = True,
+    srcs = ["conftest.py"],
+    visibility = ["//:__subpackages__"],
+)

gazelle/python/testdata/directive_python_include_ancestor_conftest/README.md

@@ -0,0 +1,17 @@
+# Directive: `python_include_ancestor_conftest`
+
+This test case asserts that the `# gazelle:python_include_ancestor_conftest`
+directive correctly includes or excludes ancestor contest targets in `py_test`
+target dependencies.
+
+The test also asserts that the directive can be applied at any level and that
+child levels will inherit the value:
+
++ The root level does not set the directive (it defaults to True).
++ The next level, `one/`, inherits that value.
++ The next level, `one/two/`, sets the directive to False and thus the
+  `py_test` target only includes the sibling `:conftest` target.
++ The final level, `one/two/three`, sets the directive back to True and thus
+  the `py_test` target includes a total of 4 `conftest` targets.
+
+See [Issue #3595](https://github.com/bazel-contrib/rules_python/issues/3595).

gazelle/python/testdata/directive_python_include_ancestor_conftest/one/BUILD.out

@@ -0,0 +1,17 @@
+load("@rules_python//python:defs.bzl", "py_library", "py_test")
+
+py_library(
+    name = "conftest",
+    testonly = True,
+    srcs = ["conftest.py"],
+    visibility = ["//:__subpackages__"],
+)
+
+py_test(
+    name = "my_test",
+    srcs = ["my_test.py"],
+    deps = [
+        ":conftest",
+        "//:conftest",
+    ],
+)

gazelle/python/testdata/directive_python_include_ancestor_conftest/one/two/BUILD.in

@@ -0,0 +1 @@
+# gazelle:python_include_ancestor_conftest false

gazelle/python/testdata/directive_python_include_ancestor_conftest/one/two/BUILD.out

@@ -0,0 +1,16 @@
+load("@rules_python//python:defs.bzl", "py_library", "py_test")
+
+# gazelle:python_include_ancestor_conftest false
+
+py_library(
+    name = "conftest",
+    testonly = True,
+    srcs = ["conftest.py"],
+    visibility = ["//:__subpackages__"],
+)
+
+py_test(
+    name = "my_test",
+    srcs = ["my_test.py"],
+    deps = [":conftest"],
+)

gazelle/python/testdata/directive_python_include_ancestor_conftest/one/two/three/BUILD.in

@@ -0,0 +1 @@
+# gazelle:python_include_ancestor_conftest true

gazelle/python/testdata/directive_python_include_ancestor_conftest/one/two/three/BUILD.out

@@ -0,0 +1,21 @@
+load("@rules_python//python:defs.bzl", "py_library", "py_test")
+
+# gazelle:python_include_ancestor_conftest true
+
+py_library(
+    name = "conftest",
+    testonly = True,
+    srcs = ["conftest.py"],
+    visibility = ["//:__subpackages__"],
+)
+
+py_test(
+    name = "my_test",
+    srcs = ["my_test.py"],
+    deps = [
+        ":conftest",
+        "//:conftest",
+        "//one:conftest",
+        "//one/two:conftest",
+    ],
+)

gazelle/python/testdata/directive_python_include_ancestor_conftest/test.yaml

@@ -0,0 +1,3 @@
+---
+expect:
+  exit_code: 0

gazelle/pythonconfig/pythonconfig.go

@@ -116,6 +116,15 @@ const (
 	// like "import a" can be resolved to sibling modules. When disabled, they
 	// can only be resolved as an absolute import.
 	PythonResolveSiblingImports = "python_resolve_sibling_imports"
+	// PythonIncludeAncestorConftest represents the directive that controls
+	// whether ancestor conftest.py files are added as dependencies to py_test
+	// targets. When enabled (the default), ancestor conftest.py files are
+	// included as deps.
+	// See also https://github.com/bazel-contrib/rules_python/pull/3498, which
+	// fixed previous behavior that was incorrectly _not_ adding the files and
+	// https://github.com/bazel-contrib/rules_python/issues/3595 which requested
+	// that the behavior be configurable.
+	PythonIncludeAncestorConftest = "python_include_ancestor_conftest"
 )
 
 // GenerationModeType represents one of the generation modes for the Python
@@ -209,6 +218,7 @@ type Config struct {
 	generatePyiSrcs                           bool
 	generateProto                             bool
 	resolveSiblingImports                     bool
+	includeAncestorConftest                   bool
 }
 
 type LabelNormalizationType int
@@ -250,6 +260,7 @@ func New(
 		generatePyiSrcs:                           false,
 		generateProto:                             false,
 		resolveSiblingImports:                     false,
+		includeAncestorConftest:                   true,
 	}
 }
 
@@ -288,6 +299,7 @@ func (c *Config) NewChild() *Config {
 		generatePyiSrcs:                           c.generatePyiSrcs,
 		generateProto:                             c.generateProto,
 		resolveSiblingImports:                     c.resolveSiblingImports,
+		includeAncestorConftest:                   c.includeAncestorConftest,
 	}
 }
 
@@ -629,6 +641,16 @@ func (c *Config) ResolveSiblingImports() bool {
 	return c.resolveSiblingImports
 }
 
+// SetIncludeAncestorConftest sets whether ancestor conftest files are added to py_test targets.
+func (c *Config) SetIncludeAncestorConftest(includeAncestorConftest bool) {
+	c.includeAncestorConftest = includeAncestorConftest
+}
+
+// IncludeAncestorConftest returns whether ancestor conftest files are added to py_test targets.
+func (c *Config) IncludeAncestorConftest() bool {
+	return c.includeAncestorConftest
+}
+
 // 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)