geoh5py.shared package

geoh5py.shared package#

Subpackages#

Submodules#

geoh5py.shared.entity module#

class geoh5py.shared.entity.Entity(*, entity_type: shared.EntityType | None = None, allow_delete: bool = True, allow_move: bool = True, allow_rename: bool = True, clipping_ids: list[uuid.UUID] | None = None, metadata: dict | None = None, name: str | None = None, on_file: bool = False, partially_hidden: bool = False, parent: EntityContainer | None = None, public: bool = True, uid: uuid.UUID | None = None, visible: bool = True, **kwargs)#

Bases: ABC

Base entity class for Objects, Groups and Data.

Parameters:

entity_type – Entity type registered by the Workspace.
allow_delete – Entity can be deleted from the workspace.
allow_move – Entity can change parent
allow_rename – Entity can change name
clipping_ids – List of clipping uuids
metadata – Metadata attached to the entity.
name – Name of the entity
on_file – Whether this Entity is already stored on h5file.
partially_hidden – Whether this Entity is partially hidden.
parent – Parent entity.
public – Whether this Entity is accessible in the workspace tree and other parts of the user interface in ANALYST.
uid – Unique identifier of the entity.
visible – Whether the Entity is visible in camera (checked in ANALYST object tree).

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 classmethod default_type_uid() → UUID | None#: Abstract method to return the default type uid for the class.

abstract property entity_type#: Abstract property to get the entity type of the entity.

classmethod find_or_create_type(workspace: Workspace, **kwargs) → EntityType#

Find or create a type instance for a given object class.

Parameters:: workspace – Target Workspace.
Returns:: The ObjectType instance for the given object class.

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#

update_metadata(value: dict)#

Update the metadata of the entity.

Parameters:: value – Metadata to update.

abstract validate_entity_type(entity_type)#: Validate the entity type.

validate_metadata(value: ndarray | dict | None) → dict | None#

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_container module#

class geoh5py.shared.entity_container.EntityContainer(**kwargs)#

Bases: Entity

Base Entity class

add_children(children: Entity | PropertyGroup | list[Entity | PropertyGroup])#

Parameters:: children – Add a list of entities as children

add_comment(comment: str, author: str | None = None)#

Add text comment to an object.

Parameters:

comment – Text to be added as comment.
author – Author’s name or contributors.

add_file(file: str | Path | bytes, name: str = 'filename.dat')#

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

Parameters:

file – File name with path to import.
name – Name of the file in the workspace.

property children#: list Children entities in the workspace tree

property comments#: Fetch a CommentsData entity from children.

abstract copy(parent=None, *, copy_children: bool = True, clear_cache: bool = False, **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.
clear_cache – Clear array attributes after copy to minimize the memory footprint of the workspace.
kwargs – Additional keyword arguments to pass to the copy constructor.

Return entity:

Registered Entity to the workspace.

copy_from_extent(extent: ndarray, parent=None, *, copy_children: bool = True, clear_cache: bool = False, inverse: bool = False, **kwargs) → Entity | None#

Function to copy an entity to a different parent entity.

Parameters:

extent – Bounding box extent requested for the input entity, as supplied for mask_by_extent().
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.
clear_cache – Clear array attributes after copy.
inverse – Keep the inverse (clip) of the extent selection.
kwargs – Additional keyword arguments to pass to the copy constructor.

Return entity:

Registered Entity to the workspace.

classmethod default_type_uid() → UUID | None#: Default uuid for the entity type.

get_entity(name: str | UUID) → list[Entity | None]#

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.

remove_children(children: list[shared.Entity | PropertyGroup])#

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().

geoh5py.shared.entity_type module#

class geoh5py.shared.entity_type.EntityType(workspace: Workspace, *, uid: uuid.UUID | None = None, description: str | None = 'Entity', name: str = '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_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[Entity] | 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#: 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 module#

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.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: list[str])#

Bases: BaseValidationError

Error on property group validation.

classmethod message(name, value, validation)#: Builds custom error message.

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

Bases: BaseValidationError

classmethod 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.exceptions.iterable(value: Any, checklen: bool = False) → bool#: Checks if object is iterable.

Parameters#

value : Object to check for iterableness. checklen : Restrict objects with __iter__ method to len > 1.

Returns#

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

geoh5py.shared.exceptions.iterable_message(valid: list[Any] | None) → str#: Append possibly iterable valid: “Must be (one of): {valid}.”.

geoh5py.shared.utils module#

class geoh5py.shared.utils.ClassIdentifierEnum(value)#

Bases: Enum

An enumeration.

DEFAULT_NAME = '_default_name'#

DEFAULT_TYPE_UID = '_TYPE_UID'#

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_affine(points: ndarray, tol: float = 1e-06) → bool#

Check if world points can be explained by an affine transformation from pixel coordinates.

Requires coplanarity check first. Returns True for fewer than 3 points.

Parameters:

points – List of (pixel_coords, world_coords) tuples.
tol – Maximum allowed residual distance.

Returns:

True if affine transformation fits within tolerance.

geoh5py.shared.utils.are_coplanar(points: ndarray, tol: float = 1e-06) → bool#

Check if a set of points are coplanar.

Parameters:

points – Array of shape (N, 3) containing the points to check.
tol – Tolerance for coplanarity check.

Returns:

True if points are coplanar, False otherwise.

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.are_orthogonal(point1: ndarray, point2: ndarray, point3: ndarray, tol: float = 1e-06) → bool#

Check if the vectors formed by three points are orthogonal.

Parameters:

point1 – First point as a numpy array.
point2 – Second point as a numpy array.
point3 – Third point as a numpy array.
tol – Tolerance for orthogonality check.

Returns:

True if the vectors are orthogonal within the given tolerance.

geoh5py.shared.utils.array_is_colour(values: ndarray) → bool#

Check if the values are RGB or RGBA. The function does not consider the type as we are formatting it.

Parameters:: values – The values to check.
Returns:: True if the values are RGB or RGBA.

geoh5py.shared.utils.as_float_if_isnumeric(value: str) → float | str#: Convert bytes to string

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 | Sequence, extent_b: ndarray | Sequence) → 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 coordinated, array or list of shape (2, N)
extent_b – Second extent coordinated, array or list of shape (2, N)

Returns:

Logic if the box extents intersect along all dimensions.

geoh5py.shared.utils.clean_extent_for_intersection(extent: ndarray, locations: ndarray) → ndarray#

Clean and prepare extent array for 3D intersection calculations.

Parameters:

extent – Input extent array, shape (2, 2) or (2, 3)
locations – Array of vertices to extract Z bounds from, shape (N, 3)

Returns:

Cleaned extent array with shape (2, 3)

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)#

Utility to compare array properties from two Entities

Parameters:

object_a – First Entity
object_b – Second Entity
attribute – Attribute to compare
decimal – Decimal precision for comparison

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.copy_dict_relatives(values: dict, parent: EntityContainer | Workspace, clear_cache: bool = False)#

Copy the objects and groups referenced in a dictionary of values to a new parent.

The input dictionary is not modified. The values must be already promoted.

Parameters:

values – A dictionary of values possibly containing references to objects and groups.
parent – The parent to copy the objects and groups to.
clear_cache – If True, clear the array attributes of the copied objects and groups.

geoh5py.shared.utils.copy_no_reference(values: dict) → dict#

Copy a dictionary without references to objects UUID.

Parameters:: values – The dictionary to copy.
Returns:: The copied dictionary.

geoh5py.shared.utils.decode_byte_array(values: ndarray, data_type: type) → array#

Decode a byte array to an array of a given data type.

Parameters:

values – The byte array to decode.
data_type – The data type to convert the values to.

Returns:

The decoded array.

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.dict_to_json_str(data: dict) → str#

Format all values in a dictionary for json serialization.

Parameters:: data – Dictionary of values to be converted.
Returns:: A json string representation of the dictionary.

geoh5py.shared.utils.dip_azimuth_to_vector(dip: float | ndarray, azimuth: float | ndarray) → ndarray#

Convert dip and azimuth to a unit vector.

Parameters:

dip – The dip angle in degree from horizontal (positive up).
azimuth – The azimuth angle in degree from North (clockwise).

Returns:

The unit vector.

geoh5py.shared.utils.ensure_counter_clockwise(polygon: ndarray) → ndarray#

Ensure polygon vertices are ordered counter-clockwise.

Reverses the vertex order if the polygon area is negative (clockwise orientation).

Parameters:: polygon – Array of shape (N, 2) containing polygon vertices.
Returns:: Polygon vertices in counter-clockwise order.

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.equalize_string(x: str) → str#: Replaces spaces and lowercases for flexible string comparison.

geoh5py.shared.utils.extract_uids(values) → list[UUID] | None#

Extract the UUIDs from a list of UUIDs, Data objects or strings.

Parameters:: values – A list of UUIDs, Data objects or strings.
Returns:: A list of UUIDs or None if input is None.

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.find_unique_name(name: str, names: list[str], case_sensitive=True) → str#

Generate a unique name not in names. If the name ends with (n), increment n until unique. For files with extensions, insert the counter before all extensions.

Parameters:

name – Proposed name.
names – List of names to avoid.

Returns:

A unique name.

geoh5py.shared.utils.format_numeric_values(input_values: ndarray, n_decimals: int, max_chars: int) → ndarray#

Format numeric values for display.

For values that are too long, scientific notation is used. If the value is less than 1, it is rounded to a number of decimals depending on its magnitude. Trailing zeros and decimal points are removed.

Parameters:

input_values – The array of values to format.
n_decimals – The number of decimal places to round to.
max_chars – The maximum number of characters for each formatted value.

Returns:

An array of formatted strings.

geoh5py.shared.utils.get_attributes(entity, omit_list=(), attributes=None) → dict#: Extract the attributes of an object with omissions.

geoh5py.shared.utils.get_unique_name_from_entities(name: str, entities: list[Any], key: str = 'name', types: type | tuple[type] | None = None) → str#

Find a unique name in an object, optionally filtering by type.

Parameters:

name – Proposed name.
entities – The list of entities to search in.
key – The key of the object to extract
types – If provided, only entities of this type will be considered.

Returns:

A unique name.

geoh5py.shared.utils.inf2str(value)#

geoh5py.shared.utils.is_uuid(value: str) → bool#: Check if a string is UUID compliant.

geoh5py.shared.utils.list2str(value)#

geoh5py.shared.utils.map_attributes(object_, **kwargs)#

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

Parameters:

entity – The object to map the attributes to.
kwargs – The kwargs to map to the object.

geoh5py.shared.utils.map_name_attributes(object_, **kwargs: dict) → dict#

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

Parameters:

object – The object to map the attributes to.
kwargs – Dictionary of attributes.

geoh5py.shared.utils.map_to_class(class_identifier: ClassIdentifierEnum, search_modules: list[ModuleType]) → dict#

Create map from an identifier class attribute to class in provided modules.

Parameters:

class_identifier – Class attribute that identifies a class.
search_modules – Modules to search for classes.

geoh5py.shared.utils.mask_by_extent(locations: ndarray, extent: ndarray | Sequence, 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.min_max_scaler(values: ndarray, min_scaler: float = 0.0, max_scaler: float = 1.0, axis: None | int = None) → ndarray#

Min-Max scale an array.

Parameters:

values – The array to scale.
min_scaler – The minimum value to scale to.
max_scaler – The maximum value to scale to.
axis – Axis to apply scaling (eg. 0 for columns, 1 for rows).

Returns:

The scaled array.

geoh5py.shared.utils.nan2str(value)#

geoh5py.shared.utils.none2str(value)#

geoh5py.shared.utils.normalize(vector: ndarray | list) → ndarray#

Normalize a vector to unit length.

Parameters:: vector – Input vector to normalize.
Returns:: Normalized vector with unit length.

geoh5py.shared.utils.path2str(value)#

geoh5py.shared.utils.remove_duplicates_in_list(input_list: list) → list#

Remove duplicates from a list without changing the sorting.

Parameters:: input_list – the list to remove duplicates from.
Returns:: The sorted list

geoh5py.shared.utils.set_attributes(entity, **kwargs)#

Loop over kwargs and set attributes to an entity.

TODO: Deprecate in favor of explicit attribute setting.

geoh5py.shared.utils.split_name_suffixes(name: str) → tuple[str, str]#: Split the base name from its suffixes assuming they are separated by periods.

geoh5py.shared.utils.str2none(value)#

geoh5py.shared.utils.str2uuid(value: Any) → UUID | Any#: Convert string to UUID

geoh5py.shared.utils.str_json_to_dict(string: str | bytes) → dict#

Convert a json string or bytes to a dictionary.

Parameters:: string – The json string or bytes to convert to a dictionary.
Returns:: The dictionary representation of the json string with uuid promoted.

geoh5py.shared.utils.stringify(values: dict[str, Any]) → dict[str, Any]#

Convert all values in a dictionary to string.

Parameters:: values – Dictionary of values to be converted.
Returns:: Dictionary of string values.

geoh5py.shared.utils.to_list(value: Any) → list#

Convert value to a list.

Parameters:: value – The value to convert.
Returns:: A list

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.uuid_from_values(data: dict | str) → UUID#

Create a deterministic uuid of a dictionary or its json string representation.

Floats are formatted to fixed precision scientific notation and objects are converted to uid strings.

Parameters:: data – Dictionary or a string representation of a dictionary containing

parameters/values of an application.

Returns:: Unique but recoverable uuid file identifier string.

geoh5py.shared.utils.validate_3d_array(value: ndarray) → ndarray#

Validate that input is a 3D numpy array.

Parameters:: value – Input array to validate.
Returns:: The validated 3D array.

geoh5py.shared.utils.validate_normalized_vector(value: ndarray) → ndarray#

Validate that input is a normalized 3D vector.

Parameters:: value – Input array to validate.
Returns:: The validated normalized 3D vector.

geoh5py.shared.utils.workspace2path(value)#

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 module#

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: str = 'association'#

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

Bases: BaseValidator

classmethod validate(name, value, valid)#: Custom validation function.

validator_type: str = '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.

validator_type: str#

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: str = 'optional'#

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

Bases: BaseValidator

Validate property_group from parent entity.

classmethod validate(name: str, value: PropertyGroup, valid: str | list[str]) → None#: Custom validation function.

validator_type: str = '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: str = '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: str = '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: str = '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: str = '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: str = 'values'#

geoh5py.shared.validators.class_or_raise(value: UUID) → type[ObjectBase] | type[Group]#: Promote uid to class, raise if uid is not a geoh5py type uid.

geoh5py.shared.validators.none_to_empty_string(value)#: None transforms to empty string for serialization.

geoh5py.shared.validators.to_class(values: list[UUID | type[ObjectBase] | type[Group]]) → list[type[ObjectBase] | type[Group]]#

Promote uid to class.

Passes existing classes and raises if uid is not a geoh5py type uid.

geoh5py.shared.validators.to_list(value: Any) → list[Any]#: Promote single values to list.

geoh5py.shared.validators.to_path(value: list[str]) → list[Path]#: Promote path strings to patlib.Path objects.

Promote strings to uuid and pass anything else.

Strings can represent both uid(s) or names that represent geoh5py objects. We first attempt to convert strings to uid(s) and then fall back on conversion from name to class(es), and finally to type uid(s). GA naming doesn’t match geoh5py naming, so we must map names to classes before type uid conversion.

Parameters:: values – List of strings representing either geoh5py type uids or class names.
Returns:: List of UUID or geoh5py objects/groups.

geoh5py.shared.validators.types_to_string(types: list) → list[str] | str#

geoh5py.shared.weakref_utils module#

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.

geoh5py.shared package

Contents

geoh5py.shared package#

Subpackages#

Submodules#

geoh5py.shared.entity module#

geoh5py.shared.entity_container module#

geoh5py.shared.entity_type module#

geoh5py.shared.exceptions module#

Parameters#

Returns#

geoh5py.shared.utils module#

geoh5py.shared.validators module#

geoh5py.shared.weakref_utils module#

Module contents#