0
# BetterProto
1

2
A modern, idiomatic Python implementation of Protocol Buffers (protobuf) and gRPC code generation that addresses limitations of the official Google protoc plugin. It generates clean, readable Python code using modern language features including dataclasses, async/await, type hints, and timezone-aware datetime objects for Python 3.6+.
3

4
## Package Information
5

6
- **Package Name**: betterproto
7
- **Language**: Python
8
- **Installation**: `pip install betterproto` (runtime) or `pip install "betterproto[compiler]"` (with code generation)
9

10
## Core Imports
11

12
```python
13
import betterproto
14
```
15

16
For message classes and field definitions:
17

18
```python
19
from betterproto import Message, Enum
20
```
21

22
For field creation functions:
23

24
```python
25
from betterproto import (
26
    string_field, int32_field, bool_field, message_field, 
27
    enum_field, bytes_field, map_field
28
)
29
```
30

31
## Basic Usage
32

33
### Defining Messages
34

35
```python
36
from dataclasses import dataclass
37
from typing import List
38
import betterproto
39

40
@dataclass
41
class Person(betterproto.Message):
42
    name: str = betterproto.string_field(1)
43
    age: int = betterproto.int32_field(2)
44
    email: str = betterproto.string_field(3)
45

46
@dataclass  
47
class AddressBook(betterproto.Message):
48
    people: List[Person] = betterproto.message_field(1)
49
```
50

51
### Serialization and Deserialization
52

53
```python
54
# Create a message
55
person = Person(name="Alice", age=30, email="alice@example.com")
56

57
# Serialize to binary
58
binary_data = bytes(person)
59

60
# Parse from binary
61
parsed_person = Person().parse(binary_data)
62

63
# JSON serialization
64
json_str = person.to_json()
65
person_from_json = Person().from_json(json_str)
66

67
# Dictionary conversion
68
person_dict = person.to_dict()
69
person_from_dict = Person().from_dict(person_dict)
70
```
71

72
### Using with gRPC
73

74
```python
75
import asyncio
76
from grpclib.client import Channel
77
import betterproto
78

79
class GreeterServiceStub(betterproto.ServiceStub):
80
    async def say_hello(
81
        self, 
82
        request: HelloRequest,
83
        *,
84
        timeout: Optional[float] = None,
85
        deadline: Optional["Deadline"] = None,
86
        metadata: Optional[betterproto._MetadataLike] = None,
87
    ) -> HelloReply:
88
        return await self._unary_unary(
89
            "/helloworld.Greeter/SayHello",
90
            request,
91
            HelloReply,
92
            timeout=timeout,
93
            deadline=deadline,
94
            metadata=metadata,
95
        )
96

97
async def main():
98
    async with Channel("localhost", 50051) as channel:
99
        greeter = GreeterServiceStub(channel)
100
        reply = await greeter.say_hello(HelloRequest(name="World"))
101
        print(f"Greeting: {reply.message}")
102
```
103

104
## Architecture
105

106
BetterProto's architecture consists of several key components:
107

108
- **Message Base Class**: All generated messages inherit from `betterproto.Message` providing serialization, parsing, and JSON conversion
109
- **Field Metadata System**: `FieldMetadata` dataclass stores protobuf-specific information (field numbers, types, wire formats)
110
- **Code Generator Plugin**: `betterproto.plugin` generates Python dataclasses from `.proto` files
111
- **Wire Format Handling**: Built-in varint encoding/decoding and wire type management compatible with standard protobuf
112
- **gRPC Integration**: `ServiceStub` base class for async gRPC client generation with `grpclib` support
113

114
## Capabilities
115

116
### Message Definition and Field Types
117

118
Core message functionality including field creation functions for all protobuf types, dataclass integration, and metadata handling for proper serialization and deserialization.
119

120
```python { .api }
121
class Message:
122
    def __bytes__(self) -> bytes: ...
123
    def parse(self, data: bytes) -> T: ...
124
    def to_dict(self, casing: Casing = Casing.CAMEL, include_default_values: bool = False) -> dict: ...
125
    def from_dict(self, value: dict) -> T: ...
126
    def to_json(self, indent: Union[None, int, str] = None) -> str: ...
127
    def from_json(self, value: Union[str, bytes]) -> T: ...
128

129
def string_field(number: int, group: Optional[str] = None) -> Any: ...
130
def int32_field(number: int, group: Optional[str] = None) -> Any: ...
131
def int64_field(number: int, group: Optional[str] = None) -> Any: ...
132
def bool_field(number: int, group: Optional[str] = None) -> Any: ...
133
def bytes_field(number: int, group: Optional[str] = None) -> Any: ...
134
def message_field(number: int, group: Optional[str] = None, wraps: Optional[str] = None) -> Any: ...
135
```
136

137
[Message and Field Types](./message-fields.md)
138

139
### Enumerations
140

141
Protobuf enumeration support with integer-based enums that provide string name conversion and integration with the message system.
142

143
```python { .api }
144
class Enum(int, enum.Enum):
145
    @classmethod
146
    def from_string(cls, name: str) -> int: ...
147

148
def enum_field(number: int, group: Optional[str] = None) -> Any: ...
149
```
150

151
[Enumerations](./enumerations.md)
152

153
### gRPC Service Integration
154

155
Async gRPC client stub generation with support for unary and streaming calls, timeout handling, metadata, and deadline management using grpclib.
156

157
```python { .api }
158
class ServiceStub:
159
    def __init__(
160
        self,
161
        channel: Channel,
162
        *,
163
        timeout: Optional[float] = None,
164
        deadline: Optional[Deadline] = None,
165
        metadata: Optional[_MetadataLike] = None,
166
    ) -> None: ...
167
    
168
    async def _unary_unary(
169
        self,
170
        route: str,
171
        request: IProtoMessage,
172
        response_type: Type[T],
173
        *,
174
        timeout: Optional[float] = None,
175
        deadline: Optional[Deadline] = None,
176
        metadata: Optional[_MetadataLike] = None,
177
    ) -> T: ...
178
```
179

180
[gRPC Service Integration](./grpc-services.md)
181

182
### Code Generation
183

184
Protocol buffer compiler plugin that generates clean Python dataclasses from .proto files with proper type hints, async gRPC stubs, and modern Python conventions.
185

186
```python { .api }
187
def main() -> None: ...
188
def generate_code(request, response) -> None: ...
189
```
190

191
[Code Generation](./code-generation.md)
192

193
### Serialization and Wire Format
194

195
Low-level serialization utilities including varint encoding/decoding, wire type handling, and binary format parsing compatible with standard protobuf implementations.
196

197
```python { .api }
198
def encode_varint(value: int) -> bytes: ...
199
def decode_varint(buffer: bytes, pos: int, signed: bool = False) -> Tuple[int, int]: ...
200
def parse_fields(value: bytes) -> Generator[ParsedField, None, None]: ...
201
def serialized_on_wire(message: Message) -> bool: ...
202
```
203

204
[Serialization and Wire Format](./serialization.md)
205

206
### Utility Functions
207

208
Helper functions for message introspection, one-of field handling, and casing conversion to support generated code and user applications.
209

210
```python { .api }
211
def which_one_of(message: Message, group_name: str) -> Tuple[str, Any]: ...
212
def safe_snake_case(value: str) -> str: ...
213
```
214

215
[Utility Functions](./utilities.md)
216

217
## Types
218

219
```python { .api }
220
@dataclass(frozen=True)
221
class FieldMetadata:
222
    number: int
223
    proto_type: str
224
    map_types: Optional[Tuple[str, str]] = None
225
    group: Optional[str] = None
226
    wraps: Optional[str] = None
227

228
@dataclass(frozen=True)
229
class ParsedField:
230
    number: int
231
    wire_type: int
232
    value: Any
233
    raw: bytes
234

235
class Casing(enum.Enum):
236
    CAMEL: Callable
237
    SNAKE: Callable
238

239
# Type variables and aliases
240
T = TypeVar('T', bound='Message')  # Bound type variable for Message subclasses
241
_Value = Union[str, bytes]
242
_MetadataLike = Union[Mapping[str, _Value], Collection[Tuple[str, _Value]]]
243
```