caikit.core.data_model.base =========================== .. py:module:: caikit.core.data_model.base .. autoapi-nested-parse:: Base classes and functionality for all data structures. Attributes ---------- .. autoapisummary:: caikit.core.data_model.base.log caikit.core.data_model.base.error Classes ------- .. autoapisummary:: caikit.core.data_model.base._DataBaseMetaClass caikit.core.data_model.base.DataBase Module Contents --------------- .. py:data:: log .. py:data:: error :type: Callable[Ellipsis, NoReturn] .. py:class:: _DataBaseMetaClass Bases: :py:obj:`type` .. py:attribute:: fields :type: Tuple .. py:attribute:: full_name :type: str .. py:attribute:: fields_enum_map :type: Dict .. py:attribute:: fields_enum_rev :type: Dict .. py:attribute:: _fields_oneofs_map :type: Dict .. py:attribute:: _fields_to_oneof :type: Dict .. py:attribute:: _fields_to_type :type: Dict .. py:attribute:: _fields_map :type: Tuple .. py:attribute:: _fields_message :type: Tuple .. py:attribute:: _fields_message_repeated :type: Tuple .. py:attribute:: _fields_enum :type: Tuple .. py:attribute:: _fields_enum_repeated :type: Tuple .. py:attribute:: _fields_primitive :type: Tuple .. py:attribute:: _fields_primitive_repeated :type: Tuple .. py:attribute:: _proto_class :type: ClassVar[Type[google.protobuf.message.Message]] Meta class for all structures in the data model. .. py:attribute:: class_registry .. py:attribute:: _MISSING_ATTRIBUTE :value: 'missing attribute' .. py:attribute:: _FWD_DECL_FIELDS :value: '__fwd_decl_fields__' .. py:attribute:: _BACKEND_ATTR :value: '_backend' .. py:attribute:: _WHICH_ONEOF_ATTR :value: '_which_oneof' .. py:attribute:: _USER_DEFINED_DEFAULTS :value: '__user_defined_defaults__' .. py:attribute:: _PROTO_TYPE_ORDER .. py:attribute:: supports_file_operations :value: False .. py:method:: parse_proto_descriptor(cls) :classmethod: Encapsulate the logic for parsing the protobuf descriptor here. This allows the parsing to be done as a post-process after metaclass initialization .. py:method:: _make_property_getter(field, oneof_name=None) :classmethod: This helper creates an @property attribute getter for the given field NOTE: This needs to live as a standalone function in order for the given field name to be properly bound to the closure for the attrs .. py:method:: _make_init(fields) :staticmethod: This helper creates an __init__ function for a class which has the arguments for all the fields and just sets them as instance attributes. .. py:method:: _sorted_oneof_field_names(oneof: google.protobuf.descriptor.OneofDescriptor) -> List[str] :classmethod: Helper to get the list of oneof fields while ensuring field names are sorted such that bool < int < float. This ensures that when iterating fields for which_oneof inference, lower-precedence types take precedence. .. py:class:: DataBase Base class for all structures in the data model. Notes: All leaves in the hierarchy of derived classes should have a corresponding protobufs class defined in the interface definitions. If not, an exception will be thrown at runtime. .. py:attribute:: PROTO_CONVERSION_SPECIAL_TYPES .. py:class:: OneofFieldVal Helper struct that backends can use to return information about values in oneofs along with which of the oneofs is currently valid .. py:attribute:: val :type: Any .. py:attribute:: which_oneof :type: str .. py:method:: __setattr__(name, val) Handle attribute setting for oneofs and named fields with delegation to backends as needed .. py:method:: get_proto_class() -> Type[google.protobuf.message.Message] :classmethod: .. py:method:: get_field_defaults() -> Type[google.protobuf.message.Message] :classmethod: Get mapping of fields to default values. Mapping will not include fields without defaults .. py:method:: get_field_message_type(field_name: str) -> Optional[type] :classmethod: Get the python type for the given field. This function relies on the metaclass to fill cls._fields_to_type. This is to avoid costly computation during runtime Args: field_name (str): Field name to check (AttributeError raised if name is invalid) Returns: field_type: type The data model class type for the given field .. py:method:: from_backend(backend) :classmethod: .. py:property:: backend :type: Optional[DataModelBackendBase] .. py:method:: which_oneof(oneof_name: str) -> Optional[str] Get the name of the oneof field set for the given oneof or None if no field is set .. py:method:: _infer_which_oneof(oneof_name: str, oneof_val: Any) -> Optional[str] :classmethod: Check each candidate field within the oneof to see if it's a type match NOTE: In the case where fields within a oneof have the same type, the first field whose type matches will be used! .. py:method:: _get_which_oneof_dict() -> Dict[str, str] .. py:method:: _get_type_for_field(field_name: str) -> type :classmethod: Helper class method to return the type hint for a particular field .. py:method:: _is_valid_type_for_field(field_name: str, val: Any) -> bool :classmethod: Check whether the given value is valid for the given field .. py:method:: from_binary_buffer(buf) :classmethod: Builds the data model object out of the binary string Args: buf: The binary buffer containing a serialized protobufs message Returns: A data model object instantiated from the protobufs message deserialized out of `buf` .. py:method:: from_proto(proto) :classmethod: Build a DataBase from protobufs. Args: proto: A protocol buffer to serialize from. Returns: protobufs: A DataBase object. .. py:method:: from_json(json_str, ignore_unknown_fields=False) :classmethod: Build a DataBase from a given JSON string. Use google's protobufs.json_format for deserialization Args: json_str (str or dict): A stringified JSON specification/dict of the data_model ignore_unknown_fields (bool): If True, ignores unknown JSON fields Returns: caikit.core.data_model.DataBase: A DataBase object. .. py:method:: from_file(file_obj: io.IOBase) :classmethod: :abstractmethod: Build a DataBase from a given file-like object. Args: file_obj IOBase: A file object that contains some representation of the dataobject Returns: caikit.core.data_model.DataBase: A DataBase object. .. py:method:: to_proto() Return a new protobufs populated with the information in this data structure. .. py:method:: to_binary_buffer() Returns a binary buffer with a serialized protobufs message of this data model .. py:method:: fill_proto(proto) Populate a protobufs with the values from this data model object. Args: proto: A protocol buffer to be populated. Returns: protobufs: The filled protobufs. Notes: The protobufs is filled in place, so the argument and the return value are the same at the end of this call. .. py:method:: to_dict() -> dict Convert to a dictionary representation. .. py:method:: to_kwargs() -> dict Convert to flat dictionary representation. (Like .to_dict, but not recursive) This keeps the attribute names of any fields backed by oneofs, instead of using the internal oneof field name .. py:method:: to_json(**kwargs) -> str Convert to a json representation. .. py:method:: to_file(file_obj: io.IOBase) -> Optional[File] :abstractmethod: Export a DataBaseObject into a file-like object `file_obj`. If the DataBase object has requirements around file name or file type it can return them via the optional "File" return object Args: file_obj IOBase: a file object to be filled Returns: file_descriptor: Optional[caikit.interfaces.common.data_mode.File] .. py:method:: __repr__() Human-friendly representation. .. py:method:: _field_to_dict_element(field) Convert field into a representation that can be placed into a dictionary. Recursively calls to_dict on other data model objects. .. py:method:: get_class_for_proto(proto: Union[google.protobuf.descriptor.Descriptor, google.protobuf.descriptor.FieldDescriptor, google.protobuf.descriptor.EnumDescriptor, google.protobuf.message.Message]) -> Type[DataBase] :staticmethod: Look up the data model class corresponding to the given protobuf If no data model is found, this raises an AttributeError Args: proto (Union[Descriptor, ProtoMessageType]) The proto name or descriptor to look up against Returns: dm_class (Type[DataBase]): The data model class corresponding to the given protobuf .. py:method:: get_class_for_name(class_name: str) -> Type[DataBase] :staticmethod: Look up the data model class corresponding to the given name This lookup attempts to encode various naming conventions that might be used, but it can fail in multiple ways: 1. No class with the given name is known 2. Multiple classes with the same name, but different qualified parents are found A ValueError will be raised if either of the above happens Args: class_name (str) The name of the class either as a fully-qualified protobuf name or as the unqualified class name Returns: dm_class (Type[DataBase]): The data model class corresponding to the given protobuf