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`