google.protobuf.message

Contains an abstract base class for protocol messages.

exception google.protobuf.message.DecodeError

Exception raised when deserializing messages.

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception google.protobuf.message.EncodeError

Exception raised when serializing messages.

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception google.protobuf.message.Error

Base error type for this module.

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

ByteSize()

Returns the serialized size of this message.

Recursively calls ByteSize() on all contained messages.

Returns

The number of bytes required to serialize this message.

Return type

int

Clear()

Clears all data that was set in the message.

ClearExtension(extension_handle)

Clears the contents of a given extension.

Parameters

extension_handle – The handle for the extension to clear.

ClearField(field_name)

Clears the contents of a given field.

Inside a oneof group, clears the field set. If the name neither refers to a defined field or oneof group, ValueError is raised.

Parameters

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

Raises

ValueError – if the field_name is not a member of this message.

CopyFrom(other_msg)

Copies the content of the specified message into the current message.

The method clears the current message and then merges the specified message using MergeFrom.

Parameters

other_msg (Message) – A message to copy into the current one.

DESCRIPTOR = None

The google.protobuf.descriptor.Descriptor for this message type.

DiscardUnknownFields()

Clears all fields in the UnknownFieldSet.

This operation is recursive for nested message.

HasExtension(extension_handle)

Checks if a certain extension is present for this message.

Extensions are retrieved using the Extensions mapping (if present).

Parameters

extension_handle – The handle for the extension to check.

Returns

Whether the extension is present for this message.

Return type

bool

Raises

KeyError – if the extension is repeated. Similar to repeated fields, there is no separate notion of presence: a “not present” repeated extension is an empty list.

HasField(field_name)

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters

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

Returns

Whether a value has been set for the named field.

Return type

bool

Raises

ValueError – if the field_name is not a member of this message.

IsInitialized()

Checks if the message is initialized.

Returns

The method returns True if the message is initialized (i.e. all of its required fields are set).

Return type

bool

ListFields()

Returns a list of (FieldDescriptor, value) tuples for present fields.

A message field is non-empty if HasField() would return true. A singular primitive field is non-empty if HasField() would return true in proto2 or it is non zero in proto3. A repeated field is non-empty if it contains at least one element. The fields are ordered by field number.

Returns

field descriptors and values for all fields in the message which are not empty. The values vary by field type.

Return type

list[tuple(FieldDescriptor, value)]

MergeFrom(other_msg)

Merges the contents of the specified message into current message.

This method merges the contents of the specified message into the current message. Singular fields that are set in the specified message overwrite the corresponding fields in the current message. Repeated fields are appended. Singular sub-messages and groups are recursively merged.

Parameters

other_msg (Message) – A message to merge into the current message.

MergeFromString(serialized)

Merges serialized protocol buffer data into this message.

When we find a field in serialized that is already present in this message:

• If it’s a “repeated” field, we append to the end of our list.

• Else, if it’s a scalar, we overwrite our field.

• Else, (it’s a nonrepeated composite), we recursively merge into the existing composite.

Parameters

serialized (bytes) – Any object that allows us to call memoryview(serialized) to access a string of bytes using the buffer interface.

Returns

The number of bytes read from serialized. For non-group messages, this will always be len(serialized), but for messages which are actually groups, this will generally be less than len(serialized), since we must stop when we reach an END_GROUP tag. Note that if we do stop because of an END_GROUP tag, the number of bytes returned does not include the bytes for the END_GROUP tag information.

Return type

int

Raises

DecodeError – if the input cannot be parsed.

ParseFromString(serialized)

Parse serialized protocol buffer data into this message.

Like MergeFromString(), except we clear the object first.

SerializePartialToString(**kwargs)

Serializes the protocol message to a binary string.

This method is similar to SerializeToString but doesn’t check if the message is initialized.

Keyword Arguments

deterministic (bool) – If true, requests deterministic serialization of the protobuf, with predictable ordering of map keys.

Returns

A serialized representation of the partial message.

Return type

bytes

SerializeToString(**kwargs)

Serializes the protocol message to a binary string.

Keyword Arguments

deterministic (bool) – If true, requests deterministic serialization of the protobuf, with predictable ordering of map keys.

Returns

A binary string representation of the message if all of the required fields in the message are set (i.e. the message is initialized).

Raises

EncodeError – if the message isn’t initialized (see IsInitialized()).

SetInParent()

Mark this as present in the parent.

This normally happens automatically when you assign a field of a sub-message, but sometimes you want to make the sub-message present while keeping it empty. If you find yourself using this, you may want to reconsider your design.

UnknownFields()

Returns the UnknownFieldSet.

Returns

The unknown fields stored in this message.

Return type

UnknownFieldSet

WhichOneof(oneof_group)

Returns the name of the field that is set inside a oneof group.

If no field is set, returns None.

Parameters

oneof_group (str) – the name of the oneof group to check.

Returns

The name of the group that is set, or None.

Return type

str or None

Raises

ValueError – no group with the given name exists