Utils

The vibe_core.data.utils modules provides utility functions and classes for working with STAC (SpatioTemporal Asset Catalog) Items and converting them to and from BaseVibe objects. This module simplifies the process of managing and organizing the data used throughout FarmVibes.AI, offering utility functions for serializing and deserializing STAC Items, field conversion, and type resolution.

Hierarchy

classDiagram class FieldConverter { } class StacConverter { }

Documentation

Utilities for interacting with STAC items and serialization/deserialization.

class vibe_core.data.utils.FieldConverter(serializer, deserializer)

Bases: tuple

A named tuple representing a field converter.

deserializer: Callable[[Any], Any]: A function that deserialize a value.

serializer: Callable[[Any], Any]: A function that serialize a value.

class vibe_core.data.utils.StacConverter

Bases: object

Convert BaseVibe objects to STAC Items.

convert_field(field_value, field_type, converter)

Convert a field value to a given type, using a converter function.

Parameters:

field_value (Any) – The value of the field to convert.
field_type (Any) – The type to convert the field value to.
converter (Callable[[Any, Any], Any]) – The converter function to use.

Returns:

The converted field value.

Return type:

Any

deserialize_fields(field_values, field_types)

Deserialize a dictionary of fields.

Parameters:

field_values (Dict[str, Any]) – The dictionary of field values to deserialize.
field_types (Dict[str, Any]) – The dictionary of field types to deserialize to.

Returns:

The deserialized dictionary of field values.

Return type:

Dict[str, Any]

from_stac_item(input)

Convert STAC to :class`BaseVibe`.

Convert a STAC item or a list of STAC items to a :class`BaseVibe` or a list of :class`BaseVibe`.

Parameters:: input (Item | List[Item]) – The STAC item or list of STAC items to convert.
Returns:: A – class`BaseVibe` or a list of :class`BaseVibe`.
Return type:: BaseVibe | List[BaseVibe]

resolve_type(input)

Resolve the type of a :class`BaseVibe` object from a STAC item.

Parameters:: input (Item) – The STAC item to resolve the type from.
Returns:: The type of – class`BaseVibe`.
Return type:: Type[BaseVibe]

sanitize_properties(properties)

Sanitize a dictionary of properties to ensure they are JSON serializable.

Parameters:: properties (Dict[Any, Any]) – The dictionary of properties to sanitize.
Returns:: The sanitized dictionary of properties.
Return type:: Dict[Any, Any]

serialize_fields(field_values, field_types)

Serialize a dictionary of fields.

Parameters:

field_values (Dict[str, Any]) – The dictionary of field values to serialize.
field_types (Dict[str, Any]) – The dictionary of field types to serialize to.

Returns:

The serialized dictionary of field values.

Return type:

Dict[str, Any]

to_stac_item(input)

Convert :class`BaseVibe` to STAC.

Convert a :class`BaseVibe` or a list of :class`BaseVibe` to a STAC item or a list of STAC items.

Parameters:: input (List[BaseVibe] | BaseVibe) – The :class`BaseVibe` or list of :class`BaseVibe` to convert.
Returns:: A STAC item or a list of STAC items.

BASEVIBE_FALLBACK_DATETIME = datetime.datetime(1970, 1, 1, 0, 0): The fallback datetime to use for BaseVibe objects.

VIBE_DATA_TYPE_FIELD = 'terravibes_data_type': The name of the field that contains the data type of the BaseVibe object.

field_converters = {<class 'shapely.geometry.base.BaseGeometry'>: FieldConverter(serializer=<function mapping>, deserializer=<function shape>), <class 'datetime.datetime'>: FieldConverter(serializer=<function to_isoformat>, deserializer=<built-in method fromisoformat of type object>)}: A dictionary mapping field types to field converters.

vibe_core.data.utils.convert_time_range(item)

Convert the time range of a STAC item to a tuple of datetimes.

Parameters:: item (Item) – The STAC item to convert the time range for.
Returns:: A tuple of datetimes representing the start and end of the time range.
Return type:: Tuple[datetime, datetime]

vibe_core.data.utils.deserialize_stac(arg)

Deserialize dict to STAC.

Deserialize a dictionary or a list of dictionaries to a STAC item or a list of STAC items.

Parameters:: arg (List[Dict[str, Any]] | Dict[str, Any]) – The dictionary or list of dictionaries to deserialize.
Returns:: A STAC item or a list of STAC items.

vibe_core.data.utils.get_base_type(vibetype)

Determine the base type of a typing specification.

Parameters:: vibetype (Type[BaseVibe] | Type[List[BaseVibe]]) – The type to determine the base type of.
Returns:: The base type of vibetype.
Raises:: ValueError – If the type hierarchy contains nested container types (e.g., List[List[DataVibe]]).
Return type:: Type[BaseVibe]

Doctests: >>> get_base_type(DataVibe) vibe_core.data.DataVibe >>> get_base_type([List[DataVibe]) vibe_core.data.DataVibe

vibe_core.data.utils.get_most_specific_type(types)

Determine the most specific type of a list of types.

Parameters:: types (List[Type[BaseVibe] | Type[List[BaseVibe]]]) – The list of types to determine the most specific type of.
Returns:: The most specific type of types.
Raises:: ValueError – If the types are not compatible.
Return type:: Type[BaseVibe] | Type[List[BaseVibe]]

vibe_core.data.utils.is_container_type(typeclass)

Check if a type is a container type.

Parameters:: typeclass (Type[V] | List[Type[V]]) – The type to check.
Returns:: True if the type is a container type, False otherwise.
Return type:: bool

vibe_core.data.utils.is_json_serializable(x)

Check if a field is JSON serializable by Python’s default serializer.

Parameters:: x (Any) – The value to check.
Returns:: True if the value is JSON serializable, False otherwise.
Return type:: bool

vibe_core.data.utils.is_vibe_list(typeclass)

Check if a type is a list of :class`BaseVibe` objects.

Parameters:: typeclass (Type[BaseVibe] | Type[List[BaseVibe]]) – The type to check.
Returns:: True if the type is a list of – class`BaseVibe` objects, False otherwise.
Return type:: bool

vibe_core.data.utils.serialize_input(input_data)

Serialize :class`BaseVibe` to STAC.

Serialize a single :class`BaseVibe` object, or a list or dictionary of them, to a STAC item or a list or dictionary of STAC items.

Parameters:: input_data (Any) – The :class`BaseVibe` object or a list or dictionary of :class`BaseVibe` objects to serialize.
Returns:: A list, a dictionary or a single STAC Item representing the – class`BaseVibe` object.
Raises:: NotImplementedError – If the input data is not a :class`BaseVibe` object, or a list or dictionary of :class`BaseVibe`.
Return type:: Any

vibe_core.data.utils.serialize_stac(arg)

Serialize a STAC item or a list of STAC items to a dictionary or a list of dictionaries.

Parameters:: arg (Item | List[Item]) – The STAC item or list of STAC items to serialize.
Returns:: A dictionary or a list of dictionaries representing the STAC item or list of STAC items.

vibe_core.data.utils.to_isoformat(x)

Convert a datetime object to an ISO format string.

Parameters:: x (datetime) – The datetime object to convert.
Returns:: The ISO format string.
Return type:: str