pure-protobuf 0.5.0

Python implementation of Protocol Buffers data types

pure-protobuf

Python implementation of Protocol Buffers data types.

Usage

Assume you have the following definition:

message Test2 {
  string b = 2;
}

This is how you can create a message and get it serialized:

from __future__ import print_function

from io import BytesIO

from pure_protobuf import MessageType, Unicode

# Create the type instance and add the field.
type_ = MessageType()
type_.add_field(2, 'b', Unicode)

message = type_()
message.b = 'testing'

# Dump into a string.
print(message.dumps())

# Dump into a file-like object.
fp = BytesIO()
message.dump(fp)

# Load from a string.
assert type_.loads(message.dumps()) == message

# Load from a file-like object.
fp.seek(0)
assert type_.load(fp) == message

Sample 2. Required field

To add a missing field you should pass an additional flags parameter to add_field like this:

from pure_protobuf.protobuf import Flags, MessageType, Unicode

type_ = MessageType()
type_.add_field(2, 'b', Unicode, flags=Flags.REQUIRED)

message = type_()
message.b = 'hello, world'

assert type_.dumps(message)

If you'll not fill in a required field, then ValueError will be raised during serialization.

Sample 3. Repeated field

from pure_protobuf.protobuf import Flags, MessageType, UVarint

type_ = MessageType()
type_.add_field(1, 'b', UVarint, flags=Flags.REPEATED)

message = type_()
message.b = (1, 2, 3)

assert type_.dumps(message)

Value of a repeated field can be any iterable object. The loaded value will always be list.

Sample 4. Packed repeated field

from pure_protobuf.protobuf import Flags, MessageType, UVarint

type_ = MessageType()
type_.add_field(4, 'd', UVarint, flags=Flags.PACKED_REPEATED)

message = type_()
message.d = (3, 270, 86942)

assert type_.dumps(message)

Sample 5. Embedded messages

message Test1 {
  int32 a = 1;
}

message Test3 {
  required Test1 c = 3;
}

To create an embedded field, wrap inner type with EmbeddedMessage:

from pure_protobuf import EmbeddedMessage, MessageType, UVarint

inner_type = MessageType()
inner_type.add_field(1, 'a', UVarint)
outer_type = MessageType()
outer_type.add_field(3, 'c', EmbeddedMessage(inner_type))

message = outer_type()
message.c = inner_type()
message.c.a = 150

assert outer_type.dumps(message)

Data types

Type	Python	Description
UVarint	int	unsigned integer (variable length)
Varint	int	signed integer (variable length)
Bool	bool	boolean
Fixed64	bytes	8-byte string
UInt64	int	C 64-bit unsigned long long
Int64	int	C 64-bit long long
Float64	float	C double
Fixed32	bytes	4-byte string
UInt32	int	C 32-bit unsigned int
Int32	int	C 32-bit int
Float32	float	C float
Bytes	bytes	byte string
Unicode	str	unicode string

Some techniques

Streaming messages

The Protocol Buffers format is not self-delimiting. But you can wrap your message type with EmbeddedMessage and write or read messages sequentially.

add_field chaining

add_field return the message type itself, thus you can do so:

from pure_protobuf import EmbeddedMessage, MessageType, UVarint

MessageType().add_field(1, 'a', EmbeddedMessage(MessageType().add_field(1, 'a', UVarint)))