/thirdparty/breakpad/third_party/protobuf/protobuf/python/google/protobuf/reflection.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# This code is meant to work on Python 2.4 and above only.
 32
 33"""Contains a metaclass and helper functions used to create
 34protocol message classes from Descriptor objects at runtime.
 35
 36Recall that a metaclass is the "type" of a class.
 37(A class is to a metaclass what an instance is to a class.)
 38
 39In this case, we use the GeneratedProtocolMessageType metaclass
 40to inject all the useful functionality into the classes
 41output by the protocol compiler at compile-time.
 42
 43The upshot of all this is that the real implementation
 44details for ALL pure-Python protocol buffers are *here in
 45this file*.
 46"""
 47
 48__author__ = 'robinson@google.com (Will Robinson)'
 49
 50
 51from google.protobuf.internal import api_implementation
 52from google.protobuf import descriptor as descriptor_mod
 53_FieldDescriptor = descriptor_mod.FieldDescriptor
 54
 55
 56if api_implementation.Type() == 'cpp':
 57  from google.protobuf.internal import cpp_message
 58  _NewMessage = cpp_message.NewMessage
 59  _InitMessage = cpp_message.InitMessage
 60else:
 61  from google.protobuf.internal import python_message
 62  _NewMessage = python_message.NewMessage
 63  _InitMessage = python_message.InitMessage
 64
 65
 66class 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]
115    _NewMessage(descriptor, dictionary)
116    superclass = super(GeneratedProtocolMessageType, cls)
117
118    new_class = superclass.__new__(cls, name, bases, dictionary)
119    setattr(descriptor, '_concrete_class', new_class)
120    return new_class
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]
140    _InitMessage(descriptor, cls)
141    superclass = super(GeneratedProtocolMessageType, cls)
142    superclass.__init__(name, bases, dictionary)