Message and Field

class proto.message.Message(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

The abstract base class for a message.

Parameters:
  • mapping (Union[dict, Message]) – A dictionary or message to be used to determine the values for this message.

  • ignore_unknown_fields (Optional(bool)) – If True, do not raise errors for unknown fields. Only applied if mapping is a mapping type or there are keyword parameters.

  • kwargs (dict) – Keys and values corresponding to the fields of the message.

classmethod pb(obj=None, *, coerce: bool = False)

Return the underlying protobuf Message class or instance.

Parameters:
  • obj – If provided, and an instance of cls, return the underlying protobuf instance.

  • coerce (bool) – If provided, will attempt to coerce obj to cls if it is not already an instance.

classmethod wrap(pb)

Return a Message object that shallowly wraps the descriptor.

Parameters:

pb – A protocol buffer object, such as would be returned by pb().

classmethod serialize(instance) bytes

Return the serialized proto.

Parameters:

instance – An instance of this message type, or something compatible (accepted by the type’s constructor).

Returns:

The serialized representation of the protocol buffer.

Return type:

bytes

classmethod deserialize(payload: bytes) Message

Given a serialized proto, deserialize it into a Message instance.

Parameters:

payload (bytes) – The serialized proto.

Returns:

An instance of the message class against which this method was called.

Return type:

Message

classmethod to_json(instance, *, use_integers_for_enums=True, including_default_value_fields=None, preserving_proto_field_name=False, sort_keys=False, indent=2, float_precision=None, always_print_fields_with_no_presence=None) str

Given a message instance, serialize it to json

Parameters:
  • instance – An instance of this message type, or something compatible (accepted by the type’s constructor).

  • use_integers_for_enums (Optional(bool)) – An option that determines whether enum values should be represented by strings (False) or integers (True). Default is True.

  • including_default_value_fields (Optional(bool)) – Deprecated. Use argument always_print_fields_with_no_presence instead. An option that determines whether the default field values should be included in the results. This value must match always_print_fields_with_no_presence, if both arguments are explicitly set.

  • preserving_proto_field_name (Optional(bool)) – An option that determines whether field name representations preserve proto case (snake_case) or use lowerCamelCase. Default is False.

  • sort_keys (Optional(bool)) – If True, then the output will be sorted by field names. Default is False.

  • indent (Optional(int)) – The JSON object will be pretty-printed with this indent level. An indent level of 0 or negative will only insert newlines. Pass None for the most compact representation without newlines.

  • float_precision (Optional(int)) – If set, use this to specify float field valid digits. Default is None.

  • always_print_fields_with_no_presence (Optional(bool)) – If True, fields without presence (implicit presence scalars, repeated fields, and map fields) will always be serialized. Any field that supports presence is not affected by this option (including singular message fields and oneof fields). This value must match including_default_value_fields, if both arguments are explicitly set.

Returns:

The json string representation of the protocol buffer.

Return type:

str

classmethod from_json(payload, *, ignore_unknown_fields=False) Message

Given a json string representing an instance, parse it into a message.

Parameters:
  • payload – A json string representing a message.

  • ignore_unknown_fields (Optional(bool)) – If True, do not raise errors for unknown fields.

Returns:

An instance of the message class against which this method was called.

Return type:

Message

classmethod to_dict(instance, *, use_integers_for_enums=True, preserving_proto_field_name=True, including_default_value_fields=None, float_precision=None, always_print_fields_with_no_presence=None) Dict[str, Any]

Given a message instance, return its representation as a python dict.

Parameters:
  • instance – An instance of this message type, or something compatible (accepted by the type’s constructor).

  • use_integers_for_enums (Optional(bool)) – An option that determines whether enum values should be represented by strings (False) or integers (True). Default is True.

  • preserving_proto_field_name (Optional(bool)) – An option that determines whether field name representations preserve proto case (snake_case) or use lowerCamelCase. Default is True.

  • including_default_value_fields (Optional(bool)) – Deprecated. Use argument always_print_fields_with_no_presence instead. An option that determines whether the default field values should be included in the results. This value must match always_print_fields_with_no_presence, if both arguments are explicitly set.

  • float_precision (Optional(int)) – If set, use this to specify float field valid digits. Default is None.

  • always_print_fields_with_no_presence (Optional(bool)) – If True, fields without presence (implicit presence scalars, repeated fields, and map fields) will always be serialized. Any field that supports presence is not affected by this option (including singular message fields and oneof fields). This value must match including_default_value_fields, if both arguments are explicitly set.

Returns:

A representation of the protocol buffer using pythonic data structures.

Messages and map fields are represented as dicts, repeated fields are represented as lists.

Return type:

dict

classmethod copy_from(instance, other)

Equivalent for protobuf.Message.CopyFrom

Parameters:
  • instance – An instance of this message type

  • other – (Union[dict, ~.Message): A dictionary or message to reinitialize the values for this message.

class proto.fields.Field(proto_type, *, number: int, message=None, enum=None, oneof: str = None, json_name: str = None, optional: bool = False)[source]

A representation of a type of field in protocol buffers.

property descriptor

Return the descriptor for the field.

property name: str

Return the name of the field.

property package: str

Return the package of the field.

property pb_type

Return the composite type of the field, or the primitive type if a primitive.

class proto.fields.MapField(key_type, value_type, *, number: int, message=None, enum=None)[source]

A representation of a map field in protocol buffers.

class proto.fields.RepeatedField(proto_type, *, number: int, message=None, enum=None, oneof: str = None, json_name: str = None, optional: bool = False)[source]

A representation of a repeated field in protocol buffers.

class proto.enums.Enum(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

A enum object that also builds a protobuf enum descriptor.

class proto.enums.ProtoEnumMeta(name, bases, attrs)[source]

A metaclass for building and registering protobuf enums.