geoh5py.shared

geoh5py.shared.concatenation

geoh5py.shared.entity

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

Bases: ABC

Base Entity class

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 clipping_ids: list[UUID] | None

List of clipping uuids

property coordinate_reference_system: dict

Coordinate reference system attached to the entity.

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

Abstract property to get the entity type of the entity.

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.

abstract mask_by_extent(extent: ndarray, inverse: bool = False) → ndarray | None

Get a mask array from coordinate extent.

Parameters:

• extent – Bounding box extent coordinates defined by either: - obj:numpy.ndarray of shape (2, 3) 3D coordinate: [[west, south, bottom], [east, north, top]] - obj:numpy.ndarray of shape (2, 2) Horizontal coordinates: [[west, south], [east, north]].

• inverse – Return the complement of the mask extent. Default to False

Returns:

Array of bool defining the vertices or cell centers within the mask extent, or None if no intersection.

property metadata: dict | None

Metadata attached to the entity. To update the metadata, use the setter method. To remove the metadata, set it to None.

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.

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: Workspace, uid: uuid.UUID | None = None, description: str | None = 'Entity', name: str | None = 'Entity', on_file: bool = False, **_)

Bases: ABC

The base class for all entity types.

Parameters:

• workspace – The workspace to associate the entity type with.

• uid – The unique identifier of the entity type.

• description – The description of the entity type.

• name – The name of the entity type.

• on_file – Return True if the entity is on file.

property attribute_map: dict[str, str]

Correspondence map between property names used in geoh5py and geoh5.

classmethod convert_kwargs(kwargs: dict[str, Any]) → dict[str, Any]

Convert the kwargs to the geoh5py attribute names.

Parameters:

kwargs – The kwargs to convert.

Returns:

The converted kwargs.

copy(**kwargs)

Copy this entity type to another workspace.

classmethod create(workspace, **kwargs)

WILL BE DEPRECATED IN 10.0.0 Creates a new instance of DataType with corresponding PrimitiveTypeEnum.

Parameters:

• workspace – The workspace to associate the entity type with.

• kwargs – Keyword arguments to initialize the new DataType.

Returns:

A new instance of DataType.

classmethod create_custom(workspace: Workspace, **kwargs)

WILL BE DEPRECATED IN 10.0.0

Creates a new instance of GroupType for an unlisted custom Group type with a new auto-generated UUID.

property description: str | None

The description of the entity type.

classmethod find(workspace: 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

classmethod find_or_create(workspace: Workspace, uid: uuid.UUID | None = None, entity_class: type | None = None, **kwargs)

Find or creates an EntityType with given uid that matches the given Group implementation class.

It is expected to have a single instance of EntityType in the Workspace for each concrete Entity class.

To find an object, the kwargs must contain an existing ‘uid’ keyword, or a ‘entity_class’ keyword, containing an object class.

Parameters:

• workspace – An active Workspace class

• uid – The unique identifier of the entity type.

• entity_class – The class of the entity.

• kwargs – The attributes of the entity type.

Returns:

EntityType

property name: str | None

The name of the entity type.

property on_file: bool

Return True if Entity already present in the workspace.

property uid: UUID

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

property workspace: Workspace

The Workspace associated to the object.

geoh5py.shared.exceptions

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

Bases: BaseValidationError

classmethod message(name, value, validation=None)

Builds custom error message.

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.

classmethod message(name, value, validation)

Builds custom error message.

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

Bases: BaseValidationError

classmethod message(name, value, validation=None)

Builds custom error message.

exception geoh5py.shared.exceptions.BaseValidationError

Bases: ABC, Exception

Base class for custom exceptions.

abstract classmethod 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.InCollectionValidationError(name: str, value: list[str])

Bases: BaseValidationError

collection = 'Collection'

item = 'data'

classmethod message(name, value, validation=None)

Builds custom error message.

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

Bases: Exception

Error on uuid validation.

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

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

classmethod message(name, value, validation)

Builds custom error message.

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

Bases: InCollectionValidationError

collection = 'Form'

item = 'member'

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

Bases: BaseValidationError

classmethod message(name, value, validation=None)

Builds custom error message.

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

Bases: InCollectionValidationError

collection = 'UIJson'

item = 'parameter'

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

Bases: BaseValidationError

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

Builds custom error message.

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

Bases: InCollectionValidationError

collection = 'Workspace'

item = 'object'

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.TypeUIDValidationError(name: str, value, validation: list[str])

Bases: BaseValidationError

Error on type uid validation.

classmethod 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.UIJsonFormatError(name, msg)

Bases: BaseValidationError

classmethod 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

class geoh5py.shared.utils.SetDict(**kwargs)

Bases: dict

make_set(value)

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

geoh5py.shared.utils.are_objects_similar(obj1, obj2, ignore: list[str] | None)

Compare two objects to see if they are similar. This is a shallow comparison.

Parameters:

• obj1 – The first object.

• obj2 – The first object.

• ignore – List of attributes to ignore.

Returns:

If attributes similar or not.

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.box_intersect(extent_a: ndarray, extent_b: ndarray) → bool

Compute the intersection of two axis-aligned bounding extents defined by their arrays of minimum and maximum bounds in N-D space.

Parameters:

• extent_a – First extent or shape (2, N)

• extent_b – Second extent or shape (2, N)

Returns:

Logic if the box extents intersect along all dimensions.

geoh5py.shared.utils.clear_array_attributes(entity: Entity, recursive: bool = False)

Clear all stashed values of attributes from an entity to free up memory.

Parameters:

• entity – Entity to clear attributes from.

• recursive – Clear attributes from children entities.

geoh5py.shared.utils.compare_arrays(object_a, object_b, attribute: str, decimal: int = 6)

geoh5py.shared.utils.compare_bytes(object_a, object_b)

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

geoh5py.shared.utils.compare_floats(object_a, object_b, attribute: str, decimal: int = 6)

geoh5py.shared.utils.compare_list(object_a, object_b, attribute: str, ignore: list[str] | None)

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

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.dip_points(points: ndarray, dip: float, rotation: float = 0) → ndarray

Rotate points about the x-axis by the dip angle and then about the z-axis by the rotation angle. :param points: an array of points to rotate :param dip: the dip angle in radians :param rotation: the rotation angle in radians :return: the rotated points

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

Ensure that the value is a UUID.

If not, it raises a type error.

Parameters:

value – The value to ensure is a UUID.

Returns:

The verified UUID.

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 | File | Path, mode: str = 'r') → 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.map_attributes(object_, **kwargs)

Map attributes to an object. The object must have an ‘_attribute_map’.

Parameters:

• object – The object to map the attributes to.

• kwargs – The kwargs to map to the object.

geoh5py.shared.utils.mask_by_extent(locations: ndarray, extent: ndarray, inverse: bool = False) → 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.

• inverse – Return the complement of the mask extent.

Returns:

Array of bool for the locations inside or outside the box extent.

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.to_tuple(value: Any) → tuple

Convert value to a tuple.

Parameters:

value – The value to convert.

Returns:

A tuple

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

Convert UUID to a known entity.

geoh5py.shared.utils.xy_rotation_matrix(angle: float) → ndarray

Rotation matrix about the z-axis.

Parameters:

angle – Rotation angle in radians.

Return rot:

Rotation matrix.

geoh5py.shared.utils.yz_rotation_matrix(angle: float) → ndarray

Rotation matrix about the x-axis. :param angle: Rotation angle in radians. :return: rot: Rotation matrix.

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: type | list[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.