python/google/protobuf/descriptor.py

   1 # Protocol Buffers - Google's data interchange format
   2 # Copyright 2008 Google Inc.  All rights reserved.
   3 # https://developers.google.com/protocol-buffers/
   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 """Descriptors essentially contain exactly the information found in a .proto
  32 file, in types that make this information accessible in Python.
  33 """
  34
  35 __author__ = 'robinson@google.com (Will Robinson)'
  36
  37 import threading
  38 import six
  39
  40 from google.protobuf.internal import api_implementation
  41
  42 _USE_C_DESCRIPTORS = False
  43 if api_implementation.Type() == 'cpp':
  44   # Used by MakeDescriptor in cpp mode
  45   import binascii
  46   import os
  47   from google.protobuf.pyext import _message
  48   _USE_C_DESCRIPTORS = getattr(_message, '_USE_C_DESCRIPTORS', False)
  49
  50
  51 class Error(Exception):
  52   """Base error for this module."""
  53
  54
  55 class TypeTransformationError(Error):
  56   """Error transforming between python proto type and corresponding C++ type."""
  57
  58
  59 if _USE_C_DESCRIPTORS:
  60   # This metaclass allows to override the behavior of code like
  61   #     isinstance(my_descriptor, FieldDescriptor)
  62   # and make it return True when the descriptor is an instance of the extension
  63   # type written in C++.
  64   class DescriptorMetaclass(type):
  65     def __instancecheck__(cls, obj):
  66       if super(DescriptorMetaclass, cls).__instancecheck__(obj):
  67         return True
  68       if isinstance(obj, cls._C_DESCRIPTOR_CLASS):
  69         return True
  70       return False
  71 else:
  72   # The standard metaclass; nothing changes.
  73   DescriptorMetaclass = type
  74
  75
  76 class _Lock(object):
  77   """Wrapper class of threading.Lock(), which is allowed by 'with'."""
  78
  79   def __new__(cls):
  80     self = object.__new__(cls)
  81     self._lock = threading.Lock()  # pylint: disable=protected-access
  82     return self
  83
  84   def __enter__(self):
  85     self._lock.acquire()
  86
  87   def __exit__(self, exc_type, exc_value, exc_tb):
  88     self._lock.release()
  89
  90
  91 _lock = threading.Lock()
  92
  93
  94 class DescriptorBase(six.with_metaclass(DescriptorMetaclass)):
  95
  96   """Descriptors base class.
  97
  98   This class is the base of all descriptor classes. It provides common options
  99   related functionality.
 100
 101   Attributes:
 102     has_options:  True if the descriptor has non-default options.  Usually it
 103         is not necessary to read this -- just call GetOptions() which will
 104         happily return the default instance.  However, it's sometimes useful
 105         for efficiency, and also useful inside the protobuf implementation to
 106         avoid some bootstrapping issues.
 107   """
 108
 109   if _USE_C_DESCRIPTORS:
 110     # The class, or tuple of classes, that are considered as "virtual
 111     # subclasses" of this descriptor class.
 112     _C_DESCRIPTOR_CLASS = ()
 113
 114   def __init__(self, options, serialized_options, options_class_name):
 115     """Initialize the descriptor given its options message and the name of the
 116     class of the options message. The name of the class is required in case
 117     the options message is None and has to be created.
 118     """
 119     self._options = options
 120     self._options_class_name = options_class_name
 121     self._serialized_options = serialized_options
 122
 123     # Does this descriptor have non-default options?
 124     self.has_options = (options is not None) or (serialized_options is not None)
 125
 126   def _SetOptions(self, options, options_class_name):
 127     """Sets the descriptor's options
 128
 129     This function is used in generated proto2 files to update descriptor
 130     options. It must not be used outside proto2.
 131     """
 132     self._options = options
 133     self._options_class_name = options_class_name
 134
 135     # Does this descriptor have non-default options?
 136     self.has_options = options is not None
 137
 138   def GetOptions(self):
 139     """Retrieves descriptor options.
 140
 141     This method returns the options set or creates the default options for the
 142     descriptor.
 143     """
 144     if self._options:
 145       return self._options
 146
 147     from google.protobuf import descriptor_pb2
 148     try:
 149       options_class = getattr(descriptor_pb2,
 150                               self._options_class_name)
 151     except AttributeError:
 152       raise RuntimeError('Unknown options class name %s!' %
 153                          (self._options_class_name))
 154
 155     with _lock:
 156       if self._serialized_options is None:
 157         self._options = options_class()
 158       else:
 159         self._options = _ParseOptions(options_class(),
 160                                       self._serialized_options)
 161
 162       return self._options
 163
 164
 165 class _NestedDescriptorBase(DescriptorBase):
 166   """Common class for descriptors that can be nested."""
 167
 168   def __init__(self, options, options_class_name, name, full_name,
 169                file, containing_type, serialized_start=None,
 170                serialized_end=None, serialized_options=None):
 171     """Constructor.
 172
 173     Args:
 174       options: Protocol message options or None
 175         to use default message options.
 176       options_class_name: (str) The class name of the above options.
 177
 178       name: (str) Name of this protocol message type.
 179       full_name: (str) Fully-qualified name of this protocol message type,
 180         which will include protocol "package" name and the name of any
 181         enclosing types.
 182       file: (FileDescriptor) Reference to file info.
 183       containing_type: if provided, this is a nested descriptor, with this
 184         descriptor as parent, otherwise None.
 185       serialized_start: The start index (inclusive) in block in the
 186         file.serialized_pb that describes this descriptor.
 187       serialized_end: The end index (exclusive) in block in the
 188         file.serialized_pb that describes this descriptor.
 189       serialized_options: Protocol message serilized options or None.
 190     """
 191     super(_NestedDescriptorBase, self).__init__(
 192         options, serialized_options, options_class_name)
 193
 194     self.name = name
 195     # TODO(falk): Add function to calculate full_name instead of having it in
 196     #             memory?
 197     self.full_name = full_name
 198     self.file = file
 199     self.containing_type = containing_type
 200
 201     self._serialized_start = serialized_start
 202     self._serialized_end = serialized_end
 203
 204   def CopyToProto(self, proto):
 205     """Copies this to the matching proto in descriptor_pb2.
 206
 207     Args:
 208       proto: An empty proto instance from descriptor_pb2.
 209
 210     Raises:
 211       Error: If self couldnt be serialized, due to to few constructor arguments.
 212     """
 213     if (self.file is not None and
 214         self._serialized_start is not None and
 215         self._serialized_end is not None):
 216       proto.ParseFromString(self.file.serialized_pb[
 217           self._serialized_start:self._serialized_end])
 218     else:
 219       raise Error('Descriptor does not contain serialization.')
 220
 221
 222 class Descriptor(_NestedDescriptorBase):
 223
 224   """Descriptor for a protocol message type.
 225
 226   A Descriptor instance has the following attributes:
 227
 228     name: (str) Name of this protocol message type.
 229     full_name: (str) Fully-qualified name of this protocol message type,
 230       which will include protocol "package" name and the name of any
 231       enclosing types.
 232
 233     containing_type: (Descriptor) Reference to the descriptor of the
 234       type containing us, or None if this is top-level.
 235
 236     fields: (list of FieldDescriptors) Field descriptors for all
 237       fields in this type.
 238     fields_by_number: (dict int -> FieldDescriptor) Same FieldDescriptor
 239       objects as in |fields|, but indexed by "number" attribute in each
 240       FieldDescriptor.
 241     fields_by_name: (dict str -> FieldDescriptor) Same FieldDescriptor
 242       objects as in |fields|, but indexed by "name" attribute in each
 243       FieldDescriptor.
 244     fields_by_camelcase_name: (dict str -> FieldDescriptor) Same
 245       FieldDescriptor objects as in |fields|, but indexed by
 246       "camelcase_name" attribute in each FieldDescriptor.
 247
 248     nested_types: (list of Descriptors) Descriptor references
 249       for all protocol message types nested within this one.
 250     nested_types_by_name: (dict str -> Descriptor) Same Descriptor
 251       objects as in |nested_types|, but indexed by "name" attribute
 252       in each Descriptor.
 253
 254     enum_types: (list of EnumDescriptors) EnumDescriptor references
 255       for all enums contained within this type.
 256     enum_types_by_name: (dict str ->EnumDescriptor) Same EnumDescriptor
 257       objects as in |enum_types|, but indexed by "name" attribute
 258       in each EnumDescriptor.
 259     enum_values_by_name: (dict str -> EnumValueDescriptor) Dict mapping
 260       from enum value name to EnumValueDescriptor for that value.
 261
 262     extensions: (list of FieldDescriptor) All extensions defined directly
 263       within this message type (NOT within a nested type).
 264     extensions_by_name: (dict, string -> FieldDescriptor) Same FieldDescriptor
 265       objects as |extensions|, but indexed by "name" attribute of each
 266       FieldDescriptor.
 267
 268     is_extendable:  Does this type define any extension ranges?
 269
 270     oneofs: (list of OneofDescriptor) The list of descriptors for oneof fields
 271       in this message.
 272     oneofs_by_name: (dict str -> OneofDescriptor) Same objects as in |oneofs|,
 273       but indexed by "name" attribute.
 274
 275     file: (FileDescriptor) Reference to file descriptor.
 276   """
 277
 278   if _USE_C_DESCRIPTORS:
 279     _C_DESCRIPTOR_CLASS = _message.Descriptor
 280
 281     def __new__(cls, name, full_name, filename, containing_type, fields,
 282                 nested_types, enum_types, extensions, options=None,
 283                 serialized_options=None,
 284                 is_extendable=True, extension_ranges=None, oneofs=None,
 285                 file=None, serialized_start=None, serialized_end=None,  # pylint: disable=redefined-builtin
 286                 syntax=None):
 287       _message.Message._CheckCalledFromGeneratedFile()
 288       return _message.default_pool.FindMessageTypeByName(full_name)
 289
 290   # NOTE(tmarek): The file argument redefining a builtin is nothing we can
 291   # fix right now since we don't know how many clients already rely on the
 292   # name of the argument.
 293   def __init__(self, name, full_name, filename, containing_type, fields,
 294                nested_types, enum_types, extensions, options=None,
 295                serialized_options=None,
 296                is_extendable=True, extension_ranges=None, oneofs=None,
 297                file=None, serialized_start=None, serialized_end=None,  # pylint: disable=redefined-builtin
 298                syntax=None):
 299     """Arguments to __init__() are as described in the description
 300     of Descriptor fields above.
 301
 302     Note that filename is an obsolete argument, that is not used anymore.
 303     Please use file.name to access this as an attribute.
 304     """
 305     super(Descriptor, self).__init__(
 306         options, 'MessageOptions', name, full_name, file,
 307         containing_type, serialized_start=serialized_start,
 308         serialized_end=serialized_end, serialized_options=serialized_options)
 309
 310     # We have fields in addition to fields_by_name and fields_by_number,
 311     # so that:
 312     #   1. Clients can index fields by "order in which they're listed."
 313     #   2. Clients can easily iterate over all fields with the terse
 314     #      syntax: for f in descriptor.fields: ...
 315     self.fields = fields
 316     for field in self.fields:
 317       field.containing_type = self
 318     self.fields_by_number = dict((f.number, f) for f in fields)
 319     self.fields_by_name = dict((f.name, f) for f in fields)
 320     self._fields_by_camelcase_name = None
 321
 322     self.nested_types = nested_types
 323     for nested_type in nested_types:
 324       nested_type.containing_type = self
 325     self.nested_types_by_name = dict((t.name, t) for t in nested_types)
 326
 327     self.enum_types = enum_types
 328     for enum_type in self.enum_types:
 329       enum_type.containing_type = self
 330     self.enum_types_by_name = dict((t.name, t) for t in enum_types)
 331     self.enum_values_by_name = dict(
 332         (v.name, v) for t in enum_types for v in t.values)
 333
 334     self.extensions = extensions
 335     for extension in self.extensions:
 336       extension.extension_scope = self
 337     self.extensions_by_name = dict((f.name, f) for f in extensions)
 338     self.is_extendable = is_extendable
 339     self.extension_ranges = extension_ranges
 340     self.oneofs = oneofs if oneofs is not None else []
 341     self.oneofs_by_name = dict((o.name, o) for o in self.oneofs)
 342     for oneof in self.oneofs:
 343       oneof.containing_type = self
 344     self.syntax = syntax or "proto2"
 345
 346   @property
 347   def fields_by_camelcase_name(self):
 348     if self._fields_by_camelcase_name is None:
 349       self._fields_by_camelcase_name = dict(
 350           (f.camelcase_name, f) for f in self.fields)
 351     return self._fields_by_camelcase_name
 352
 353   def EnumValueName(self, enum, value):
 354     """Returns the string name of an enum value.
 355
 356     This is just a small helper method to simplify a common operation.
 357
 358     Args:
 359       enum: string name of the Enum.
 360       value: int, value of the enum.
 361
 362     Returns:
 363       string name of the enum value.
 364
 365     Raises:
 366       KeyError if either the Enum doesn't exist or the value is not a valid
 367         value for the enum.
 368     """
 369     return self.enum_types_by_name[enum].values_by_number[value].name
 370
 371   def CopyToProto(self, proto):
 372     """Copies this to a descriptor_pb2.DescriptorProto.
 373
 374     Args:
 375       proto: An empty descriptor_pb2.DescriptorProto.
 376     """
 377     # This function is overridden to give a better doc comment.
 378     super(Descriptor, self).CopyToProto(proto)
 379
 380
 381 # TODO(robinson): We should have aggressive checking here,
 382 # for example:
 383 #   * If you specify a repeated field, you should not be allowed
 384 #     to specify a default value.
 385 #   * [Other examples here as needed].
 386 #
 387 # TODO(robinson): for this and other *Descriptor classes, we
 388 # might also want to lock things down aggressively (e.g.,
 389 # prevent clients from setting the attributes).  Having
 390 # stronger invariants here in general will reduce the number
 391 # of runtime checks we must do in reflection.py...
 392 class FieldDescriptor(DescriptorBase):
 393
 394   """Descriptor for a single field in a .proto file.
 395
 396   A FieldDescriptor instance has the following attributes:
 397
 398     name: (str) Name of this field, exactly as it appears in .proto.
 399     full_name: (str) Name of this field, including containing scope.  This is
 400       particularly relevant for extensions.
 401     camelcase_name: (str) Camelcase name of this field.
 402     index: (int) Dense, 0-indexed index giving the order that this
 403       field textually appears within its message in the .proto file.
 404     number: (int) Tag number declared for this field in the .proto file.
 405
 406     type: (One of the TYPE_* constants below) Declared type.
 407     cpp_type: (One of the CPPTYPE_* constants below) C++ type used to
 408       represent this field.
 409
 410     label: (One of the LABEL_* constants below) Tells whether this
 411       field is optional, required, or repeated.
 412     has_default_value: (bool) True if this field has a default value defined,
 413       otherwise false.
 414     default_value: (Varies) Default value of this field.  Only
 415       meaningful for non-repeated scalar fields.  Repeated fields
 416       should always set this to [], and non-repeated composite
 417       fields should always set this to None.
 418
 419     containing_type: (Descriptor) Descriptor of the protocol message
 420       type that contains this field.  Set by the Descriptor constructor
 421       if we're passed into one.
 422       Somewhat confusingly, for extension fields, this is the
 423       descriptor of the EXTENDED message, not the descriptor
 424       of the message containing this field.  (See is_extension and
 425       extension_scope below).
 426     message_type: (Descriptor) If a composite field, a descriptor
 427       of the message type contained in this field.  Otherwise, this is None.
 428     enum_type: (EnumDescriptor) If this field contains an enum, a
 429       descriptor of that enum.  Otherwise, this is None.
 430
 431     is_extension: True iff this describes an extension field.
 432     extension_scope: (Descriptor) Only meaningful if is_extension is True.
 433       Gives the message that immediately contains this extension field.
 434       Will be None iff we're a top-level (file-level) extension field.
 435
 436     options: (descriptor_pb2.FieldOptions) Protocol message field options or
 437       None to use default field options.
 438
 439     containing_oneof: (OneofDescriptor) If the field is a member of a oneof
 440       union, contains its descriptor. Otherwise, None.
 441
 442     file: (FileDescriptor) Reference to file descriptor.
 443   """
 444
 445   # Must be consistent with C++ FieldDescriptor::Type enum in
 446   # descriptor.h.
 447   #
 448   # TODO(robinson): Find a way to eliminate this repetition.
 449   TYPE_DOUBLE         = 1
 450   TYPE_FLOAT          = 2
 451   TYPE_INT64          = 3
 452   TYPE_UINT64         = 4
 453   TYPE_INT32          = 5
 454   TYPE_FIXED64        = 6
 455   TYPE_FIXED32        = 7
 456   TYPE_BOOL           = 8
 457   TYPE_STRING         = 9
 458   TYPE_GROUP          = 10
 459   TYPE_MESSAGE        = 11
 460   TYPE_BYTES          = 12
 461   TYPE_UINT32         = 13
 462   TYPE_ENUM           = 14
 463   TYPE_SFIXED32       = 15
 464   TYPE_SFIXED64       = 16
 465   TYPE_SINT32         = 17
 466   TYPE_SINT64         = 18
 467   MAX_TYPE            = 18
 468
 469   # Must be consistent with C++ FieldDescriptor::CppType enum in
 470   # descriptor.h.
 471   #
 472   # TODO(robinson): Find a way to eliminate this repetition.
 473   CPPTYPE_INT32       = 1
 474   CPPTYPE_INT64       = 2
 475   CPPTYPE_UINT32      = 3
 476   CPPTYPE_UINT64      = 4
 477   CPPTYPE_DOUBLE      = 5
 478   CPPTYPE_FLOAT       = 6
 479   CPPTYPE_BOOL        = 7
 480   CPPTYPE_ENUM        = 8
 481   CPPTYPE_STRING      = 9
 482   CPPTYPE_MESSAGE     = 10
 483   MAX_CPPTYPE         = 10
 484
 485   _PYTHON_TO_CPP_PROTO_TYPE_MAP = {
 486       TYPE_DOUBLE: CPPTYPE_DOUBLE,
 487       TYPE_FLOAT: CPPTYPE_FLOAT,
 488       TYPE_ENUM: CPPTYPE_ENUM,
 489       TYPE_INT64: CPPTYPE_INT64,
 490       TYPE_SINT64: CPPTYPE_INT64,
 491       TYPE_SFIXED64: CPPTYPE_INT64,
 492       TYPE_UINT64: CPPTYPE_UINT64,
 493       TYPE_FIXED64: CPPTYPE_UINT64,
 494       TYPE_INT32: CPPTYPE_INT32,
 495       TYPE_SFIXED32: CPPTYPE_INT32,
 496       TYPE_SINT32: CPPTYPE_INT32,
 497       TYPE_UINT32: CPPTYPE_UINT32,
 498       TYPE_FIXED32: CPPTYPE_UINT32,
 499       TYPE_BYTES: CPPTYPE_STRING,
 500       TYPE_STRING: CPPTYPE_STRING,
 501       TYPE_BOOL: CPPTYPE_BOOL,
 502       TYPE_MESSAGE: CPPTYPE_MESSAGE,
 503       TYPE_GROUP: CPPTYPE_MESSAGE
 504       }
 505
 506   # Must be consistent with C++ FieldDescriptor::Label enum in
 507   # descriptor.h.
 508   #
 509   # TODO(robinson): Find a way to eliminate this repetition.
 510   LABEL_OPTIONAL      = 1
 511   LABEL_REQUIRED      = 2
 512   LABEL_REPEATED      = 3
 513   MAX_LABEL           = 3
 514
 515   # Must be consistent with C++ constants kMaxNumber, kFirstReservedNumber,
 516   # and kLastReservedNumber in descriptor.h
 517   MAX_FIELD_NUMBER = (1 << 29) - 1
 518   FIRST_RESERVED_FIELD_NUMBER = 19000
 519   LAST_RESERVED_FIELD_NUMBER = 19999
 520
 521   if _USE_C_DESCRIPTORS:
 522     _C_DESCRIPTOR_CLASS = _message.FieldDescriptor
 523
 524     def __new__(cls, name, full_name, index, number, type, cpp_type, label,
 525                 default_value, message_type, enum_type, containing_type,
 526                 is_extension, extension_scope, options=None,
 527                 serialized_options=None,
 528                 has_default_value=True, containing_oneof=None, json_name=None,
 529                 file=None):  # pylint: disable=redefined-builtin
 530       _message.Message._CheckCalledFromGeneratedFile()
 531       if is_extension:
 532         return _message.default_pool.FindExtensionByName(full_name)
 533       else:
 534         return _message.default_pool.FindFieldByName(full_name)
 535
 536   def __init__(self, name, full_name, index, number, type, cpp_type, label,
 537                default_value, message_type, enum_type, containing_type,
 538                is_extension, extension_scope, options=None,
 539                serialized_options=None,
 540                has_default_value=True, containing_oneof=None, json_name=None,
 541                file=None):  # pylint: disable=redefined-builtin
 542     """The arguments are as described in the description of FieldDescriptor
 543     attributes above.
 544
 545     Note that containing_type may be None, and may be set later if necessary
 546     (to deal with circular references between message types, for example).
 547     Likewise for extension_scope.
 548     """
 549     super(FieldDescriptor, self).__init__(
 550         options, serialized_options, 'FieldOptions')
 551     self.name = name
 552     self.full_name = full_name
 553     self.file = file
 554     self._camelcase_name = None
 555     if json_name is None:
 556       self.json_name = _ToJsonName(name)
 557     else:
 558       self.json_name = json_name
 559     self.index = index
 560     self.number = number
 561     self.type = type
 562     self.cpp_type = cpp_type
 563     self.label = label
 564     self.has_default_value = has_default_value
 565     self.default_value = default_value
 566     self.containing_type = containing_type
 567     self.message_type = message_type
 568     self.enum_type = enum_type
 569     self.is_extension = is_extension
 570     self.extension_scope = extension_scope
 571     self.containing_oneof = containing_oneof
 572     if api_implementation.Type() == 'cpp':
 573       if is_extension:
 574         self._cdescriptor = _message.default_pool.FindExtensionByName(full_name)
 575       else:
 576         self._cdescriptor = _message.default_pool.FindFieldByName(full_name)
 577     else:
 578       self._cdescriptor = None
 579
 580   @property
 581   def camelcase_name(self):
 582     if self._camelcase_name is None:
 583       self._camelcase_name = _ToCamelCase(self.name)
 584     return self._camelcase_name
 585
 586   @staticmethod
 587   def ProtoTypeToCppProtoType(proto_type):
 588     """Converts from a Python proto type to a C++ Proto Type.
 589
 590     The Python ProtocolBuffer classes specify both the 'Python' datatype and the
 591     'C++' datatype - and they're not the same. This helper method should
 592     translate from one to another.
 593
 594     Args:
 595       proto_type: the Python proto type (descriptor.FieldDescriptor.TYPE_*)
 596     Returns:
 597       descriptor.FieldDescriptor.CPPTYPE_*, the C++ type.
 598     Raises:
 599       TypeTransformationError: when the Python proto type isn't known.
 600     """
 601     try:
 602       return FieldDescriptor._PYTHON_TO_CPP_PROTO_TYPE_MAP[proto_type]
 603     except KeyError:
 604       raise TypeTransformationError('Unknown proto_type: %s' % proto_type)
 605
 606
 607 class EnumDescriptor(_NestedDescriptorBase):
 608
 609   """Descriptor for an enum defined in a .proto file.
 610
 611   An EnumDescriptor instance has the following attributes:
 612
 613     name: (str) Name of the enum type.
 614     full_name: (str) Full name of the type, including package name
 615       and any enclosing type(s).
 616
 617     values: (list of EnumValueDescriptors) List of the values
 618       in this enum.
 619     values_by_name: (dict str -> EnumValueDescriptor) Same as |values|,
 620       but indexed by the "name" field of each EnumValueDescriptor.
 621     values_by_number: (dict int -> EnumValueDescriptor) Same as |values|,
 622       but indexed by the "number" field of each EnumValueDescriptor.
 623     containing_type: (Descriptor) Descriptor of the immediate containing
 624       type of this enum, or None if this is an enum defined at the
 625       top level in a .proto file.  Set by Descriptor's constructor
 626       if we're passed into one.
 627     file: (FileDescriptor) Reference to file descriptor.
 628     options: (descriptor_pb2.EnumOptions) Enum options message or
 629       None to use default enum options.
 630   """
 631
 632   if _USE_C_DESCRIPTORS:
 633     _C_DESCRIPTOR_CLASS = _message.EnumDescriptor
 634
 635     def __new__(cls, name, full_name, filename, values,
 636                 containing_type=None, options=None,
 637                 serialized_options=None, file=None,  # pylint: disable=redefined-builtin
 638                 serialized_start=None, serialized_end=None):
 639       _message.Message._CheckCalledFromGeneratedFile()
 640       return _message.default_pool.FindEnumTypeByName(full_name)
 641
 642   def __init__(self, name, full_name, filename, values,
 643                containing_type=None, options=None,
 644                serialized_options=None, file=None,  # pylint: disable=redefined-builtin
 645                serialized_start=None, serialized_end=None):
 646     """Arguments are as described in the attribute description above.
 647
 648     Note that filename is an obsolete argument, that is not used anymore.
 649     Please use file.name to access this as an attribute.
 650     """
 651     super(EnumDescriptor, self).__init__(
 652         options, 'EnumOptions', name, full_name, file,
 653         containing_type, serialized_start=serialized_start,
 654         serialized_end=serialized_end, serialized_options=serialized_options)
 655
 656     self.values = values
 657     for value in self.values:
 658       value.type = self
 659     self.values_by_name = dict((v.name, v) for v in values)
 660     # Values are reversed to ensure that the first alias is retained.
 661     self.values_by_number = dict((v.number, v) for v in reversed(values))
 662
 663   def CopyToProto(self, proto):
 664     """Copies this to a descriptor_pb2.EnumDescriptorProto.
 665
 666     Args:
 667       proto: An empty descriptor_pb2.EnumDescriptorProto.
 668     """
 669     # This function is overridden to give a better doc comment.
 670     super(EnumDescriptor, self).CopyToProto(proto)
 671
 672
 673 class EnumValueDescriptor(DescriptorBase):
 674
 675   """Descriptor for a single value within an enum.
 676
 677     name: (str) Name of this value.
 678     index: (int) Dense, 0-indexed index giving the order that this
 679       value appears textually within its enum in the .proto file.
 680     number: (int) Actual number assigned to this enum value.
 681     type: (EnumDescriptor) EnumDescriptor to which this value
 682       belongs.  Set by EnumDescriptor's constructor if we're
 683       passed into one.
 684     options: (descriptor_pb2.EnumValueOptions) Enum value options message or
 685       None to use default enum value options options.
 686   """
 687
 688   if _USE_C_DESCRIPTORS:
 689     _C_DESCRIPTOR_CLASS = _message.EnumValueDescriptor
 690
 691     def __new__(cls, name, index, number,
 692                 type=None,  # pylint: disable=redefined-builtin
 693                 options=None, serialized_options=None):
 694       _message.Message._CheckCalledFromGeneratedFile()
 695       # There is no way we can build a complete EnumValueDescriptor with the
 696       # given parameters (the name of the Enum is not known, for example).
 697       # Fortunately generated files just pass it to the EnumDescriptor()
 698       # constructor, which will ignore it, so returning None is good enough.
 699       return None
 700
 701   def __init__(self, name, index, number,
 702                type=None,  # pylint: disable=redefined-builtin
 703                options=None, serialized_options=None):
 704     """Arguments are as described in the attribute description above."""
 705     super(EnumValueDescriptor, self).__init__(
 706         options, serialized_options, 'EnumValueOptions')
 707     self.name = name
 708     self.index = index
 709     self.number = number
 710     self.type = type
 711
 712
 713 class OneofDescriptor(DescriptorBase):
 714   """Descriptor for a oneof field.
 715
 716     name: (str) Name of the oneof field.
 717     full_name: (str) Full name of the oneof field, including package name.
 718     index: (int) 0-based index giving the order of the oneof field inside
 719       its containing type.
 720     containing_type: (Descriptor) Descriptor of the protocol message
 721       type that contains this field.  Set by the Descriptor constructor
 722       if we're passed into one.
 723     fields: (list of FieldDescriptor) The list of field descriptors this
 724       oneof can contain.
 725   """
 726
 727   if _USE_C_DESCRIPTORS:
 728     _C_DESCRIPTOR_CLASS = _message.OneofDescriptor
 729
 730     def __new__(
 731         cls, name, full_name, index, containing_type, fields, options=None,
 732         serialized_options=None):
 733       _message.Message._CheckCalledFromGeneratedFile()
 734       return _message.default_pool.FindOneofByName(full_name)
 735
 736   def __init__(
 737       self, name, full_name, index, containing_type, fields, options=None,
 738       serialized_options=None):
 739     """Arguments are as described in the attribute description above."""
 740     super(OneofDescriptor, self).__init__(
 741         options, serialized_options, 'OneofOptions')
 742     self.name = name
 743     self.full_name = full_name
 744     self.index = index
 745     self.containing_type = containing_type
 746     self.fields = fields
 747
 748
 749 class ServiceDescriptor(_NestedDescriptorBase):
 750
 751   """Descriptor for a service.
 752
 753     name: (str) Name of the service.
 754     full_name: (str) Full name of the service, including package name.
 755     index: (int) 0-indexed index giving the order that this services
 756       definition appears withing the .proto file.
 757     methods: (list of MethodDescriptor) List of methods provided by this
 758       service.
 759     methods_by_name: (dict str -> MethodDescriptor) Same MethodDescriptor
 760       objects as in |methods_by_name|, but indexed by "name" attribute in each
 761       MethodDescriptor.
 762     options: (descriptor_pb2.ServiceOptions) Service options message or
 763       None to use default service options.
 764     file: (FileDescriptor) Reference to file info.
 765   """
 766
 767   if _USE_C_DESCRIPTORS:
 768     _C_DESCRIPTOR_CLASS = _message.ServiceDescriptor
 769
 770     def __new__(cls, name, full_name, index, methods, options=None,
 771                 serialized_options=None, file=None,  # pylint: disable=redefined-builtin
 772                 serialized_start=None, serialized_end=None):
 773       _message.Message._CheckCalledFromGeneratedFile()  # pylint: disable=protected-access
 774       return _message.default_pool.FindServiceByName(full_name)
 775
 776   def __init__(self, name, full_name, index, methods, options=None,
 777                serialized_options=None, file=None,  # pylint: disable=redefined-builtin
 778                serialized_start=None, serialized_end=None):
 779     super(ServiceDescriptor, self).__init__(
 780         options, 'ServiceOptions', name, full_name, file,
 781         None, serialized_start=serialized_start,
 782         serialized_end=serialized_end, serialized_options=serialized_options)
 783     self.index = index
 784     self.methods = methods
 785     self.methods_by_name = dict((m.name, m) for m in methods)
 786     # Set the containing service for each method in this service.
 787     for method in self.methods:
 788       method.containing_service = self
 789
 790   def FindMethodByName(self, name):
 791     """Searches for the specified method, and returns its descriptor."""
 792     return self.methods_by_name.get(name, None)
 793
 794   def CopyToProto(self, proto):
 795     """Copies this to a descriptor_pb2.ServiceDescriptorProto.
 796
 797     Args:
 798       proto: An empty descriptor_pb2.ServiceDescriptorProto.
 799     """
 800     # This function is overridden to give a better doc comment.
 801     super(ServiceDescriptor, self).CopyToProto(proto)
 802
 803
 804 class MethodDescriptor(DescriptorBase):
 805
 806   """Descriptor for a method in a service.
 807
 808   name: (str) Name of the method within the service.
 809   full_name: (str) Full name of method.
 810   index: (int) 0-indexed index of the method inside the service.
 811   containing_service: (ServiceDescriptor) The service that contains this
 812     method.
 813   input_type: The descriptor of the message that this method accepts.
 814   output_type: The descriptor of the message that this method returns.
 815   options: (descriptor_pb2.MethodOptions) Method options message or
 816     None to use default method options.
 817   """
 818
 819   if _USE_C_DESCRIPTORS:
 820     _C_DESCRIPTOR_CLASS = _message.MethodDescriptor
 821
 822     def __new__(cls, name, full_name, index, containing_service,
 823                 input_type, output_type, options=None, serialized_options=None):
 824       _message.Message._CheckCalledFromGeneratedFile()  # pylint: disable=protected-access
 825       return _message.default_pool.FindMethodByName(full_name)
 826
 827   def __init__(self, name, full_name, index, containing_service,
 828                input_type, output_type, options=None, serialized_options=None):
 829     """The arguments are as described in the description of MethodDescriptor
 830     attributes above.
 831
 832     Note that containing_service may be None, and may be set later if necessary.
 833     """
 834     super(MethodDescriptor, self).__init__(
 835         options, serialized_options, 'MethodOptions')
 836     self.name = name
 837     self.full_name = full_name
 838     self.index = index
 839     self.containing_service = containing_service
 840     self.input_type = input_type
 841     self.output_type = output_type
 842
 843
 844 class FileDescriptor(DescriptorBase):
 845   """Descriptor for a file. Mimics the descriptor_pb2.FileDescriptorProto.
 846
 847   Note that enum_types_by_name, extensions_by_name, and dependencies
 848   fields are only set by the message_factory module, and not by the
 849   generated proto code.
 850
 851   name: name of file, relative to root of source tree.
 852   package: name of the package
 853   syntax: string indicating syntax of the file (can be "proto2" or "proto3")
 854   serialized_pb: (str) Byte string of serialized
 855     descriptor_pb2.FileDescriptorProto.
 856   dependencies: List of other FileDescriptors this FileDescriptor depends on.
 857   public_dependencies: A list of FileDescriptors, subset of the dependencies
 858     above, which were declared as "public".
 859   message_types_by_name: Dict of message names and their descriptors.
 860   enum_types_by_name: Dict of enum names and their descriptors.
 861   extensions_by_name: Dict of extension names and their descriptors.
 862   services_by_name: Dict of services names and their descriptors.
 863   pool: the DescriptorPool this descriptor belongs to.  When not passed to the
 864     constructor, the global default pool is used.
 865   """
 866
 867   if _USE_C_DESCRIPTORS:
 868     _C_DESCRIPTOR_CLASS = _message.FileDescriptor
 869
 870     def __new__(cls, name, package, options=None,
 871                 serialized_options=None, serialized_pb=None,
 872                 dependencies=None, public_dependencies=None,
 873                 syntax=None, pool=None):
 874       # FileDescriptor() is called from various places, not only from generated
 875       # files, to register dynamic proto files and messages.
 876       if serialized_pb:
 877         # TODO(amauryfa): use the pool passed as argument. This will work only
 878         # for C++-implemented DescriptorPools.
 879         return _message.default_pool.AddSerializedFile(serialized_pb)
 880       else:
 881         return super(FileDescriptor, cls).__new__(cls)
 882
 883   def __init__(self, name, package, options=None,
 884                serialized_options=None, serialized_pb=None,
 885                dependencies=None, public_dependencies=None,
 886                syntax=None, pool=None):
 887     """Constructor."""
 888     super(FileDescriptor, self).__init__(
 889         options, serialized_options, 'FileOptions')
 890
 891     if pool is None:
 892       from google.protobuf import descriptor_pool
 893       pool = descriptor_pool.Default()
 894     self.pool = pool
 895     self.message_types_by_name = {}
 896     self.name = name
 897     self.package = package
 898     self.syntax = syntax or "proto2"
 899     self.serialized_pb = serialized_pb
 900
 901     self.enum_types_by_name = {}
 902     self.extensions_by_name = {}
 903     self.services_by_name = {}
 904     self.dependencies = (dependencies or [])
 905     self.public_dependencies = (public_dependencies or [])
 906
 907     if (api_implementation.Type() == 'cpp' and
 908         self.serialized_pb is not None):
 909       _message.default_pool.AddSerializedFile(self.serialized_pb)
 910
 911   def CopyToProto(self, proto):
 912     """Copies this to a descriptor_pb2.FileDescriptorProto.
 913
 914     Args:
 915       proto: An empty descriptor_pb2.FileDescriptorProto.
 916     """
 917     proto.ParseFromString(self.serialized_pb)
 918
 919
 920 def _ParseOptions(message, string):
 921   """Parses serialized options.
 922
 923   This helper function is used to parse serialized options in generated
 924   proto2 files. It must not be used outside proto2.
 925   """
 926   message.ParseFromString(string)
 927   return message
 928
 929
 930 def _ToCamelCase(name):
 931   """Converts name to camel-case and returns it."""
 932   capitalize_next = False
 933   result = []
 934
 935   for c in name:
 936     if c == '_':
 937       if result:
 938         capitalize_next = True
 939     elif capitalize_next:
 940       result.append(c.upper())
 941       capitalize_next = False
 942     else:
 943       result += c
 944
 945   # Lower-case the first letter.
 946   if result and result[0].isupper():
 947     result[0] = result[0].lower()
 948   return ''.join(result)
 949
 950
 951 def _OptionsOrNone(descriptor_proto):
 952   """Returns the value of the field `options`, or None if it is not set."""
 953   if descriptor_proto.HasField('options'):
 954     return descriptor_proto.options
 955   else:
 956     return None
 957
 958
 959 def _ToJsonName(name):
 960   """Converts name to Json name and returns it."""
 961   capitalize_next = False
 962   result = []
 963
 964   for c in name:
 965     if c == '_':
 966       capitalize_next = True
 967     elif capitalize_next:
 968       result.append(c.upper())
 969       capitalize_next = False
 970     else:
 971       result += c
 972
 973   return ''.join(result)
 974
 975
 976 def MakeDescriptor(desc_proto, package='', build_file_if_cpp=True,
 977                    syntax=None):
 978   """Make a protobuf Descriptor given a DescriptorProto protobuf.
 979
 980   Handles nested descriptors. Note that this is limited to the scope of defining
 981   a message inside of another message. Composite fields can currently only be
 982   resolved if the message is defined in the same scope as the field.
 983
 984   Args:
 985     desc_proto: The descriptor_pb2.DescriptorProto protobuf message.
 986     package: Optional package name for the new message Descriptor (string).
 987     build_file_if_cpp: Update the C++ descriptor pool if api matches.
 988                        Set to False on recursion, so no duplicates are created.
 989     syntax: The syntax/semantics that should be used.  Set to "proto3" to get
 990             proto3 field presence semantics.
 991   Returns:
 992     A Descriptor for protobuf messages.
 993   """
 994   if api_implementation.Type() == 'cpp' and build_file_if_cpp:
 995     # The C++ implementation requires all descriptors to be backed by the same
 996     # definition in the C++ descriptor pool. To do this, we build a
 997     # FileDescriptorProto with the same definition as this descriptor and build
 998     # it into the pool.
 999     from google.protobuf import descriptor_pb2
1000     file_descriptor_proto = descriptor_pb2.FileDescriptorProto()
1001     file_descriptor_proto.message_type.add().MergeFrom(desc_proto)
1002
1003     # Generate a random name for this proto file to prevent conflicts with any
1004     # imported ones. We need to specify a file name so the descriptor pool
1005     # accepts our FileDescriptorProto, but it is not important what that file
1006     # name is actually set to.
1007     proto_name = binascii.hexlify(os.urandom(16)).decode('ascii')
1008
1009     if package:
1010       file_descriptor_proto.name = os.path.join(package.replace('.', '/'),
1011                                                 proto_name + '.proto')
1012       file_descriptor_proto.package = package
1013     else:
1014       file_descriptor_proto.name = proto_name + '.proto'
1015
1016     _message.default_pool.Add(file_descriptor_proto)
1017     result = _message.default_pool.FindFileByName(file_descriptor_proto.name)
1018
1019     if _USE_C_DESCRIPTORS:
1020       return result.message_types_by_name[desc_proto.name]
1021
1022   full_message_name = [desc_proto.name]
1023   if package: full_message_name.insert(0, package)
1024
1025   # Create Descriptors for enum types
1026   enum_types = {}
1027   for enum_proto in desc_proto.enum_type:
1028     full_name = '.'.join(full_message_name + [enum_proto.name])
1029     enum_desc = EnumDescriptor(
1030       enum_proto.name, full_name, None, [
1031           EnumValueDescriptor(enum_val.name, ii, enum_val.number)
1032           for ii, enum_val in enumerate(enum_proto.value)])
1033     enum_types[full_name] = enum_desc
1034
1035   # Create Descriptors for nested types
1036   nested_types = {}
1037   for nested_proto in desc_proto.nested_type:
1038     full_name = '.'.join(full_message_name + [nested_proto.name])
1039     # Nested types are just those defined inside of the message, not all types
1040     # used by fields in the message, so no loops are possible here.
1041     nested_desc = MakeDescriptor(nested_proto,
1042                                  package='.'.join(full_message_name),
1043                                  build_file_if_cpp=False,
1044                                  syntax=syntax)
1045     nested_types[full_name] = nested_desc
1046
1047   fields = []
1048   for field_proto in desc_proto.field:
1049     full_name = '.'.join(full_message_name + [field_proto.name])
1050     enum_desc = None
1051     nested_desc = None
1052     if field_proto.json_name:
1053       json_name = field_proto.json_name
1054     else:
1055       json_name = None
1056     if field_proto.HasField('type_name'):
1057       type_name = field_proto.type_name
1058       full_type_name = '.'.join(full_message_name +
1059                                 [type_name[type_name.rfind('.')+1:]])
1060       if full_type_name in nested_types:
1061         nested_desc = nested_types[full_type_name]
1062       elif full_type_name in enum_types:
1063         enum_desc = enum_types[full_type_name]
1064       # Else type_name references a non-local type, which isn't implemented
1065     field = FieldDescriptor(
1066         field_proto.name, full_name, field_proto.number - 1,
1067         field_proto.number, field_proto.type,
1068         FieldDescriptor.ProtoTypeToCppProtoType(field_proto.type),
1069         field_proto.label, None, nested_desc, enum_desc, None, False, None,
1070         options=_OptionsOrNone(field_proto), has_default_value=False,
1071         json_name=json_name)
1072     fields.append(field)
1073
1074   desc_name = '.'.join(full_message_name)
1075   return Descriptor(desc_proto.name, desc_name, None, None, fields,
1076                     list(nested_types.values()), list(enum_types.values()), [],
1077                     options=_OptionsOrNone(desc_proto))