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