core.skeleton.skeleton

Classes

SeoKeyBone

Special kind of StringBone saving its contents as viurCurrentSeoKeys into the entity's viur dict.

Skeleton

This is a container-object holding information about one database entity.

Module Contents

class core.skeleton.skeleton.SeoKeyBone(*, caseSensitive=True, max_length=254, min_length=None, natural_sorting=False, escape_html=True, **kwargs)

Bases: core.bones.string.StringBone

Special kind of StringBone saving its contents as viurCurrentSeoKeys into the entity’s viur dict.

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.

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.

Parameters:

  • skel (core.skeleton.instance.SkeletonInstance) – A SkeletonInstance object containing the values to be deserialized.

  • name (str) – The property name of the bone in its Skeleton (not the description).

Returns:

True if deserialization is successful, False otherwise.

Return type:

bool

serialize(skel, name, parentIndexed)

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

Parameters:

  • skel (core.skeleton.instance.SkeletonInstance) – A SkeletonInstance object containing the values to be serialized.

  • name (str) – A string representing the property name of the bone in its Skeleton (not the description).

  • parentIndexed (bool) – A boolean indicating whether the parent bone is indexed.

Returns:

A boolean indicating whether the serialization was successful.

Return type:

bool

class core.skeleton.skeleton.Skeleton(*args, **kwargs)

Bases: core.skeleton.meta.BaseSkeleton

This is a container-object holding information about one database entity.

It has to be sub-classed with individual information about the kindName of the entities and its specific data attributes, the so called bones. The Skeleton stores its bones in an OrderedDict-Instance, so the definition order of the contained bones remains constant.

Variables:

  • key (server.bones.BaseBone) – This bone stores the current database key of this entity. Assigning to this bones value is dangerous and does not affect the actual key its stored in.

  • creationdate (server.bones.DateBone) – The date and time where this entity has been created.

  • changedate (server.bones.DateBone) – The date and time of the last change to this entity.

kindName: str

Specifies the entity kind name this Skeleton is associated with. Will be determined automatically when not explicitly set.

database_adapters: core.skeleton.adapter.DatabaseAdapter | Iterable[core.skeleton.adapter.DatabaseAdapter] | None

Custom database adapters. Allows to hook special functionalities that during skeleton modifications.

subSkels
interBoneValidations: list[Callable[[Skeleton], list[core.bones.base.ReadFromClientError]]] = []
__seo_key_trans
key
shortkey
name
creationdate
changedate
viurCurrentSeoKeys
__repr__()
__str__()
classmethod all(skel, **kwargs)

Create a query with the current Skeletons kindName.

Returns:

A db.Query object which allows for entity filtering and sorting.

Return type:

viur.core.db.Query

classmethod fromClient(skel, data, *, amend=False, ignore=None)

This function works similar to setValues(), except that the values retrieved from data are checked against the bones and their validity checks.

Even if this function returns False, all bones are guaranteed to be in a valid state. The ones which have been read correctly are set to their valid values; Bones with invalid values are set back to a safe default (None in most cases). So its possible to call write() afterwards even if reading data with this function failed (through this might violates the assumed consistency-model).

Parameters:

  • skel (core.skeleton.instance.SkeletonInstance) – The skeleton instance to be filled.

  • data (dict[str, list[str] | str]) – Dictionary from which the data is read.

  • amend (bool) – Defines whether content of data may be incomplete to amend the skel, which is useful for edit-actions.

  • ignore (Optional[Iterable[str]]) – optional list of bones to be ignored; Defaults to all readonly-bones when set to None.

Returns:

True if all data was successfully read and complete. False otherwise (e.g. some required fields where missing or where invalid).

Return type:

bool

classmethod fromDB(skel, key)

Deprecated function, replaced by Skeleton.read().

Parameters:
Return type:

bool

classmethod read(skel, key=None, *, create=False, _check_legacy=True)

Read Skeleton with key from the datastore into the Skeleton. If not key is given, skel[“key”] will be used.

Reads all available data of entity kind kindName and the key key from the Datastore into the Skeleton structure’s bones. Any previous data of the bones will discard.

To store a Skeleton object to the Datastore, see write().

Parameters:

  • key (Optional[viur.core.db.KeyType]) – A viur.core.db.Key, string, or int; from which the data shall be fetched. If not provided, skel[“key”] will be used.

  • create (bool | dict | Callable[[core.skeleton.instance.SkeletonInstance], None]) – Allows to specify a dict or initial callable that is executed in case the Skeleton with the given key does not exist, it will be created.

  • skel (core.skeleton.instance.SkeletonInstance)

  • _check_legacy (bool)

Returns:

None on error, or the given SkeletonInstance on success.

Return type:

Optional[core.skeleton.instance.SkeletonInstance]

classmethod toDB(skel, update_relations=True, **kwargs)

Deprecated function, replaced by Skeleton.write().

Parameters:
Return type:

viur.core.db.Key

classmethod write(skel, key=None, *, update_relations=True, _check_legacy=True)

Write current Skeleton to the datastore.

Stores the current data of this instance into the database. If an key value is set to the object, this entity will ne updated; Otherwise a new entity will be created.

To read a Skeleton object from the data store, see read().

Parameters:

  • key (Optional[viur.core.db.KeyType]) – Allows to specify a key that is set to the skeleton and used for writing.

  • update_relations (bool) – If False, this entity won’t be marked dirty; This avoids from being fetched by the background task updating relations.

  • skel (core.skeleton.instance.SkeletonInstance)

  • _check_legacy (bool)

Returns:

The Skeleton.

Return type:

core.skeleton.instance.SkeletonInstance

classmethod delete(skel, key=None)

Deletes the entity associated with the current Skeleton from the data store.

Parameters:
Return type:

None

classmethod patch(skel, values={}, *, key=None, check=None, create=None, update_relations=True, ignore=(), internal=True, retry=0)

Performs an edit operation on a Skeleton within a transaction.

The transaction performs a read, sets bones and afterwards does a write with exclusive access on the given Skeleton and its underlying database entity.

All value-dicts that are being fed to this function are provided to skel.fromClient(). Instead of dicts, a callable can also be given that can individually modify the Skeleton that is edited.

Parameters:

  • values (Optional[dict | Callable[[core.skeleton.instance.SkeletonInstance], None]]) –

    A dict of key-values to update on the entry, or a callable that is executed within the transaction.

    This dict allows for a special notation: Keys starting with “+” or “-” are added or substracted to the given value, which can be used for counters.

  • key (Optional[viur.core.db.Key | int | str]) – A viur.core.db.Key, string, or int; from which the data shall be fetched. If not provided, skel[“key”] will be used.

  • check (Optional[dict | Callable[[core.skeleton.instance.SkeletonInstance], None]]) – An optional dict of key-values or a callable to check on the Skeleton before updating. If something fails within this check, an AssertionError is being raised.

  • create (Optional[bool | dict | Callable[[core.skeleton.instance.SkeletonInstance], None]]) – Allows to specify a dict or initial callable that is executed in case the Skeleton with the given key does not exist.

  • update_relations (bool) – Trigger update relations task on success. Defaults to False.

  • ignore (Optional[Iterable[str]]) – optional list of bones to be ignored from values; Defaults to an empty list, so that all bones are accepted (even read-only ones, as skel.patch() is being used internally)

  • internal (bool) – Internal patch does ignore any NotSet and Empty errors that may raise in skel.fromClient()

  • retry (int) – On RuntimeError, retry for this amount of times. - DEPRECATED!

  • skel (core.skeleton.instance.SkeletonInstance)

Return type:

core.skeleton.instance.SkeletonInstance

If the function does not raise an Exception, all went well. The function always returns the input Skeleton.

Raises:

ValueError: In case parameters where given wrong or incomplete. AssertionError: In case an asserted check parameter did not match. ReadFromClientException: In case a skel.fromClient() failed with a high severity.

classmethod preProcessBlobLocks(skel, locks)

Can be overridden to modify the list of blobs referenced by this skeleton

Parameters:

skel (core.skeleton.instance.SkeletonInstance)

classmethod preProcessSerializedData(skel, entity)

Can be overridden to modify the viur.core.db.Entity before its actually written to the data store.

Parameters:

skel (core.skeleton.instance.SkeletonInstance)

classmethod postSavedHandler(skel, key, dbObj)

Can be overridden to perform further actions after the entity has been written to the data store.

Parameters:

skel (core.skeleton.instance.SkeletonInstance)

classmethod postDeletedHandler(skel, key)

Can be overridden to perform further actions after the entity has been deleted from the data store.

Parameters:

skel (core.skeleton.instance.SkeletonInstance)

classmethod getCurrentSEOKeys(skel)

Should be overridden to return a dictionary of language -> SEO-Friendly key this entry should be reachable under. How theses names are derived are entirely up to the application. If the name is already in use for this module, the server will automatically append some random string to make it unique. :return:

Parameters:

skel (core.skeleton.instance.SkeletonInstance)

Return type:

None | dict[str, str]