:py:mod:`core.bones.key`
========================

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


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

Classes
~~~~~~~

.. autoapisummary::

   core.bones.key.KeyBone




.. 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 str descr: The description of the KeyBone.
   :param bool readOnly: Whether the KeyBone is read-only.
   :param bool visible: Whether the KeyBone is visible.
   :param Union[None, List[str]] allowed_kinds: The allowed entity kinds for the KeyBone.
   :param bool check: Whether to check for entity existence.

   Initializes a new Bone.

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

      

   .. py:method:: singleValueFromClient(value, skel, bone_name, client_data)

      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:: unserialize(skel, name)

      This method is the inverse of :meth:serialize. It reads the key value from the datastore
      and populates the corresponding KeyBone in the Skeleton. The method converts the value from
      the datastore into an appropriate format for further use in the program.

      :param skel: The SkeletonValues instance this bone is a part of.
      :param name: The property name of this bone in the Skeleton (not the description).

      :return: A boolean value indicating whether the operation was successful. Returns True if
          the key value was successfully unserialized and added to the accessedValues of the
          Skeleton, and False otherwise.

      .. note:: The method contains an inner function, fixVals(val), which normalizes and
          validates the key values before populating the bone.


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

      This method serializes the KeyBone into a format that can be written to the datastore. It
      converts the key value from the Skeleton object into a format suitable for storage in the
      datastore.

      :param skel: The SkeletonInstance this bone is a part of.
      :param name: The property name of this bone in the Skeleton (not the description).
      :param parentIndexed: A boolean value indicating whether the parent entity is indexed or not.

      :return: A boolean value indicating whether the operation was successful. Returns True if
          the key value was successfully serialized and added to the datastore entity, and False
          otherwise.

      .. note:: Key values are always indexed, so the method discards any exclusion from indexing
          for key values.


   .. 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.