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 | # This code is meant to work on Python 2.4 and above only. |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 32 | |
| 33 | """Contains a metaclass and helper functions used to create |
| 34 | protocol message classes from Descriptor objects at runtime. |
| 35 | |
| 36 | Recall that a metaclass is the "type" of a class. |
| 37 | (A class is to a metaclass what an instance is to a class.) |
| 38 | |
| 39 | In this case, we use the GeneratedProtocolMessageType metaclass |
| 40 | to inject all the useful functionality into the classes |
| 41 | output by the protocol compiler at compile-time. |
| 42 | |
| 43 | The upshot of all this is that the real implementation |
| 44 | details for ALL pure-Python protocol buffers are *here in |
| 45 | this file*. |
| 46 | """ |
| 47 | |
| 48 | __author__ = 'robinson@google.com (Will Robinson)' |
| 49 | |
kenton@google.com | fccb146 | 2009-12-18 02:11:36 +0000 | [diff] [blame] | 50 | |
liujisi@google.com | 33165fe | 2010-11-02 13:14:58 +0000 | [diff] [blame^] | 51 | from google.protobuf.internal import api_implementation |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 52 | from google.protobuf import descriptor as descriptor_mod |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 53 | _FieldDescriptor = descriptor_mod.FieldDescriptor |
| 54 | |
| 55 | |
liujisi@google.com | 33165fe | 2010-11-02 13:14:58 +0000 | [diff] [blame^] | 56 | if api_implementation.Type() == 'cpp': |
| 57 | from google.protobuf.internal import cpp_message |
| 58 | _NewMessage = cpp_message.NewMessage |
| 59 | _InitMessage = cpp_message.InitMessage |
| 60 | else: |
| 61 | from google.protobuf.internal import python_message |
| 62 | _NewMessage = python_message.NewMessage |
| 63 | _InitMessage = python_message.InitMessage |
| 64 | |
| 65 | |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 66 | class GeneratedProtocolMessageType(type): |
| 67 | |
| 68 | """Metaclass for protocol message classes created at runtime from Descriptors. |
| 69 | |
| 70 | We add implementations for all methods described in the Message class. We |
| 71 | also create properties to allow getting/setting all fields in the protocol |
| 72 | message. Finally, we create slots to prevent users from accidentally |
| 73 | "setting" nonexistent fields in the protocol message, which then wouldn't get |
| 74 | serialized / deserialized properly. |
| 75 | |
| 76 | The protocol compiler currently uses this metaclass to create protocol |
| 77 | message classes at runtime. Clients can also manually create their own |
| 78 | classes at runtime, as in this example: |
| 79 | |
| 80 | mydescriptor = Descriptor(.....) |
| 81 | class MyProtoClass(Message): |
| 82 | __metaclass__ = GeneratedProtocolMessageType |
| 83 | DESCRIPTOR = mydescriptor |
| 84 | myproto_instance = MyProtoClass() |
| 85 | myproto.foo_field = 23 |
| 86 | ... |
| 87 | """ |
| 88 | |
| 89 | # Must be consistent with the protocol-compiler code in |
| 90 | # proto2/compiler/internal/generator.*. |
| 91 | _DESCRIPTOR_KEY = 'DESCRIPTOR' |
| 92 | |
| 93 | def __new__(cls, name, bases, dictionary): |
| 94 | """Custom allocation for runtime-generated class types. |
| 95 | |
| 96 | We override __new__ because this is apparently the only place |
| 97 | where we can meaningfully set __slots__ on the class we're creating(?). |
| 98 | (The interplay between metaclasses and slots is not very well-documented). |
| 99 | |
| 100 | Args: |
| 101 | name: Name of the class (ignored, but required by the |
| 102 | metaclass protocol). |
| 103 | bases: Base classes of the class we're constructing. |
| 104 | (Should be message.Message). We ignore this field, but |
| 105 | it's required by the metaclass protocol |
| 106 | dictionary: The class dictionary of the class we're |
| 107 | constructing. dictionary[_DESCRIPTOR_KEY] must contain |
| 108 | a Descriptor object describing this protocol message |
| 109 | type. |
| 110 | |
| 111 | Returns: |
| 112 | Newly-allocated class. |
| 113 | """ |
| 114 | descriptor = dictionary[GeneratedProtocolMessageType._DESCRIPTOR_KEY] |
liujisi@google.com | 33165fe | 2010-11-02 13:14:58 +0000 | [diff] [blame^] | 115 | _NewMessage(descriptor, dictionary) |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 116 | superclass = super(GeneratedProtocolMessageType, cls) |
liujisi@google.com | 33165fe | 2010-11-02 13:14:58 +0000 | [diff] [blame^] | 117 | |
| 118 | new_class = superclass.__new__(cls, name, bases, dictionary) |
| 119 | setattr(descriptor, '_concrete_class', new_class) |
| 120 | return new_class |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 121 | |
| 122 | def __init__(cls, name, bases, dictionary): |
| 123 | """Here we perform the majority of our work on the class. |
| 124 | We add enum getters, an __init__ method, implementations |
| 125 | of all Message methods, and properties for all fields |
| 126 | in the protocol type. |
| 127 | |
| 128 | Args: |
| 129 | name: Name of the class (ignored, but required by the |
| 130 | metaclass protocol). |
| 131 | bases: Base classes of the class we're constructing. |
| 132 | (Should be message.Message). We ignore this field, but |
| 133 | it's required by the metaclass protocol |
| 134 | dictionary: The class dictionary of the class we're |
| 135 | constructing. dictionary[_DESCRIPTOR_KEY] must contain |
| 136 | a Descriptor object describing this protocol message |
| 137 | type. |
| 138 | """ |
| 139 | descriptor = dictionary[GeneratedProtocolMessageType._DESCRIPTOR_KEY] |
liujisi@google.com | 33165fe | 2010-11-02 13:14:58 +0000 | [diff] [blame^] | 140 | _InitMessage(descriptor, cls) |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 141 | superclass = super(GeneratedProtocolMessageType, cls) |
kenton@google.com | eb241fa | 2008-12-02 02:33:13 +0000 | [diff] [blame] | 142 | superclass.__init__(name, bases, dictionary) |