Registry / serialization / betterproto

betterproto

JSON →
library1.2.5pypypi✓ verified 22d ago

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 betterproto
INSTALL
IMPORT
SIG · BETTERPROTO
B
betterproto
serializationpythonv1.2.5
Install
3.6s avg
Import
218ms
Disk
21MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.0.0b7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.234s · 22.6MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 3.6s · import 0.201s · 23MB
21MB installed
● package 21MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Message
from betterproto import Message
enum
import betterproto.enum
For working with Protobuf enums.
string_field
from betterproto import string_field
Used in generated code to define Protobuf fields.

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.

import os from pathlib import Path import subprocess import sys # 1. Define a .proto file proto_content = """ syntax = "proto3"; message GreetRequest { string name = 1; } message GreetResponse { string greeting = 1; } """ proto_file_path = Path("greet.proto") proto_file_path.write_text(proto_content) # 2. Compile the .proto file using protoc with betterproto plugin # Ensure `protoc` is installed and in your PATH. # The betterproto Python package ships its own protoc plugin. try: # Find the betterproto plugin betterproto_plugin = next( p for p in sys.path if 'betterproto' in p and 'site-packages' in p ) + '/betterproto/plugin/protoc-gen-python_betterproto' print(f"Using betterproto plugin: {betterproto_plugin}") compile_command = [ "protoc", f"--plugin=protoc-gen-python_betterproto={betterproto_plugin}", "--python_betterproto_out=.", str(proto_file_path) ] subprocess.run(compile_command, check=True, capture_output=True) print("Proto file compiled successfully to greet.py") # 3. Use the generated Python code from greet import GreetRequest, GreetResponse request = GreetRequest(name="World") print(f"Created request: {request.name}") # Serialize the message serialized_data = bytes(request) print(f"Serialized data (bytes): {serialized_data}") # Deserialize the message deserialized_request = GreetRequest().parse(serialized_data) print(f"Deserialized request: {deserialized_request.name}") response = GreetResponse(greeting=f"Hello, {deserialized_request.name}!") print(f"Created response: {response.greeting}") except FileNotFoundError: print("Error: 'protoc' command not found. Please install Protocol Buffers compiler.") except subprocess.CalledProcessError as e: print(f"Error compiling proto file: {e.stderr.decode()}") except ImportError: print("Error: Could not import generated 'greet' module. Compilation might have failed or plugin path is incorrect.") finally: # Clean up generated files Path("greet.py").unlink(missing_ok=True) Path("greet.proto").unlink(missing_ok=True) print("Cleaned up temporary files.")
betterproto --version
Debug
Known issues
breakingBetterproto v2.0.0b7+ drops support for Pydantic v1. If you use Pydantic dataclasses, you must upgrade to Pydantic v2.
fix
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.
affects: 2.0.0b7+
breakingIn Betterproto v2.0.0b7+, attempting to access an unset `oneof` field will now raise an `AttributeError`. Previously, this might have returned a default value or `None` without explicit checking.
fix
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.
affects: 2.0.0b7+
breakingBetterproto v2.0.0b6+ requires Python 3.7 or newer. Earlier beta versions had different minimum Python requirements.
fix
Ensure your Python environment is running version 3.7 or higher when using betterproto v2.x.
affects: 2.0.0b6+
breakingIn Betterproto v2.0.0b5+, gRPC client calls and server handlers now require input message fields to be explicitly wrapped in their respective message objects.
fix
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.
affects: 2.0.0b5+
gotchaBetterproto is a code generator; you *must* have the `protoc` (Protocol Buffers compiler) executable installed and in your system's PATH to use it. `pip install betterproto` only installs the Python library and its `protoc` plugin, not `protoc` itself.
fix
Install `protoc` by following the official Protocol Buffers documentation for your operating system (e.g., via `apt`, `brew`, or downloading from GitHub releases).
affects: All versions
gotchaThe `betterproto` library has two major versions currently active: stable `1.x` and an actively developed `2.x` beta. The `2.x` branch introduces many breaking changes and new features (like Pydantic v2 support, gRPC API changes, etc.).
fix
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.
affects: All versions
Errors
Common errors & fixes
protoc-gen-python_betterproto: program not found or is not executable
The `protoc` compiler cannot find the `protoc-gen-python_betterproto` plugin, either because `protoc` itself is not installed, the plugin is not in your system's PATH, or the `betterproto` Python package (which includes the plugin) is not correctly installed or linked.
fix
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`.
AttributeError: 'datetime.datetime' object has no attribute 'to_pydict'
This error occurs in `betterproto` when attempting to call `to_pydict()` on a message containing a `repeated google.protobuf.Timestamp` field, as the `datetime.datetime` objects within the list do not have the `to_pydict` method directly callable on them during the recursive serialization process.
fix
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`.
from .google import protobuf ModuleNotFoundError: No module named 'google.protobuf'
This `ModuleNotFoundError` often happens in generated `betterproto` code when the `protoc` compiler cannot correctly resolve imports for Google's well-known types (like `Timestamp` or `Empty`), leading to incorrect relative import statements or missing generated modules for `google.protobuf` within your output directory.
fix
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.
AttributeError: 'Message' object has no attribute 'oneof_field_name'
In `betterproto` versions 2.0.0b7 and later, direct access to unset `oneof` fields will raise an `AttributeError`. Previously, it might have returned `None` or a default value. This is a breaking change to encourage explicit checking for `oneof` field presence.
fix
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.
ModuleNotFoundError: No module named 'betterproto'
The betterproto library has not been installed in the current Python environment.
fix
pip install betterproto
Upgrade
Version history
1.2.5latest on PyPI · released May 27, 2020
Audit
Dependencies
grpcliboptionalRequired for gRPC client/server functionality.
pydanticoptionalRequired for generating Pydantic dataclasses (available in 2.0.0b6+ with `--python_betterproto_opt=pydantic_dataclasses`).
Agent activity
43 hits · last 30 days
node
36
OpenAI (training)
1
Resources
betterproto — pip install betterproto · libregistry