evo-objects 0.6.4__tar.gz → 0.6.6__tar.gz

{evo_objects-0.6.4 → evo_objects-0.6.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: evo-objects
-Version: 0.6.4
+Version: 0.6.6
 Summary: Python SDK for using the Seequent Evo Geoscience Object API
 Project-URL: Source, https://github.com/SeequentEvo/evo-python-sdk
 Project-URL: Tracker, https://github.com/SeequentEvo/evo-python-sdk/issues
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://developer.seequent.com/
 Author-email: Seequent <support@seequent.com>
 License-File: LICENSE.md
 Requires-Python: >=3.10
-Requires-Dist: evo-sdk-common[jmespath]>=0.5.26
+Requires-Dist: evo-sdk-common[jmespath]>=0.5.31
 Requires-Dist: pydantic<3,>=2
 Provides-Extra: aiohttp
 Requires-Dist: evo-sdk-common[aiohttp]; extra == 'aiohttp'

{evo_objects-0.6.4 → evo_objects-0.6.6}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "evo-objects"
 description = "Python SDK for using the Seequent Evo Geoscience Object API"
-version = "0.6.4"
+version = "0.6.6"
 requires-python = ">=3.10"
 license-files = ["LICENSE.md"]
 dynamic = ["readme"]
@@ -10,7 +10,7 @@ authors = [
 ]
 
 dependencies = [
-    "evo-sdk-common[jmespath]>=0.5.26",
+    "evo-sdk-common[jmespath]>=0.5.31",
     "pydantic>=2,<3",
 ]
 

{evo_objects-0.6.4 → evo_objects-0.6.6}/src/evo/objects/exceptions.py

@@ -11,7 +11,7 @@
 
 from uuid import UUID
 
-from evo.common.exceptions import CustomTypedError, EvoClientException
+from evo.common.exceptions import BadRequestException, CustomTypedError, EvoClientException
 
 
 class SchemaIDFormatError(EvoClientException):
@@ -41,6 +41,30 @@ class SchemaValidationError(EvoClientException):
     """Failed to validate data against a geoscience object schema"""
 
 
+class InvalidGeoscienceObjectError(CustomTypedError, BadRequestException):
+    """The service rejected an object that does not match its geoscience object schema."""
+
+    TYPE_ID = "/geoscienceobject/schemas/invalid-object"
+
+    def __str__(self) -> str:
+        error_message = super().__str__()
+        detail = self.detail
+        if detail:
+            error_message = error_message.removesuffix(f"\nDetail: {detail}")
+        if json_path := self.content.get("json_path"):
+            error_message += f"\nInvalid value at: {json_path}"
+        if schema_path := self.content.get("schema_path"):
+            error_message += f"\nFailed schema rule: {schema_path}"
+        if detail:
+            if len(detail) > 500:
+                detail = (
+                    f"{detail[:250]} ... [omitted] ... {detail[-250:]}\n"
+                    "(For the full detail, catch this exception as exc and run print(exc.detail).)"
+                )
+            error_message += f"\nDetail: {detail}"
+        return error_message
+
+
 class ObjectAlreadyExistsError(CustomTypedError):
     TYPE_ID = "/geoscienceobject/objects/already-exists"
 

{evo_objects-0.6.4 → evo_objects-0.6.6}/src/evo/objects/typed/_grid.py

@@ -22,6 +22,7 @@ import pandas as pd
 from pydantic import AliasChoices, Field
 
 from evo.common import IFeedback
+from evo.common.typed import FloatArrayLike3, IntArrayLike3
 from evo.common.utils import NoFeedback
 
 from ._model import DataLocation, SchemaLocation, SchemaModel
@@ -46,23 +47,35 @@ class Base3DGridData(BaseSpatialObjectData):
     """Base class for all 3D grid data.
 
     Contains the common properties shared by all grid types: origin, size, rotation, and cell_data.
+    Origin and size accept their named types or three values in a list, tuple, or 1D array.
+    All inputs, including named types, are validated and normalized.
     """
 
-    origin: Point3
-    size: Size3i
+    origin: Point3 | FloatArrayLike3
+    size: Size3i | IntArrayLike3
     cell_data: pd.DataFrame | None = None
     rotation: Rotation | None = None
 
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "origin", Point3.from_array_like(self.origin))
+        object.__setattr__(self, "size", Size3i.from_array_like(self.size))
+
 
 @dataclass(kw_only=True, frozen=True)
 class BaseRegular3DGridData(Base3DGridData):
     """Base class for regular 3D grid data (both masked and non-masked).
 
     Contains the common properties shared by Regular3DGridData and RegularMasked3DGridData.
-    Adds cell_size to the base grid properties.
+    Adds cell_size to the base grid properties; it accepts a Size3d or three
+    values in a list, tuple, or 1D array.
+    All inputs, including Size3d instances, are validated and normalized.
     """
 
-    cell_size: Size3d
+    cell_size: Size3d | FloatArrayLike3
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        object.__setattr__(self, "cell_size", Size3d.from_array_like(self.cell_size))
 
     def compute_bounding_box(self) -> BoundingBox:
         return BoundingBox.from_regular_grid(self.origin, self.size, self.cell_size, self.rotation)
@@ -223,15 +236,20 @@ class RegularBlockModelData:
     """
 
     name: str
-    origin: Point3
-    n_blocks: Size3i
-    block_size: Size3d
+    origin: Point3 | FloatArrayLike3
+    n_blocks: Size3i | IntArrayLike3
+    block_size: Size3d | FloatArrayLike3
     cell_data: pd.DataFrame | None = None
     description: str | None = None
     coordinate_reference_system: str | None = None
     size_unit_id: str | None = None
     units: dict[str, str] = field(default_factory=dict)
 
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "origin", Point3.from_array_like(self.origin))
+        object.__setattr__(self, "n_blocks", Size3i.from_array_like(self.n_blocks))
+        object.__setattr__(self, "block_size", Size3d.from_array_like(self.block_size))
+
 
 @dataclass(frozen=True, kw_only=True)
 class BlockModelData(BaseSpatialObjectData):

{evo_objects-0.6.4 → evo_objects-0.6.6}/src/evo/objects/typed/base.py

@@ -19,8 +19,9 @@ from dataclasses import dataclass
 from typing import Annotated, Any, ClassVar
 from uuid import UUID
 
-from evo import jmespath
+from evo import jmespath, logging
 from evo.common import IContext, IFeedback, StaticContext
+from evo.common.exceptions import error_context
 from evo.common.utils import NoFeedback
 from evo.objects import DownloadedObject, ObjectMetadata, ObjectReference, ObjectSchema, SchemaVersion
 
@@ -36,6 +37,8 @@ if sys.version_info >= (3, 11):
 else:
     from typing_extensions import Self
 
+logger = logging.getLogger("object")
+
 __all__ = [
     "BaseObject",
     "BaseObjectData",
@@ -254,9 +257,15 @@ class _BaseObject(SchemaModel):
 
         # Take a copy to avoid the context changes affecting the object
         context = StaticContext.create_copy(context)
-        object_dict = await cls._data_to_schema(data, context)
+        description = f"{cls.__name__} '{data.name}'"
+        with error_context(f"While preparing data for {description}", logger=logger):
+            object_dict = await cls._data_to_schema(data, context)
         object_dict["uuid"] = None  # New UUID is generated by the service
-        obj = await create_geoscience_object(context, object_dict, parent, path)
+        target = f"path '{path}'" if path is not None else f"parent path '{parent or ''}'"
+        with error_context(
+            f"While creating {description} at {target} (schema: {object_dict['schema']})", logger=logger
+        ):
+            obj = await create_geoscience_object(context, object_dict, parent, path)
         return cls(obj)
 
     @classmethod
@@ -285,10 +294,15 @@ class _BaseObject(SchemaModel):
             workspace_id=reference.workspace_id,
         )
 
-        object_dict = await cls._data_to_schema(data, reference_context)
-        obj = await replace_geoscience_object(
-            reference_context, reference, object_dict, create_if_missing=create_if_missing
-        )
+        description = f"{cls.__name__} '{data.name}'"
+        with error_context(f"While preparing replacement data for {description}", logger=logger):
+            object_dict = await cls._data_to_schema(data, reference_context)
+        with error_context(
+            f"While replacing {description} at '{reference}' (schema: {object_dict['schema']})", logger=logger
+        ):
+            obj = await replace_geoscience_object(
+                reference_context, reference, object_dict, create_if_missing=create_if_missing
+            )
         return cls(obj)
 
     @classmethod
@@ -362,12 +376,18 @@ class _BaseObject(SchemaModel):
 
         :return: A new instance with refreshed data.
 
-        Example:
+        Example::
+
             >>> # After a remote operation modifies the object...
             >>> obj = await obj.refresh()
             >>> obj.attributes  # Now shows the latest attributes
         """
-        return await self.from_reference(self._api_context, self.metadata.url)
+        # metadata.url pins the current version_id, which would just re-download the same version.
+        latest_reference = ObjectReference.new(
+            environment=self.metadata.environment,
+            object_id=self.metadata.id,
+        )
+        return await self.from_reference(self._api_context, latest_reference)
 
     def search(self, expression: str) -> Any:
         """Search the object metadata using a JMESPath expression.

{evo_objects-0.6.4 → evo_objects-0.6.6}/src/evo/objects/typed/block_model_ref.py

@@ -192,7 +192,8 @@ class BlockModel(BaseSpatialObject):
             :param fb: Optional feedback interface for progress reporting.
             :return: DataFrame containing the block model data with user-friendly column names.
 
-            Example:
+            Example::
+
                 >>> df = await block_model.to_dataframe()
                 >>> df.head()
             """
@@ -207,7 +208,8 @@ class BlockModel(BaseSpatialObject):
 
             :return: A new BlockModel instance with refreshed data.
 
-            Example:
+            Example::
+
                 >>> # After running kriging that adds attributes...
                 >>> block_model = await block_model.refresh()
                 >>> block_model.attributes  # Now shows the new attributes
@@ -335,7 +337,8 @@ class BlockModel(BaseSpatialObject):
             :param fb: Optional feedback interface for progress reporting.
             :return: The updated BlockModel instance (refreshed from server).
 
-            Example:
+            Example::
+
                 >>> from evo.blockmodels import Units
                 >>> block_model = await block_model.set_attribute_units({
                 ...     "Au": Units.GRAMS_PER_TONNE,
@@ -361,7 +364,8 @@ class BlockModel(BaseSpatialObject):
             :param fb: Optional feedback interface for progress reporting.
             :return: A Report instance representing the created report.
 
-            Example:
+            Example::
+
                 >>> from evo.blockmodels.typed import ReportSpecificationData, ReportColumnSpec, ReportCategorySpec
                 >>> report = await block_model.create_report(ReportSpecificationData(
                 ...     name="Gold Resource Report",

{evo_objects-0.6.4 → evo_objects-0.6.6}/src/evo/objects/typed/regular_grid.py

@@ -36,6 +36,7 @@ class Regular3DGridData(BaseRegular3DGridData):
     vertex_data: pd.DataFrame | None = None
 
     def __post_init__(self):
+        super().__post_init__()
         if self.cell_data is not None and self.cell_data.shape[0] != self.size.total_size:
             raise ObjectValidationError(
                 f"The number of rows in the cell_data dataframe ({self.cell_data.shape[0]}) does not match the number of cells in the grid ({self.size.nx * self.size.ny * self.size.nz})."

{evo_objects-0.6.4 → evo_objects-0.6.6}/src/evo/objects/typed/regular_masked_grid.py

@@ -43,6 +43,7 @@ class RegularMasked3DGridData(BaseRegular3DGridData):
     mask: np.ndarray
 
     def __post_init__(self):
+        super().__post_init__()
         if self.mask.shape[0] != self.size.total_size:
             raise ObjectValidationError(
                 f"The number of rows in the mask ({self.mask.shape[0]}) does not match the number of cells in the grid ({self.size.nx * self.size.ny * self.size.nz})."

{evo_objects-0.6.4 → evo_objects-0.6.6}/src/evo/objects/typed/tensor_grid.py

@@ -69,6 +69,7 @@ class Tensor3DGridData(Base3DGridData):
     vertex_data: pd.DataFrame | None = None
 
     def __post_init__(self):
+        super().__post_init__()
         # Validate cell size array lengths
         if self.cell_sizes_x.shape[0] != self.size.nx:
             raise ObjectValidationError(

{evo_objects-0.6.4 → evo_objects-0.6.6}/src/evo/objects/typed/types.py

@@ -12,6 +12,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from numbers import Real
 from typing import Annotated, Any, overload
 
 import numpy as np
@@ -20,7 +21,7 @@ import pydantic
 
 # Import basic geometry types from evo.common and re-export
 from evo.common.crs import EpsgCode, parse_crs
-from evo.common.typed import Point3, Size3d, Size3i
+from evo.common.typed import FloatArrayLike3, Point3, Size3d, Size3i, _validate_array_like
 
 __all__ = [
     "BoundingBox",
@@ -204,12 +205,26 @@ class BoundingBox:
 
 @dataclass(frozen=True)
 class Rotation:
-    """A rotation defined by dip azimuth, dip, and pitch angles."""
+    """A clockwise intrinsic ZXZ Euler rotation in degrees.
+
+    Dip azimuth [0, 360], dip [0, 180], and pitch [0, 360] rotate about
+    successive local Z, X, and Z axes, respectively. For column vectors,
+    the rotation matrix is Rz(dip azimuth) @ Rx(dip) @ Rz(pitch).
+    """
 
     dip_azimuth: float
     dip: float
     pitch: float
 
+    def __post_init__(self) -> None:
+        for name, value, lower, upper in (
+            ("dip_azimuth", self.dip_azimuth, 0, 360),
+            ("dip", self.dip, 0, 180),
+            ("pitch", self.pitch, 0, 360),
+        ):
+            if not isinstance(value, Real) or isinstance(value, bool) or not lower <= value <= upper:
+                raise ValueError(f"{name} must be a finite angle between {lower} and {upper} degrees (inclusive)")
+
     def as_rotation_matrix(self) -> np.ndarray:
         """Convert the rotation to a rotation matrix.
 
@@ -246,6 +261,12 @@ class Rotation:
         # Combined intrinsic rotations: dip_azimuth -> dip -> pitch
         return dip_azimuth_rotation_matrix @ dip_rotation_matrix @ pitch_rotation_matrix
 
+    @classmethod
+    def from_array_like(cls, value: Rotation | FloatArrayLike3) -> Rotation:
+        if isinstance(value, Rotation):
+            value = (value.dip_azimuth, value.dip, value.pitch)
+        return cls(*_validate_array_like(value, kind=Real, positive=False))
+
 
 @dataclass
 class EllipsoidRanges:
@@ -256,9 +277,9 @@ class EllipsoidRanges:
     minor: float
 
     def __init__(self, major: float, semi_major: float, minor: float):
-        self.major = major
-        self.semi_major = semi_major
-        self.minor = minor
+        self.major, self.semi_major, self.minor = _validate_array_like(
+            (major, semi_major, minor), kind=Real, positive=True
+        )
 
     def to_dict(self) -> dict[str, Any]:
         return {"major": self.major, "semi_major": self.semi_major, "minor": self.minor}
@@ -270,17 +291,37 @@ class EllipsoidRanges:
             minor=self.minor * factor,
         )
 
+    @classmethod
+    def from_array_like(cls, value: EllipsoidRanges | FloatArrayLike3) -> EllipsoidRanges:
+        if isinstance(value, EllipsoidRanges):
+            value = (value.major, value.semi_major, value.minor)
+        return cls(*_validate_array_like(value, kind=Real, positive=True))
+
 
 @dataclass
 class Ellipsoid:
-    """An ellipsoid defining a spatial region."""
+    """An ellipsoid defining a spatial region.
+
+    Ranges are ordered major, semi-major, minor. Rotation angles are in
+    degrees and ordered dip azimuth [0, 360], dip [0, 180], pitch [0, 360].
+    They specify clockwise intrinsic rotations about the successive Z, X,
+    and Z axes, respectively.
+
+    Ranges accept an EllipsoidRanges instance or a three-value list, tuple,
+    or 1D NumPy array. Rotation accepts a Rotation instance or the same
+    three-value sequence forms; omitting it applies no rotation.
+    """
 
     ranges: EllipsoidRanges
     _rotation: Rotation | None = None
 
-    def __init__(self, ranges: EllipsoidRanges, rotation: Rotation | None = None):
-        self.ranges = ranges
-        self._rotation = rotation
+    def __init__(
+        self,
+        ranges: EllipsoidRanges | FloatArrayLike3,
+        rotation: Rotation | FloatArrayLike3 | None = None,
+    ):
+        self.ranges = EllipsoidRanges.from_array_like(ranges)
+        self._rotation = Rotation.from_array_like(rotation) if rotation is not None else None
 
     @property
     def rotation(self) -> Rotation:

{evo_objects-0.6.4 → evo_objects-0.6.6}/src/evo/objects/typed/variogram.py

@@ -70,7 +70,8 @@ class VariogramStructure:
         - Creating search ellipsoids via scaled()
         - Kriging search neighborhoods
 
-        Example:
+        Example::
+
             >>> # Get ellipsoid from variogram structure
             >>> var_ell = variogram.structures[0].to_ellipsoid()
             >>>
@@ -277,7 +278,8 @@ class VariogramData(BaseObjectData):
         - `modelling_space`: Set to "data" for original units or "normalscore" for gaussian space
         - `data_variance`: Should match the sill value for non-normalized data
 
-    Example using typed structures (recommended):
+    Example using typed structures (recommended)::
+
         >>> data = VariogramData(
         ...     name="My Variogram",
         ...     sill=1.0,
@@ -407,7 +409,8 @@ class Variogram(BaseObject):
         Returns:
             Ellipsoid configured with the structure's anisotropy ranges and rotation.
 
-        Example:
+        Example::
+
             >>> # Get ellipsoid from structure with largest range (default)
             >>> var_ell = variogram.get_ellipsoid()
             >>>
@@ -475,7 +478,8 @@ class Variogram(BaseObject):
         Returns:
             Tuple of (major_curve, semi_major_curve, minor_curve) as VariogramCurveData.
 
-        Example with Plotly:
+        Example with Plotly::
+
             >>> major, semi_maj, minor = variogram.get_principal_directions()
             >>> import plotly.graph_objects as go
             >>> fig = go.Figure()
@@ -549,7 +553,8 @@ class Variogram(BaseObject):
         Returns:
             Tuple of (distance, semivariance) as numpy arrays, suitable for plotting.
 
-        Example with Plotly:
+        Example with Plotly::
+
             >>> distance, semivariance = variogram.get_direction(azimuth=45, dip=30)
             >>> import plotly.graph_objects as go
             >>> fig = go.Figure()
@@ -557,7 +562,8 @@ class Variogram(BaseObject):
             >>> fig.update_layout(xaxis_title='Distance', yaxis_title='Semivariance')
             >>> fig.show()
 
-        Example with Matplotlib:
+        Example with Matplotlib::
+
             >>> distance, semivariance = variogram.get_direction(azimuth=0, dip=0)
             >>> import matplotlib.pyplot as plt
             >>> plt.plot(distance, semivariance)

{evo_objects-0.6.4 → evo_objects-0.6.6}/src/evo/objects/utils/data.py

@@ -19,7 +19,7 @@ import numpy as np
 
 from evo import logging
 from evo.common import APIConnector, Environment, ICache, IFeedback, StaticContext
-from evo.common.exceptions import StorageFileNotFoundError
+from evo.common.exceptions import StorageFileNotFoundError, error_context
 from evo.common.io.exceptions import DataExistsError
 from evo.common.utils import NoFeedback, PartialFeedback, split_feedback
 
@@ -143,22 +143,24 @@ class ObjectDataClient:
         n_names = len(names)
         logger.debug(f"Found {n_names} data reference{'' if n_names == 1 else 's'}")
         n_uploaded = 0
-        async for ctx in ObjectDataUpload._create_multiple(
-            connector=self._connector,
-            environment=self._environment,
-            names=names,
-        ):
-            if fb is not NoFeedback:
-                fb_part = PartialFeedback(parent=fb, start=n_uploaded / n_names, end=(n_uploaded + 1) / n_names)
-            else:
-                fb_part = NoFeedback
-
-            data_file = self.cache_location / ctx.name
-            logger.debug(f"Uploading data: {ctx.name}")
-            if not data_file.exists():
-                raise StorageFileNotFoundError(f"Object data file not found in cache: {data_file}")
-            await ctx.upload_from_path(filename=data_file, transport=self._connector.transport, fb=fb_part)
-            n_uploaded += 1
+        with error_context("While uploading referenced data", logger=logger):
+            async for ctx in ObjectDataUpload._create_multiple(
+                connector=self._connector,
+                environment=self._environment,
+                names=names,
+            ):
+                if fb is not NoFeedback:
+                    fb_part = PartialFeedback(parent=fb, start=n_uploaded / n_names, end=(n_uploaded + 1) / n_names)
+                else:
+                    fb_part = NoFeedback
+
+                with error_context(f"While uploading referenced data '{ctx.name}'", logger=logger):
+                    data_file = self.cache_location / ctx.name
+                    logger.debug(f"Uploading data: {ctx.name}")
+                    if not data_file.exists():
+                        raise StorageFileNotFoundError(f"Object data file not found in cache: {data_file}")
+                    await ctx.upload_from_path(filename=data_file, transport=self._connector.transport, fb=fb_part)
+                n_uploaded += 1
 
         logger.debug(
             f"Uploaded {n_uploaded} data reference{'' if n_uploaded == 1 else 's'}, skipped {n_names - n_uploaded}"
@@ -183,9 +185,10 @@ class ObjectDataClient:
         """
         from .table_formats import get_known_format
 
-        if not isinstance(table_format, KnownTableFormat):
-            table_format = get_known_format(table, table_formats=table_format)
-        table_info = table_format.save_table(table=table, destination=self.cache_location)
+        with error_context("While preparing an Arrow table for Evo Parquet storage", logger=logger):
+            if not isinstance(table_format, KnownTableFormat):
+                table_format = get_known_format(table, table_formats=table_format)
+            table_info = table_format.save_table(table=table, destination=self.cache_location)
         return table_info
 
     async def upload_table(
@@ -210,11 +213,12 @@ class ObjectDataClient:
         """
         table_info = self.save_table(table, table_format)
         upload = ObjectDataUpload(connector=self._connector, environment=self._environment, name=table_info["data"])
-        try:
-            await upload.upload_from_cache(cache=self._cache, transport=self._connector.transport, fb=fb)
-        except DataExistsError:
-            logger.debug(f"Data not uploaded because data already exists (label: {table_info['data']})")
-            fb.progress(1)
+        with error_context(f"While uploading table data '{table_info['data']}'", logger=logger):
+            try:
+                await upload.upload_from_cache(cache=self._cache, transport=self._connector.transport, fb=fb)
+            except DataExistsError:
+                logger.debug(f"Data not uploaded because data already exists (label: {table_info['data']})")
+                fb.progress(1)
         return table_info
 
     async def upload_category_table(self, table: pa.Table, fb: IFeedback = NoFeedback) -> CategoryInfo: