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