geoh5py.shared

geoh5py.shared.concatenation

class geoh5py.shared.concatenation.Concatenated(entity_type, **kwargs)

Bases: Entity

Class modifier for concatenated objects and data.

property concatenator: Concatenator

Parental Concatenator entity.

get_data(name: str) → list[Data]

Generic function to get data values from object.

get_data_list()

Get list of data names.

property parent: Concatenated | Concatenator

property property_groups: list | None

class geoh5py.shared.concatenation.Concatenator(group_type: GroupType, **kwargs)

Bases: Group

Class modifier for concatenation of objects and data.

add_attribute(uid: str) → None

Add new element to the concatenated attributes.

Parameters

uid – Unique identifier of the new concatenated entity in str format.

add_save_concatenated(child) → None

Add or save a concatenated entity.

Parameters

child – Concatenated entity

property attributes_keys: list | None

List of uuids present in the concatenated attributes.

property concatenated_attributes: dict | None

Dictionary of concatenated objects and data attributes.

property concatenated_object_ids: list[bytes] | None

Dictionary of concatenated objects and data concatenated_object_ids.

property data: dict

Concatenated data values stored as a dictionary.

delete_index_data(label: str, index: int) → None

fetch_concatenated_objects() → dict

Load all concatenated children.

fetch_index(entity: Concatenated, field: str) → int | None

Fetch the array index for specific concatenated object and data field.

Parameters

• entity – Parent entity with data

• field – Name of the target data.

fetch_start_index(entity: Concatenated, label: str) → int

Fetch starting index for a given entity and label. Existing date is removed such that new entries can be appended.

Parameters

• entity – Concatenated entity to be added.

• label – Name of the attribute requiring an update.

fetch_values(entity: Concatenated, field: str) → np.ndarray | None

Get an array of values from concatenated data.

Parameters

• entity – Parent entity with data

• field – Name of the target data.

get_attributes(uid: bytes | str | uuid.UUID) → dict

Fast reference index to concatenated attribute keys.

property index: dict

Concatenated index stored as a dictionary.

property property_group_ids: list | None

Dictionary of concatenated objects and data property_group_ids.

update_array_attribute(entity: Concatenated, field: str) → None

Update values stored as data. Row data and indices are first remove then appended.

Parameters

• entity – Concatenated entity with array values.

• field – Name of the valued field.

update_attributes(entity: Concatenated, label: str) → None

Update a concatenated entity.

update_concatenated_attributes(entity: Concatenated) → None

Update the concatenated attributes. :param entity: Concatenated entity with attributes.

geoh5py.shared.entity

class geoh5py.shared.entity.Entity(uid: uuid.UUID | None = None, **kwargs)

Bases: ABC

Base Entity class

add_children(children: list[shared.Entity])

Parameters

children – Add a list of entities as children

add_file(file: str)

Add a file to the object or group stored as bytes on a FilenameData

Parameters

file – File name with path to import.

property allow_delete: bool

bool Entity can be deleted from the workspace.

property allow_move: bool

bool Entity can change parent

property allow_rename: bool

bool Entity can change name

property attribute_map: dict

dict Correspondence map between property names used in geoh5py and geoh5.

property children

list Children entities in the workspace tree

property clipping_ids: list[uuid.UUID] | None

List of clipping uuids

copy(parent=None, copy_children: bool = True)

Function to copy an entity to a different parent entity.

Parameters

• parent – Target parent to copy the entity under. Copied to current parent if None.

• copy_children – Create copies of all children entities along with it.

Return entity

Registered Entity to the workspace.

classmethod create(workspace, **kwargs)

Function to create an entity.

Parameters

• workspace – Workspace to be added to.

• kwargs – List of keyword arguments defining the properties of a class.

Return entity

Registered Entity to the workspace.

abstract property entity_type: shared.EntityType

classmethod fix_up_name(name: str) → str

If the given name is not a valid one, transforms it to make it valid :return: a valid name built from the given name. It simply returns the given name if it was already valid.

get_entity(name: str | uuid.UUID) → list[Entity]

Get a child Data by name.

Parameters

• name – Name of the target child data

• entity_type – Sub-select entities based on type.

Returns

A list of children Data objects

get_entity_list(entity_type=<class 'abc.ABC'>) → list[str]

Get a list of names of all children Data.

Parameters

entity_type – Option to sub-select based on type.

Returns

List of names of data associated with the object.

property metadata: dict | None

Metadata attached to the entity.

property name: str

str Name of the entity

property on_file: bool

Whether this Entity is already stored on h5file.

property parent

property partially_hidden: bool

Whether this Entity is partially hidden.

property public: bool

Whether this Entity is accessible in the workspace tree and other parts

of the the user interface in ANALYST.

reference_to_uid(value: Entity | str | uuid.UUID) → list[uuid.UUID]

General entity reference translation.

Parameters

value – Either an Entity, string or uuid

Returns

List of unique identifier associated with the input reference.

remove_children(children: list[shared.Entity])

Remove children from the list of children entities.

Parameters

children – List of entities

Warning

Removing a child entity without re-assigning it to a different parent may cause it to become inactive. Inactive entities are removed from the workspace by remove_none_referents().

remove_data_from_group(data: list | Entity | uuid.UUID | str, name: str = None) → None

Remove data children to a PropertyGroup All given data must be children of the parent object.

Parameters

• data – Data object, uid or name of data.

• name – Name of a PropertyGroup. A new group is created if none exist with the given name.

save(add_children: bool = True)

Alias method of save_entity().

Parameters

add_children – Option to also save the children.

property uid: UUID

property visible: bool

Whether the Entity is visible in camera (checked in ANALYST object tree).

property workspace: Workspace

Workspace to which the Entity belongs to.

geoh5py.shared.entity_type

class geoh5py.shared.entity_type.EntityType(workspace: ws.Workspace, uid: uuid.UUID | None = None, **kwargs)

Bases: ABC

property attribute_map

dict Correspondence map between property names used in geoh5py and geoh5.

property description: str | None

classmethod find(workspace: ws.Workspace, type_uid: uuid.UUID) → TEntityType | None

Finds in the given Workspace the EntityType with the given UUID for this specific EntityType implementation class.

Returns

EntityType of None

property name: str | None

property on_file: bool

bool Entity already present in h5file.

property uid: UUID

uuid.UUID The unique identifier of an entity, either as stored in geoh5 or generated in uuid4() format.

property workspace: ws.Workspace

Workspace registering this type.

geoh5py.shared.exceptions

exception geoh5py.shared.exceptions.AssociationValidationError(name: str, value: Entity | PropertyGroup | UUID, validation: Entity | Workspace)

Bases: BaseValidationError

Error on association between child and parent entity validation.

static message(name, value, validation)

Builds custom error message.

exception geoh5py.shared.exceptions.AtLeastOneValidationError(name: str, value: list[str])

Bases: BaseValidationError

static message(name, value, validation=None)

Builds custom error message.

exception geoh5py.shared.exceptions.BaseValidationError

Bases: ABC, Exception

Base class for custom exceptions.

abstract static message(name, value, validation)

Builds custom error message.

exception geoh5py.shared.exceptions.Geoh5FileClosedError

Bases: ABC, Exception

Error for closed geoh5 file.

exception geoh5py.shared.exceptions.JSONParameterValidationError(name: str, err: str)

Bases: Exception

Error on uuid validation.

static message(name, err)

exception geoh5py.shared.exceptions.OptionalValidationError(name: str, value: Any | None, validation: bool)

Bases: BaseValidationError

Error if None value provided to non-optional parameter.

static message(name, value, validation)

Builds custom error message.

exception geoh5py.shared.exceptions.PropertyGroupValidationError(name: str, value: PropertyGroup, validation: str)

Bases: BaseValidationError

Error on property group validation.

static message(name, value, validation)

Builds custom error message.

exception geoh5py.shared.exceptions.RequiredValidationError(name: str)

Bases: BaseValidationError

static message(name, value=None, validation=None)

Builds custom error message.

exception geoh5py.shared.exceptions.ShapeValidationError(name: str, value: tuple[int], validation: tuple[int] | str)

Bases: BaseValidationError

Error on shape validation.

static message(name, value, validation)

Builds custom error message.

exception geoh5py.shared.exceptions.TypeValidationError(name: str, value: str, validation: str | list[str])

Bases: BaseValidationError

Error on type validation.

static message(name, value, validation)

Builds custom error message.

exception geoh5py.shared.exceptions.UUIDValidationError(name: str, value: str)

Bases: BaseValidationError

Error on uuid string validation.

static message(name, value, validation=None)

Builds custom error message.

exception geoh5py.shared.exceptions.ValueValidationError(name: str, value: Any, validation: list[Any])

Bases: BaseValidationError

Error on value validation.

static message(name, value, validation)

Builds custom error message.

geoh5py.shared.utils

geoh5py.shared.utils.as_str_if_utf8_bytes(value) → str

Convert bytes to string

geoh5py.shared.utils.as_str_if_uuid(value: UUID | Any) → str | Any

Convert UUID to string used in geoh5.

geoh5py.shared.utils.bool_value(value: int8) → bool

Convert logical int8 to bool.

geoh5py.shared.utils.compare_entities(object_a, object_b, ignore: list | None = None, decimal: int = 6) → None

geoh5py.shared.utils.dict_mapper(val, string_funcs: list[Callable], *args, omit: dict | None = None) → dict

Recursion through nested dictionaries and applies mapping functions to values.

Parameters

• val – Value (could be another dictionary) to apply transform functions.

• string_funcs – Functions to apply on values within the input dictionary.

• omit – Dictionary of functions to omit.

Return val

Transformed values

geoh5py.shared.utils.entity2uuid(value: Any) → UUID | Any

Convert an entity to its UUID.

geoh5py.shared.utils.fetch_h5_handle(file: str | h5py.File | Path, mode: str = 'r') → h5py.File

Open in read+ mode a geoh5 file from string. If receiving a file instead of a string, merely return the given file.

Parameters

• file – Name or handle to a geoh5 file.

• mode – Set the h5 read/write mode

Return h5py.File

Handle to an opened h5py file.

geoh5py.shared.utils.is_uuid(value: str) → bool

Check if a string is UUID compliant.

geoh5py.shared.utils.iterable(value: Any, checklen: bool = False) → bool

Checks if object is iterable.

Parameters

valueObject to check for iterableness.

checklenRestrict objects with __iter__ method to len > 1.

Returns

True if object has __iter__ attribute but is not string or dict type.

geoh5py.shared.utils.iterable_message(valid: list[Any] | None) → str

Append possibly iterable valid: “Must be (one of): {valid}.”.

geoh5py.shared.utils.match_values(vec_a, vec_b, collocation_distance=0.0001) → ndarray

Find indices of matching values between two arrays, within collocation_distance.

Param

vec_a, list or numpy.ndarray Input sorted values

Param

vec_b, list or numpy.ndarray Query values

Returns

indices, numpy.ndarray Pairs of indices for matching values between the two arrays such that vec_a[ind[:, 0]] == vec_b[ind[:, 1]].

geoh5py.shared.utils.merge_arrays(head, tail, replace='A->B', mapping=None, collocation_distance=0.0001, return_mapping=False) → ndarray

Given two numpy.arrays of different length, find the matching values and append both arrays.

Param

head, numpy.array of float First vector of shape(M,) to be appended.

Param

tail, numpy.array of float Second vector of shape(N,) to be appended

Param

mapping=None, numpy.ndarray of int Optional array where values from the head are replaced by the tail.

Param

collocation_distance=1e-4, float Tolerance between matching values.

Returns

numpy.array shape(O,) Unique values from head to tail without repeats, within collocation_distance.

geoh5py.shared.utils.str2uuid(value: Any) → UUID | Any

Convert string to UUID

geoh5py.shared.utils.uuid2entity(value: UUID, workspace: Workspace) → Entity | Any

Convert UUID to a known entity.

geoh5py.shared.validators

class geoh5py.shared.validators.AssociationValidator(**kwargs)

Bases: BaseValidator

Validate the association between data and parent object.

classmethod validate(name: str, value: Entity | PropertyGroup | UUID | None, valid: Entity | Workspace) → None

Parameters

• name – Parameter identifier.

• value – Input parameter value.

• valid – Expected value shape

validator_type = 'association'

class geoh5py.shared.validators.AtLeastOneValidator(**kwargs)

Bases: BaseValidator

classmethod validate(name, value, valid)

Custom validation function.

validator_type = 'one_of'

class geoh5py.shared.validators.BaseValidator(**kwargs)

Bases: ABC

Concrete base class for validators.

abstract classmethod validate(name: str, value: Any, valid: Any)

Custom validation function.

abstract property validator_type

classmethod(function) -> method

Convert a function to be a class method.

A class method receives the class as implicit first argument, just like an instance method receives the instance. To declare a class method, use this idiom:

class C:

@classmethod def f(cls, arg1, arg2, …):

…

It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()). The instance is ignored except for its class. If a class method is called for a derived class, the derived class object is passed as the implied first argument.

Class methods are different than C++ or Java static methods. If you want those, see the staticmethod builtin.

class geoh5py.shared.validators.OptionalValidator(**kwargs)

Bases: BaseValidator

Validate that forms contain optional parameter if None value is given.

classmethod validate(name: str, value: Any | None, valid: bool) → None

Parameters

• name – Parameter identifier.

• value – Input parameter value.

• valid – True if optional keyword in form for parameter.

validator_type = 'optional'

class geoh5py.shared.validators.PropertyGroupValidator(**kwargs)

Bases: BaseValidator

Validate property_group from parent entity.

classmethod validate(name: str, value: PropertyGroup, valid: str) → None

Custom validation function.

validator_type = 'property_group_type'

class geoh5py.shared.validators.RequiredValidator(**kwargs)

Bases: BaseValidator

Validate that required keys are present in parameter.

classmethod validate(name: str, value: Any, valid: bool) → None

Parameters

• name – Parameter identifier.

• value – Input parameter value.

• valid – Assert to be required

validator_type = 'required'

class geoh5py.shared.validators.ShapeValidator(**kwargs)

Bases: BaseValidator

Validate the shape of provided value.

classmethod validate(name: str, value: Any, valid: tuple[int]) → None

Parameters

• name – Parameter identifier.

• value – Input parameter value.

• valid – Expected value shape

validator_type = 'shape'

class geoh5py.shared.validators.TypeValidator(**kwargs)

Bases: BaseValidator

Validate the value type from a list of valid types.

classmethod validate(name: str, value: Any, valid: list[type] | type) → None

Parameters

• name – Parameter identifier.

• value – Input parameter value.

• valid – List of accepted value types

validator_type = 'types'

class geoh5py.shared.validators.UUIDValidator(**kwargs)

Bases: BaseValidator

Validate a uuui.UUID value or uuid string.

classmethod validate(name: str, value: Any, valid: None = None) → None

Parameters

• name – Parameter identifier.

• value – Input parameter uuid.

• valid – [Optional] Validate uuid from parental entity or known uuids

validator_type = 'uuid'

class geoh5py.shared.validators.ValueValidator(**kwargs)

Bases: BaseValidator

Validator that ensures that values are valid entries.

classmethod validate(name: str, value: Any, valid: list[float | str]) → None

Parameters

• name – Parameter identifier.

• value – Input parameter value.

• valid – List of accepted values

validator_type = 'values'

geoh5py.shared.weakref_utils

geoh5py.shared.weakref_utils.get_clean_ref(some_dict: dict[K, ReferenceType[T]], key: K) → T | None

Gets the referent value for the given key in a some_dict of weakref values. In case key points to a reference to a deleted value, remove that key from some_dict on the fly, and returns None.

Parameters

• some_dict – The dictionary of weakref values.

• key – The key

Returns

the referent value for key if found in the the dictionary, else None.

geoh5py.shared.weakref_utils.insert_once(some_dict: dict[K, ReferenceType], key: K, value)

Check if the reference to an Entity with uuid is already in use.

Parameters

• some_dict – Dictionary of UUID keys and weakref values.

• key – UUID key to be checked.

• value – Entity to be checked

Returns

Dictionary with clean weakref

geoh5py.shared.weakref_utils.remove_none_referents(some_dict: dict[K, ReferenceType])

Removes any key from the given some_dict where the value is a reference to a deleted value (that is where referent of the weakref value is None).

Parameters

some_dict – The dictionary to be cleaned up.