← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/mozc/oneiric

« back to all changes in this revision

Viewing changes to protobuf/files/python/google/protobuf/message.py

  • Committer: Bazaar Package Importer
  • Author(s): Nobuhiro Iwamatsu
  • Date: 2010-07-14 03:26:47 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20100714032647-13qjisj6m8cm8jdx
Tags: 0.12.410.102-1
http://bugs.debian.org/588971
http://bugs.debian.org/588972
* New upstream release (Closes: #588971).
  - Add mozc-server, mozc-utils-gui and scim-mozc packages.
* Update debian/rules.
  Add --gypdir option to build_mozc.py.
* Update debian/control.
  - Bumped standards-version to 3.9.0.
  - Update description.
* Add mozc icon (Closes: #588972).
* Add patch which revises issue 18.
  ibus_mozc_issue18.patch
* kFreeBSD build support.
  support_kfreebsd.patch

Show diffs side-by-side

added added

removed removed

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