Betterproto is a Python library that generates Python dataclasses, Protobuf serialization, and gRPC client/server stubs directly from `.proto` files. It aims to provide a more Pythonic interface than the official `protobuf` library. The current stable version is 1.2.5, but a 2.0.0 beta is under active development, introducing significant breaking changes and new features. Releases are somewhat irregular, with recent focus on the 2.0.0 branch.
pip install betterprotoVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to define a `.proto` file, compile it using `protoc` with the `betterproto` plugin, and then interact with the generated Python message classes. It covers basic message instantiation, serialization, and deserialization. Ensure the Protocol Buffers compiler (`protoc`) is installed and available in your system's PATH.
Upgrade Pydantic to version 2.x and ensure your betterproto generated code is also updated for Pydantic v2 compatibility. Pass `--python_betterproto_opt=pydantic_dataclasses` during compilation to enable Pydantic dataclasses.
Refer to the betterproto documentation on how to properly check and access `oneof` fields using their `is_set` or `which_oneof` methods before direct access.
Ensure your Python environment is running version 3.7 or higher when using betterproto v2.x.
Update client calls from `service.method(field1='val')` to `service.method(RequestMessage(field1='val'))` and adjust server handlers accordingly. This aligns with a more common gRPC pattern.
Install `protoc` by following the official Protocol Buffers documentation for your operating system (e.g., via `apt`, `brew`, or downloading from GitHub releases).
Be mindful of which version you are installing (`pip install betterproto` for 1.x, `pip install betterproto==2.0.0bX` for 2.x beta) and consult the release notes and upgrade guides for the specific version you intend to use.
Ensure `protoc` is installed and in your system's PATH. Then, install `betterproto` with the compiler extras: `pip install 'betterproto[compiler]'`. If `protoc` still can't find the plugin, manually specify its path in the `protoc` command, e.g., `--plugin=protoc-gen-python_betterproto=/path/to/venv/bin/protoc-gen-python_betterproto`.
For versions where this is a bug (e.g., betterproto 2.0.0b7, though potentially affecting earlier versions with specific `to_pydict` usage), consider using `to_dict()` instead of `to_pydict()` if dictionary output is acceptable, or upgrade to a `betterproto` version where this bug has been resolved. If stuck on an older version, a workaround might involve manually transforming the repeated timestamp fields before calling `to_pydict`.
Ensure you are providing `protoc` with the correct include paths (`-I` or `--proto_path`) that point to the directory containing the Google Protobuf well-known type definitions (usually found in the `include` directory of your `protobuf` installation). For `betterproto` specifically, ensure `protoc` can find the necessary `betterproto.lib.google.protobuf` modules by either ensuring proper generation setup or explicitly adding `--python_betterproto_opt=INCLUDE_GOOGLE` during compilation if `betterproto` is not compiling these references automatically.
Before accessing a `oneof` field, use `betterproto.which_one_of(message, 'oneof_group_name')` to determine which field in the `oneof` group is set. This method returns a tuple of `(field_name, value)` or `('', None)` if no field is set.pip install betterproto