Warning

You are reading the documentation for the latest committed changes of the Protocol Buffers package for Python. Some features may not yet be released. Read the documentation for the latest released package at googleapis.dev.

google.protobuf.text_format

Contains routines for printing protocol messages in text format.

Simple usage example:

# Create a proto object and serialize it to a text proto string.
message = my_proto_pb2.MyMessage(foo='bar')
text_proto = text_format.MessageToString(message)

# Parse a text proto string.
message = text_format.Parse(text_proto, my_proto_pb2.MyMessage())
google.protobuf.text_format.MessageToString(message, as_utf8=False, as_one_line=False, use_short_repeated_primitives=False, pointy_brackets=False, use_index_order=False, float_format=None, double_format=None, use_field_number=False, descriptor_pool=None, indent=0, message_formatter=None, print_unknown_fields=False)

Convert protobuf message to text format.

Double values can be formatted compactly with 15 digits of precision (which is the most that IEEE 754 “double” can guarantee) using double_format=’.15g’. To ensure that converting to text and back to a proto will result in an identical value, double_format=’.17g’ should be used.

Parameters

  • message – The protocol buffers message.

  • as_utf8 – Return unescaped Unicode for non-ASCII characters. In Python 3 actual Unicode characters may appear as is in strings. In Python 2 the return value will be valid UTF-8 rather than only ASCII.

  • as_one_line – Don’t introduce newlines between fields.

  • use_short_repeated_primitives – Use short repeated format for primitives.

  • pointy_brackets – If True, use angle brackets instead of curly braces for nesting.

  • use_index_order – If True, fields of a proto message will be printed using the order defined in source code instead of the field number, extensions will be printed at the end of the message and their relative order is determined by the extension number. By default, use the field number order.

  • float_format (str) – If set, use this to specify float field formatting (per the “Format Specification Mini-Language”); otherwise, 8 valid digits is used (default ‘.8g’). Also affect double field if double_format is not set but float_format is set.

  • double_format (str) – If set, use this to specify double field formatting (per the “Format Specification Mini-Language”); if it is not set but float_format is set, use float_format. Otherwise, use str()

  • use_field_number – If True, print field numbers instead of names.

  • descriptor_pool (DescriptorPool) – Descriptor pool used to resolve Any types.

  • indent (int) – The initial indent level, in terms of spaces, for pretty print.

  • message_formatter (function(message, indent, as_one_line) -> unicode|None) – Custom formatter for selected sub-messages (usually based on message type). Use to pretty print parts of the protobuf for easier diffing.

  • print_unknown_fields – If True, unknown fields will be printed.

Returns

A string of the text formatted protocol buffer message.

Return type

str

google.protobuf.text_format.Parse(text, message, allow_unknown_extension=False, allow_field_number=False, descriptor_pool=None, allow_unknown_field=False)

Parses a text representation of a protocol message into a message.

NOTE: for historical reasons this function does not clear the input message. This is different from what the binary msg.ParseFrom(…) does. If text contains a field already set in message, the value is appended if the field is repeated. Otherwise, an error is raised.

Example:

a = MyProto()
a.repeated_field.append('test')
b = MyProto()

# Repeated fields are combined
text_format.Parse(repr(a), b)
text_format.Parse(repr(a), b) # repeated_field contains ["test", "test"]

# Non-repeated fields cannot be overwritten
a.singular_field = 1
b.singular_field = 2
text_format.Parse(repr(a), b) # ParseError

# Binary version:
b.ParseFromString(a.SerializeToString()) # repeated_field is now "test"

Caller is responsible for clearing the message as needed.

Parameters

  • text (str) – Message text representation.

  • message (Message) – A protocol buffer message to merge into.

  • allow_unknown_extension – if True, skip over missing extensions and keep parsing

  • allow_field_number – if True, both field number and field name are allowed.

  • descriptor_pool (DescriptorPool) – Descriptor pool used to resolve Any types.

  • allow_unknown_field – if True, skip over unknown field and keep parsing. Avoid to use this option if possible. It may hide some errors (e.g. spelling error on field name)

Returns

The same message passed as argument.

Return type

Message

Raises

ParseError – On text parsing problems.

google.protobuf.text_format.PrintMessage(message, out, indent=0, as_utf8=False, as_one_line=False, use_short_repeated_primitives=False, pointy_brackets=False, use_index_order=False, float_format=None, double_format=None, use_field_number=False, descriptor_pool=None, message_formatter=None, print_unknown_fields=False)
google.protobuf.text_format.PrintField(field, value, out, indent=0, as_utf8=False, as_one_line=False, use_short_repeated_primitives=False, pointy_brackets=False, use_index_order=False, float_format=None, double_format=None, message_formatter=None, print_unknown_fields=False)

Print a single field name/value pair.

google.protobuf.text_format.PrintFieldValue(field, value, out, indent=0, as_utf8=False, as_one_line=False, use_short_repeated_primitives=False, pointy_brackets=False, use_index_order=False, float_format=None, double_format=None, message_formatter=None, print_unknown_fields=False)

Print a single field value (not including name).

google.protobuf.text_format.Merge(text, message, allow_unknown_extension=False, allow_field_number=False, descriptor_pool=None, allow_unknown_field=False)

Parses a text representation of a protocol message into a message.

Like Parse(), but allows repeated values for a non-repeated field, and uses the last one. This means any non-repeated, top-level fields specified in text replace those in the message.

Parameters

  • text (str) – Message text representation.

  • message (Message) – A protocol buffer message to merge into.

  • allow_unknown_extension – if True, skip over missing extensions and keep parsing

  • allow_field_number – if True, both field number and field name are allowed.

  • descriptor_pool (DescriptorPool) – Descriptor pool used to resolve Any types.

  • allow_unknown_field – if True, skip over unknown field and keep parsing. Avoid to use this option if possible. It may hide some errors (e.g. spelling error on field name)

Returns

The same message passed as argument.

Return type

Message

Raises

ParseError – On text parsing problems.

google.protobuf.text_format.MessageToBytes(message, **kwargs)

Convert protobuf message to encoded text format. See MessageToString.