API reference
The following document outlines betterproto's api. These classes should not be extended manually.
Message
Bases: ABC
The base class for protobuf messages, all generated messages will inherit from it. 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.
FromString(data)
classmethod
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 :meth:parse.
Parameters
data: :class:bytes
The data to parse the protobuf from.
Returns
:class:Message
The initialized message.
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
:class:bytes
The binary encoded Protobuf representation of this message instance
__bool__()
True if the message has any fields with non-default values.
__bytes__()
Get the binary encoded Protobuf representation of this message instance.
dump(stream, delimit=False)
Dumps the binary encoded Protobuf message to the stream.
Parameters
stream: :class:BinaryIO
The stream to dump the message to.
delimit:
Whether to prefix the message with a varint declaring its size.
TODO is it actually needed?
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[:class:str, Any]
The dictionary to parse from.
Returns
:class:Message
The initialized message.
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[:class:str, :class:bytes]
The value to pass to :func:json.loads.
Returns
:class:Message
The initialized message.
from_pydict(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[:class:str, Any]
The dictionary to parse from.
Returns
:class:Message
The initialized message.
is_set(name)
Check if field with the given name has been set.
Parameters
name: :class:str
The name of the field to check for.
Returns
:class:bool
True if field has been set, otherwise False.
load(stream, size=None)
Load the binary encoded Protobuf from a stream into this message instance. This returns the instance itself and is therefore assignable and chainable.
Parameters
stream: :class:bytes
The stream to load the message from.
size: :class:Optional[int]
The size of the message in the stream.
Reads stream until EOF if None is given.
Reads based on a size delimiter prefix varint if SIZE_DELIMITED is given.
Returns
:class:Message
The initialized message.
parse(data)
Parse the binary encoded Protobuf into this message instance. This returns the instance itself and is therefore assignable and chainable.
Parameters
data: :class:bytes
The data to parse the message from.
Returns
:class:Message
The initialized message.
to_dict(*, output_format=OutputFormat.PROTO_JSON, casing=Casing.CAMEL, include_default_values=False)
Return a dict representation of the message.
Parameters
casing: :class:Casing
The casing to use for key values. Default is :attr:Casing.CAMEL for
compatibility purposes.
include_default_values: :class: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
Dict[:class:str, Any]
The JSON serializable dict representation of this object.
to_json(indent=None, include_default_values=False, casing=Casing.CAMEL)
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[:class:int, :class:str]]
The indent to pass to :func:json.dumps.
:class: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.
:class:Casing
The casing to use for key values. Default is :attr:Casing.CAMEL for
compatibility purposes.
Returns
:class:str
The JSON representation of the message.
Return the name and value of a message's one-of field group.
Returns
Tuple[:class:str, Any]
The field name and the value for that field.
Enumerations
Bases: IntEnum
from_string(name)
classmethod
Return the value which corresponds to the string name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The name of the enum member to get. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
The member was not found in the Enum. |
Returns:
| Type | Description |
|---|---|
Self
|
The corresponding value |