| # Python rules |
| |
| Rules for generating Python protobuf and gRPC `.py` files and libraries using standard Protocol Buffers and gRPC or [grpclib](https://github.com/vmagamedov/grpclib). Libraries are created with `py_library` from `rules_python`. To use the fast C++ Protobuf implementation, you can add `--define=use_fast_cpp_protos=true` to your build, but this requires you setup the path to your Python headers. |
| |
| Note: On Windows, the path to Python for `pip_install` may need updating to `Python.exe`, depending on your install. |
| |
| | Rule | Description | |
| | ---: | :--- | |
| | [python_proto_compile](#python_proto_compile) | Generates Python protobuf `.py` artifacts | |
| | [python_grpc_compile](#python_grpc_compile) | Generates Python protobuf+gRPC `.py` artifacts | |
| | [python_grpclib_compile](#python_grpclib_compile) | Generates Python protobuf+grpclib `.py` artifacts (supports Python 3 only) | |
| | [python_proto_library](#python_proto_library) | Generates a Python protobuf library using `py_library` from `rules_python` | |
| | [python_grpc_library](#python_grpc_library) | Generates a Python protobuf+gRPC library using `py_library` from `rules_python` | |
| | [python_grpclib_library](#python_grpclib_library) | Generates a Python protobuf+grpclib library using `py_library` from `rules_python` (supports Python 3 only) | |
| |
| --- |
| |
| ## `python_proto_compile` |
| |
| Generates Python protobuf `.py` artifacts |
| |
| ### `WORKSPACE` |
| |
| ```starlark |
| load("@rules_proto_grpc//python:repositories.bzl", rules_proto_grpc_python_repos = "python_repos") |
| |
| rules_proto_grpc_python_repos() |
| ``` |
| |
| ### `BUILD.bazel` |
| |
| ```starlark |
| load("@rules_proto_grpc//python:defs.bzl", "python_proto_compile") |
| |
| python_proto_compile( |
| name = "person_python_proto", |
| protos = ["@rules_proto_grpc//example/proto:person_proto"], |
| ) |
| |
| python_proto_compile( |
| name = "place_python_proto", |
| protos = ["@rules_proto_grpc//example/proto:place_proto"], |
| ) |
| |
| python_proto_compile( |
| name = "thing_python_proto", |
| protos = ["@rules_proto_grpc//example/proto:thing_proto"], |
| ) |
| ``` |
| |
| ### Attributes |
| |
| | Name | Type | Mandatory | Default | Description | |
| | ---: | :--- | --------- | ------- | ----------- | |
| | `protos` | `list<ProtoInfo>` | true | `[]` | List of labels that provide a `ProtoInfo` (such as `rules_proto` `proto_library`) | |
| | `options` | `dict<string, list(string)>` | false | `[]` | Extra options to pass to plugins, as a dict of plugin label -> list of strings. The key * can be used exclusively to apply to all plugins | |
| | `verbose` | `int` | false | `0` | The verbosity level. Supported values and results are 1: *show command*, 2: *show command and sandbox after running protoc*, 3: *show command and sandbox before and after running protoc*, 4. *show env, command, expected outputs and sandbox before and after running protoc* | |
| | `prefix_path` | `string` | false | `""` | Path to prefix to the generated files in the output directory | |
| | `extra_protoc_args` | `list<string>` | false | `[]` | A list of extra args to pass directly to protoc, not as plugin options | |
| |
| ### Plugins |
| |
| - `@rules_proto_grpc//python:python_plugin` |
| |
| --- |
| |
| ## `python_grpc_compile` |
| |
| Generates Python protobuf+gRPC `.py` artifacts |
| |
| ### `WORKSPACE` |
| |
| ```starlark |
| load("@rules_proto_grpc//python:repositories.bzl", rules_proto_grpc_python_repos = "python_repos") |
| |
| rules_proto_grpc_python_repos() |
| |
| load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps") |
| |
| grpc_deps() |
| ``` |
| |
| ### `BUILD.bazel` |
| |
| ```starlark |
| load("@rules_proto_grpc//python:defs.bzl", "python_grpc_compile") |
| |
| python_grpc_compile( |
| name = "thing_python_grpc", |
| protos = ["@rules_proto_grpc//example/proto:thing_proto"], |
| ) |
| |
| python_grpc_compile( |
| name = "greeter_python_grpc", |
| protos = ["@rules_proto_grpc//example/proto:greeter_grpc"], |
| ) |
| ``` |
| |
| ### Attributes |
| |
| | Name | Type | Mandatory | Default | Description | |
| | ---: | :--- | --------- | ------- | ----------- | |
| | `protos` | `list<ProtoInfo>` | true | `[]` | List of labels that provide a `ProtoInfo` (such as `rules_proto` `proto_library`) | |
| | `options` | `dict<string, list(string)>` | false | `[]` | Extra options to pass to plugins, as a dict of plugin label -> list of strings. The key * can be used exclusively to apply to all plugins | |
| | `verbose` | `int` | false | `0` | The verbosity level. Supported values and results are 1: *show command*, 2: *show command and sandbox after running protoc*, 3: *show command and sandbox before and after running protoc*, 4. *show env, command, expected outputs and sandbox before and after running protoc* | |
| | `prefix_path` | `string` | false | `""` | Path to prefix to the generated files in the output directory | |
| | `extra_protoc_args` | `list<string>` | false | `[]` | A list of extra args to pass directly to protoc, not as plugin options | |
| |
| ### Plugins |
| |
| - `@rules_proto_grpc//python:python_plugin` |
| - `@rules_proto_grpc//python:grpc_python_plugin` |
| |
| --- |
| |
| ## `python_grpclib_compile` |
| |
| Generates Python protobuf+grpclib `.py` artifacts (supports Python 3 only) |
| |
| ### `WORKSPACE` |
| |
| ```starlark |
| load("@rules_proto_grpc//python:repositories.bzl", rules_proto_grpc_python_repos = "python_repos") |
| |
| rules_proto_grpc_python_repos() |
| |
| load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps") |
| |
| grpc_deps() |
| |
| load("@rules_python//python:pip.bzl", "pip_install") |
| |
| pip_install( |
| name = "rules_proto_grpc_py3_deps", |
| python_interpreter = "python3", |
| requirements = "@rules_proto_grpc//python:requirements.txt", |
| ) |
| ``` |
| |
| ### `BUILD.bazel` |
| |
| ```starlark |
| load("@rules_proto_grpc//python:defs.bzl", "python_grpclib_compile") |
| |
| python_grpclib_compile( |
| name = "thing_python_grpc", |
| protos = ["@rules_proto_grpc//example/proto:thing_proto"], |
| ) |
| |
| python_grpclib_compile( |
| name = "greeter_python_grpc", |
| protos = ["@rules_proto_grpc//example/proto:greeter_grpc"], |
| ) |
| ``` |
| |
| ### Attributes |
| |
| | Name | Type | Mandatory | Default | Description | |
| | ---: | :--- | --------- | ------- | ----------- | |
| | `protos` | `list<ProtoInfo>` | true | `[]` | List of labels that provide a `ProtoInfo` (such as `rules_proto` `proto_library`) | |
| | `options` | `dict<string, list(string)>` | false | `[]` | Extra options to pass to plugins, as a dict of plugin label -> list of strings. The key * can be used exclusively to apply to all plugins | |
| | `verbose` | `int` | false | `0` | The verbosity level. Supported values and results are 1: *show command*, 2: *show command and sandbox after running protoc*, 3: *show command and sandbox before and after running protoc*, 4. *show env, command, expected outputs and sandbox before and after running protoc* | |
| | `prefix_path` | `string` | false | `""` | Path to prefix to the generated files in the output directory | |
| | `extra_protoc_args` | `list<string>` | false | `[]` | A list of extra args to pass directly to protoc, not as plugin options | |
| |
| ### Plugins |
| |
| - `@rules_proto_grpc//python:python_plugin` |
| - `@rules_proto_grpc//python:grpclib_python_plugin` |
| |
| --- |
| |
| ## `python_proto_library` |
| |
| Generates a Python protobuf library using `py_library` from `rules_python` |
| |
| ### `WORKSPACE` |
| |
| ```starlark |
| load("@rules_proto_grpc//python:repositories.bzl", rules_proto_grpc_python_repos = "python_repos") |
| |
| rules_proto_grpc_python_repos() |
| ``` |
| |
| ### `BUILD.bazel` |
| |
| ```starlark |
| load("@rules_proto_grpc//python:defs.bzl", "python_proto_library") |
| |
| python_proto_library( |
| name = "person_python_proto", |
| protos = ["@rules_proto_grpc//example/proto:person_proto"], |
| deps = ["place_python_proto"], |
| ) |
| |
| python_proto_library( |
| name = "place_python_proto", |
| protos = ["@rules_proto_grpc//example/proto:place_proto"], |
| deps = ["thing_python_proto"], |
| ) |
| |
| python_proto_library( |
| name = "thing_python_proto", |
| protos = ["@rules_proto_grpc//example/proto:thing_proto"], |
| ) |
| ``` |
| |
| ### Attributes |
| |
| | Name | Type | Mandatory | Default | Description | |
| | ---: | :--- | --------- | ------- | ----------- | |
| | `protos` | `list<ProtoInfo>` | true | `[]` | List of labels that provide a `ProtoInfo` (such as `rules_proto` `proto_library`) | |
| | `options` | `dict<string, list(string)>` | false | `[]` | Extra options to pass to plugins, as a dict of plugin label -> list of strings. The key * can be used exclusively to apply to all plugins | |
| | `verbose` | `int` | false | `0` | The verbosity level. Supported values and results are 1: *show command*, 2: *show command and sandbox after running protoc*, 3: *show command and sandbox before and after running protoc*, 4. *show env, command, expected outputs and sandbox before and after running protoc* | |
| | `prefix_path` | `string` | false | `""` | Path to prefix to the generated files in the output directory | |
| | `extra_protoc_args` | `list<string>` | false | `[]` | A list of extra args to pass directly to protoc, not as plugin options | |
| | `deps` | `list<Label/string>` | false | `[]` | List of labels to pass as deps attr to underlying lang_library rule | |
| |
| --- |
| |
| ## `python_grpc_library` |
| |
| Generates a Python protobuf+gRPC library using `py_library` from `rules_python` |
| |
| ### `WORKSPACE` |
| |
| ```starlark |
| load("@rules_proto_grpc//python:repositories.bzl", rules_proto_grpc_python_repos = "python_repos") |
| |
| rules_proto_grpc_python_repos() |
| |
| load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps") |
| |
| grpc_deps() |
| ``` |
| |
| ### `BUILD.bazel` |
| |
| ```starlark |
| load("@rules_proto_grpc//python:defs.bzl", "python_grpc_library") |
| |
| python_grpc_library( |
| name = "thing_python_grpc", |
| protos = ["@rules_proto_grpc//example/proto:thing_proto"], |
| ) |
| |
| python_grpc_library( |
| name = "greeter_python_grpc", |
| protos = ["@rules_proto_grpc//example/proto:greeter_grpc"], |
| deps = ["thing_python_grpc"], |
| ) |
| ``` |
| |
| ### Attributes |
| |
| | Name | Type | Mandatory | Default | Description | |
| | ---: | :--- | --------- | ------- | ----------- | |
| | `protos` | `list<ProtoInfo>` | true | `[]` | List of labels that provide a `ProtoInfo` (such as `rules_proto` `proto_library`) | |
| | `options` | `dict<string, list(string)>` | false | `[]` | Extra options to pass to plugins, as a dict of plugin label -> list of strings. The key * can be used exclusively to apply to all plugins | |
| | `verbose` | `int` | false | `0` | The verbosity level. Supported values and results are 1: *show command*, 2: *show command and sandbox after running protoc*, 3: *show command and sandbox before and after running protoc*, 4. *show env, command, expected outputs and sandbox before and after running protoc* | |
| | `prefix_path` | `string` | false | `""` | Path to prefix to the generated files in the output directory | |
| | `extra_protoc_args` | `list<string>` | false | `[]` | A list of extra args to pass directly to protoc, not as plugin options | |
| | `deps` | `list<Label/string>` | false | `[]` | List of labels to pass as deps attr to underlying lang_library rule | |
| |
| --- |
| |
| ## `python_grpclib_library` |
| |
| Generates a Python protobuf+grpclib library using `py_library` from `rules_python` (supports Python 3 only) |
| |
| ### `WORKSPACE` |
| |
| ```starlark |
| load("@rules_proto_grpc//python:repositories.bzl", rules_proto_grpc_python_repos = "python_repos") |
| |
| rules_proto_grpc_python_repos() |
| |
| load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps") |
| |
| grpc_deps() |
| |
| load("@rules_python//python:pip.bzl", "pip_install") |
| |
| pip_install( |
| name = "rules_proto_grpc_py3_deps", |
| python_interpreter = "python3", |
| requirements = "@rules_proto_grpc//python:requirements.txt", |
| ) |
| ``` |
| |
| ### `BUILD.bazel` |
| |
| ```starlark |
| load("@rules_proto_grpc//python:defs.bzl", "python_grpclib_library") |
| |
| python_grpclib_library( |
| name = "thing_python_grpc", |
| protos = ["@rules_proto_grpc//example/proto:thing_proto"], |
| ) |
| |
| python_grpclib_library( |
| name = "greeter_python_grpc", |
| protos = ["@rules_proto_grpc//example/proto:greeter_grpc"], |
| deps = ["thing_python_grpc"], |
| ) |
| ``` |
| |
| ### Attributes |
| |
| | Name | Type | Mandatory | Default | Description | |
| | ---: | :--- | --------- | ------- | ----------- | |
| | `protos` | `list<ProtoInfo>` | true | `[]` | List of labels that provide a `ProtoInfo` (such as `rules_proto` `proto_library`) | |
| | `options` | `dict<string, list(string)>` | false | `[]` | Extra options to pass to plugins, as a dict of plugin label -> list of strings. The key * can be used exclusively to apply to all plugins | |
| | `verbose` | `int` | false | `0` | The verbosity level. Supported values and results are 1: *show command*, 2: *show command and sandbox after running protoc*, 3: *show command and sandbox before and after running protoc*, 4. *show env, command, expected outputs and sandbox before and after running protoc* | |
| | `prefix_path` | `string` | false | `""` | Path to prefix to the generated files in the output directory | |
| | `extra_protoc_args` | `list<string>` | false | `[]` | A list of extra args to pass directly to protoc, not as plugin options | |
| | `deps` | `list<Label/string>` | false | `[]` | List of labels to pass as deps attr to underlying lang_library rule | |
