feat(gazelle): Add directives for label format & normalisation (#1976)

Adds new directives to alter default Gazelle label format to third-party
dependencies useful for re-using Gazelle plugin with other rules,
including `rules_pycross`.

Fixes #1939

Author: wingsofovnia

CHANGELOG.md

@@ -68,6 +68,11 @@ A brief description of the categories of changes:
 * (toolchains) {obj}`//python/runtime_env_toolchains:all`, which is a drop-in
   replacement for the "autodetecting" toolchain.
 
+### Added
+* (gazelle) Added new `python_label_convention` and `python_label_normalization` directives. These directive 
+  allows altering default Gazelle label format to third-party dependencies useful for re-using Gazelle plugin
+  with other rules, including `rules_pycross`. See [#1939](https://github.com/bazelbuild/rules_python/issues/1939).
+
 ### Removed
 * (pip): Removes the `entrypoint` macro that was replaced by `py_console_script_binary` in 0.26.0.
 

gazelle/README.md

@@ -204,7 +204,10 @@ Python-specific directives are as follows:
 | Appends additional visibility labels to each generated target. This directive can be set multiple times. | |
 | [`# gazelle:python_test_file_pattern`](#directive-python_test_file_pattern) | `*_test.py,test_*.py` |
 | Filenames matching these comma-separated `glob`s will be mapped to `py_test` targets. |
-
+| `# gazelle:python_label_convention` | `$distribution_name$` |
+| Defines the format of the distribution name in labels to third-party deps. Useful for using Gazelle plugin with other rules with different repository conventions (e.g. `rules_pycross`). Full label is always prepended with (pip) repository name, e.g. `@pip//numpy`. |
+| `# gazelle:python_label_normalization` | `snake_case` |
+| Controls how distribution names in labels to third-party deps are normalized. Useful for using Gazelle plugin with other rules with different label conventions (e.g. `rules_pycross` uses PEP-503). Can be "snake_case", "none", or "pep503". |
 
 #### Directive: `python_root`:
 

gazelle/python/configure.go

@@ -67,6 +67,8 @@ func (py *Configurer) KnownDirectives() []string {
 		pythonconfig.DefaultVisibilty,
 		pythonconfig.Visibility,
 		pythonconfig.TestFilePattern,
+		pythonconfig.LabelConvention,
+		pythonconfig.LabelNormalization,
 	}
 }
 
@@ -196,6 +198,23 @@ func (py *Configurer) Configure(c *config.Config, rel string, f *rule.File) {
 				}
 			}
 			config.SetTestFilePattern(globStrings)
+		case pythonconfig.LabelConvention:
+			value := strings.TrimSpace(d.Value)
+			if value == "" {
+				log.Fatalf("directive '%s' requires a value", pythonconfig.LabelConvention)
+			}
+			config.SetLabelConvention(value)
+		case pythonconfig.LabelNormalization:
+			switch directiveArg := strings.ToLower(strings.TrimSpace(d.Value)); directiveArg {
+			case "pep503":
+				config.SetLabelNormalization(pythonconfig.Pep503LabelNormalizationType)
+			case "none":
+				config.SetLabelNormalization(pythonconfig.NoLabelNormalizationType)
+			case "snake_case":
+				config.SetLabelNormalization(pythonconfig.SnakeCaseLabelNormalizationType)
+			default:
+				config.SetLabelNormalization(pythonconfig.DefaultLabelNormalizationType)
+			}
 		}
 	}
 

gazelle/python/testdata/annotation_include_dep/__init__.py

@@ -1,5 +1,5 @@
-import module1
 import foo  # third party package
+import module1
 
 # gazelle:include_dep //foo/bar:baz
 # gazelle:include_dep //hello:world,@star_wars//rebel_alliance/luke:skywalker

gazelle/python/testdata/directive_python_label_convention/README.md

@@ -0,0 +1,4 @@
+# Directive: `python_label_convention`
+
+This test case asserts that the `# gazelle:python_label_convention` directive
+works as intended when set.

gazelle/python/testdata/directive_python_label_convention/WORKSPACE

@@ -0,0 +1,11 @@
+load("@rules_python//python:defs.bzl", "py_library")
+
+py_library(
+    name = "test1_unset",
+    srcs = ["bar.py"],
+    visibility = ["//:__subpackages__"],
+    deps = [
+        "@gazelle_python_test//google_cloud_aiplatform",
+        "@gazelle_python_test//google_cloud_storage",
+    ],
+)

gazelle/python/testdata/directive_python_label_convention/test.yaml

@@ -0,0 +1,6 @@
+from google.cloud import aiplatform, storage
+
+
+def main():
+    a = dir(aiplatform)
+    b = dir(storage)