API reference

The following document outlines betterproto’s api. None of these classes should be extended by the user manually.

Message

class betterproto.Message

The base class for protobuf messages, all generated messages will inherit from this. This class registers the message fields which are used by the serializers and parsers to go between the Python, binary and JSON representations of the message.

bytes(x)

Calls __bytes__().

bool(x)

Calls __bool__().

__bool__()

True if the Message has any fields with non-default values.

__bytes__()

Get the binary encoded Protobuf representation of this message instance.

SerializeToString()

Get the binary encoded Protobuf representation of this message instance.

Note

This is a method for compatibility with other libraries, you should really use bytes(x).

Returns

The binary encoded Protobuf representation of this message instance

Return type

bytes

parse(data)

Parse the binary encoded Protobuf into this message instance. This returns the instance itself and is therefore assignable and chainable.

Parameters

data (bytes) – The data to parse the protobuf from.

Returns

The initialized message.

Return type

Message

classmethod FromString(data)

Parse the binary encoded Protobuf into this message instance. This returns the instance itself and is therefore assignable and chainable.

Note

This is a method for compatibility with other libraries, you should really use parse().

Parameters

data (bytes) – The data to parse the protobuf from.

Returns

The initialized message.

Return type

Message

to_dict(casing=<function camel_case>, include_default_values=False)

Returns a JSON serializable dict representation of this object.

Parameters

• casing (Casing) – The casing to use for key values. Default is Casing.CAMEL for compatibility purposes.

• include_default_values (bool) – If True will include the default values of fields. Default is False. E.g. an int32 field will be included with a value of 0 if this is set to True, otherwise this would be ignored.

Returns

The JSON serializable dict representation of this object.

Return type

Dict[str, Any]

from_dict(value)

Parse the key/value pairs into the current message instance. This returns the instance itself and is therefore assignable and chainable.

Parameters

value (Dict[str, Any]) – The dictionary to parse from.

Returns

The initialized message.

Return type

Message

to_json(indent=None)

A helper function to parse the message instance into its JSON representation.

This is equivalent to:

json.dumps(message.to_dict(), indent=indent)

Parameters

indent (Optional[Union[int, str]]) – The indent to pass to json.dumps().

Returns

The JSON representation of the message.

Return type

str

from_json(value)

A helper function to return the message instance from its JSON representation. This returns the instance itself and is therefore assignable and chainable.

This is equivalent to:

return message.from_dict(json.loads(value))

Parameters

value (Union[str, bytes]) – The value to pass to json.loads().

Returns

The initialized message.

Return type

Message

is_set(name)

Check if field with the given name has been set.

Parameters

name (str) – The name of the field to check for.

Returns

True if field has been set, otherwise False.

Return type

bool

betterproto.serialized_on_wire(message)

If this message was or should be serialized on the wire. This can be used to detect presence (e.g. optional wrapper message) and is used internally during parsing/serialization.

Returns

Whether this message was or should be serialized on the wire.

Return type

bool

betterproto.which_one_of(message, group_name)

Return the name and value of a message’s one-of field group.

Returns

The field name and the value for that field.

Return type

Tuple[str, Any]

Enumerations

class betterproto.Enum

The base class for protobuf enumerations, all generated enumerations will inherit from this. Bases enum.IntEnum.

classmethod from_string(name)

Return the value which corresponds to the string name.

Parameters

name (str) – The name of the enum member to get

Raises

ValueError – The member was not found in the Enum.

class betterproto.Casing

Casing constants for serialization.

CAMEL(strict=True)

A camelCase sterilization function.

SNAKE(strict=True)

A snake_case sterilization function.