Utilities

This section shows general objects and helper functions that are used with this package.

Data Item / Data Item Collection

class balderhub.data.lib.utils.SingleDataItem

Bases: BaseModel, ABC

This is a base class for data items. Data items are pydantic BaseModel classes that are used for defining the model to test.

classmethod all_field_lookups_are_within(field_lookup: str | LookupFieldString, within_list_of_lookups: list[str | balderhub.data.lib.utils.lookup_field_string.LookupFieldString]) → bool

Helper method that returns True if the provided single-data-item field is within the provided lookup list. Both needs to be relative to this single-data-item.

Note

It also returns True if the field given by field_lookup is from type SingleDataItem too and all their resolved lookups are contained within the within_list_of_lookups list.

Parameters:

field_lookup – the field lookup of the field that should be checked
within_list_of_lookups – a list of fully resolved lookups

Returns:

True if the field_lookup is within the within_list_of_lookups list

all_fields_are_not_definable() → bool

Returns:: returns true in case all fields have the value NOT_DEFINABLE.

compare(other: SingleDataItemTypeT, ignore_field_lookups: List[str] | None = None, allow_non_definable: bool = False, validate_unique_identification_separately=True) → bool

This method compares a data item with another data item from same type.

Parameters:

other – the other data item to compare with
ignore_field_lookups – a list with field lookups that should be ignored
allow_non_definable – True if the method should ignore fields for which one data item has the value NOT_DEFINABLE
validate_unique_identification_separately – True if the method should validate the unique-identification value (provided with balderhub.data.lib.utils.SingleDataItem.get_unique_identification()) separately

Returns:

True if the data of both data item objects are equal

classmethod create_as_nested(**kwargs): Class method for create a data item out of field-lookups (attribute name) :param kwargs: the field lookups with its value :return: the instantiated data item

classmethod create_non_definable(nested=True) → SingleDataItemTypeT

Returns:: returns instance of this data item with NON_DEFINABLE for every field

classmethod get_all_fields_for(subkey: str | LookupFieldString | None = None, nested=True, except_fields: list[str | balderhub.data.lib.utils.lookup_field_string.LookupFieldString] | None = None) → list[str]

This method returns a list with all field names, that matches the requested filter.

Parameters:

subkey – all fields that belongs to this subkey are returned - if this is None, all fields of this data item are returned.
nested – True if the method should return all nested fields and not only the direct fields
except_fields – a list of fields to exclude from the returned list (if subkey is given, they are relative to this subkey, otherwise they are relative to this data item)

Returns:

a list of fields as strings in lookup syntax (concat with __)

classmethod get_cleaned_field_data_type(field_lookup: LookupFieldString | str) → type | GenericAlias: This method returns the specific data type of a field. It automatically resolves subscripted type definitions. :param field_lookup: the field lookup string :return: the cleared type spec (can be a normal type, Optional[type] or list[type])

get_difference_error_messages(other: SingleDataItemTypeT, ignore_field_lookups: List[LookupFieldString | str] | None = None, allow_non_definable: bool = False, validate_unique_identification_separately=True) → List[str]

Parameters:

other – the other data item to compare with
ignore_field_lookups – a list with field lookups that should be ignored
allow_non_definable – True if the method should ignore fields for which one data item has the value NOT_DEFINABLE
validate_unique_identification_separately – True if the method should validate the unique-identification value (provided with SingleDataItem.get_unique_identification()) separately

Returns:

A list with detected error messages

classmethod get_element_type_for_list(field_lookup: str | LookupFieldString) → type

This method returns the inner element type for the requested field. It will recheck that the provided field references a list before.

Parameters:: field_lookup – the field lookup string
Returns:: the data type the list items should have

classmethod get_field(field_lookup: str | LookupFieldString) → FieldInfo

Returns the specific data class field by its field lookup name

Parameters:: field_lookup – the field lookup string
Returns:: the pydantic field

classmethod get_field_data_type(field_lookup: LookupFieldString | str) → type: This method returns the specific data type of a field. It automatically resolves subscripted type definitions. :param field_lookup: the field lookup string :return: the unsubscripted field type

get_field_value(field_lookup: str)

This method returns the value of the provided field.

Parameters:: field_lookup – the field lookup string
Returns:: the field value

abstract get_unique_identification(): Individual method that returns a unique identifier for the data item. :return: a unique identifier for the specific data item object

classmethod is_optional_field(field_lookup: str | LookupFieldString, consider_upper_optionals_too=True) → bool

This method checks if the field is optional. If consider_upper_optionals_too=True it will check the type definitions of any field in the field chain too and returns Ture as soon as one element is defined as optional.

Parameters:

field_lookup – the field lookup string
consider_upper_optionals_too –

Returns:

True if the field is optional, False otherwise

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'strict': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

set_field_value(field_lookup: str, value: Any, only_change_this_value=False) → None

This method sets a specific value in the data item. It sets the value that is provided as field_name inside the data item. In case the field_name is a nested lookup field, it will overwrite the nested items by setting a new data item for the nested field. In case the value is a dictionary matching the definition of the data item type of the nested field, it will set all values that are provided in this dict. Any other value will be set with NOT_DEFINABLE.

Parameters:

field_lookup – the name of the field (nested lookup field allowed)
value – the value that should be set (dicts for nested structures are allowed)
only_change_this_value – this value is given in case that the method should not recreate all nested data items and set their undefined values to NOT_DEFINABLE

class balderhub.data.lib.utils.SingleDataItemCollection(items: List[SingleDataItem] = None)

Bases: object

helper class to manage a collection of SingleDateItems

exception DoesNotExist

Bases: Exception

raised in case that the requested data item does not exist

exception MultipleElementsReturned

Bases: Exception

raised in case there are more than one matching elements in the list

append(item: SingleDataItem) → None: This method adds an item to the collection. :param item: the item that should be added

compare(other_collection: SingleDataItemCollection, ignore_order: bool = False, ignore_field_lookups: List[str] | None = None, allow_non_definable: bool = False) → bool

This method returns True if the collections are the same

Parameters:

other_collection – the other collection to compare with
ignore_order – True if the order does not matter and the method should match the elements by its unique identifier
ignore_field_lookups – a list with field-lookups that should be ignored while comparing the items
allow_non_definable – True if the method should ignore fields for which one data item has the value NOT_DEFINABLE

Returns:

True if the collection is the same, otherwise False

copy()

This method returns a new SingleDataItemCollection instance with the same items.

Note

The inner items will not be copied.

Returns:: the copied SingleDataItemCollection instance

filter(filter_obj: Filter | None) → SingleDataItemCollection: This method applies a filter to all items in the collection :param filter_obj: :return:

filter_by(**kwargs) → SingleDataItemCollection

This method returns a new collection with the applied filters. You can use lookup-field syntax for defining the filter statements.

Parameters:: kwargs – the filter variables
Returns:: a new collection that holds the filtered subset

get_all_unique_identifier()

This method returns a list with all unique-identification values (provided by SingleDataItem.get_unique_identification()) of the items.

Returns:: the unique-identification values

get_by(**kwargs) → SingleDataItem

This method returns a single element defined by the provided filters. You can use lookup-field syntax for defining the filter statements.

Note

The filters need to specify exactly one element, otherwise the method raises an exception.

Parameters:: kwargs – the filter variables
Returns:

get_by_identifier(identifier: Any)

This method returns a specific element by its unique identifier. It throws an error in case there are more than one element with this unique-identifier or if there are no elements with this unique-identifier.

Parameters:: identifier – the unique identifier
Returns:: the determined object

get_difference_error_messages(other_collection: SingleDataItemCollection, ignore_order: bool = False, ignore_field_lookups: List[str] | None = None, allow_non_definable: bool = False) → List[str]

This method returns a list with all error messages that has been returned by comparing the list elements with each other.

Parameters:

other_collection – the other collection to compare with
ignore_order – True if the order does not matter and the method should match the elements by its unique identifier
ignore_field_lookups – a list with field-lookups that should be ignored while comparing the items
allow_non_definable – True if the method should ignore fields for which one data item has the value NOT_DEFINABLE

Returns:

a list of error messages (empty list if the collection is identically)

get_random() → SingleDataItem

Returns:: returns a random element

has_unique_elements() → bool

Returns:: returns True if all items within the collection are unique (identified by SingleDataItem.get_unique_identification())

remove(item: SingleDataItem) → None: This method removes an item from the collection. :param item: the item that should be removed

sort(key: Callable | None = None, reverse: bool = False) → SingleDataItemCollection: This method sorts the items in the collection according to the given key. :param key: a sorting callable :param reverse: True if the order should be reversed, otherwise False :return: a new SingleDataItemCollection instance with the sorted items

Utilities for Data Items

class balderhub.data.lib.utils.filter.Filter

Bases: ABC

Object allows to define filter for a specific data class

abstract apply(item: T) → bool: Method that executes the filtering. It will be called for every list element and should return True if the element is still part of the list or False if it is not part of the list. :param item: the current item :return: True if the item should be added to the filtered result, otherwise False

class balderhub.data.lib.utils.LookupFieldString(*args: str | LookupFieldString)

Bases: object

Helper class to represent a lookup field string

add_sub_field(field: str | LookupFieldString): Adds another lookup field to this lookup field string :param field: the field or lookup field that should be added :return: a new lookup field string with the appended sub-field / sub-lookup field

property nested_level: int

Returns:: returns the number of nested field names (LookupFieldString.split_field_keys())

relative_to(value: str | LookupFieldString) → LookupFieldString | None

Returns a new LookupFieldString object representing the path relative to the provided value, or None if the provided value is an empty string. If the provided value is not a part of the current LookupFieldString, a ValueError is raised.

Parameters:: value – The base LookupFieldString or string against which the relative path is calculated.
Returns:: A new LookupFieldString object representing the relative path, or None if the input value is an empty string.
Raises:: ValueError – If value is not part of the current LookupFieldString.

property split_field_keys: list[str]

Returns:: returns a list of nested field names

startswith(value: str | LookupFieldString) → bool

Check if the string representation of the instance starts with the specified value.

Parameters:: value – The string or LookupFieldString to compare against the start of the instance’s string representation.
Returns:: True if the instance’s string representation starts with the given lookup parts, otherwise False.

class balderhub.data.lib.utils.not_definable._NOT_DEFINABLE_TYPE

Bases: object

Type for NON_DEFINABLE values. This object is assigned for all fields that are unable to define either by user or by data interacting features.

balderhub.data.lib.utils.functions.convert_field_lookups_to_dict_structure(dictionary: dict | list, nested=True) → dict | list

This method converts filed-lookups into a dictionary structure.

Example:

>>> convert_field_lookups_to_dict_structure({'a__d': 3.2, 'a__b__c': 2, 'a__b__d': 3, 'a__c': 'H', 'b': 3})
{'a': {'d': 3.2, 'b': {'c': 2, 'd': 3}, 'c': 'H'}, 'b': 3}

Parameters:

dictionary – a flat dictionary with field-lookups as keys and their values as values.
nested – False if the function should only return the first level - True if it should return nested directories.

Returns:

the converted (nested) dictionary

balderhub.data.lib.utils.functions.convert_dict_structure_to_field_lookups(dictionary: dict | list) → dict | list

This method converts the nested dictionary structure to a flat dictionary by using lookup-fields as key:

>>> convert_dict_structure_to_field_lookups({'a': {'d': 3.2, 'b': {'c': 2, 'd': 3}, 'c': 'H'}, 'b': 3})
{'a__d': 3.2, 'a__b__c': 2, 'a__b__d': 3, 'a__c': 'H', 'b': 3}

Parameters:: dictionary – the nested dictionary structure
Returns:: the flat directory while using lookup-fields as key:

balderhub.data.lib.utils.functions.set_lookup_field_in_data_dict(data_dict: dict[str, Any], field_to_set: LookupFieldString | str, value_to_set: Any) → None

Helper function to set a lookup-field within a nested dictionary structure

Parameters:

data_dict – the nested data dictionary the value should be set
field_to_set – the field lookup
value_to_set – the value that should be set

balderhub.data.lib.utils.functions.full_dictionary_is_not_definable(data_dict: dict[str, Any]) → bool

This method checks if the (nested) dictionary’s values are NOT_DEFINABLE only.

Parameters:: data_dict – the nested data dictionary that should be checked
Returns:: Ture if all values are NOT_DEFINABLE, False otherwise

Additional / Special Types

class balderhub.data.lib.utils.UnorderedList(iterable=(), /)

Bases: list[T]

Represents a list that compares equality by its elements, regardless of their order. This class is intended to provide functionality for unordered list comparisons, particularly useful when order does not hold significance in operations like equality checks.

Response Messages

Response Message Objects

class balderhub.data.lib.utils.BaseResponseMessage

Bases: object

Base Response message object, that is used for validating responses from data interactions.

class balderhub.data.lib.utils.ResponseMessage(text: str, body: str | None = None)

Bases: BaseResponseMessage

Response message object, that is used for validating responses from data interactions.

property body: str | None

Returns:: returns an optional body of the response message or None otherwise

property text: str

Returns:: returns the response message main text

Response Message List

class balderhub.data.lib.utils.ResponseMessageList(responses: list[balderhub.data.lib.utils.base_response_message.BaseResponseMessage | str] | None = None)

Bases: object

holds a list of BaseResponseMessage objects

append(elem: BaseResponseMessage | str) → None: This method adds a Response Message object to the list :param elem: the message that should be added

compare(other_list: ResponseMessageList) → bool: This method compares two response-message lists with each other. :param other_list: the other response-message list :return: True if both lists are equal, False otherwise

copy(): This method copies the list. Note: The inner items will not be copied. :return: returns a copies list

Base Factory

class balderhub.data.lib.utils.AutoFeatureFactory

Bases: ABC

Base factory class for creating data-item bounded factories.

classmethod get_for(data_item_cls: type[SingleDataItem], **kwargs) → type[AbstractDataItemRelatedFeature]

Defines a new feature for the specific data-item class given by attribute data_item_cls.

Parameters:

data_item_cls – the single data-item class
kwargs – optional further attributes that will be forwarded to internal method AutoFeatureFactory.register_cls() and AutoFeatureFactory._define_class().

Returns:

the feature type class

classmethod register_cls(data_item_cls: type[balderhub.data.lib.utils.single_data_item.SingleDataItem], **kwargs) → None

Method to register a new data-item bounded feature class. This method ensures that the feature class is defined.

Parameters:

data_item_cls – the data item type for which the feature should be defined
kwargs – further attributes that are forwarded from AutoFeatureFactory.get_for()

Exceptions

class balderhub.data.lib.utils.exceptions.MisconfiguredDataItemError

Bases: Exception

exception that is thrown in case the data items are misconfigured

class balderhub.data.lib.utils.exceptions.DuplicateDataObjectError

Bases: Exception

exception for duplicated data objects