feat(gazelle): Gazelle plugin generates py_proto_library (#3057)

Fixes #2994.

Please go over this with a fine-toothed comb! This is my first
contribution to `rules_python` / the gazelle plugin, and while I've
worked in Gazelle before, I'm pretty unfamiliar with the Python plugin's
architecture.

This adds support in the Gazelle plugin for generating
`py_proto_library` rules automatically, if there are any `proto_library`
rules detected in a given package. We do this via a new Gazelle
directive, `python_generate_proto`, which defaults to `true`, and
controls whether these rules are generated.

See the tests in `testdata/directive_python_generate_proto` for
examples.

By default, we source the `py_proto_library` rule from the `@protobuf`
repository. I think this the intended long-term home of the rule? Users
are expected to use `gazelle:map_kind` to change this if need be.

I haven't done anything here to support resolution of imports of
`py_proto_library`. I think this is worth landing first, to save folks
from having to maintain these by hand. But this should lay the
foundation for resolving that in
#1703.

---------

Co-authored-by: Douglas Thor <[email protected]>

Author: shaldengeki

CHANGELOG.md

@@ -106,6 +106,8 @@ END_UNRELEASED_TEMPLATE
     * 3.12.11
     * 3.13.5
     * 3.14.0b3
+* (gazelle) New directive `gazelle:python_generate_proto`; when `true`,
+  Gazelle generates `py_proto_library` rules for `proto_library`. `false` by default.
 
 {#v0-0-0-removed}
 ### Removed

examples/bzlmod/py_proto_library/BUILD.bazel

@@ -6,15 +6,15 @@ py_test(
     srcs = ["test.py"],
     main = "test.py",
     deps = [
-        "//py_proto_library/example.com/proto:pricetag_proto_py_pb2",
+        "//py_proto_library/example.com/proto:pricetag_py_pb2",
     ],
 )
 
 py_test(
     name = "message_test",
     srcs = ["message_test.py"],
     deps = [
-        "//py_proto_library/example.com/another_proto:message_proto_py_pb2",
+        "//py_proto_library/example.com/another_proto:message_py_pb2",
     ],
 )
 

examples/bzlmod/py_proto_library/example.com/another_proto/BUILD.bazel

@@ -2,7 +2,7 @@ load("@com_google_protobuf//bazel:proto_library.bzl", "proto_library")
 load("@rules_python//python:proto.bzl", "py_proto_library")
 
 py_proto_library(
-    name = "message_proto_py_pb2",
+    name = "message_py_pb2",
     visibility = ["//visibility:public"],
     deps = [":message_proto"],
 )

examples/bzlmod/py_proto_library/example.com/proto/BUILD.bazel

@@ -2,7 +2,7 @@ load("@com_google_protobuf//bazel:proto_library.bzl", "proto_library")
 load("@rules_python//python:proto.bzl", "py_proto_library")
 
 py_proto_library(
-    name = "pricetag_proto_py_pb2",
+    name = "pricetag_py_pb2",
     visibility = ["//visibility:public"],
     deps = [":pricetag_proto"],
 )

examples/py_proto_library/BUILD.bazel

@@ -5,14 +5,14 @@ py_test(
     srcs = ["test.py"],
     main = "test.py",
     deps = [
-        "//example.com/proto:pricetag_proto_py_pb2",
+        "//example.com/proto:pricetag_py_pb2",
     ],
 )
 
 py_test(
     name = "message_test",
     srcs = ["message_test.py"],
     deps = [
-        "//example.com/another_proto:message_proto_py_pb2",
+        "//example.com/another_proto:message_py_pb2",
     ],
 )

examples/py_proto_library/example.com/another_proto/BUILD.bazel

@@ -2,7 +2,7 @@ load("@com_google_protobuf//bazel:proto_library.bzl", "proto_library")
 load("@rules_python//python:proto.bzl", "py_proto_library")
 
 py_proto_library(
-    name = "message_proto_py_pb2",
+    name = "message_py_pb2",
     visibility = ["//visibility:public"],
     deps = [":message_proto"],
 )

examples/py_proto_library/example.com/proto/BUILD.bazel

@@ -2,7 +2,7 @@ load("@com_google_protobuf//bazel:proto_library.bzl", "proto_library")
 load("@rules_python//python:proto.bzl", "py_proto_library")
 
 py_proto_library(
-    name = "pricetag_proto_py_pb2",
+    name = "pricetag_py_pb2",
     visibility = ["//visibility:public"],
     deps = [":pricetag_proto"],
 )

gazelle/README.md

@@ -224,6 +224,8 @@ Python-specific directives are as follows:
 | Controls whether Gazelle resolves dependencies for import statements that use paths relative to the current package. Can be "true" or "false".|
 | `# gazelle:python_generate_pyi_deps`                                                                                                                                                                                                                                                            | `false` |
 | Controls whether to generate a separate `pyi_deps` attribute for type-checking dependencies or merge them into the regular `deps` attribute. When `false` (default), type-checking dependencies are merged into `deps` for backward compatibility. When `true`, generates separate `pyi_deps`. Imports in blocks with the format `if typing.TYPE_CHECKING:`/`if TYPE_CHECKING:` and type-only stub packages (eg. boto3-stubs) are recognized as type-checking dependencies. |
+| [`# gazelle:python_generate_proto`](#directive-python_generate_proto)                                                                                                                                                                                                                                                                | `false` |
+| Controls whether to generate a `py_proto_library` for each `proto_library` in the package. By default we load this rule from the `@protobuf` repository; use `gazelle:map_kind` if you need to load this from somewhere else. |
 
 #### Directive: `python_root`:
 
@@ -484,6 +486,41 @@ def py_test(name, main=None, **kwargs):
 )
 ```
 
+#### Directive: `python_generate_proto`:
+
+When `# gazelle:python_generate_proto true`, Gazelle will generate one
+`py_proto_library` for each `proto_library`, generating Python clients for
+protobuf in each package. By default this is turned off. Gazelle will also
+generate a load statement for the `py_proto_library` - attempting to detect
+the configured name for the `@protobuf` / `@com_google_protobuf` repo in your
+`MODULE.bazel`, and otherwise falling back to `@com_google_protobuf` for
+compatibility with `WORKSPACE`.
+
+For example, in a package with `# gazelle:python_generate_proto true` and a
+`foo.proto`, if you have both the proto extension and the Python extension
+loaded into Gazelle, you'll get something like:
+
+```starlark
+load("@protobuf//bazel:py_proto_library.bzl", "py_proto_library")
+load("@rules_proto//proto:defs.bzl", "proto_library")
+
+# gazelle:python_generate_proto true
+
+proto_library(
+    name = "foo_proto",
+    srcs = ["foo.proto"],
+    visibility = ["//:__subpackages__"],
+)
+
+py_proto_library(
+    name = "foo_py_pb2",
+    visibility = ["//:__subpackages__"],
+    deps = [":foo_proto"],
+)
+```
+
+When `false`, Gazelle will ignore any `py_proto_library`, including previously-generated or hand-created rules.
+
 ### Annotations
 
 *Annotations* refer to comments found _within Python files_ that configure how

gazelle/python/BUILD.bazel

@@ -34,6 +34,7 @@ go_library(
         "@bazel_gazelle//config:go_default_library",
         "@bazel_gazelle//label:go_default_library",
         "@bazel_gazelle//language:go_default_library",
+        "@bazel_gazelle//language/proto:go_default_library",
         "@bazel_gazelle//repo:go_default_library",
         "@bazel_gazelle//resolve:go_default_library",
         "@bazel_gazelle//rule:go_default_library",
@@ -91,7 +92,10 @@ gazelle_test(
 
 gazelle_binary(
     name = "gazelle_binary",
-    languages = [":python"],
+    languages = [
+        "@bazel_gazelle//language/proto",
+        ":python",
+    ],
     visibility = ["//visibility:public"],
 )
 

gazelle/python/configure.go

@@ -70,6 +70,7 @@ func (py *Configurer) KnownDirectives() []string {
 		pythonconfig.LabelNormalization,
 		pythonconfig.GeneratePyiDeps,
 		pythonconfig.ExperimentalAllowRelativeImports,
+		pythonconfig.GenerateProto,
 	}
 }
 
@@ -237,6 +238,12 @@ func (py *Configurer) Configure(c *config.Config, rel string, f *rule.File) {
 				log.Fatal(err)
 			}
 			config.SetGeneratePyiDeps(v)
+		case pythonconfig.GenerateProto:
+			v, err := strconv.ParseBool(strings.TrimSpace(d.Value))
+			if err != nil {
+				log.Fatal(err)
+			}
+			config.SetGenerateProto(v)
 		}
 	}