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