core.bones.string

Module Contents

Classes

StringBone

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

Attributes

DB_TYPE_INDEXED

core.bones.string.DB_TYPE_INDEXED: TypeAlias
class core.bones.string.StringBone(*, caseSensitive=True, max_length=254, min_length=None, natural_sorting=False, escape_html=True, **kwargs)

Bases: viur.core.bones.base.BaseBone

The “StringBone” represents a data field that contains text values.

Initializes a new StringBone.

Parameters:

  • caseSensitive (bool) – When filtering for values in this bone, should it be case-sensitive?

  • max_length (int | None) – The maximum length allowed for values of this bone. Set to None for no limitation.

  • min_length (int | None) – The minimum length allowed for values of this bone. Set to None for no limitation.

  • natural_sorting (bool | Callable) – 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.

  • escape_html (bool) – Replace some characters in the string with HTML-safe sequences with using utils.string.escape() for safe use in HTML.

  • kwargs – Inherited arguments from the BaseBone.

type = 'str'
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).

Parameters:

value (Any) –

Return type:

str

singleValueSerialize(value, skel, name, parentIndexed)

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

Parameters:

  • value (Any) – The value to serialize. It should be a str value, if not it is forced with type_coerce_single_value().

  • skel (core.skeleton.SkeletonInstance) – The skeleton instance that this data field belongs to.

  • name (str) – The name of this data field.

  • parentIndexed (bool) – A boolean value indicating whether the parent object has an index on this data field or not.

Returns:

The serialized value.

Return type:

str | DB_TYPE_INDEXED

singleValueUnserialize(value)

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

Parameters:

value (str | DB_TYPE_INDEXED) – The serialized value to unserialize.

Returns:

The unserialized value.

Return type:

str

getEmptyValue()

Returns the empty value for this data field.

Returns:

An empty string.

Return type:

str

isEmpty(value)

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

Parameters:

value – The value to check for emptiness.

Returns:

A boolean value indicating whether the value is empty or not.

isInvalid(value)

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

Parameters:

value (Any) –

Return type:

str | None

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.

buildDBFilter(name, skel, dbFilter, rawFilter, prefix=None)

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

Parameters:

  • name (str) – The name of this data field.

  • skel (core.skeleton.SkeletonInstance) – The skeleton instance that this data field belongs to.

  • dbFilter (viur.core.db.Query) – The database filter to add query clauses to.

  • rawFilter (dict) – A dictionary containing the raw filter data for this data field.

  • prefix (Optional[str]) – An optional prefix to add to the query clause.

Returns:

The database filter with the added query clauses.

Return type:

viur.core.db.Query

buildDBSort(name, skel, query, params, postfix='')

Same as buildDBFilter, but this time its not about filtering the results, but by sorting them. Again: query is controlled by the client, so you must expect and safely handle malformed data!

Parameters:

  • name (str) – The property-name this bone has in its Skeleton (not the description!)

  • skel (core.skeleton.SkeletonInstance) – The viur.core.skeleton.Skeleton instance this bone is part of

  • dbFilter – The current viur.core.db.Query instance the filters should be applied to

  • query (viur.core.db.Query) – The dictionary of filters the client wants to have applied

  • postfix (str) – Inherited classes may use this to add a postfix to the porperty name

  • params (dict) –

Returns:

The modified viur.core.db.Query, None if the query is unsatisfiable.

Return type:

Optional[viur.core.db.Query]

natural_sorting(value)

Implements a default natural sorting transformer.

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

Parameters:

value (str | None) –

Return type:

str | None

getSearchTags(skel, name)

Returns a set of lowercased words that represent searchable tags for the given bone.

Parameters:
Returns:

A set of lowercased words representing searchable tags.

Return type:

set[str]

getUniquePropertyIndexValues(skel, name)

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

Parameters:
Returns:

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.

Return type:

list[str]

refresh(skel, bone_name)

Refresh all values we might have cached from other entities.

Parameters:
Return type:

None

structure()

Describes the bone and its settings as an JSON-serializable dict. This function has to be implemented for subsequent, specialized bone types.

Return type:

dict

classmethod v_func_valid_chars(valid_chars=string.printable)

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.

Parameters:

valid_chars (Iterable) – An iterable of valid characters.

Returns:

A function that takes a string and check whether it contains valid characters.

Return type:

Callable

Example for digits only: .. code-block:: python

str_bone = StringBone(vfunc=StringBone.v_func_valid_chars(string.digits))