Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# Protocol Buffers - Google's data interchange format
2# Copyright 2008 Google Inc. All rights reserved.
3#
4# Use of this source code is governed by a BSD-style
5# license that can be found in the LICENSE file or at
6# https://developers.google.com/open-source/licenses/bsd
8# TODO: We should just make these methods all "pure-virtual" and move
9# all implementation out, into reflection.py for now.
10"""Contains an abstract base class for protocol messages."""
12__author__ = 'robinson@google.com (Will Robinson)'
14_INCONSISTENT_MESSAGE_ATTRIBUTES = ('Extensions',)
17class Error(Exception):
18 """Base error type for this module."""
20 pass
23class DecodeError(Error):
24 """Exception raised when deserializing messages."""
26 pass
29class EncodeError(Error):
30 """Exception raised when serializing messages."""
32 pass
35class FrozenInstanceError(AttributeError):
36 """Exception raised when mutating a frozen message."""
38 pass
41class Message(object):
42 """Abstract base class for protocol messages.
44 Protocol message classes are almost always generated by the protocol
45 compiler. These generated types subclass Message and implement the methods
46 shown below.
47 """
49 # TODO: Link to an HTML document here.
51 # TODO: Document that instances of this class will also
52 # have an Extensions attribute with __getitem__ and __setitem__.
53 # Again, not sure how to best convey this.
55 # TODO: Document these fields and methods.
57 __slots__ = []
59 #: The :class:`google.protobuf.Descriptor`
60 # for this message type.
61 DESCRIPTOR = None
63 def __deepcopy__(self, memo=None):
64 clone = type(self)()
65 clone.MergeFrom(self)
66 return clone
68 def __dir__(self):
69 """Provides the list of all accessible Message attributes."""
70 message_attributes = set(super().__dir__())
72 # TODO: Remove this once the UPB implementation is improved.
73 # The UPB proto implementation currently doesn't provide proto fields as
74 # attributes and they have to added.
75 if self.DESCRIPTOR is not None:
76 for field in self.DESCRIPTOR.fields:
77 message_attributes.add(field.name)
79 # The Fast C++ proto implementation provides inaccessible attributes that
80 # have to be removed.
81 for attribute in _INCONSISTENT_MESSAGE_ATTRIBUTES:
82 if attribute not in message_attributes:
83 continue
84 try:
85 getattr(self, attribute)
86 except AttributeError:
87 message_attributes.remove(attribute)
89 return sorted(message_attributes)
91 def __eq__(self, other_msg):
92 """Recursively compares two messages by value and structure."""
93 raise NotImplementedError
95 def __ne__(self, other_msg):
96 # Can't just say self != other_msg, since that would infinitely recurse. :)
97 return not self == other_msg
99 def __hash__(self):
100 raise TypeError('unhashable object')
102 def __str__(self):
103 """Outputs a human-readable representation of the message."""
104 raise NotImplementedError
106 def __unicode__(self):
107 """Outputs a human-readable representation of the message."""
108 raise NotImplementedError
110 def __contains__(self, field_name_or_key):
111 """Checks if a certain field is set for the message.
113 Has presence fields return true if the field is set, false if the field is
114 not set. Fields without presence do raise `ValueError` (this includes
115 repeated fields, map fields, and implicit presence fields).
117 If field_name is not defined in the message descriptor, `ValueError` will
118 be raised.
119 Note: WKT Struct checks if the key is contained in fields. ListValue checks
120 if the item is contained in the list.
122 Args:
123 field_name_or_key: For Struct, the key (str) of the fields map. For
124 ListValue, any type that may be contained in the list. For other
125 messages, name of the field (str) to check for presence.
127 Returns:
128 bool: For Struct, whether the item is contained in fields. For ListValue,
129 whether the item is contained in the list. For other message,
130 whether a value has been set for the named field.
132 Raises:
133 ValueError: For normal messages, if the `field_name_or_key` is not a
134 member of this message or `field_name_or_key` is not a string.
135 """
136 raise NotImplementedError
138 def MergeFrom(self, other_msg):
139 """Merges the contents of the specified message into current message.
141 This method merges the contents of the specified message into the current
142 message. Singular fields that are set in the specified message overwrite
143 the corresponding fields in the current message. Repeated fields are
144 appended. Singular sub-messages and groups are recursively merged.
146 Args:
147 other_msg (Message): A message to merge into the current message.
148 """
149 raise NotImplementedError
151 def CopyFrom(self, other_msg):
152 """Copies the content of the specified message into the current message.
154 The method clears the current message and then merges the specified
155 message using MergeFrom.
157 Args:
158 other_msg (Message): A message to copy into the current one.
159 """
160 if self is other_msg:
161 return
162 self.Clear()
163 self.MergeFrom(other_msg)
165 def Clear(self):
166 """Clears all data that was set in the message."""
167 raise NotImplementedError
169 def SetInParent(self):
170 """Mark this as present in the parent.
172 This normally happens automatically when you assign a field of a
173 sub-message, but sometimes you want to make the sub-message
174 present while keeping it empty. If you find yourself using this,
175 you may want to reconsider your design.
176 """
177 raise NotImplementedError
179 def IsInitialized(self):
180 """Checks if the message is initialized.
182 Returns:
183 bool: The method returns True if the message is initialized (i.e. all of
184 its required fields are set).
185 """
186 raise NotImplementedError
188 # TODO: MergeFromString() should probably return None and be
189 # implemented in terms of a helper that returns the # of bytes read. Our
190 # deserialization routines would use the helper when recursively
191 # deserializing, but the end user would almost always just want the no-return
192 # MergeFromString().
194 def MergeFromString(self, serialized):
195 """Merges serialized protocol buffer data into this message.
197 When we find a field in `serialized` that is already present
198 in this message:
200 - If it's a "repeated" field, we append to the end of our list.
201 - Else, if it's a scalar, we overwrite our field.
202 - Else, (it's a nonrepeated composite), we recursively merge
203 into the existing composite.
205 Args:
206 serialized (bytes): Any object that allows us to call
207 ``memoryview(serialized)`` to access a string of bytes using the buffer
208 interface.
210 Returns:
211 int: The number of bytes read from `serialized`.
212 For non-group messages, this will always be `len(serialized)`,
213 but for messages which are actually groups, this will
214 generally be less than `len(serialized)`, since we must
215 stop when we reach an ``END_GROUP`` tag. Note that if
216 we *do* stop because of an ``END_GROUP`` tag, the number
217 of bytes returned does not include the bytes
218 for the ``END_GROUP`` tag information.
220 Raises:
221 DecodeError: if the input cannot be parsed.
222 """
223 # TODO: Document handling of unknown fields.
224 # TODO: When we switch to a helper, this will return None.
225 raise NotImplementedError
227 def ParseFromString(self, serialized):
228 """Parse serialized protocol buffer data in binary form into this message.
230 Like :func:`MergeFromString()`, except we clear the object first.
232 Raises:
233 message.DecodeError if the input cannot be parsed.
234 """
235 self.Clear()
236 return self.MergeFromString(serialized)
238 def SerializeToString(self, **kwargs):
239 """Serializes the protocol message to a binary string.
241 Keyword Args:
242 deterministic (bool): If true, requests deterministic serialization
243 of the protobuf. Note that there is no canonical representation of
244 protobuf messages: deterministic serialization only means 'consistent
245 for current build, but not stable between rebuilds, and may not match
246 decisions made by other languages'.
247 See
248 https://protobuf.dev/programming-guides/serialization-not-canonical/.
250 Returns:
251 A binary string representation of the message if all of the required
252 fields in the message are set (i.e. the message is initialized).
254 Raises:
255 EncodeError: if the message isn't initialized (see :func:`IsInitialized`).
256 """
257 raise NotImplementedError
259 def SerializePartialToString(self, **kwargs):
260 """Serializes the protocol message to a binary string.
262 This method is similar to SerializeToString but doesn't check if the
263 message is initialized.
265 Keyword Args:
266 deterministic (bool): If true, requests deterministic serialization
267 of the protobuf. Note that 'deterministic' serialization only means
268 'Consistent for current build, but still arbitary and not stable over
269 time'. There is no canonical representation of protobuf messages,
270 See
271 https://protobuf.dev/programming-guides/serialization-not-canonical/.
273 Returns:
274 bytes: A serialized representation of the partial message.
275 """
276 raise NotImplementedError
278 # TODO: Decide whether we like these better
279 # than auto-generated has_foo() and clear_foo() methods
280 # on the instances themselves. This way is less consistent
281 # with C++, but it makes reflection-type access easier and
282 # reduces the number of magically autogenerated things.
283 #
284 # TODO: Be sure to document (and test) exactly
285 # which field names are accepted here. Are we case-sensitive?
286 # What do we do with fields that share names with Python keywords
287 # like 'lambda' and 'yield'?
288 #
289 # nnorwitz says:
290 # """
291 # Typically (in python), an underscore is appended to names that are
292 # keywords. So they would become lambda_ or yield_.
293 # """
294 def ListFields(self):
295 """Returns a list of (FieldDescriptor, value) tuples for present fields.
297 A message field is non-empty if HasField() would return true. A singular
298 primitive field is non-empty if HasField() would return true in proto2 or it
299 is non zero in proto3. A repeated field is non-empty if it contains at least
300 one element. The fields are ordered by field number.
302 Returns:
303 list[tuple(FieldDescriptor, value)]: field descriptors and values
304 for all fields in the message which are not empty. The values vary by
305 field type.
306 """
307 raise NotImplementedError
309 def HasField(self, field_name):
310 """Checks if a certain field is set for the message.
312 For a oneof group, checks if any field inside is set. Note that if the
313 field_name is not defined in the message descriptor, :exc:`ValueError` will
314 be raised.
316 Args:
317 field_name (str): The name of the field to check for presence.
319 Returns:
320 bool: Whether a value has been set for the named field.
322 Raises:
323 ValueError: if the `field_name` is not a member of this message.
324 """
325 raise NotImplementedError
327 def ClearField(self, field_name):
328 """Clears the contents of a given field.
330 Inside a oneof group, clears the field set. If the name neither refers to a
331 defined field or oneof group, :exc:`ValueError` is raised.
333 Args:
334 field_name (str): The name of the field to check for presence.
336 Raises:
337 ValueError: if the `field_name` is not a member of this message.
338 """
339 raise NotImplementedError
341 def WhichOneof(self, oneof_group):
342 """Returns the name of the field that is set inside a oneof group.
344 If no field is set, returns None.
346 Args:
347 oneof_group (str): the name of the oneof group to check.
349 Returns:
350 str or None: The name of the group that is set, or None.
352 Raises:
353 ValueError: no group with the given name exists
354 """
355 raise NotImplementedError
357 def HasExtension(self, field_descriptor):
358 """Checks if a certain extension is present for this message.
360 Extensions are retrieved using the :attr:`Extensions` mapping (if present).
362 Args:
363 field_descriptor: The field descriptor for the extension to check.
365 Returns:
366 bool: Whether the extension is present for this message.
368 Raises:
369 KeyError: if the extension is repeated. Similar to repeated fields,
370 there is no separate notion of presence: a "not present" repeated
371 extension is an empty list.
372 """
373 raise NotImplementedError
375 def ClearExtension(self, field_descriptor):
376 """Clears the contents of a given extension.
378 Args:
379 field_descriptor: The field descriptor for the extension to clear.
380 """
381 raise NotImplementedError
383 def UnknownFields(self):
384 """Returns the UnknownFieldSet.
386 Returns:
387 UnknownFieldSet: The unknown fields stored in this message.
388 """
389 raise NotImplementedError
391 def DiscardUnknownFields(self):
392 """Clears all fields in the :class:`UnknownFieldSet`.
394 This operation is recursive for nested message.
395 """
396 raise NotImplementedError
398 def ByteSize(self):
399 """Returns the serialized size of this message.
401 Recursively calls ByteSize() on all contained messages.
403 Returns:
404 int: The number of bytes required to serialize this message.
405 """
406 raise NotImplementedError
408 @classmethod
409 def FromString(cls, s):
410 raise NotImplementedError
412 def _SetListener(self, message_listener):
413 """Internal method used by the protocol message implementation.
415 Clients should not call this directly.
417 Sets a listener that this message will call on certain state transitions.
419 The purpose of this method is to register back-edges from children to
420 parents at runtime, for the purpose of setting "has" bits and
421 byte-size-dirty bits in the parent and ancestor objects whenever a child or
422 descendant object is modified.
424 If the client wants to disconnect this Message from the object tree, she
425 explicitly sets callback to None.
427 If message_listener is None, unregisters any existing listener. Otherwise,
428 message_listener must implement the MessageListener interface in
429 internal/message_listener.py, and we discard any listener registered
430 via a previous _SetListener() call.
431 """
432 raise NotImplementedError
434 def __getstate__(self):
435 """Support the pickle protocol."""
436 return dict(serialized=self.SerializePartialToString())
438 def __setstate__(self, state):
439 """Support the pickle protocol."""
440 self.__init__()
441 serialized = state['serialized']
442 # On Python 3, using encoding='latin1' is required for unpickling
443 # protos pickled by Python 2.
444 if not isinstance(serialized, bytes):
445 serialized = serialized.encode('latin1')
446 self.ParseFromString(serialized)
448 def __reduce__(self):
449 message_descriptor = self.DESCRIPTOR
450 if message_descriptor.containing_type is None:
451 return type(self), (), self.__getstate__()
452 # the message type must be nested.
453 # Python does not pickle nested classes; use the symbol_database on the
454 # receiving end.
455 container = message_descriptor
456 return (
457 _InternalConstructMessage,
458 (container.full_name,),
459 self.__getstate__(),
460 )
463def _InternalConstructMessage(full_name):
464 """Constructs a nested message."""
465 from google.protobuf import symbol_database # pylint:disable=g-import-not-at-top
467 return symbol_database.Default().GetSymbol(full_name)()