core.bones.string
=================

.. py:module:: core.bones.string


Attributes
----------

.. autoapisummary::

   core.bones.string.DB_TYPE_INDEXED


Classes
-------

.. autoapisummary::

   core.bones.string.StringBone


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

.. py:type:: DB_TYPE_INDEXED
   :canonical: dict[t.Literal['val', 'idx', 'sort_idx'], str]


.. py:class:: StringBone(*, caseSensitive = True, max_length = 254, min_length = None, natural_sorting = False, escape_html = True, **kwargs)

   Bases: :py:obj:`core.bones.raw.RawBone`


   The "StringBone" represents a data field that contains text values.

   Initializes a new StringBone.

   :param caseSensitive: When filtering for values in this bone, should it be case-sensitive?
   :param max_length: The maximum length allowed for values of this bone. Set to None for no limitation.
   :param min_length: The minimum length allowed for values of this bone. Set to None for no limitation.
   :param natural_sorting: Allows a more natural sorting
       than the default sorting on the plain values.
       This uses the .sort_idx property.
       `True` enables sorting according to DIN 5007 Variant 2.
       With passing a `callable`, a custom transformer method can be set
       that creates the value for the index property.
   :param escape_html: Replace some characters in the string with HTML-safe sequences with
       using :meth:`utils.string.escape` for safe use in HTML.
   :param kwargs: Inherited arguments from the BaseBone.


   .. py:attribute:: type
      :value: 'str'



   .. py:attribute:: caseSensitive
      :value: True



   .. py:attribute:: max_length
      :value: 254



   .. py:attribute:: min_length
      :value: None



   .. py:attribute:: escape_html
      :value: True



   .. py:method:: type_coerce_single_value(value)

      Convert a value to a string (if not already)

      Converts a value that is not a string into a string
      if a meaningful conversion is possible (simple data types only).



   .. py:method:: singleValueSerialize(value, skel, name, parentIndexed)

      Serializes a single value of this data field for storage in the database.

      :param value: The value to serialize.
          It should be a str value, if not it is forced with :meth:`type_coerce_single_value`.
      :param skel: The skeleton instance that this data field belongs to.
      :param name: The name of this data field.
      :param parentIndexed: A boolean value indicating whether the parent object has an index on
          this data field or not.
      :return: The serialized value.



   .. py:method:: singleValueUnserialize(value)

      Unserializes a single value of this data field from the database.

      :param value: The serialized value to unserialize.
      :return: The unserialized value.



   .. py:method:: getEmptyValue()

      Returns the empty value for this data field.

      :return: An empty string.



   .. py:method:: isEmpty(value)

      Determines whether a value for this data field is empty or not.

      :param value: The value to check for emptiness.
      :return: A boolean value indicating whether the value is empty or not.



   .. py:method:: isInvalid(value)

      Returns None if the value would be valid for
      this bone, an error-message otherwise.



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

      Returns None and the escaped value if the value would be valid for
      this bone, otherwise the empty value and an error-message.



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

      Builds and returns a database filter for this data field based on the provided raw filter data.

      :param name: The name of this data field.
      :param skel: The skeleton instance that this data field belongs to.
      :param dbFilter: The database filter to add query clauses to.
      :param rawFilter: A dictionary containing the raw filter data for this data field.
      :param prefix: An optional prefix to add to the query clause.
      :return: The database filter with the added query clauses.



   .. py:method:: buildDBSort(name, skel, query, params, postfix = '')


   .. py:method:: natural_sorting(value)

      Implements a default natural sorting transformer.

      The sorting is according to DIN 5007 Variant 2
      and sets ö and oe, etc. equal.



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

      Returns a list of unique index values for a given property name.

      :param skel: The skeleton instance.
      :param name: The name of the property.
      :return: A list of unique index values for the property.
      :raises NotImplementedError: If the StringBone has languages and the implementation
          for this case is not yet defined.



   .. py:method:: refresh(skel, bone_name)


   .. py:method:: structure()


   .. py:method:: v_func_valid_chars(valid_chars = string.printable)
      :classmethod:


      Returns a function that takes a string and checks whether it contains valid characters.
      If all characters of the string are valid, it returns None, and succeeds.
      If invalid characters are present, it returns an appropriate error message.

      :param valid_chars: An iterable of valid characters.
      :return: A function that takes a string and check whether it contains valid characters.

      Example for digits only:
      .. code-block:: python
          str_bone = StringBone(vfunc=StringBone.v_func_valid_chars(string.digits))