evo-objects 0.3.3__tar.gz → 0.4.0__tar.gz

{evo_objects-0.3.3 → evo_objects-0.4.0}/.gitignore

@@ -14,7 +14,7 @@ build/
 # Reporting
 .coverage
 
-# Environmnents
+# Environments
 venv/
 venv*/
 .venv/
@@ -31,3 +31,12 @@ samples/*/download*/data/*
 
 # macOS invisible files
 .DS_Store
+
+# MkDocs
+mkdocs/site/*
+!mkdocs/site/packages/
+!mkdocs/site/packages/**
+!mkdocs/site/
+
+# Other
+drilling_campaign.xlsx

{evo_objects-0.3.3 → evo_objects-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evo-objects
-Version: 0.3.3
+Version: 0.4.0
 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
@@ -13,6 +13,8 @@ Requires-Dist: evo-sdk-common[jmespath]>=0.5.8
 Requires-Dist: pydantic<3,>=2
 Provides-Extra: aiohttp
 Requires-Dist: evo-sdk-common[aiohttp]; extra == 'aiohttp'
+Provides-Extra: blockmodels
+Requires-Dist: evo-blockmodels[utils]>=0.2.0; extra == 'blockmodels'
 Provides-Extra: notebooks
 Requires-Dist: evo-sdk-common[notebooks]; extra == 'notebooks'
 Provides-Extra: utils

{evo_objects-0.3.3 → evo_objects-0.4.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "evo-objects"
 description = "Python SDK for using the Seequent Evo Geoscience Object API"
-version = "0.3.3"
+version = "0.4.0"
 requires-python = ">=3.10"
 license-files = ["LICENSE.md"]
 dynamic = ["readme"]
@@ -24,11 +24,12 @@ Documentation = "https://developer.seequent.com/"
 aiohttp = ["evo-sdk-common[aiohttp]"]
 notebooks = ["evo-sdk-common[notebooks]"]
 utils = ["pyarrow", "pyarrow-stubs", "pandas", "numpy"]
+blockmodels = ["evo-blockmodels[utils]>=0.2.0"]
 
 [dependency-groups]
 # Dev dependencies. The version is left unspecified so the latest is installed.
 test = [
-    "evo-objects[aiohttp,utils]",
+    "evo-objects[aiohttp,utils,blockmodels]",
     "pandas",
     "parameterized==0.9.0",
     "pytest",

{evo_objects-0.3.3 → evo_objects-0.4.0}/src/evo/objects/client/api_client.py

@@ -15,7 +15,7 @@ from collections.abc import AsyncIterator, Sequence
 from uuid import UUID
 
 from evo import logging
-from evo.common import APIConnector, BaseAPIClient, HealthCheckType, ICache, Page, ServiceHealth
+from evo.common import APIConnector, BaseAPIClient, HealthCheckType, ICache, IContext, Page, ServiceHealth
 from evo.common.data import EmptyResponse, Environment, OrderByOperatorEnum
 from evo.common.utils import get_service_health, parse_order_by
 
@@ -52,6 +52,21 @@ class ObjectAPIClient(BaseAPIClient):
         self._metadata_api = MetadataApi(connector=connector)
         self._cache = cache
 
+    @classmethod
+    def from_context(cls, context: IContext) -> ObjectAPIClient:
+        """Create a ObjectAPIClient from the given context.
+
+        The context must have a hub_url, org_id, and workspace_id set.
+
+        :param context: The context to create the client from.
+        :return: A ObjectAPIClient instance.
+        """
+        return cls(
+            environment=context.get_environment(),
+            connector=context.get_connector(),
+            cache=context.get_cache(),
+        )
+
     async def get_service_health(self, check_type: HealthCheckType = HealthCheckType.FULL) -> ServiceHealth:
         """Get the health of the geoscience object service.
 

{evo_objects-0.3.3 → evo_objects-0.4.0}/src/evo/objects/client/object_client.py

@@ -11,6 +11,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import contextlib
 from collections.abc import AsyncGenerator, Iterator, Sequence
 from typing import Any, TypeVar
@@ -19,9 +20,9 @@ from uuid import UUID
 from pydantic import ConfigDict, TypeAdapter
 
 from evo import jmespath, logging
-from evo.common import APIConnector, ICache, IFeedback
+from evo.common import APIConnector, Environment, ICache, IContext, IFeedback
 from evo.common.io.exceptions import DataNotFoundError
-from evo.common.utils import NoFeedback, PartialFeedback
+from evo.common.utils import NoFeedback, split_feedback
 
 from ..data import ObjectMetadata, ObjectReference, ObjectSchema
 from ..endpoints import ObjectsApi, models
@@ -73,29 +74,12 @@ logger = logging.getLogger("object.client")
 _T = TypeVar("_T")
 
 
-def _split_feedback(left: int, right: int) -> float:
-    """Helper to split feedback range into two parts based on left and right sizes.
+class DownloadedObject(IContext):
+    """A downloaded geoscience object.
 
-    :param left: Number of parts for the left side of the split.
-    :param right: Number of parts for the right side of the split.
-
-    :return: Proportion of feedback to allocate to the left side (between 0.0 and 1.0).
-        The right side will be the remainder (1.0 - proportion).
-
-    :raises ValueError: If left or right is negative.
+    This class also implements the IContext interface, allowing it to be used
+    directly as a context for further API operations.
     """
-    if left < 0 or right < 0:
-        raise ValueError("Left and right sizes must be non-negative")
-    elif left >= 0 and right == 0:
-        return 1.0  # Left gets all feedback if right is zero
-    elif right > 0 and left == 0:
-        return 0.0  # Right gets all feedback if left is zero
-    else:
-        return left / (left + right)  # Proportion of feedback for left
-
-
-class DownloadedObject:
-    """A downloaded geoscience object."""
 
     def __init__(
         self,
@@ -172,6 +156,25 @@ class DownloadedObject:
             cache=cache,
         )
 
+    @staticmethod
+    async def from_context(
+        context: IContext,
+        reference: ObjectReference | str,
+    ) -> DownloadedObject:
+        """Download a geoscience object from the service using a context.
+
+        :param context: The context providing the connector and cache.
+        :param reference: The reference to the object to download, or a URL as a string that can be parsed into
+            a reference.
+
+        :raises ValueError: If the reference is invalid, or if the connector base URL does not match the reference hub URL.
+        """
+        return await DownloadedObject.from_reference(
+            connector=context.get_connector(),
+            reference=reference,
+            cache=context.get_cache(),
+        )
+
     @property
     def schema(self) -> ObjectSchema:
         """The schema of the object."""
@@ -182,6 +185,36 @@ class DownloadedObject:
         """The metadata of the object."""
         return self._metadata
 
+    # IContext interface implementation
+
+    def get_environment(self) -> Environment:
+        """Gets the Environment associated with this object.
+
+        :return: The Environment.
+        """
+        return self._metadata.environment
+
+    def get_org_id(self) -> UUID:
+        """Gets the organization ID associated with this object.
+
+        :return: The organization ID.
+        """
+        return self._metadata.environment.org_id
+
+    def get_connector(self) -> APIConnector:
+        """Gets the APIConnector associated with this object.
+
+        :return: The APIConnector.
+        """
+        return self._connector
+
+    def get_cache(self) -> ICache | None:
+        """Gets the ICache associated with this object, if any.
+
+        :return: The ICache, or None if no cache is associated.
+        """
+        return self._cache
+
     def as_dict(self) -> dict:
         """Get this object as a dictionary."""
         return self._object.model_dump(mode="python", by_alias=True)
@@ -384,15 +417,17 @@ class DownloadedObject:
                 category_info["values"]["length"] * category_info["values"]["width"]
             )  # Total number of cells in values
             t_size = category_info["table"]["length"] * 2  # Lookup tables always have 2 columns
-            split = _split_feedback(v_size, t_size)
+            values_fb, table_fb = split_feedback(fb, [v_size, t_size])
 
-            values_table = await self.download_table(
+            # Download both tables concurrently
+            values_table_coro = self.download_table(
                 category_info["values"],
                 nan_values=nan_values,
                 column_names=column_names,
-                fb=PartialFeedback(fb, start=0, end=split),
+                fb=values_fb,
             )
-            lookup_table = await self.download_table(category_info["table"], fb=PartialFeedback(fb, start=split, end=1))
+            lookup_table_coro = self.download_table(category_info["table"], fb=table_fb)
+            values_table, lookup_table = await asyncio.gather(values_table_coro, lookup_table_coro)
 
             arrays = []
             for array in values_table.columns:

{evo_objects-0.3.3 → evo_objects-0.4.0}/src/evo/objects/parquet/__init__.py

@@ -14,8 +14,8 @@ try:
 except ImportError:
     raise ImportError("The 'pyarrow' package is required to use ParquetLoader") from None
 
+from ..utils.types import ArrayTableInfo, AttributeInfo, CategoryInfo, LookupTableInfo, TableInfo
 from .loader import ParquetDownloader, ParquetLoader
-from .types import ArrayTableInfo, AttributeInfo, CategoryInfo, LookupTableInfo, TableInfo
 
 __all__ = [
     "ArrayTableInfo",

{evo_objects-0.3.3 → evo_objects-0.4.0}/src/evo/objects/parquet/loader.py

@@ -27,8 +27,7 @@ from evo.common.io import BytesDestination, ChunkedIOManager, Download, HTTPSour
 from evo.common.utils import NoFeedback
 
 from ..exceptions import SchemaValidationError, TableFormatError
-from ..utils import ArrowTableFormat, KnownTableFormat
-from .types import TableInfo
+from ..utils import ArrowTableFormat, KnownTableFormat, TableInfo
 
 try:
     import pandas as pd

evo_objects-0.4.0/src/evo/objects/typed/__init__.py

@@ -0,0 +1,140 @@
+#  Copyright © 2025 Bentley Systems, Incorporated
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#      http://www.apache.org/licenses/LICENSE-2.0
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from ._grid import BlockModelData, BlockModelGeometry
+from .attributes import (
+    Attribute,
+    Attributes,
+    BlockModelAttribute,
+    BlockModelAttributes,
+    BlockModelPendingAttribute,
+    PendingAttribute,
+)
+from .base import BaseObject, object_from_path, object_from_reference, object_from_uuid
+from .block_model_ref import (
+    BlockModel,
+)
+from .pointset import (
+    Locations,
+    PointSet,
+    PointSetData,
+)
+from .regular_grid import (
+    Regular3DGrid,
+    Regular3DGridData,
+)
+from .regular_masked_grid import (
+    MaskedCells,
+    RegularMasked3DGrid,
+    RegularMasked3DGridData,
+)
+from .spatial import BaseSpatialObject
+from .tensor_grid import (
+    Tensor3DGrid,
+    Tensor3DGridData,
+)
+from .types import (
+    BoundingBox,
+    CoordinateReferenceSystem,
+    Ellipsoid,
+    EllipsoidRanges,
+    EpsgCode,
+    Point3,
+    Rotation,
+    Size3d,
+    Size3i,
+)
+from .variogram import (
+    CubicStructure,
+    ExponentialStructure,
+    GaussianStructure,
+    GeneralisedCauchyStructure,
+    LinearStructure,
+    SphericalStructure,
+    SpheroidalStructure,
+    Variogram,
+    VariogramCurveData,
+    VariogramData,
+    VariogramStructure,
+)
+
+__all__ = [
+    "Attribute",
+    "Attributes",
+    "BaseObject",
+    "BaseSpatialObject",
+    "BlockModel",
+    "BlockModelAttribute",
+    "BlockModelAttributes",
+    "BlockModelData",
+    "BlockModelGeometry",
+    "BlockModelPendingAttribute",
+    "BoundingBox",
+    "CoordinateReferenceSystem",
+    "CubicStructure",
+    "Ellipsoid",
+    "EllipsoidRanges",
+    "EpsgCode",
+    "ExponentialStructure",
+    "GaussianStructure",
+    "GeneralisedCauchyStructure",
+    "LinearStructure",
+    "Locations",
+    "MaskedCells",
+    "PendingAttribute",
+    "Point3",
+    "PointSet",
+    "PointSetData",
+    "Regular3DGrid",
+    "Regular3DGridData",
+    "RegularMasked3DGrid",
+    "RegularMasked3DGridData",
+    "Rotation",
+    "Size3d",
+    "Size3i",
+    "SphericalStructure",
+    "SpheroidalStructure",
+    "Tensor3DGrid",
+    "Tensor3DGridData",
+    "Variogram",
+    "VariogramCurveData",
+    "VariogramData",
+    "VariogramStructure",
+    "object_from_path",
+    "object_from_reference",
+    "object_from_uuid",
+]
+
+# Conditionally export report types when evo-blockmodels is installed
+try:
+    from evo.blockmodels.typed import (  # noqa: F401
+        Aggregation,
+        MassUnits,
+        RegularBlockModelData,
+        Report,
+        ReportCategorySpec,
+        ReportColumnSpec,
+        ReportResult,
+        ReportSpecificationData,
+    )
+
+    __all__ += [
+        "Aggregation",
+        "MassUnits",
+        "RegularBlockModelData",
+        "Report",
+        "ReportCategorySpec",
+        "ReportColumnSpec",
+        "ReportResult",
+        "ReportSpecificationData",
+    ]
+except ImportError:
+    pass

evo_objects-0.4.0/src/evo/objects/typed/_data.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from typing import Annotated, Any, ClassVar
+
+import pandas as pd
+
+from evo.common import IFeedback
+from evo.common.interfaces import IContext
+from evo.common.utils import NoFeedback
+from evo.objects.typed.attributes import Attributes
+from evo.objects.utils.table_formats import KnownTableFormat
+
+from ._model import SchemaBuilder, SchemaLocation, SchemaModel
+from ._utils import get_data_client
+from .exceptions import DataLoaderError, ObjectValidationError
+
+
+class DataTable(SchemaModel):
+    length: Annotated[int, SchemaLocation("length")]
+    _data: Annotated[str, SchemaLocation("data")]
+
+    table_format: ClassVar[KnownTableFormat | None] = None
+    data_columns: ClassVar[list[str]] = []
+
+    async def to_dataframe(self, fb: IFeedback = NoFeedback) -> pd.DataFrame:
+        """Load a DataFrame containing values for this table.
+
+        :param fb: Optional feedback object to report download progress.
+        :return: The loaded DataFrame with values for this table.
+        """
+        if self._context.is_data_modified(self._data):
+            raise DataLoaderError("Data was modified since the object was downloaded")
+        return await self._obj.download_dataframe(self.as_dict(), fb=fb, column_names=self.data_columns)
+
+    async def from_dataframe(self, df: pd.DataFrame, fb: IFeedback = NoFeedback) -> None:
+        """Update the values of this table.
+
+        :param df: DataFrame containing the new values for this table.
+        :param fb: Optional feedback object to report upload progress.
+        """
+        self._document.update(await self._data_to_schema(df, self._context, fb=fb))
+
+        # Mark the context as modified so loading data is not allowed
+        self._context.mark_modified(self._data)
+
+    @classmethod
+    async def _data_to_schema(cls, data: Any, context: IContext, fb: IFeedback = NoFeedback) -> Any:
+        """Upload a DataFrame and return the schema dictionary for the DataTable."""
+        if not isinstance(data, pd.DataFrame):
+            raise ObjectValidationError(f"Input data must be a pandas DataFrame, but got {type(data)}")
+        if list(data.columns) != cls.data_columns:
+            raise ObjectValidationError(
+                f"Input DataFrame must have columns {cls.data_columns}, but got {list(data.columns)}"
+            )
+
+        data_client = get_data_client(context)
+        return await data_client.upload_dataframe(data, table_format=cls.table_format, fb=fb)
+
+
+class DataTableAndAttributes(SchemaModel):
+    """A dataset representing a table of data along with associated attributes.
+
+    Subclasses should redefine the _table property to provide additional details about the data table like:
+    1. the location of it within the schema using SchemaLocation
+    2. the data columns that are expected in the table, which is done by creating a subclass of DataTable,
+    3. the table format used for storing the data, which can also be done by creating a subclass of DataTable.
+
+    e.g.,
+    class LocationTable(DataTable):
+        table_format: ClassVar[KnownTableFormat] = FLOAT_ARRAY_3
+        data_columns: ClassVar[list[str]] = ["x", "y", "z"]
+
+
+    class Locations(DataTableAndAttributes):
+        _table: Annotated[LocationTable, SchemaLocation("coordinates")]
+
+    """
+
+    attributes: Annotated[Attributes, SchemaLocation("attributes")]
+    _table: DataTable
+
+    @property
+    def length(self) -> int:
+        """The expected number of rows in the table and attributes."""
+        return self._table.length
+
+    async def to_dataframe(self, *keys: str, fb: IFeedback = NoFeedback) -> pd.DataFrame:
+        """Load a DataFrame containing the values and attributes.
+
+        :param keys: Optional attribute keys to include. If not specified, all attributes are included.
+        :param fb: Optional feedback object to report download progress.
+        :return: DataFrame with data columns (e.g., X, Y, Z) and additional columns for attributes.
+        """
+        table_df = await self._table.to_dataframe(fb=fb)
+        if self.attributes is not None and len(self.attributes) > 0:
+            attr_df = await self.attributes.to_dataframe(*keys, fb=fb)
+            combined_df = pd.concat([table_df, attr_df], axis=1)
+            return combined_df
+        else:
+            return table_df
+
+    async def from_dataframe(self, df: pd.DataFrame, fb: IFeedback = NoFeedback) -> None:
+        """Set the table data and attributes from a DataFrame.
+
+        :param df: DataFrame containing data columns (e.g., X, Y, Z) and additional columns for attributes.
+        :param fb: Optional feedback object to report upload progress.
+        """
+        table_df, attr_df = self._split_dataframe(df, self._table.data_columns)
+
+        await self._table.from_dataframe(table_df, fb=fb)
+        if attr_df is not None:
+            await self.attributes.set_attributes(attr_df, fb=fb)
+        else:
+            await self.attributes.clear()
+
+    def validate(self) -> None:
+        """Validate that all attributes have the correct length."""
+        self.attributes.validate_lengths(self.length)
+
+    @classmethod
+    def _split_dataframe(cls, data: pd.DataFrame, data_columns: list[str]) -> tuple[pd.DataFrame, pd.DataFrame | None]:
+        """Validate and split a DataFrame into table data and attribute data."""
+
+        missing = set(data_columns) - set(data.columns)
+        if missing:
+            raise ObjectValidationError(f"Input DataFrame must have {data_columns} columns. Missing: {missing}")
+
+        table_df = data[data_columns]
+        attr_cols = [col for col in data.columns if col not in data_columns]
+        attr_df = data[attr_cols] if attr_cols else None
+        return table_df, attr_df
+
+    @classmethod
+    async def _data_to_schema(cls, data: Any, context: IContext) -> Any:
+        if not isinstance(data, pd.DataFrame):
+            raise ObjectValidationError(f"Input data must be a pandas DataFrame, but got {type(data)}")
+
+        # Lookup the metadata of the _table sub-model, as sub-classes may redefine it
+        table_metadata = cls._sub_models["_table"]
+        table_type = table_metadata.model_type
+        table_df, attr_df = cls._split_dataframe(data, table_type.data_columns)
+
+        builder = SchemaBuilder(cls, context)
+        await builder.set_sub_model_value("_table", table_df)
+        await builder.set_sub_model_value("attributes", attr_df)
+        return builder.document