core.bones.key
==============

.. py:module:: core.bones.key


Classes
-------

.. autoapisummary::

   core.bones.key.KeyBone


Module Contents
---------------

.. py:class:: KeyBone(*, descr = 'Key', readOnly = True, visible = False, allowed_kinds = None, check = False, **kwargs)

   Bases: :py:obj:`viur.core.bones.base.BaseBone`


   The KeyBone is used for managing keys in the database. It provides various methods for validating,
   converting, and storing key values, as well as querying the database.
   Key management is crucial for maintaining relationships between entities in the database, and the
   KeyBone class helps ensure that keys are handled correctly and efficiently throughout the system.

   :param descr: The description of the KeyBone.
   :param readOnly: Whether the KeyBone is read-only.
   :param visible: Whether the KeyBone is visible.
   :param allowed_kinds: The allowed entity kinds for the KeyBone.
   :param check: Whether to check for entity existence.

   Initializes a new Bone.


   .. py:attribute:: type
      :value: 'key'



   .. py:attribute:: allowed_kinds
      :value: None



   .. py:attribute:: check
      :value: False



   .. py:method:: singleValueFromClient(value, skel=None, bone_name=None, client_data=None, parse_only = False)

      Load a single value from a client

      :param value: The single value which should be loaded.
      :param skel: The SkeletonInstance where the value should be loaded into.
      :param bone_name: The bone name of this bone in the SkeletonInstance.
      :param client_data: The data taken from the client,
          a dictionary with usually bone names as key
      :return: A tuple. If the value is valid, the first element is
          the parsed value and the second is None.
          If the value is invalid or not parseable, the first element is a empty value
          and the second a list of *ReadFromClientError*.



   .. py:method:: singleValueUnserialize(val)

      Unserializes a single value of the bone from the stored database value.

      Derived bone classes should overwrite this method to implement their own logic for unserializing
      single values. The unserialized value should be suitable for use in the application logic.



   .. py:method:: unserialize(skel, name)

      Deserialize bone data from the datastore and populate the bone with the deserialized values.

      This function is the inverse of the serialize function. It converts data from the datastore
      into a format that can be used by the bones in the skeleton.

      :param skel: A SkeletonInstance object containing the values to be deserialized.
      :param name: The property name of the bone in its Skeleton (not the description).
      :returns: True if deserialization is successful, False otherwise.



   .. py:method:: serialize(skel, name, parentIndexed)

      Serializes this bone into a format that can be written into the datastore.

      :param skel: A SkeletonInstance object containing the values to be serialized.
      :param name: A string representing the property name of the bone in its Skeleton (not the description).
      :param parentIndexed: A boolean indicating whether the parent bone is indexed.
      :return: A boolean indicating whether the serialization was successful.



   .. py:method:: buildDBFilter(name, skel, dbFilter, rawFilter, prefix = None)

      This method parses the search filter specified by the client in their request and converts
      it into a format that can be understood by the datastore. It takes care of ignoring filters
      that do not target this bone and safely handles malformed data in the raw filter.

      :param name: The property name of this bone in the Skeleton (not the description).
      :param skel: The :class:viur.core.skeleton.SkeletonInstance this bone is a part of.
      :param dbFilter: The current :class:viur.core.db.Query instance the filters should be
          applied to.
      :param rawFilter: The dictionary of filters the client wants to have applied.
      :param prefix: An optional string to prepend to the filter key. Defaults to None.

      :return: The modified :class:viur.core.db.Query.

      The method takes the following steps:

      #. Decodes the provided key(s) from the raw filter.
      #. If the filter contains a list of keys, it iterates through the list, creating a new
          filter for each key and appending it to the list of queries.
      #. If the filter contains a single key, it applies the filter directly to the query.
      #. In case of any invalid key or other issues, it raises a RuntimeError.



   .. py:method:: _atomic_dump(value)

      One atomic value of the bone.