1# Protocol Buffers - Google's data interchange format 2# Copyright 2008 Google Inc. All rights reserved. 3# http://code.google.com/p/protobuf/ 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__ = 'robinson@google.com (Will Robinson)' 38 39 40class Error(Exception): pass 41class DecodeError(Error): pass 42class EncodeError(Error): pass 43 44 45class Message(object): 46 47 """Abstract base class for protocol messages. 48 49 Protocol message classes are almost always generated by the protocol 50 compiler. These generated types subclass Message and implement the methods 51 shown below. 52 53 TODO(robinson): Link to an HTML document here. 54 55 TODO(robinson): Document that instances of this class will also 56 have an Extensions attribute with __getitem__ and __setitem__. 57 Again, not sure how to best convey this. 58 59 TODO(robinson): Document that the class must also have a static 60 RegisterExtension(extension_field) method. 61 Not sure how to best express at this point. 62 """ 63 64 # TODO(robinson): Document these fields and methods. 65 66 __slots__ = [] 67 68 DESCRIPTOR = None 69 70 def __deepcopy__(self, memo=None): 71 clone = type(self)() 72 clone.MergeFrom(self) 73 return clone 74 75 def __eq__(self, other_msg): 76 """Recursively compares two messages by value and structure.""" 77 raise NotImplementedError 78 79 def __ne__(self, other_msg): 80 # Can't just say self != other_msg, since that would infinitely recurse. :) 81 return not self == other_msg 82 83 def __hash__(self): 84 raise TypeError('unhashable object') 85 86 def __str__(self): 87 """Outputs a human-readable representation of the message.""" 88 raise NotImplementedError 89 90 def __unicode__(self): 91 """Outputs a human-readable representation of the message.""" 92 raise NotImplementedError 93 94 def MergeFrom(self, other_msg): 95 """Merges the contents of the specified message into current message. 96 97 This method merges the contents of the specified message into the current 98 message. Singular fields that are set in the specified message overwrite 99 the corresponding fields in the current message. Repeated fields are 100 appended. Singular sub-messages and groups are recursively merged. 101 102 Args: 103 other_msg: Message to merge into the current message. 104 """ 105 raise NotImplementedError 106 107 def CopyFrom(self, other_msg): 108 """Copies the content of the specified message into the current message. 109 110 The method clears the current message and then merges the specified 111 message using MergeFrom. 112 113 Args: 114 other_msg: Message to copy into the current one. 115 """ 116 if self is other_msg: 117 return 118 self.Clear() 119 self.MergeFrom(other_msg) 120 121 def Clear(self): 122 """Clears all data that was set in the message.""" 123 raise NotImplementedError 124 125 def SetInParent(self): 126 """Mark this as present in the parent. 127 128 This normally happens automatically when you assign a field of a 129 sub-message, but sometimes you want to make the sub-message 130 present while keeping it empty. If you find yourself using this, 131 you may want to reconsider your design.""" 132 raise NotImplementedError 133 134 def IsInitialized(self): 135 """Checks if the message is initialized. 136 137 Returns: 138 The method returns True if the message is initialized (i.e. all of its 139 required fields are set). 140 """ 141 raise NotImplementedError 142 143 # TODO(robinson): MergeFromString() should probably return None and be 144 # implemented in terms of a helper that returns the # of bytes read. Our 145 # deserialization routines would use the helper when recursively 146 # deserializing, but the end user would almost always just want the no-return 147 # MergeFromString(). 148 149 def MergeFromString(self, serialized): 150 """Merges serialized protocol buffer data into this message. 151 152 When we find a field in |serialized| that is already present 153 in this message: 154 - If it's a "repeated" field, we append to the end of our list. 155 - Else, if it's a scalar, we overwrite our field. 156 - Else, (it's a nonrepeated composite), we recursively merge 157 into the existing composite. 158 159 TODO(robinson): Document handling of unknown fields. 160 161 Args: 162 serialized: Any object that allows us to call buffer(serialized) 163 to access a string of bytes using the buffer interface. 164 165 TODO(robinson): When we switch to a helper, this will return None. 166 167 Returns: 168 The number of bytes read from |serialized|. 169 For non-group messages, this will always be len(serialized), 170 but for messages which are actually groups, this will 171 generally be less than len(serialized), since we must 172 stop when we reach an END_GROUP tag. Note that if 173 we *do* stop because of an END_GROUP tag, the number 174 of bytes returned does not include the bytes 175 for the END_GROUP tag information. 176 """ 177 raise NotImplementedError 178 179 def ParseFromString(self, serialized): 180 """Like MergeFromString(), except we clear the object first.""" 181 self.Clear() 182 self.MergeFromString(serialized) 183 184 def SerializeToString(self): 185 """Serializes the protocol message to a binary string. 186 187 Returns: 188 A binary string representation of the message if all of the required 189 fields in the message are set (i.e. the message is initialized). 190 191 Raises: 192 message.EncodeError if the message isn't initialized. 193 """ 194 raise NotImplementedError 195 196 def SerializePartialToString(self): 197 """Serializes the protocol message to a binary string. 198 199 This method is similar to SerializeToString but doesn't check if the 200 message is initialized. 201 202 Returns: 203 A string representation of the partial message. 204 """ 205 raise NotImplementedError 206 207 # TODO(robinson): Decide whether we like these better 208 # than auto-generated has_foo() and clear_foo() methods 209 # on the instances themselves. This way is less consistent 210 # with C++, but it makes reflection-type access easier and 211 # reduces the number of magically autogenerated things. 212 # 213 # TODO(robinson): Be sure to document (and test) exactly 214 # which field names are accepted here. Are we case-sensitive? 215 # What do we do with fields that share names with Python keywords 216 # like 'lambda' and 'yield'? 217 # 218 # nnorwitz says: 219 # """ 220 # Typically (in python), an underscore is appended to names that are 221 # keywords. So they would become lambda_ or yield_. 222 # """ 223 def ListFields(self): 224 """Returns a list of (FieldDescriptor, value) tuples for all 225 fields in the message which are not empty. A singular field is non-empty 226 if HasField() would return true, and a repeated field is non-empty if 227 it contains at least one element. The fields are ordered by field 228 number""" 229 raise NotImplementedError 230 231 def HasField(self, field_name): 232 """Checks if a certain field is set for the message. Note if the 233 field_name is not defined in the message descriptor, ValueError will be 234 raised.""" 235 raise NotImplementedError 236 237 def ClearField(self, field_name): 238 raise NotImplementedError 239 240 def HasExtension(self, extension_handle): 241 raise NotImplementedError 242 243 def ClearExtension(self, extension_handle): 244 raise NotImplementedError 245 246 def ByteSize(self): 247 """Returns the serialized size of this message. 248 Recursively calls ByteSize() on all contained messages. 249 """ 250 raise NotImplementedError 251 252 def _SetListener(self, message_listener): 253 """Internal method used by the protocol message implementation. 254 Clients should not call this directly. 255 256 Sets a listener that this message will call on certain state transitions. 257 258 The purpose of this method is to register back-edges from children to 259 parents at runtime, for the purpose of setting "has" bits and 260 byte-size-dirty bits in the parent and ancestor objects whenever a child or 261 descendant object is modified. 262 263 If the client wants to disconnect this Message from the object tree, she 264 explicitly sets callback to None. 265 266 If message_listener is None, unregisters any existing listener. Otherwise, 267 message_listener must implement the MessageListener interface in 268 internal/message_listener.py, and we discard any listener registered 269 via a previous _SetListener() call. 270 """ 271 raise NotImplementedError 272 273 def __getstate__(self): 274 """Support the pickle protocol.""" 275 return dict(serialized=self.SerializePartialToString()) 276 277 def __setstate__(self, state): 278 """Support the pickle protocol.""" 279 self.__init__() 280 self.ParseFromString(state['serialized']) 281