evo-objects 0.6.2__tar.gz → 0.6.3__tar.gz

{evo_objects-0.6.2 → evo_objects-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: evo-objects
-Version: 0.6.2
+Version: 0.6.3
 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
@@ -95,6 +95,42 @@ You can also get a list of all objects. Internally, this recursively calls the `
 
 Check out the other methods on the `ObjectAPIClient` for more details on how to upload and download objects, or get object versions.
 
+### Typed downhole collections
+
+`DownholeCollection` provides a DataFrame-based API for creating and reading downhole objects. A collection can contain
+distance tables, interval tables, or both. `hole_index` is an integer key in the object's `hole_id` lookup table, not a
+row position or a pandas categorical code. The creation helper uses dense zero-based keys in sorted hole-ID order unless
+an explicit `hole_indices` mapping is supplied. Persisted objects may use arbitrary integer keys. Collection holes may
+contain a subset or repeated chunks.
+
+```python
+import pandas as pd
+
+from evo.objects.typed import DownholeCollection, DownholeCollectionData
+from evo.objects.typed.downhole_collection import IntervalCollection
+from evo.objects.utils.downhole import hole_chunks_from_ids
+
+intervals = pd.DataFrame({"from": [0.0], "to": [1.5], "lithology": ["sandstone"]})
+collections = [
+    IntervalCollection(
+        name="geology",
+        holes=hole_chunks_from_ids(pd.Series(["DH-01"])),
+        table=intervals,
+        unit="m",  # Collection coordinate units are set explicitly here.
+    )
+]
+
+# Build DownholeCollectionData with matching path, location-hole chunks, and collar properties,
+# then create it with: await DownholeCollection.create(context, data)
+```
+
+Use `await dhc.location.to_dataframe()` and `await dhc.location.path_to_dataframe()` to read collars and paths.
+Distance and interval tables provide `to_dataframe()` and `to_dataframe_by_hole()`. Before reading a large object, call
+`await dhc.prefetch_collections("geology")` to warm only the requested collection data (and location data by default).
+Attribute descriptions for ordinary attributes round-trip through `DataFrame.attrs["attribute_descriptions"]`.
+Collection coordinate units come only from `DistanceCollection.unit` or `IntervalCollection.unit`; unit metadata on the
+distance or `from` column is ignored.
+
 ## Contributing
 
 For instructions on contributing to the development of this library, please refer to the [evo-python-sdk documentation](https://github.com/seequentevo/evo-python-sdk).

{evo_objects-0.6.2 → evo_objects-0.6.3}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "evo-objects"
 description = "Python SDK for using the Seequent Evo Geoscience Object API"
-version = "0.6.2"
+version = "0.6.3"
 requires-python = ">=3.10"
 license-files = ["LICENSE.md"]
 dynamic = ["readme"]

{evo_objects-0.6.2 → evo_objects-0.6.3}/src/evo/objects/typed/__init__.py

@@ -12,17 +12,24 @@
 from ._grid import BlockModelData, BlockModelGeometry
 from .attributes import (
     Attribute,
+    AttributeDescription,
     Attributes,
     BlockModelAttribute,
     BlockModelAttributes,
     BlockModelPendingAttribute,
     PendingAttribute,
+    Unit,
 )
 from .base import BaseObject, object_from_path, object_from_reference, object_from_uuid
 from .block_model_ref import (
     BlockModel,
 )
-from .downhole_collection import DownholeCollection, DownholeCollectionData
+from .downhole_collection import (
+    DistanceCollection,
+    DownholeCollection,
+    DownholeCollectionData,
+    IntervalCollection,
+)
 from .downhole_intervals import DownholeIntervals, DownholeIntervalsData
 from .pointset import (
     Locations,
@@ -70,6 +77,7 @@ from .variogram import (
 
 __all__ = [
     "Attribute",
+    "AttributeDescription",
     "Attributes",
     "BaseObject",
     "BaseSpatialObject",
@@ -82,6 +90,7 @@ __all__ = [
     "BoundingBox",
     "CoordinateReferenceSystem",
     "CubicStructure",
+    "DistanceCollection",
     "DownholeCollection",
     "DownholeCollectionData",
     "DownholeIntervals",
@@ -92,6 +101,7 @@ __all__ = [
     "ExponentialStructure",
     "GaussianStructure",
     "GeneralisedCauchyStructure",
+    "IntervalCollection",
     "LinearStructure",
     "Locations",
     "MaskedCells",
@@ -110,6 +120,7 @@ __all__ = [
     "SpheroidalStructure",
     "Tensor3DGrid",
     "Tensor3DGridData",
+    "Unit",
     "Variogram",
     "VariogramCurveData",
     "VariogramData",

{evo_objects-0.6.2 → evo_objects-0.6.3}/src/evo/objects/typed/_model.py

@@ -450,15 +450,30 @@ class SchemaList(Sequence[_M]):
             if get_origin(base) is SchemaList:
                 args = get_args(base)
                 if args:
-                    cls._item_type = args[0]
+                    item_type = args[0]
+                    if isinstance(item_type, type):
+                        cls._item_type = item_type
+                    elif "_resolve_item_type" not in cls.__dict__ or "_data_to_schema" not in cls.__dict__:
+                        raise TypeError(
+                            "SchemaList with a non-class item type must override _resolve_item_type() and _data_to_schema()"
+                        )
                     break
 
     def __getitem__(self, index: int) -> _M:
-        return self._item_type(self._context, self._document[index])
+        document = self._document[index]
+        return self._resolve_item_type(document)(self._context, document)
 
     def __iter__(self):
         for item in self._document:
-            yield self._item_type(self._context, item)
+            yield self._resolve_item_type(item)(self._context, item)
+
+    @classmethod
+    def _resolve_item_type(cls, document: dict[str, Any]) -> type[_M]:
+        """Resolve the schema model used for a document item.
+
+        Subclasses with heterogeneous document items can override this hook.
+        """
+        return cls._item_type
 
     def __len__(self) -> int:
         return len(self._document)

evo_objects-0.6.3/src/evo/objects/typed/_prefetch.py

@@ -0,0 +1,72 @@
+#  Copyright © 2026 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.
+
+"""Helpers for warming typed-object data in the local cache."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from typing import Any
+
+from evo.common import IFeedback
+from evo.common.utils import NoFeedback
+from evo.objects import DownloadedObject
+from evo.objects.io import _CACHE_SCOPE
+
+
+def collect_data_ids(documents: Any) -> list[str]:
+    """Collect de-duplicated ``data`` references from document values."""
+    ids: list[str] = []
+
+    def visit(value: Any) -> None:
+        if isinstance(value, dict):
+            for key, nested in value.items():
+                if key == "data" and isinstance(nested, str) and nested not in ids:
+                    ids.append(nested)
+                else:
+                    visit(nested)
+        elif isinstance(value, (list, tuple)):
+            for nested in value:
+                visit(nested)
+
+    visit(documents)
+    return ids
+
+
+async def prefetch_object_data(
+    obj: DownloadedObject,
+    *,
+    data_ids: Sequence[str] | None = None,
+    max_concurrent: int = 8,
+    fb: IFeedback = NoFeedback,
+) -> None:
+    """Warm cache entries referenced by an object, downloading each ID at most once."""
+    if max_concurrent < 1:
+        raise ValueError("max_concurrent must be at least 1")
+    cache = obj.get_cache()
+    if cache is None:
+        raise ValueError("prefetch requires an IContext with a cache")
+    identifiers = list(dict.fromkeys(data_ids if data_ids is not None else collect_data_ids(obj.as_dict())))
+    if not identifiers:
+        return
+    cache_location = cache.get_location(environment=obj.get_environment(), scope=_CACHE_SCOPE)
+    identifiers = [identifier for identifier in identifiers if not (cache_location / identifier).exists()]
+    if not identifiers:
+        return
+    contexts = list(obj.prepare_data_download(identifiers))
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def download(context: Any) -> None:
+        async with semaphore:
+            await context.download_to_cache(cache, obj.get_connector().transport, fb=fb)
+
+    await asyncio.gather(*(download(context) for context in contexts))

{evo_objects-0.6.2 → evo_objects-0.6.3}/src/evo/objects/typed/attributes.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 import typing
 import uuid
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Annotated, Any
+from typing import TYPE_CHECKING, Annotated, Any, Protocol, runtime_checkable
 from uuid import UUID
 
 import pandas as pd
@@ -41,11 +41,13 @@ if TYPE_CHECKING:
 
 __all__ = [
     "Attribute",
+    "AttributeDescription",
     "Attributes",
     "BlockModelAttribute",
     "BlockModelAttributes",
     "BlockModelPendingAttribute",
     "PendingAttribute",
+    "Unit",
 ]
 
 
@@ -53,6 +55,13 @@ class UnSupportedDataTypeError(Exception):
     """An unsupported data type was encountered while processing data."""
 
 
+@runtime_checkable
+class Unit(Protocol):
+    """A schema unit enum represented by its string value."""
+
+    value: str
+
+
 def _infer_attribute_type_from_series(series: pd.Series) -> str:
     """Infer the attribute type from a Pandas Series.
 
@@ -89,13 +98,20 @@ _attribute_table_formats = {
 class AttributeDescription:
     discipline: str = ""
     type: str = ""
-    unit: str | None = None
+    unit: str | Unit | None = None
     scale: str | None = None
     extensions: dict[str, typing.Any] | None = None
     tags: dict[str, str] | None = None
 
-    def to_schema(self):
-        result = {
+    def __post_init__(self) -> None:
+        if self.unit is None or isinstance(self.unit, str):
+            return
+        if not isinstance(self.unit, Unit) or not isinstance(self.unit.value, str):
+            raise TypeError("unit must be a str, a Unit with a string value, or None")
+        self.unit = self.unit.value
+
+    def to_schema(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
             "discipline": self.discipline,
             "type": self.type,
         }
@@ -117,6 +133,7 @@ class Attribute(SchemaModel):
     _attribute_type: Annotated[str, SchemaLocation("attribute_type")]
     _key: Annotated[str | None, SchemaLocation("key")]
     _data: Annotated[str, SchemaLocation("values.data")]
+    _attribute_description: Annotated[dict[str, Any] | None, SchemaLocation("attribute_description")]
 
     @property
     def key(self) -> str:
@@ -132,6 +149,12 @@ class Attribute(SchemaModel):
         """The type of this attribute."""
         return self._attribute_type
 
+    @property
+    def attribute_description(self) -> AttributeDescription | None:
+        """Optional descriptive metadata associated with this attribute."""
+        raw = self._attribute_description
+        return AttributeDescription(**raw) if raw else None
+
     @property
     def exists(self) -> bool:
         """Whether this attribute exists on the object.
@@ -241,7 +264,7 @@ class Attributes(SchemaList[Attribute]):
     attribute descriptions are attached to the DataFrame's `attrs` attribute.
 
     >>> df.attrs
-    {'attribute_description': {<column names>:  <AttributeDescription>}, ...}
+    {'attribute_descriptions': {<column names>: <AttributeDescription>}, ...}
     """
 
     _schema_path: str | None = None
@@ -320,8 +343,8 @@ class Attributes(SchemaList[Attribute]):
             if attr_desc is not None:
                 if not isinstance(attr_desc, AttributeDescription):
                     raise TypeError("attribute description must be a AttributeDescription.")
-                if attr_desc.unit is not None:
-                    attr_doc["attribute_description"] = attr_desc.to_schema()
+                if description := attr_desc.to_schema():
+                    attr_doc["attribute_description"] = description
 
             attributes_list.append(attr_doc)
 
@@ -337,7 +360,15 @@ class Attributes(SchemaList[Attribute]):
         """
         attributes = [self[key] for key in keys] if keys else list(self)
         parts = [await attribute.to_dataframe(fb=fb_part) for attribute, fb_part in iter_with_fb(attributes, fb)]
-        return pd.concat(parts, axis=1) if len(parts) > 0 else pd.DataFrame()
+        result = pd.concat(parts, axis=1) if len(parts) > 0 else pd.DataFrame()
+        descriptions = {
+            attribute.name: description
+            for attribute in attributes
+            if isinstance(attribute, Attribute) and (description := attribute.attribute_description) is not None
+        }
+        if descriptions:
+            result.attrs["attribute_descriptions"] = descriptions
+        return result
 
     async def append_attribute(self, df: pd.DataFrame, fb: IFeedback = NoFeedback):
         """Add a new attribute to the object.
@@ -601,3 +632,14 @@ class Category(SchemaModel):
         if self._context.is_data_modified(self._data):
             raise DataLoaderError("Data was modified since the object was downloaded")
         return await self._obj.download_category_dataframe(self.as_dict(), fb=fb)
+
+    async def to_indexed_dataframe(self, fb: IFeedback = NoFeedback) -> pd.DataFrame:
+        """Load the persisted category lookup as ``[key, value]`` rows.
+
+        Pandas categorical codes are dense positional values and must not be used
+        as schema lookup keys. This method is intended for joins involving an
+        index column such as ``hole_index``.
+        """
+        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()["table"], fb=fb)

{evo_objects-0.6.2 → evo_objects-0.6.3}/src/evo/objects/typed/base.py

@@ -14,15 +14,18 @@ from __future__ import annotations
 import copy
 import sys
 import weakref
+from collections.abc import Sequence
 from dataclasses import dataclass
 from typing import Annotated, Any, ClassVar
 from uuid import UUID
 
 from evo import jmespath
-from evo.common import IContext, StaticContext
+from evo.common import IContext, IFeedback, StaticContext
+from evo.common.utils import NoFeedback
 from evo.objects import DownloadedObject, ObjectMetadata, ObjectReference, ObjectSchema, SchemaVersion
 
 from ._model import ModelContext, SchemaLocation, SchemaModel
+from ._prefetch import prefetch_object_data
 from ._utils import (
     create_geoscience_object,
     replace_geoscience_object,
@@ -416,6 +419,17 @@ class BaseObject(_BaseObject):
     tags: Annotated[dict[str, str], SchemaLocation("tags")] = {}
     extensions: Annotated[dict, SchemaLocation("extensions")] = {}
 
+    async def prefetch(
+        self,
+        *,
+        data_ids: Sequence[str] | None = None,
+        max_concurrent: int = 8,
+        fb: IFeedback = NoFeedback,
+    ) -> None:
+        """Warm cached data files referenced by this object."""
+
+        await prefetch_object_data(self._obj, data_ids=data_ids, max_concurrent=max_concurrent, fb=fb)
+
     @classmethod
     def create(
         cls,