protobuf 6.33.0__cp39-abi3-manylinux2014_s390x.whl

google/protobuf/message.py

@@ -0,0 +1,448 @@
+# Protocol Buffers - Google's data interchange format
+# Copyright 2008 Google Inc.  All rights reserved.
+#
+# Use of this source code is governed by a BSD-style
+# license that can be found in the LICENSE file or at
+# https://developers.google.com/open-source/licenses/bsd
+
+# TODO: We should just make these methods all "pure-virtual" and move
+# all implementation out, into reflection.py for now.
+
+
+"""Contains an abstract base class for protocol messages."""
+
+__author__ = 'robinson@google.com (Will Robinson)'
+
+_INCONSISTENT_MESSAGE_ATTRIBUTES = ('Extensions',)
+
+
+class Error(Exception):
+  """Base error type for this module."""
+  pass
+
+
+class DecodeError(Error):
+  """Exception raised when deserializing messages."""
+  pass
+
+
+class EncodeError(Error):
+  """Exception raised when serializing messages."""
+  pass
+
+
+class Message(object):
+
+  """Abstract base class for protocol messages.
+
+  Protocol message classes are almost always generated by the protocol
+  compiler.  These generated types subclass Message and implement the methods
+  shown below.
+  """
+
+  # TODO: Link to an HTML document here.
+
+  # TODO: Document that instances of this class will also
+  # have an Extensions attribute with __getitem__ and __setitem__.
+  # Again, not sure how to best convey this.
+
+  # TODO: Document these fields and methods.
+
+  __slots__ = []
+
+  #: The :class:`google.protobuf.Descriptor`
+  # for this message type.
+  DESCRIPTOR = None
+
+  def __deepcopy__(self, memo=None):
+    clone = type(self)()
+    clone.MergeFrom(self)
+    return clone
+
+  def __dir__(self):
+    """Provides the list of all accessible Message attributes."""
+    message_attributes = set(super().__dir__())
+
+    # TODO: Remove this once the UPB implementation is improved.
+    # The UPB proto implementation currently doesn't provide proto fields as
+    # attributes and they have to added.
+    if self.DESCRIPTOR is not None:
+      for field in self.DESCRIPTOR.fields:
+        message_attributes.add(field.name)
+
+    # The Fast C++ proto implementation provides inaccessible attributes that
+    # have to be removed.
+    for attribute in _INCONSISTENT_MESSAGE_ATTRIBUTES:
+      if attribute not in message_attributes:
+        continue
+      try:
+        getattr(self, attribute)
+      except AttributeError:
+        message_attributes.remove(attribute)
+
+    return sorted(message_attributes)
+
+  def __eq__(self, other_msg):
+    """Recursively compares two messages by value and structure."""
+    raise NotImplementedError
+
+  def __ne__(self, other_msg):
+    # Can't just say self != other_msg, since that would infinitely recurse. :)
+    return not self == other_msg
+
+  def __hash__(self):
+    raise TypeError('unhashable object')
+
+  def __str__(self):
+    """Outputs a human-readable representation of the message."""
+    raise NotImplementedError
+
+  def __unicode__(self):
+    """Outputs a human-readable representation of the message."""
+    raise NotImplementedError
+
+  def __contains__(self, field_name_or_key):
+    """Checks if a certain field is set for the message.
+
+    Has presence fields return true if the field is set, false if the field is
+    not set. Fields without presence do raise `ValueError` (this includes
+    repeated fields, map fields, and implicit presence fields).
+
+    If field_name is not defined in the message descriptor, `ValueError` will
+    be raised.
+    Note: WKT Struct checks if the key is contained in fields. ListValue checks
+    if the item is contained in the list.
+
+    Args:
+      field_name_or_key: For Struct, the key (str) of the fields map. For
+        ListValue, any type that may be contained in the list. For other
+        messages, name of the field (str) to check for presence.
+
+    Returns:
+      bool: For Struct, whether the item is contained in fields. For ListValue,
+            whether the item is contained in the list. For other message,
+            whether a value has been set for the named field.
+
+    Raises:
+      ValueError: For normal messages,  if the `field_name_or_key` is not a
+                  member of this message or `field_name_or_key` is not a string.
+    """
+    raise NotImplementedError
+
+  def MergeFrom(self, other_msg):
+    """Merges the contents of the specified message into current message.
+
+    This method merges the contents of the specified message into the current
+    message. Singular fields that are set in the specified message overwrite
+    the corresponding fields in the current message. Repeated fields are
+    appended. Singular sub-messages and groups are recursively merged.
+
+    Args:
+      other_msg (Message): A message to merge into the current message.
+    """
+    raise NotImplementedError
+
+  def CopyFrom(self, other_msg):
+    """Copies the content of the specified message into the current message.
+
+    The method clears the current message and then merges the specified
+    message using MergeFrom.
+
+    Args:
+      other_msg (Message): A message to copy into the current one.
+    """
+    if self is other_msg:
+      return
+    self.Clear()
+    self.MergeFrom(other_msg)
+
+  def Clear(self):
+    """Clears all data that was set in the message."""
+    raise NotImplementedError
+
+  def SetInParent(self):
+    """Mark this as present in the parent.
+
+    This normally happens automatically when you assign a field of a
+    sub-message, but sometimes you want to make the sub-message
+    present while keeping it empty.  If you find yourself using this,
+    you may want to reconsider your design.
+    """
+    raise NotImplementedError
+
+  def IsInitialized(self):
+    """Checks if the message is initialized.
+
+    Returns:
+      bool: The method returns True if the message is initialized (i.e. all of
+      its required fields are set).
+    """
+    raise NotImplementedError
+
+  # TODO: MergeFromString() should probably return None and be
+  # implemented in terms of a helper that returns the # of bytes read.  Our
+  # deserialization routines would use the helper when recursively
+  # deserializing, but the end user would almost always just want the no-return
+  # MergeFromString().
+
+  def MergeFromString(self, serialized):
+    """Merges serialized protocol buffer data into this message.
+
+    When we find a field in `serialized` that is already present
+    in this message:
+
+    -   If it's a "repeated" field, we append to the end of our list.
+    -   Else, if it's a scalar, we overwrite our field.
+    -   Else, (it's a nonrepeated composite), we recursively merge
+        into the existing composite.
+
+    Args:
+      serialized (bytes): Any object that allows us to call
+        ``memoryview(serialized)`` to access a string of bytes using the
+        buffer interface.
+
+    Returns:
+      int: The number of bytes read from `serialized`.
+      For non-group messages, this will always be `len(serialized)`,
+      but for messages which are actually groups, this will
+      generally be less than `len(serialized)`, since we must
+      stop when we reach an ``END_GROUP`` tag.  Note that if
+      we *do* stop because of an ``END_GROUP`` tag, the number
+      of bytes returned does not include the bytes
+      for the ``END_GROUP`` tag information.
+
+    Raises:
+      DecodeError: if the input cannot be parsed.
+    """
+    # TODO: Document handling of unknown fields.
+    # TODO: When we switch to a helper, this will return None.
+    raise NotImplementedError
+
+  def ParseFromString(self, serialized):
+    """Parse serialized protocol buffer data in binary form into this message.
+
+    Like :func:`MergeFromString()`, except we clear the object first.
+
+    Raises:
+      message.DecodeError if the input cannot be parsed.
+    """
+    self.Clear()
+    return self.MergeFromString(serialized)
+
+  def SerializeToString(self, **kwargs):
+    """Serializes the protocol message to a binary string.
+
+    Keyword Args:
+      deterministic (bool): If true, requests deterministic serialization
+        of the protobuf, with predictable ordering of map keys.
+
+    Returns:
+      A binary string representation of the message if all of the required
+      fields in the message are set (i.e. the message is initialized).
+
+    Raises:
+      EncodeError: if the message isn't initialized (see :func:`IsInitialized`).
+    """
+    raise NotImplementedError
+
+  def SerializePartialToString(self, **kwargs):
+    """Serializes the protocol message to a binary string.
+
+    This method is similar to SerializeToString but doesn't check if the
+    message is initialized.
+
+    Keyword Args:
+      deterministic (bool): If true, requests deterministic serialization
+        of the protobuf, with predictable ordering of map keys.
+
+    Returns:
+      bytes: A serialized representation of the partial message.
+    """
+    raise NotImplementedError
+
+  # TODO: Decide whether we like these better
+  # than auto-generated has_foo() and clear_foo() methods
+  # on the instances themselves.  This way is less consistent
+  # with C++, but it makes reflection-type access easier and
+  # reduces the number of magically autogenerated things.
+  #
+  # TODO: Be sure to document (and test) exactly
+  # which field names are accepted here.  Are we case-sensitive?
+  # What do we do with fields that share names with Python keywords
+  # like 'lambda' and 'yield'?
+  #
+  # nnorwitz says:
+  # """
+  # Typically (in python), an underscore is appended to names that are
+  # keywords. So they would become lambda_ or yield_.
+  # """
+  def ListFields(self):
+    """Returns a list of (FieldDescriptor, value) tuples for present fields.
+
+    A message field is non-empty if HasField() would return true. A singular
+    primitive field is non-empty if HasField() would return true in proto2 or it
+    is non zero in proto3. A repeated field is non-empty if it contains at least
+    one element. The fields are ordered by field number.
+
+    Returns:
+      list[tuple(FieldDescriptor, value)]: field descriptors and values
+      for all fields in the message which are not empty. The values vary by
+      field type.
+    """
+    raise NotImplementedError
+
+  def HasField(self, field_name):
+    """Checks if a certain field is set for the message.
+
+    For a oneof group, checks if any field inside is set. Note that if the
+    field_name is not defined in the message descriptor, :exc:`ValueError` will
+    be raised.
+
+    Args:
+      field_name (str): The name of the field to check for presence.
+
+    Returns:
+      bool: Whether a value has been set for the named field.
+
+    Raises:
+      ValueError: if the `field_name` is not a member of this message.
+    """
+    raise NotImplementedError
+
+  def ClearField(self, field_name):
+    """Clears the contents of a given field.
+
+    Inside a oneof group, clears the field set. If the name neither refers to a
+    defined field or oneof group, :exc:`ValueError` is raised.
+
+    Args:
+      field_name (str): The name of the field to check for presence.
+
+    Raises:
+      ValueError: if the `field_name` is not a member of this message.
+    """
+    raise NotImplementedError
+
+  def WhichOneof(self, oneof_group):
+    """Returns the name of the field that is set inside a oneof group.
+
+    If no field is set, returns None.
+
+    Args:
+      oneof_group (str): the name of the oneof group to check.
+
+    Returns:
+      str or None: The name of the group that is set, or None.
+
+    Raises:
+      ValueError: no group with the given name exists
+    """
+    raise NotImplementedError
+
+  def HasExtension(self, field_descriptor):
+    """Checks if a certain extension is present for this message.
+
+    Extensions are retrieved using the :attr:`Extensions` mapping (if present).
+
+    Args:
+      field_descriptor: The field descriptor for the extension to check.
+
+    Returns:
+      bool: Whether the extension is present for this message.
+
+    Raises:
+      KeyError: if the extension is repeated. Similar to repeated fields,
+        there is no separate notion of presence: a "not present" repeated
+        extension is an empty list.
+    """
+    raise NotImplementedError
+
+  def ClearExtension(self, field_descriptor):
+    """Clears the contents of a given extension.
+
+    Args:
+      field_descriptor: The field descriptor for the extension to clear.
+    """
+    raise NotImplementedError
+
+  def UnknownFields(self):
+    """Returns the UnknownFieldSet.
+
+    Returns:
+      UnknownFieldSet: The unknown fields stored in this message.
+    """
+    raise NotImplementedError
+
+  def DiscardUnknownFields(self):
+    """Clears all fields in the :class:`UnknownFieldSet`.
+
+    This operation is recursive for nested message.
+    """
+    raise NotImplementedError
+
+  def ByteSize(self):
+    """Returns the serialized size of this message.
+
+    Recursively calls ByteSize() on all contained messages.
+
+    Returns:
+      int: The number of bytes required to serialize this message.
+    """
+    raise NotImplementedError
+
+  @classmethod
+  def FromString(cls, s):
+    raise NotImplementedError
+
+  def _SetListener(self, message_listener):
+    """Internal method used by the protocol message implementation.
+    Clients should not call this directly.
+
+    Sets a listener that this message will call on certain state transitions.
+
+    The purpose of this method is to register back-edges from children to
+    parents at runtime, for the purpose of setting "has" bits and
+    byte-size-dirty bits in the parent and ancestor objects whenever a child or
+    descendant object is modified.
+
+    If the client wants to disconnect this Message from the object tree, she
+    explicitly sets callback to None.
+
+    If message_listener is None, unregisters any existing listener.  Otherwise,
+    message_listener must implement the MessageListener interface in
+    internal/message_listener.py, and we discard any listener registered
+    via a previous _SetListener() call.
+    """
+    raise NotImplementedError
+
+  def __getstate__(self):
+    """Support the pickle protocol."""
+    return dict(serialized=self.SerializePartialToString())
+
+  def __setstate__(self, state):
+    """Support the pickle protocol."""
+    self.__init__()
+    serialized = state['serialized']
+    # On Python 3, using encoding='latin1' is required for unpickling
+    # protos pickled by Python 2.
+    if not isinstance(serialized, bytes):
+      serialized = serialized.encode('latin1')
+    self.ParseFromString(serialized)
+
+  def __reduce__(self):
+    message_descriptor = self.DESCRIPTOR
+    if message_descriptor.containing_type is None:
+      return type(self), (), self.__getstate__()
+    # the message type must be nested.
+    # Python does not pickle nested classes; use the symbol_database on the
+    # receiving end.
+    container = message_descriptor
+    return (_InternalConstructMessage, (container.full_name,),
+            self.__getstate__())
+
+
+def _InternalConstructMessage(full_name):
+  """Constructs a nested message."""
+  from google.protobuf import symbol_database  # pylint:disable=g-import-not-at-top
+
+  return symbol_database.Default().GetSymbol(full_name)()

google/protobuf/message_factory.py

@@ -0,0 +1,190 @@
+# Protocol Buffers - Google's data interchange format
+# Copyright 2008 Google Inc.  All rights reserved.
+#
+# Use of this source code is governed by a BSD-style
+# license that can be found in the LICENSE file or at
+# https://developers.google.com/open-source/licenses/bsd
+
+"""Provides a factory class for generating dynamic messages.
+
+The easiest way to use this class is if you have access to the FileDescriptor
+protos containing the messages you want to create you can just do the following:
+
+message_classes = message_factory.GetMessages(iterable_of_file_descriptors)
+my_proto_instance = message_classes['some.proto.package.MessageName']()
+"""
+
+__author__ = 'matthewtoia@google.com (Matt Toia)'
+
+import warnings
+
+from google.protobuf import descriptor_pool
+from google.protobuf import message
+from google.protobuf.internal import api_implementation
+
+if api_implementation.Type() == 'python':
+  from google.protobuf.internal import python_message as message_impl
+else:
+  from google.protobuf.pyext import cpp_message as message_impl  # pylint: disable=g-import-not-at-top
+
+
+# The type of all Message classes.
+_GENERATED_PROTOCOL_MESSAGE_TYPE = message_impl.GeneratedProtocolMessageType
+
+
+def GetMessageClass(descriptor):
+  """Obtains a proto2 message class based on the passed in descriptor.
+
+  Passing a descriptor with a fully qualified name matching a previous
+  invocation will cause the same class to be returned.
+
+  Args:
+    descriptor: The descriptor to build from.
+
+  Returns:
+    A class describing the passed in descriptor.
+  """
+  concrete_class = getattr(descriptor, '_concrete_class', None)
+  if concrete_class:
+    return concrete_class
+  return _InternalCreateMessageClass(descriptor)
+
+
+def GetMessageClassesForFiles(files, pool):
+  """Gets all the messages from specified files.
+
+  This will find and resolve dependencies, failing if the descriptor
+  pool cannot satisfy them.
+
+  This will not return the classes for nested types within those classes, for
+  those, use GetMessageClass() on the nested types within their containing
+  messages.
+
+  For example, for the message:
+
+  message NestedTypeMessage {
+    message NestedType {
+      string data = 1;
+    }
+    NestedType nested = 1;
+  }
+
+  NestedTypeMessage will be in the result, but not
+  NestedTypeMessage.NestedType.
+
+  Args:
+    files: The file names to extract messages from.
+    pool: The descriptor pool to find the files including the dependent files.
+
+  Returns:
+    A dictionary mapping proto names to the message classes.
+  """
+  result = {}
+  for file_name in files:
+    file_desc = pool.FindFileByName(file_name)
+    for desc in file_desc.message_types_by_name.values():
+      result[desc.full_name] = GetMessageClass(desc)
+
+    # While the extension FieldDescriptors are created by the descriptor pool,
+    # the python classes created in the factory need them to be registered
+    # explicitly, which is done below.
+    #
+    # The call to RegisterExtension will specifically check if the
+    # extension was already registered on the object and either
+    # ignore the registration if the original was the same, or raise
+    # an error if they were different.
+
+    for extension in file_desc.extensions_by_name.values():
+      _ = GetMessageClass(extension.containing_type)
+      if api_implementation.Type() != 'python':
+        # TODO: Remove this check here. Duplicate extension
+        # register check should be in descriptor_pool.
+        if extension is not pool.FindExtensionByNumber(
+            extension.containing_type, extension.number
+        ):
+          raise ValueError('Double registration of Extensions')
+      # Recursively load protos for extension field, in order to be able to
+      # fully represent the extension. This matches the behavior for regular
+      # fields too.
+      if extension.message_type:
+        GetMessageClass(extension.message_type)
+  return result
+
+
+def _InternalCreateMessageClass(descriptor):
+  """Builds a proto2 message class based on the passed in descriptor.
+
+  Args:
+    descriptor: The descriptor to build from.
+
+  Returns:
+    A class describing the passed in descriptor.
+  """
+  descriptor_name = descriptor.name
+  result_class = _GENERATED_PROTOCOL_MESSAGE_TYPE(
+      descriptor_name,
+      (message.Message,),
+      {
+          'DESCRIPTOR': descriptor,
+          # If module not set, it wrongly points to message_factory module.
+          '__module__': None,
+      },
+  )
+  for field in descriptor.fields:
+    if field.message_type:
+      GetMessageClass(field.message_type)
+
+  for extension in result_class.DESCRIPTOR.extensions:
+    extended_class = GetMessageClass(extension.containing_type)
+    if api_implementation.Type() != 'python':
+      # TODO: Remove this check here. Duplicate extension
+      # register check should be in descriptor_pool.
+      pool = extension.containing_type.file.pool
+      if extension is not pool.FindExtensionByNumber(
+          extension.containing_type, extension.number
+      ):
+        raise ValueError('Double registration of Extensions')
+    if extension.message_type:
+      GetMessageClass(extension.message_type)
+  return result_class
+
+
+# Deprecated. Please use GetMessageClass() or GetMessageClassesForFiles()
+# method above instead.
+class MessageFactory(object):
+  """Factory for creating Proto2 messages from descriptors in a pool."""
+
+  def __init__(self, pool=None):
+    """Initializes a new factory."""
+    self.pool = pool or descriptor_pool.DescriptorPool()
+
+
+def GetMessages(file_protos, pool=None):
+  """Builds a dictionary of all the messages available in a set of files.
+
+  Args:
+    file_protos: Iterable of FileDescriptorProto to build messages out of.
+    pool: The descriptor pool to add the file protos.
+
+  Returns:
+    A dictionary mapping proto names to the message classes. This will include
+    any dependent messages as well as any messages defined in the same file as
+    a specified message.
+  """
+  # The cpp implementation of the protocol buffer library requires to add the
+  # message in topological order of the dependency graph.
+  des_pool = pool or descriptor_pool.DescriptorPool()
+  file_by_name = {file_proto.name: file_proto for file_proto in file_protos}
+
+  def _AddFile(file_proto):
+    for dependency in file_proto.dependency:
+      if dependency in file_by_name:
+        # Remove from elements to be visited, in order to cut cycles.
+        _AddFile(file_by_name.pop(dependency))
+    des_pool.Add(file_proto)
+
+  while file_by_name:
+    _AddFile(file_by_name.popitem()[1])
+  return GetMessageClassesForFiles(
+      [file_proto.name for file_proto in file_protos], des_pool
+  )