geoh5py.shared

geoh5py.shared.concatenation

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

Bases: Entity

Base class modifier for concatenated objects and data.

property concat_attr_str: str

String identifier for the concatenated attributes.

property concatenator: Concatenator

Parental Concatenator entity.

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

Bases: Concatenated

property parent: ConcatenatedObject

property property_group

Get the property group containing the data interval.

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

Bases: ConcatenatedObject

property from_: list[Data]

Depth data corresponding to the tops of the interval values.

sort_depths()

Bypass sort_depths from previous version.

property to_: list[Data]

Depth data corresponding to the bottoms of the interval values.

validate_data(attributes: dict, property_group=None, collocation_distance=None) → tuple

Validate input drillhole data attributes.

Parameters

• attributes – Dictionary of data attributes.

• property_group – Input property group to validate against.

validate_interval_data(name: str | None, from_to: list | np.ndarray | None, values: np.ndarray, property_group: str | ConcatenatedPropertyGroup | None = None, collocation_distance=0.0001) → ConcatenatedPropertyGroup

Compare new and current depth values and re-use the property group if possible. Otherwise a new property group is added.

Parameters

• from_to – Array of from-to values.

• values – Data values to be added on the from-to intervals.

• property_group – Property group name

Collocation_distance

Threshold on the comparison between existing depth values.

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

Bases: Concatenated, ObjectBase

find_or_create_property_group(**kwargs) → ConcatenatedPropertyGroup

Find or create PropertyGroup from given name and properties.

Parameters

kwargs – Any arguments taken by the PropertyGroup class.

Returns

A new or existing PropertyGroup

get_data(name: str | uuid.UUID) → list[Data]

Generic function to get data values from object.

get_data_list(attribute='name')

Get list of data names.

property parent: Concatenator

property property_groups: list | None

List of PropertyGroup.

class geoh5py.shared.concatenation.ConcatenatedPropertyGroup(parent: ConcatenatedObject, **kwargs)

Bases: PropertyGroup

property from_

Return the data entities definind the ‘from’ depth intervals.

property parent

The parent ObjectBase

property to_

Return the data entities definind the ‘to’ depth intervals.

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

Bases: Group

Class modifier for concatenation of objects and data.

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 concat_attr_str: str

String identifier for 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.

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

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.

property data: dict

Concatenated data values stored as a dictionary.

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

fetch_concatenated_data_index()

Extract concatenation arrays.

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_concatenated_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.

remove_entity(entity: Concatenated)

Remove a concatenated entity.

save_attribute(field: str)

Save a concatenated attribute.

Parameters

field – Name of the attribute

update_array_attribute(entity: Concatenated, field: str, remove=False) → 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, name='Entity', **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, **kwargs)

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 – (Optional) Create copies of all children entities along with it.

• kwargs – Additional keyword arguments to pass to the copy constructor.

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) → 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) → EntityTypeT | 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_active_workspace(workspace: Workspace | None, mode: str = 'r')

Open a workspace in the requested ‘mode’. If receiving an opened Workspace instead, merely return the given workspace.

Parameters

• workspace – A Workspace class

• mode – Set the h5 read/write mode

Return h5py.File

Handle to an opened Workspace.

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.get_attributes(entity, omit_list=(), attributes=None)

Extract the attributes of an object with omissions.

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.mask_by_extent(locations: np.ndarray, extent: np.ndarray | list[list]) → np.ndarray

Find indices of locations within a rectangular extent.

Parameters

• locations – shape(, 3) or shape(, 2) Coordinates to be evaluated.

• extent – shape(2, 2) Limits defined by the South-West and North-East corners. Extents can also be provided as 3D coordinates with shape(2, 3) defining the top and bottom limits.

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.overwrite_kwargs(to_overwrite: dict, kwargs_to_add: dict) → dict

Overwrite kwargs with overwrite. :param to_overwrite: Dictionary of kwargs to overwrite. :param kwargs_to_add: Dictionary of kwargs to modify to_overwrite.

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: str

Validation type identifier.

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.