0
# Proto Plus
1
2
Beautiful, Pythonic protocol buffers that make protocol buffer message classes behave like native Python types. This library provides a wrapper around Google's protobuf library that makes working with protocol buffers more intuitive and idiomatic in Python, enabling seamless integration with Python's type system and standard library.
3
4
## Package Information
5
6
- **Package Name**: proto-plus
7
- **Language**: Python
8
- **Installation**: `pip install proto-plus`
9
10
## Core Imports
11
12
```python
13
import proto
14
```
15
16
For common usage patterns:
17
18
```python
19
from proto import Message, Field, Enum, RepeatedField, MapField
20
```
21
22
Type constants can be imported directly:
23
24
```python
25
from proto import STRING, INT32, BOOL, MESSAGE, ENUM
26
```
27
28
## Basic Usage
29
30
```python
31
import proto
32
33
# Define an enum
34
class Color(proto.Enum):
35
RED = 1
36
GREEN = 2
37
BLUE = 3
38
39
# Define a message
40
class Person(proto.Message):
41
name = proto.Field(proto.STRING, number=1)
42
age = proto.Field(proto.INT32, number=2)
43
email = proto.Field(proto.STRING, number=3, optional=True)
44
favorite_color = proto.Field(Color, number=4)
45
hobbies = proto.RepeatedField(proto.STRING, number=5)
46
47
# Create and use messages
48
person = Person(
49
name="Alice",
50
age=30,
51
email="alice@example.com",
52
favorite_color=Color.BLUE,
53
hobbies=["reading", "hiking"]
54
)
55
56
# Access fields like native Python attributes
57
print(person.name) # "Alice"
58
print(person.age) # 30
59
60
# Convert to/from JSON
61
json_str = Person.to_json(person)
62
person_from_json = Person.from_json(json_str)
63
64
# Convert to/from dict
65
person_dict = Person.to_dict(person)
66
person_from_dict = Person(person_dict)
67
68
# Serialize/deserialize
69
serialized = Person.serialize(person)
70
deserialized = Person.deserialize(serialized)
71
```
72
73
## Architecture
74
75
Proto-plus uses Python metaclasses to automatically generate protocol buffer descriptors and create seamless integration between protobuf messages and Python objects:
76
77
- **Message metaclass**: Automatically generates protobuf descriptors and provides Pythonic behavior
78
- **Field system**: Defines message structure with automatic type conversion and validation
79
- **Marshal system**: Handles conversion between protobuf and Python native types
80
- **Module system**: Manages package organization and protocol buffer file generation
81
82
This design enables protocol buffer messages to behave like native Python classes while maintaining full compatibility with the underlying protobuf library and wire format.
83
84
## Capabilities
85
86
### Message Definition and Usage
87
88
Core functionality for defining protocol buffer messages that behave like Python classes, with automatic serialization, deserialization, and type conversion.
89
90
```python { .api }
91
class Message(metaclass=MessageMeta):
92
def __init__(self, mapping=None, *, ignore_unknown_fields=False, **kwargs): ...
93
94
@classmethod
95
def pb(cls, obj=None, *, coerce: bool = False): ...
96
97
@classmethod
98
def wrap(cls, pb): ...
99
100
@classmethod
101
def serialize(cls, instance) -> bytes: ...
102
103
@classmethod
104
def deserialize(cls, payload: bytes) -> "Message": ...
105
106
@classmethod
107
def to_json(cls, instance, **kwargs) -> str: ...
108
109
@classmethod
110
def from_json(cls, payload, *, ignore_unknown_fields=False) -> "Message": ...
111
112
@classmethod
113
def to_dict(cls, instance, **kwargs) -> dict: ...
114
115
@classmethod
116
def copy_from(cls, instance, other): ...
117
```
118
119
[Message System](./message-system.md)
120
121
### Field Definition
122
123
Field types for defining message structure, supporting all protocol buffer field types including primitives, messages, enums, repeated fields, and maps.
124
125
```python { .api }
126
class Field:
127
def __init__(self, proto_type, *, number: int, message=None, enum=None,
128
oneof: str = None, json_name: str = None, optional: bool = False): ...
129
130
class RepeatedField(Field): ...
131
132
class MapField(Field):
133
def __init__(self, key_type, value_type, *, number: int, message=None, enum=None): ...
134
```
135
136
[Field System](./field-system.md)
137
138
### Enum Definition
139
140
Protocol buffer enums that behave like Python enums with integer compatibility and full comparison support.
141
142
```python { .api }
143
class Enum(enum.IntEnum, metaclass=ProtoEnumMeta): ...
144
```
145
146
[Enum System](./enum-system.md)
147
148
### Type Marshaling
149
150
Advanced type conversion system for seamless integration between protocol buffers and Python native types, including support for well-known types.
151
152
```python { .api }
153
class Marshal:
154
def __init__(self, *, name: str): ...
155
def register(self, proto_type: type, rule: Rule = None): ...
156
def to_python(self, proto_type, value, *, absent: bool = None): ...
157
def to_proto(self, proto_type, value, *, strict: bool = False): ...
158
def reset(self): ...
159
```
160
161
[Marshal System](./marshal-system.md)
162
163
### Module Organization
164
165
Package and module management utilities for organizing protocol buffer definitions across multiple files and packages.
166
167
```python { .api }
168
def define_module(*, package: str, marshal: str = None,
169
manifest: Set[str] = frozenset()) -> _ProtoModule: ...
170
```
171
172
[Module System](./module-system.md)
173
174
## Protocol Buffer Types
175
176
```python { .api }
177
class ProtoType(enum.IntEnum):
178
DOUBLE = 1
179
FLOAT = 2
180
INT64 = 3
181
UINT64 = 4
182
INT32 = 5
183
FIXED64 = 6
184
FIXED32 = 7
185
BOOL = 8
186
STRING = 9
187
MESSAGE = 11
188
BYTES = 12
189
UINT32 = 13
190
ENUM = 14
191
SFIXED32 = 15
192
SFIXED64 = 16
193
SINT32 = 17
194
SINT64 = 18
195
```
196
197
All ProtoType values are available as module-level constants:
198
`DOUBLE`, `FLOAT`, `INT64`, `UINT64`, `INT32`, `FIXED64`, `FIXED32`, `BOOL`, `STRING`, `MESSAGE`, `BYTES`, `UINT32`, `ENUM`, `SFIXED32`, `SFIXED64`, `SINT32`, `SINT64`