| Name | hatch-protobuf JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | None |
| Summary | A Hatch build plugin to generate Python files from Protocol Buffers .proto files |
| upload_time | 2025-07-16 09:16:57 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
grpc
hatch
protobuf
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Hatch Protocol Buffers Generator
This Hatch plugin uses grpcio to generate Python files from Protocol Buffers `.proto` files.
## Usage
You will need to add `hatch-protobuf` to your project's `pyproject.toml`:
```
[tool.hatch.build.hooks.protobuf]
dependencies = ["hatch-protobuf"]
```
There are a few options that can be set in the `[tool.hatch.build.hooks.protobuf]`
section:
| Key | Default | Description |
| --- | ------- | ----------- |
| `generate_grpc` | `true` | Whether to generate gRPC output files. |
| `generate_pyi` | `true` | Whether to generate .pyi output files. Note that these are not generated for the gRPC output. You may want to use mypy-protobuf instead. |
| `import_site_packages` | `false` | Adds your Python `site-packages` directory to `--proto_path`, so you can [`import` `.proto` files from installed Python packages](#import-proto-files-from-site-packages). This *does not* add individual `.proto` files in `site-packages` as arguments to `protoc`. |
| `proto_paths` | `["."]` or `["src"]` | An array of paths to search for `.proto` files. Also passed as `--proto_path` arguments to `protoc`. This does not follow symlinks. |
| `output_path` | `"."` or `"src"` | The default output directory. This can be overridden on a per-generator basis for custom generators. |
| `library_paths` | `[]` | Similar to `proto_paths`, but **without** building the `_pb2.py` files, allowing imports from `.proto`s not included in the Python `site-packages` directory. |
Hatch-protobuf will guess whether to use "src" as the default input/output directory in
a similar way to the [wheel builder][wheel-builder-defaults]. If
`src/<NAME>/__init__.py` exists, but `<NAME>/__init__.py` does not, it will use "src" as
the default for `proto_paths` and `output_path`. Otherwise it will use "." as the
default for both.
[wheel-builder-defaults]: https://hatch.pypa.io/latest/plugins/builder/wheel/#default-file-selection
### Custom generators
If you want to use custom generators (not just the python, gRPC and pyi ones built in to
the version of protoc that ships with grpcio-tools), you can add them in
`[[tool.hatch.build.hooks.protobuf.generators]]` sections. You will also need to add the
plugin to the list of dependencies.
Options that can be set in generator sections:
| Key | Default | Description |
| --- | ------- | ----------- |
| `name` | required | The name of the plugin. The argument passed to protoc will be `--<name>_out`. |
| `outputs` | required | A list of paths (relative to `output_path`). See below for more information. |
| `output_path` | same as `output_path` from the main `protobuf` config section | Where to write generated files to. This is the value passed to the `--<name>_out` argument. |
| `protoc_plugin` | `None` | The protoc plugin to use for this generator, if any. Will be passed as --plugin to protoc. This is useful for plugins that are not installed in the Python environment. |
| `options` | `[]` | Extra parameters to be passed to the protoc plugin using [the `--<name>_opt` argument.][protobuf-pull-2284] |
Each entry in the `outputs` field is a template that depends on the `.proto` file being
processed. The string `{proto_name}` will be replaced with the base filename of each input .proto
file, and `{proto_path}` will be replaced with the path (relative to the proto_paths) of
the input proto files. For example, if `proto_paths` is set to `["src"]`, for the
input file `src/foo/bar/test.proto` "{proto_name}" will expand to "test" and
"{proto_path}" will expand to "foo/bar".
Here is an example using the TypeScript generator:
```
[[tool.hatch.build.hooks.protobuf.generators]]
name = "ts"
outputs = ["{proto_path}/{proto_name}.ts"]
output_path = "./frontend/src"
protoc_plugin = "./frontend/node_modules/.bin/protoc-gen-ts_proto"
```
[protobuf-pull-2284]: https://github.com/protocolbuffers/protobuf/pull/2284
### Mypy output
The [mypy-protobuf](https://pypi.org/project/mypy-protobuf/) package provides mypy stub
files with comments copied from the input `.proto` files. Here is an example of how to
use it in your `pyproject.toml`:
```
[tool.hatch.build.hooks.protobuf]
dependencies = [
"hatch-protobuf",
"mypy-protobuf~=3.0",
]
generate_pyi = false # we'll let mypy-protobuf do this
[[tool.hatch.build.hooks.protobuf.generators]]
name = "mypy"
outputs = ["{proto_path}/{proto_name}_pb2.pyi"]
[[tool.hatch.build.hooks.protobuf.generators]]
name = "mypy_grpc"
outputs = ["{proto_path}/{proto_name}_pb2_grpc.pyi"]
```
### Import `.proto` files from `site-packages`
Setting `include_site_packages = true` causes the plugin to add your current
`site-packages` directory as a `--proto_path` when running `protoc`, *without*
trying to build a `_pb2.py` for *every* `.proto` file.
This allows your package to consume Protocol Buffer definitions from published
Python packages which include both `.proto` and `_pb2.py` files.
As an example, consider a gRPC service definition which includes a Protocol
Buffer message definiton from
[Google API common protos](https://github.com/googleapis/googleapis/tree/master/google/api):
```proto
// proto/example/v1/example.proto
syntax = "proto3";
package example.v1;
import "google/api/annotations.proto";
// The greeting service definition.
service Greeter {
// Sends a greeting
rpc SayHello(HelloRequest) returns (HelloReply) {
option (google.api.http) = {
get: "/say"
};
}
}
// The request message containing the user's name.
message HelloRequest {
string name = 1;
}
// The response message containing the greetings
message HelloReply {
string message = 1;
}
```
In this case, the
[`googleapis-common-protos` package](https://pypi.org/project/googleapis-common-protos/)
contains `annotations.proto` and a pre-built version of `annotations_pb2.py`,
which is normally installed in a directory tree layout which can be used by
*both* Python and `protoc`:
```
site-packages/google/api/
├── annotations_pb2.py
├── annotations.proto
├── auth_pb2.py
├── auth.proto
...
```
Setting `include_site_packages = true` makes your generated code contain imports
that reference the already-built bindings, and not rebuild them:
```python
# example/v1/example_pb2.py
from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2
```
If you had added the directory containing `google/api/annotations.proto` to this
plugin's `proto_paths` option, this would cause it to re-build Python files for
*all* `.proto` files in that directory, not just the things used for your
package, and stomp all over your `site-packages` directory.
> [!NOTE]
> You can only `import` Protocol Buffer definitions in `.proto` files from
> *non-editable* dependencies (ie: from ordinary packages published on PyPI or
> private registries).
>
> *Editable* dependencies (eg: installed with `pip install -e` or using
> [`uv` workspaces](https://docs.astral.sh/uv/concepts/projects/dependencies/#editable-dependencies))
> use a different directory layout which can't be imported from by `protoc`.
To consume Protocol Buffer definitions from published Python packages which
include only `_pb2.py` files, `library_paths` can be set to the directory
containing the `.proto` files.
For example, You can add [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto)
as a submodule in a project, and you will be able to import files from it after
including the following config:
```
[tool.hatch.build.hooks.protobuf]
library_paths = ["./libs/opentelemetry-proto"]
```
Raw data
{
"_id": null,
"home_page": null,
"name": "hatch-protobuf",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "grpc, hatch, protobuf",
"author": null,
"author_email": "Oxford Nanopore Technologies PLC <info@nanoporetech.com>",
"download_url": "https://files.pythonhosted.org/packages/a7/d4/3dbffa32726c73b7b3a652f380f7fb79439518453a85fd00b82416d9e212/hatch_protobuf-0.5.0.tar.gz",
"platform": null,
"description": "# Hatch Protocol Buffers Generator\n\nThis Hatch plugin uses grpcio to generate Python files from Protocol Buffers `.proto` files.\n\n\n## Usage\n\nYou will need to add `hatch-protobuf` to your project's `pyproject.toml`:\n\n```\n[tool.hatch.build.hooks.protobuf]\ndependencies = [\"hatch-protobuf\"]\n```\n\nThere are a few options that can be set in the `[tool.hatch.build.hooks.protobuf]`\nsection:\n\n| Key | Default | Description |\n| --- | ------- | ----------- |\n| `generate_grpc` | `true` | Whether to generate gRPC output files. |\n| `generate_pyi` | `true` | Whether to generate .pyi output files. Note that these are not generated for the gRPC output. You may want to use mypy-protobuf instead. |\n| `import_site_packages` | `false` | Adds your Python `site-packages` directory to `--proto_path`, so you can [`import` `.proto` files from installed Python packages](#import-proto-files-from-site-packages). This *does not* add individual `.proto` files in `site-packages` as arguments to `protoc`. |\n| `proto_paths` | `[\".\"]` or `[\"src\"]` | An array of paths to search for `.proto` files. Also passed as `--proto_path` arguments to `protoc`. This does not follow symlinks. |\n| `output_path` | `\".\"` or `\"src\"` | The default output directory. This can be overridden on a per-generator basis for custom generators. |\n| `library_paths` | `[]` | Similar to `proto_paths`, but **without** building the `_pb2.py` files, allowing imports from `.proto`s not included in the Python `site-packages` directory. |\n\nHatch-protobuf will guess whether to use \"src\" as the default input/output directory in\na similar way to the [wheel builder][wheel-builder-defaults]. If\n`src/<NAME>/__init__.py` exists, but `<NAME>/__init__.py` does not, it will use \"src\" as\nthe default for `proto_paths` and `output_path`. Otherwise it will use \".\" as the\ndefault for both.\n\n[wheel-builder-defaults]: https://hatch.pypa.io/latest/plugins/builder/wheel/#default-file-selection\n\n### Custom generators\n\nIf you want to use custom generators (not just the python, gRPC and pyi ones built in to\nthe version of protoc that ships with grpcio-tools), you can add them in\n`[[tool.hatch.build.hooks.protobuf.generators]]` sections. You will also need to add the\nplugin to the list of dependencies.\n\nOptions that can be set in generator sections:\n\n| Key | Default | Description |\n| --- | ------- | ----------- |\n| `name` | required | The name of the plugin. The argument passed to protoc will be `--<name>_out`. |\n| `outputs` | required | A list of paths (relative to `output_path`). See below for more information. |\n| `output_path` | same as `output_path` from the main `protobuf` config section | Where to write generated files to. This is the value passed to the `--<name>_out` argument. |\n| `protoc_plugin` | `None` | The protoc plugin to use for this generator, if any. Will be passed as --plugin to protoc. This is useful for plugins that are not installed in the Python environment. |\n| `options` | `[]` | Extra parameters to be passed to the protoc plugin using [the `--<name>_opt` argument.][protobuf-pull-2284] |\n\nEach entry in the `outputs` field is a template that depends on the `.proto` file being\nprocessed. The string `{proto_name}` will be replaced with the base filename of each input .proto\nfile, and `{proto_path}` will be replaced with the path (relative to the proto_paths) of\nthe input proto files. For example, if `proto_paths` is set to `[\"src\"]`, for the\ninput file `src/foo/bar/test.proto` \"{proto_name}\" will expand to \"test\" and\n\"{proto_path}\" will expand to \"foo/bar\".\n\nHere is an example using the TypeScript generator:\n\n```\n[[tool.hatch.build.hooks.protobuf.generators]]\nname = \"ts\"\noutputs = [\"{proto_path}/{proto_name}.ts\"]\noutput_path = \"./frontend/src\"\nprotoc_plugin = \"./frontend/node_modules/.bin/protoc-gen-ts_proto\"\n```\n\n[protobuf-pull-2284]: https://github.com/protocolbuffers/protobuf/pull/2284\n\n### Mypy output\n\nThe [mypy-protobuf](https://pypi.org/project/mypy-protobuf/) package provides mypy stub\nfiles with comments copied from the input `.proto` files. Here is an example of how to\nuse it in your `pyproject.toml`:\n\n```\n[tool.hatch.build.hooks.protobuf]\ndependencies = [\n \"hatch-protobuf\",\n \"mypy-protobuf~=3.0\",\n]\ngenerate_pyi = false # we'll let mypy-protobuf do this\n\n[[tool.hatch.build.hooks.protobuf.generators]]\nname = \"mypy\"\noutputs = [\"{proto_path}/{proto_name}_pb2.pyi\"]\n\n[[tool.hatch.build.hooks.protobuf.generators]]\nname = \"mypy_grpc\"\noutputs = [\"{proto_path}/{proto_name}_pb2_grpc.pyi\"]\n```\n\n### Import `.proto` files from `site-packages`\n\nSetting `include_site_packages = true` causes the plugin to add your current\n`site-packages` directory as a `--proto_path` when running `protoc`, *without*\ntrying to build a `_pb2.py` for *every* `.proto` file.\n\nThis allows your package to consume Protocol Buffer definitions from published\nPython packages which include both `.proto` and `_pb2.py` files.\n\nAs an example, consider a gRPC service definition which includes a Protocol\nBuffer message definiton from\n[Google API common protos](https://github.com/googleapis/googleapis/tree/master/google/api):\n\n```proto\n// proto/example/v1/example.proto\nsyntax = \"proto3\";\n\npackage example.v1;\n\nimport \"google/api/annotations.proto\";\n\n// The greeting service definition.\nservice Greeter {\n // Sends a greeting\n rpc SayHello(HelloRequest) returns (HelloReply) {\n option (google.api.http) = {\n get: \"/say\"\n };\n }\n}\n\n// The request message containing the user's name.\nmessage HelloRequest {\n string name = 1;\n}\n\n// The response message containing the greetings\nmessage HelloReply {\n string message = 1;\n}\n```\n\nIn this case, the\n[`googleapis-common-protos` package](https://pypi.org/project/googleapis-common-protos/)\ncontains `annotations.proto` and a pre-built version of `annotations_pb2.py`,\nwhich is normally installed in a directory tree layout which can be used by\n*both* Python and `protoc`:\n\n```\nsite-packages/google/api/\n\u251c\u2500\u2500 annotations_pb2.py\n\u251c\u2500\u2500 annotations.proto\n\u251c\u2500\u2500 auth_pb2.py\n\u251c\u2500\u2500 auth.proto\n...\n```\n\nSetting `include_site_packages = true` makes your generated code contain imports\nthat reference the already-built bindings, and not rebuild them:\n\n```python\n# example/v1/example_pb2.py\nfrom google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2\n```\n\nIf you had added the directory containing `google/api/annotations.proto` to this\nplugin's `proto_paths` option, this would cause it to re-build Python files for\n*all* `.proto` files in that directory, not just the things used for your\npackage, and stomp all over your `site-packages` directory.\n\n> [!NOTE]\n> You can only `import` Protocol Buffer definitions in `.proto` files from\n> *non-editable* dependencies (ie: from ordinary packages published on PyPI or\n> private registries).\n>\n> *Editable* dependencies (eg: installed with `pip install -e` or using\n> [`uv` workspaces](https://docs.astral.sh/uv/concepts/projects/dependencies/#editable-dependencies))\n> use a different directory layout which can't be imported from by `protoc`.\n\nTo consume Protocol Buffer definitions from published Python packages which\ninclude only `_pb2.py` files, `library_paths` can be set to the directory\ncontaining the `.proto` files.\nFor example, You can add [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto)\nas a submodule in a project, and you will be able to import files from it after\nincluding the following config:\n\n```\n[tool.hatch.build.hooks.protobuf]\nlibrary_paths = [\"./libs/opentelemetry-proto\"]\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A Hatch build plugin to generate Python files from Protocol Buffers .proto files",
"version": "0.5.0",
"project_urls": {
"Source code": "https://github.com/nanoporetech/hatch-protobuf"
},
"split_keywords": [
"grpc",
" hatch",
" protobuf"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5d438e095101b590b89c085c002b8b22aa384fcebab963ded13c1052219895fa",
"md5": "d17c073bf1c25529b3e3b2f012bfbe11",
"sha256": "565be3b59e83d2d9d6a11e76442b40fe4e86d045a59a53f525677dfeed61f3a7"
},
"downloads": -1,
"filename": "hatch_protobuf-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d17c073bf1c25529b3e3b2f012bfbe11",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13002,
"upload_time": "2025-07-16T09:16:56",
"upload_time_iso_8601": "2025-07-16T09:16:56.839737Z",
"url": "https://files.pythonhosted.org/packages/5d/43/8e095101b590b89c085c002b8b22aa384fcebab963ded13c1052219895fa/hatch_protobuf-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a7d43dbffa32726c73b7b3a652f380f7fb79439518453a85fd00b82416d9e212",
"md5": "c577e896728fa523495bc5d427843544",
"sha256": "9ffd784fd083eb5d37f6897e59c627238ec3349de52afb897ee161f7d1ca414e"
},
"downloads": -1,
"filename": "hatch_protobuf-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "c577e896728fa523495bc5d427843544",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 15176,
"upload_time": "2025-07-16T09:16:57",
"upload_time_iso_8601": "2025-07-16T09:16:57.842309Z",
"url": "https://files.pythonhosted.org/packages/a7/d4/3dbffa32726c73b7b3a652f380f7fb79439518453a85fd00b82416d9e212/hatch_protobuf-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 09:16:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nanoporetech",
"github_project": "hatch-protobuf",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hatch-protobuf"
}
