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 7 8# TODO: We should just make these methods all "pure-virtual" and move 9# all implementation out, into reflection.py for now. 10 11 12"""Contains an abstract base class for protocol messages.""" 13 14__author__ = 'robinson@google.com (Will Robinson)' 15 16class Error(Exception): 17 """Base error type for this module.""" 18 pass 19 20 21class DecodeError(Error): 22 """Exception raised when deserializing messages.""" 23 pass 24 25 26class EncodeError(Error): 27 """Exception raised when serializing messages.""" 28 pass 29 30 31class Message(object): 32 33 """Abstract base class for protocol messages. 34 35 Protocol message classes are almost always generated by the protocol 36 compiler. These generated types subclass Message and implement the methods 37 shown below. 38 """ 39 40 # TODO: Link to an HTML document here. 41 42 # TODO: Document that instances of this class will also 43 # have an Extensions attribute with __getitem__ and __setitem__. 44 # Again, not sure how to best convey this. 45 46 # TODO: Document these fields and methods. 47 48 __slots__ = [] 49 50 #: The :class:`google.protobuf.Descriptor` 51 # for this message type. 52 DESCRIPTOR = None 53 54 def __deepcopy__(self, memo=None): 55 clone = type(self)() 56 clone.MergeFrom(self) 57 return clone 58 59 def __eq__(self, other_msg): 60 """Recursively compares two messages by value and structure.""" 61 raise NotImplementedError 62 63 def __ne__(self, other_msg): 64 # Can't just say self != other_msg, since that would infinitely recurse. :) 65 return not self == other_msg 66 67 def __hash__(self): 68 raise TypeError('unhashable object') 69 70 def __str__(self): 71 """Outputs a human-readable representation of the message.""" 72 raise NotImplementedError 73 74 def __unicode__(self): 75 """Outputs a human-readable representation of the message.""" 76 raise NotImplementedError 77 78 def __contains__(self, field_name_or_key): 79 """Checks if a certain field is set for the message. 80 81 Has presence fields return true if the field is set, false if the field is 82 not set. Fields without presence do raise `ValueError` (this includes 83 repeated fields, map fields, and implicit presence fields). 84 85 If field_name is not defined in the message descriptor, `ValueError` will 86 be raised. 87 Note: WKT Struct checks if the key is contained in fields. ListValue checks 88 if the item is contained in the list. 89 90 Args: 91 field_name_or_key: For Struct, the key (str) of the fields map. For 92 ListValue, any type that may be contained in the list. For other 93 messages, name of the field (str) to check for presence. 94 95 Returns: 96 bool: For Struct, whether the item is contained in fields. For ListValue, 97 whether the item is contained in the list. For other message, 98 whether a value has been set for the named field. 99 100 Raises: 101 ValueError: For normal messages, if the `field_name_or_key` is not a 102 member of this message or `field_name_or_key` is not a string. 103 """ 104 raise NotImplementedError 105 106 def MergeFrom(self, other_msg): 107 """Merges the contents of the specified message into current message. 108 109 This method merges the contents of the specified message into the current 110 message. Singular fields that are set in the specified message overwrite 111 the corresponding fields in the current message. Repeated fields are 112 appended. Singular sub-messages and groups are recursively merged. 113 114 Args: 115 other_msg (Message): A message to merge into the current message. 116 """ 117 raise NotImplementedError 118 119 def CopyFrom(self, other_msg): 120 """Copies the content of the specified message into the current message. 121 122 The method clears the current message and then merges the specified 123 message using MergeFrom. 124 125 Args: 126 other_msg (Message): A message to copy into the current one. 127 """ 128 if self is other_msg: 129 return 130 self.Clear() 131 self.MergeFrom(other_msg) 132 133 def Clear(self): 134 """Clears all data that was set in the message.""" 135 raise NotImplementedError 136 137 def SetInParent(self): 138 """Mark this as present in the parent. 139 140 This normally happens automatically when you assign a field of a 141 sub-message, but sometimes you want to make the sub-message 142 present while keeping it empty. If you find yourself using this, 143 you may want to reconsider your design. 144 """ 145 raise NotImplementedError 146 147 def IsInitialized(self): 148 """Checks if the message is initialized. 149 150 Returns: 151 bool: The method returns True if the message is initialized (i.e. all of 152 its required fields are set). 153 """ 154 raise NotImplementedError 155 156 # TODO: MergeFromString() should probably return None and be 157 # implemented in terms of a helper that returns the # of bytes read. Our 158 # deserialization routines would use the helper when recursively 159 # deserializing, but the end user would almost always just want the no-return 160 # MergeFromString(). 161 162 def MergeFromString(self, serialized): 163 """Merges serialized protocol buffer data into this message. 164 165 When we find a field in `serialized` that is already present 166 in this message: 167 168 - If it's a "repeated" field, we append to the end of our list. 169 - Else, if it's a scalar, we overwrite our field. 170 - Else, (it's a nonrepeated composite), we recursively merge 171 into the existing composite. 172 173 Args: 174 serialized (bytes): Any object that allows us to call 175 ``memoryview(serialized)`` to access a string of bytes using the 176 buffer interface. 177 178 Returns: 179 int: The number of bytes read from `serialized`. 180 For non-group messages, this will always be `len(serialized)`, 181 but for messages which are actually groups, this will 182 generally be less than `len(serialized)`, since we must 183 stop when we reach an ``END_GROUP`` tag. Note that if 184 we *do* stop because of an ``END_GROUP`` tag, the number 185 of bytes returned does not include the bytes 186 for the ``END_GROUP`` tag information. 187 188 Raises: 189 DecodeError: if the input cannot be parsed. 190 """ 191 # TODO: Document handling of unknown fields. 192 # TODO: When we switch to a helper, this will return None. 193 raise NotImplementedError 194 195 def ParseFromString(self, serialized): 196 """Parse serialized protocol buffer data in binary form into this message. 197 198 Like :func:`MergeFromString()`, except we clear the object first. 199 200 Raises: 201 message.DecodeError if the input cannot be parsed. 202 """ 203 self.Clear() 204 return self.MergeFromString(serialized) 205 206 def SerializeToString(self, **kwargs): 207 """Serializes the protocol message to a binary string. 208 209 Keyword Args: 210 deterministic (bool): If true, requests deterministic serialization 211 of the protobuf, with predictable ordering of map keys. 212 213 Returns: 214 A binary string representation of the message if all of the required 215 fields in the message are set (i.e. the message is initialized). 216 217 Raises: 218 EncodeError: if the message isn't initialized (see :func:`IsInitialized`). 219 """ 220 raise NotImplementedError 221 222 def SerializePartialToString(self, **kwargs): 223 """Serializes the protocol message to a binary string. 224 225 This method is similar to SerializeToString but doesn't check if the 226 message is initialized. 227 228 Keyword Args: 229 deterministic (bool): If true, requests deterministic serialization 230 of the protobuf, with predictable ordering of map keys. 231 232 Returns: 233 bytes: A serialized representation of the partial message. 234 """ 235 raise NotImplementedError 236 237 # TODO: Decide whether we like these better 238 # than auto-generated has_foo() and clear_foo() methods 239 # on the instances themselves. This way is less consistent 240 # with C++, but it makes reflection-type access easier and 241 # reduces the number of magically autogenerated things. 242 # 243 # TODO: Be sure to document (and test) exactly 244 # which field names are accepted here. Are we case-sensitive? 245 # What do we do with fields that share names with Python keywords 246 # like 'lambda' and 'yield'? 247 # 248 # nnorwitz says: 249 # """ 250 # Typically (in python), an underscore is appended to names that are 251 # keywords. So they would become lambda_ or yield_. 252 # """ 253 def ListFields(self): 254 """Returns a list of (FieldDescriptor, value) tuples for present fields. 255 256 A message field is non-empty if HasField() would return true. A singular 257 primitive field is non-empty if HasField() would return true in proto2 or it 258 is non zero in proto3. A repeated field is non-empty if it contains at least 259 one element. The fields are ordered by field number. 260 261 Returns: 262 list[tuple(FieldDescriptor, value)]: field descriptors and values 263 for all fields in the message which are not empty. The values vary by 264 field type. 265 """ 266 raise NotImplementedError 267 268 def HasField(self, field_name): 269 """Checks if a certain field is set for the message. 270 271 For a oneof group, checks if any field inside is set. Note that if the 272 field_name is not defined in the message descriptor, :exc:`ValueError` will 273 be raised. 274 275 Args: 276 field_name (str): The name of the field to check for presence. 277 278 Returns: 279 bool: Whether a value has been set for the named field. 280 281 Raises: 282 ValueError: if the `field_name` is not a member of this message. 283 """ 284 raise NotImplementedError 285 286 def ClearField(self, field_name): 287 """Clears the contents of a given field. 288 289 Inside a oneof group, clears the field set. If the name neither refers to a 290 defined field or oneof group, :exc:`ValueError` is raised. 291 292 Args: 293 field_name (str): The name of the field to check for presence. 294 295 Raises: 296 ValueError: if the `field_name` is not a member of this message. 297 """ 298 raise NotImplementedError 299 300 def WhichOneof(self, oneof_group): 301 """Returns the name of the field that is set inside a oneof group. 302 303 If no field is set, returns None. 304 305 Args: 306 oneof_group (str): the name of the oneof group to check. 307 308 Returns: 309 str or None: The name of the group that is set, or None. 310 311 Raises: 312 ValueError: no group with the given name exists 313 """ 314 raise NotImplementedError 315 316 def HasExtension(self, field_descriptor): 317 """Checks if a certain extension is present for this message. 318 319 Extensions are retrieved using the :attr:`Extensions` mapping (if present). 320 321 Args: 322 field_descriptor: The field descriptor for the extension to check. 323 324 Returns: 325 bool: Whether the extension is present for this message. 326 327 Raises: 328 KeyError: if the extension is repeated. Similar to repeated fields, 329 there is no separate notion of presence: a "not present" repeated 330 extension is an empty list. 331 """ 332 raise NotImplementedError 333 334 def ClearExtension(self, field_descriptor): 335 """Clears the contents of a given extension. 336 337 Args: 338 field_descriptor: The field descriptor for the extension to clear. 339 """ 340 raise NotImplementedError 341 342 def UnknownFields(self): 343 """Returns the UnknownFieldSet. 344 345 Returns: 346 UnknownFieldSet: The unknown fields stored in this message. 347 """ 348 raise NotImplementedError 349 350 def DiscardUnknownFields(self): 351 """Clears all fields in the :class:`UnknownFieldSet`. 352 353 This operation is recursive for nested message. 354 """ 355 raise NotImplementedError 356 357 def ByteSize(self): 358 """Returns the serialized size of this message. 359 360 Recursively calls ByteSize() on all contained messages. 361 362 Returns: 363 int: The number of bytes required to serialize this message. 364 """ 365 raise NotImplementedError 366 367 @classmethod 368 def FromString(cls, s): 369 raise NotImplementedError 370 371 def _SetListener(self, message_listener): 372 """Internal method used by the protocol message implementation. 373 Clients should not call this directly. 374 375 Sets a listener that this message will call on certain state transitions. 376 377 The purpose of this method is to register back-edges from children to 378 parents at runtime, for the purpose of setting "has" bits and 379 byte-size-dirty bits in the parent and ancestor objects whenever a child or 380 descendant object is modified. 381 382 If the client wants to disconnect this Message from the object tree, she 383 explicitly sets callback to None. 384 385 If message_listener is None, unregisters any existing listener. Otherwise, 386 message_listener must implement the MessageListener interface in 387 internal/message_listener.py, and we discard any listener registered 388 via a previous _SetListener() call. 389 """ 390 raise NotImplementedError 391 392 def __getstate__(self): 393 """Support the pickle protocol.""" 394 return dict(serialized=self.SerializePartialToString()) 395 396 def __setstate__(self, state): 397 """Support the pickle protocol.""" 398 self.__init__() 399 serialized = state['serialized'] 400 # On Python 3, using encoding='latin1' is required for unpickling 401 # protos pickled by Python 2. 402 if not isinstance(serialized, bytes): 403 serialized = serialized.encode('latin1') 404 self.ParseFromString(serialized) 405 406 def __reduce__(self): 407 message_descriptor = self.DESCRIPTOR 408 if message_descriptor.containing_type is None: 409 return type(self), (), self.__getstate__() 410 # the message type must be nested. 411 # Python does not pickle nested classes; use the symbol_database on the 412 # receiving end. 413 container = message_descriptor 414 return (_InternalConstructMessage, (container.full_name,), 415 self.__getstate__()) 416 417 418def _InternalConstructMessage(full_name): 419 """Constructs a nested message.""" 420 from google.protobuf import symbol_database # pylint:disable=g-import-not-at-top 421 422 return symbol_database.Default().GetSymbol(full_name)() 423