geoh5py.shared¶
geoh5py.shared.concatenation¶
geoh5py.shared.entity¶
- class geoh5py.shared.entity.Entity(uid: UUID | None = None, **kwargs)[source]¶
Bases:
ABC
Base Entity class
- property allow_delete: bool¶
bool
Entity can be deleted from the workspace.
- 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)[source]¶
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[source]¶
Abstract method to return the default type uid for the class.
- abstract property entity_type: shared.EntityType¶
Abstract property to get the entity type of the entity.
- classmethod fix_up_name(name: str) → str[source]¶
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[source]¶
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 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).
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, **_)[source]¶
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][source]¶
Convert the kwargs to the geoh5py attribute names.
- Parameters:
kwargs – The kwargs to convert.
- Returns:
The converted kwargs.
- classmethod create(workspace, **kwargs)[source]¶
WILL BE DEPRECATED IN 10.0.0 Creates a new instance of
DataType
with correspondingPrimitiveTypeEnum
.- 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)[source]¶
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[source]¶
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)[source]¶
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.
geoh5py.shared.exceptions¶
- exception geoh5py.shared.exceptions.AggregateValidationError(name: str, value: list[BaseValidationError])[source]¶
Bases:
BaseValidationError
- exception geoh5py.shared.exceptions.AssociationValidationError(name: str, value: Entity | PropertyGroup | UUID, validation: Entity | Workspace)[source]¶
Bases:
BaseValidationError
Error on association between child and parent entity validation.
- exception geoh5py.shared.exceptions.AtLeastOneValidationError(name: str, value: list[str])[source]¶
Bases:
BaseValidationError
- exception geoh5py.shared.exceptions.BaseValidationError[source]¶
Bases:
ABC
,Exception
Base class for custom exceptions.
- exception geoh5py.shared.exceptions.Geoh5FileClosedError[source]¶
Bases:
ABC
,Exception
Error for closed geoh5 file.
- exception geoh5py.shared.exceptions.InCollectionValidationError(name: str, value: list[str])[source]¶
Bases:
BaseValidationError
- collection = 'Collection'¶
- item = 'data'¶
- exception geoh5py.shared.exceptions.JSONParameterValidationError(name: str, err: str)[source]¶
Bases:
Exception
Error on uuid validation.
- exception geoh5py.shared.exceptions.OptionalValidationError(name: str, value: Any | None, validation: bool)[source]¶
Bases:
BaseValidationError
Error if None value provided to non-optional parameter.
- exception geoh5py.shared.exceptions.PropertyGroupValidationError(name: str, value: PropertyGroup, validation: str)[source]¶
Bases:
BaseValidationError
Error on property group validation.
- exception geoh5py.shared.exceptions.RequiredFormMemberValidationError(name: str, value: list[str])[source]¶
Bases:
InCollectionValidationError
- collection = 'Form'¶
- item = 'member'¶
- exception geoh5py.shared.exceptions.RequiredObjectDataValidationError(name: str, value: list[tuple[str, str]])[source]¶
Bases:
BaseValidationError
- exception geoh5py.shared.exceptions.RequiredUIJsonParameterValidationError(name: str, value: list[str])[source]¶
Bases:
InCollectionValidationError
- collection = 'UIJson'¶
- item = 'parameter'¶
- exception geoh5py.shared.exceptions.RequiredValidationError(name: str)[source]¶
Bases:
BaseValidationError
- exception geoh5py.shared.exceptions.RequiredWorkspaceObjectValidationError(name: str, value: list[str])[source]¶
Bases:
InCollectionValidationError
- collection = 'Workspace'¶
- item = 'object'¶
- exception geoh5py.shared.exceptions.ShapeValidationError(name: str, value: tuple[int, ...], validation: tuple[int, ...] | str)[source]¶
Bases:
BaseValidationError
Error on shape validation.
- exception geoh5py.shared.exceptions.TypeUIDValidationError(name: str, value, validation: list[str])[source]¶
Bases:
BaseValidationError
Error on type uid validation.
- exception geoh5py.shared.exceptions.TypeValidationError(name: str, value: str, validation: str | list[str])[source]¶
Bases:
BaseValidationError
Error on type validation.
- exception geoh5py.shared.exceptions.UIJsonFormatError(name, msg)[source]¶
Bases:
BaseValidationError
- exception geoh5py.shared.exceptions.UUIDValidationError(name: str, value: str)[source]¶
Bases:
BaseValidationError
Error on uuid string validation.
- exception geoh5py.shared.exceptions.ValueValidationError(name: str, value: Any, validation: list[Any])[source]¶
Bases:
BaseValidationError
Error on value validation.
- geoh5py.shared.exceptions.iterable(value: Any, checklen: bool = False) → bool[source]¶
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¶
- geoh5py.shared.utils.are_objects_similar(obj1, obj2, ignore: list[str] | None)[source]¶
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_uuid(value: UUID | Any) → str | Any[source]¶
Convert
UUID
to string used in geoh5.
- geoh5py.shared.utils.box_intersect(extent_a: ndarray, extent_b: ndarray) → bool[source]¶
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)[source]¶
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_entities(object_a, object_b, ignore: list[str] | None = None, decimal: int = 6) → None[source]¶
- geoh5py.shared.utils.compare_list(object_a, object_b, attribute: str, ignore: list[str] | None)[source]¶
- geoh5py.shared.utils.dict_mapper(val, string_funcs: list[Callable], *args, omit: dict | None = None)[source]¶
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[source]¶
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[source]¶
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.fetch_active_workspace(workspace: Workspace | None, mode: str = 'r')[source]¶
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[source]¶
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)[source]¶
Extract the attributes of an object with omissions.
- geoh5py.shared.utils.map_attributes(entity, **kwargs)[source]¶
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.mask_by_extent(locations: ndarray, extent: ndarray, inverse: bool = False) → ndarray[source]¶
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[source]¶
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[source]¶
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.stringify(values: dict[str, Any]) → dict[str, Any][source]¶
Convert all values in a dictionary to string.
- Parameters:
values – Dictionary of values to be converted.
- geoh5py.shared.utils.to_tuple(value: Any) → tuple[source]¶
Convert value to a tuple.
- Parameters:
value – The value to convert.
- Returns:
A tuple
- geoh5py.shared.utils.uuid2entity(value: UUID, workspace: Workspace) → Entity | Any[source]¶
Convert UUID to a known entity.
geoh5py.shared.validators¶
- class geoh5py.shared.validators.AssociationValidator(**kwargs)[source]¶
Bases:
BaseValidator
Validate the association between data and parent object.
- classmethod validate(name: str, value: Entity | PropertyGroup | UUID | None, valid: Entity | Workspace) → None[source]¶
- Parameters:
name – Parameter identifier.
value – Input parameter value.
valid – Expected value shape
- validator_type: str = 'association'¶
- class geoh5py.shared.validators.AtLeastOneValidator(**kwargs)[source]¶
Bases:
BaseValidator
- validator_type: str = 'one_of'¶
- class geoh5py.shared.validators.BaseValidator(**kwargs)[source]¶
Bases:
ABC
Concrete base class for validators.
- abstract classmethod validate(name: str, value: Any, valid: Any)[source]¶
Custom validation function.
- validator_type: str¶
- class geoh5py.shared.validators.OptionalValidator(**kwargs)[source]¶
Bases:
BaseValidator
Validate that forms contain optional parameter if None value is given.
- classmethod validate(name: str, value: Any | None, valid: bool) → None[source]¶
- 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)[source]¶
Bases:
BaseValidator
Validate property_group from parent entity.
- classmethod validate(name: str, value: PropertyGroup, valid: str) → None[source]¶
Custom validation function.
- validator_type: str = 'property_group_type'¶
- class geoh5py.shared.validators.RequiredValidator(**kwargs)[source]¶
Bases:
BaseValidator
Validate that required keys are present in parameter.
- classmethod validate(name: str, value: Any, valid: bool) → None[source]¶
- Parameters:
name – Parameter identifier.
value – Input parameter value.
valid – Assert to be required
- validator_type: str = 'required'¶
- class geoh5py.shared.validators.ShapeValidator(**kwargs)[source]¶
Bases:
BaseValidator
Validate the shape of provided value.
- classmethod validate(name: str, value: Any, valid: tuple[int, ...]) → None[source]¶
- Parameters:
name – Parameter identifier.
value – Input parameter value.
valid – Expected value shape
- validator_type: str = 'shape'¶
- class geoh5py.shared.validators.TypeValidator(**kwargs)[source]¶
Bases:
BaseValidator
Validate the value type from a list of valid types.
- classmethod validate(name: str, value: Any, valid: type | list[type]) → None[source]¶
- Parameters:
name – Parameter identifier.
value – Input parameter value.
valid – List of accepted value types
- validator_type: str = 'types'¶
- class geoh5py.shared.validators.UUIDValidator(**kwargs)[source]¶
Bases:
BaseValidator
Validate a uuui.UUID value or uuid string.
- classmethod validate(name: str, value: Any, valid: None = None) → None[source]¶
- 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)[source]¶
Bases:
BaseValidator
Validator that ensures that values are valid entries.
- classmethod validate(name: str, value: Any, valid: list[float | str]) → None[source]¶
- 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][source]¶
Promote uid to class, raise if uid is not a geoh5py type uid.
- geoh5py.shared.validators.empty_string_to_uid(value)[source]¶
Promote empty string to uid, and pass all other values.
- geoh5py.shared.validators.to_class(values: list[UUID | type[ObjectBase] | type[Group]]) → list[type[ObjectBase] | type[Group]][source]¶
Promote uid to class.
Passes existing classes and raises if uid is not a geoh5py type uid.
geoh5py.shared.weakref_utils¶
- geoh5py.shared.weakref_utils.get_clean_ref(some_dict: dict[K, ReferenceType[T]], key: K) → T | None[source]¶
Gets the referent value for the given
key
in asome_dict
ofweakref
values. In casekey
points to a reference to a deleted value, remove that key fromsome_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)[source]¶
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