vcti-datanode 1.0.1__py3-none-any.whl

vcti/datanode/__init__.py

@@ -0,0 +1,22 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.datanode — lightweight data-plus-attributes node containers.
+
+``DataNode`` pairs data with a metadata/attributes dict; ``LazyDataNode``
+adds on-demand ``load()`` / ``release()`` over a loader callback for
+out-of-core data. Both are tree-agnostic value types usable as node
+payloads or anywhere a data + metadata unit is useful.
+"""
+
+from importlib.metadata import version
+
+from .lazy_node import LazyDataNode
+from .node import DataNode
+
+__version__ = version("vcti-datanode")
+
+__all__ = [
+    "__version__",
+    "DataNode",
+    "LazyDataNode",
+]

vcti/datanode/lazy_node.py

@@ -0,0 +1,139 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""LazyDataNode — DataNode with on-demand loading and release of data.
+
+Designed for large datasets (e.g. CAE models) where keeping all data in
+memory at once is impractical. Attributes stay resident; data is loaded via
+a caller-supplied callback and can be released to free memory.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from .node import DataNode
+
+
+class LazyDataNode(DataNode):
+    """DataNode with lazy loading and release of data.
+
+    Extends :class:`DataNode` with a loader callback for on-demand data
+    loading. Attributes remain in memory at all times (for filtering and
+    bookkeeping); data starts unloaded and is fetched via ``load()`` when
+    needed, then can be freed via ``release()`` and reloaded later.
+
+    The loader is a closure — it captures whatever file handle, offset,
+    dataset path, or other context it needs. ``LazyDataNode`` does not know
+    or care how the data is stored externally.
+
+    Equality is the inherited :class:`DataNode` semantics — data plus
+    attributes only. The loader and the load-state are **not** part of
+    identity, so two unloaded nodes with equal attributes compare equal even
+    if their loaders would produce different data.
+
+    Attributes:
+        data: The data (None when unloaded, populated after ``load()``).
+        attributes: Dictionary of metadata attributes (always resident).
+
+    Example:
+        >>> import numpy as np
+        >>> def make_loader():
+        ...     return lambda: np.array([1.0, 2.0, 3.0])
+        >>> node = LazyDataNode(
+        ...     loader=make_loader(),
+        ...     attributes={'units': 'mm', 'name': 'displacement'},
+        ... )
+        >>> node.is_loaded
+        False
+        >>> node.load()
+        array([1., 2., 3.])
+        >>> node.is_loaded
+        True
+        >>> node.release()
+        >>> node.is_loaded
+        False
+    """
+
+    __slots__ = ("_loader",)
+
+    def __init__(
+        self,
+        loader: Callable[[], Any],
+        attributes: dict[str, Any] | None = None,
+        *,
+        data: Any = None,
+    ) -> None:
+        """Initialize a LazyDataNode.
+
+        Args:
+            loader: Callable that returns the data when invoked.
+                Must be idempotent — multiple calls should return
+                equivalent data.
+            attributes: Optional metadata dictionary. Defaults to empty dict.
+            data: Optional pre-loaded data.  When provided, the node
+                starts in the loaded state.
+        """
+        super().__init__(data=data, attributes=attributes)
+        self._loader = loader
+
+    @property
+    def is_loaded(self) -> bool:
+        """Return True if data is currently in memory."""
+        return self.data is not None
+
+    def load(self) -> Any:
+        """Load data via the loader callback.
+
+        If data is already loaded, returns it without calling the loader
+        again.  To force a reload, call ``release()`` first.
+
+        Returns:
+            The data.
+
+        Raises:
+            RuntimeError: If the loader returns None.
+            Exception: Any exception raised by the loader propagates
+                unchanged, preserving its type (e.g. ``FileNotFoundError``)
+                so callers can handle distinct failures distinctly.
+
+        Example:
+            >>> import numpy as np
+            >>> node = LazyDataNode(loader=lambda: np.array([1, 2, 3]))
+            >>> node.is_loaded
+            False
+            >>> data = node.load()
+            >>> node.is_loaded
+            True
+        """
+        if self.data is None:
+            result = self._loader()
+            if result is None:
+                raise RuntimeError("Loader returned None")
+            self.data = result
+        return self.data
+
+    def release(self) -> None:
+        """Free data from memory.
+
+        The node keeps its attributes intact; data can be reloaded later via
+        ``load()``.
+
+        Example:
+            >>> import numpy as np
+            >>> node = LazyDataNode(loader=lambda: np.array([1, 2, 3]))
+            >>> node.load()  # doctest: +ELLIPSIS
+            array(...)
+            >>> node.release()
+            >>> node.is_loaded
+            False
+        """
+        self.data = None
+
+    def _data_status(self) -> str:
+        if self.data is None:
+            return "unloaded"
+        return super()._data_status()
+
+    def _data_detail_lines(self) -> list[str]:
+        if self.data is None:
+            return ["  Data: unloaded"]
+        return super()._data_detail_lines()

vcti/datanode/node.py

@@ -0,0 +1,142 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""DataNode — a container pairing data with a metadata/attributes dict.
+
+A small, dependency-light value type for "a unit of data plus its
+attributes." It is commonly used as a node payload in a tree, but is not
+tied to any tree or container — use it anywhere a data + metadata pair is
+useful.
+"""
+
+from typing import Any
+
+import numpy as np
+
+
+class DataNode:
+    """Container for data and a metadata/attributes dictionary.
+
+    Each instance can carry:
+
+    - **Data** — an ``np.ndarray``, a masked array, or any array-like /
+      arbitrary object (the field is untyped so it integrates by duck typing
+      with other array containers without a hard dependency on them).
+    - **Attributes** — a metadata dictionary.
+    - Both, or neither.
+
+    It is intentionally minimal: just ``data`` + ``attributes``, with value
+    equality and readable ``repr``/``str``.
+
+    Attributes:
+        data: The data (``np.ndarray``, array-like, arbitrary object, or
+            ``None``).
+        attributes: Dictionary of metadata attributes.
+
+    Example:
+        >>> import numpy as np
+        >>> node = DataNode(
+        ...     data=np.array([1.0, 2.0, 3.0]),
+        ...     attributes={'units': 'mm', 'name': 'displacement'},
+        ... )
+        >>> group = DataNode(attributes={'type': 'results'})
+    """
+
+    __slots__ = ("attributes", "data")
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, DataNode):
+            return NotImplemented
+
+        # Compare the cheap attributes dict first so an early mismatch
+        # short-circuits before any (potentially large) data comparison.
+        if self.attributes != other.attributes:
+            return False
+        return self._data_equals(other.data)
+
+    def _data_equals(self, other_data: Any) -> bool:
+        """Return whether this node's data equals ``other_data``.
+
+        For ordinary data this does not raise: any pairing of None, ndarrays,
+        other array-likes, or plain objects resolves to a bool. (A custom
+        object whose own ``__eq__`` raises is the one exception — that
+        propagates.) ndarrays compare by shape, dtype, and ``np.array_equal``
+        (note: NaN != NaN, so arrays containing NaN are unequal; for masked
+        arrays the mask is not consulted — the underlying data is compared).
+        A mismatch in kind — one side an ndarray, the other not — is treated
+        as unequal rather than coerced.
+        """
+        a, b = self.data, other_data
+        if a is None or b is None:
+            return a is None and b is None
+
+        a_is_array = isinstance(a, np.ndarray)
+        b_is_array = isinstance(b, np.ndarray)
+        if a_is_array and b_is_array:
+            return bool(a.shape == b.shape and a.dtype == b.dtype and np.array_equal(a, b))
+        if a_is_array or b_is_array:
+            # One ndarray, one not: different kinds, treat as unequal rather
+            # than letting an array-valued ``==`` blow up the bool reduction.
+            return False
+
+        result = a == b
+        if isinstance(result, bool):
+            return result
+        # Non-ndarray array-likes whose ``==`` yields a non-scalar: reduce
+        # element-wise so we still return a plain, non-raising bool.
+        return bool(np.all(result))
+
+    def __init__(
+        self,
+        data: Any = None,
+        attributes: dict[str, Any] | None = None,
+    ):
+        """Initialize a DataNode.
+
+        Args:
+            data: Optional data (any array-like object or None).
+            attributes: Optional metadata dictionary. Defaults to empty dict.
+        """
+        self.data = data
+        self.attributes = attributes if attributes is not None else {}
+
+    def _data_status(self) -> str:
+        """Return a short description of the data state for repr/str."""
+        if self.data is None:
+            return "None"
+        if isinstance(self.data, np.ndarray):
+            return f"shape={self.data.shape}, dtype={self.data.dtype}"
+        return f"type={type(self.data).__name__}"
+
+    def _data_detail_lines(self) -> list[str]:
+        """Return detail lines about the data for __str__."""
+        if self.data is None:
+            return ["  Data: None"]
+        if isinstance(self.data, np.ndarray):
+            return [
+                f"  Data shape: {self.data.shape}",
+                f"  Data dtype: {self.data.dtype}",
+            ]
+        return [f"  Data type: {type(self.data).__name__}"]
+
+    def _attributes_detail_lines(self) -> list[str]:
+        """Return detail lines about attributes for __str__."""
+        if not self.attributes:
+            return ["  Attributes: None"]
+        lines = [f"  Attributes ({len(self.attributes)}):"]
+        for key, value in list(self.attributes.items())[:5]:
+            value_str = str(value)
+            if len(value_str) > 50:
+                value_str = value_str[:47] + "..."
+            lines.append(f"    {key}: {value_str}")
+        if len(self.attributes) > 5:
+            lines.append(f"    ... and {len(self.attributes) - 5} more")
+        return lines
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(data={self._data_status()}, attrs={len(self.attributes)})"
+
+    def __str__(self) -> str:
+        parts = [f"{type(self).__name__}:"]
+        parts.extend(self._data_detail_lines())
+        parts.extend(self._attributes_detail_lines())
+        return "\n".join(parts)

vcti_datanode-1.0.1.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: vcti-datanode
+Version: 1.0.1
+Summary: Lightweight data-plus-attributes node containers, with an optional lazily-loaded variant for out-of-core data.
+Author: Visual Collaboration Technologies Inc.
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy; extra == "typecheck"
+Dynamic: license-file
+
+# Data Node
+
+Lightweight data-plus-attributes node containers, with an optional
+lazily-loaded variant for out-of-core data.
+
+## Overview
+
+`vcti-datanode` provides two small, tree-agnostic value types:
+
+- **`DataNode`** — pairs `data` (an `np.ndarray`, any array-like, or an
+  arbitrary object) with an `attributes` metadata dict. Value equality and
+  readable `repr`/`str`. That's it.
+- **`LazyDataNode`** — a `DataNode` whose data is fetched on demand through a
+  loader callback (`load()`) and can be freed (`release()`) and reloaded
+  later. Attributes stay resident; only the data comes and goes. Built for
+  large datasets (e.g. CAE models) where holding everything in memory at once
+  is impractical.
+
+They are commonly used as **node payloads** in a tree, but depend on nothing
+but numpy and can be used anywhere a "data + metadata" unit is useful.
+
+## Installation
+
+```bash
+pip install vcti-datanode
+```
+
+### In `requirements.txt`
+
+```
+vcti-datanode>=1.0.1
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-datanode>=1.0.1",
+]
+```
+
+---
+
+## Quick Start
+
+```python
+import numpy as np
+from vcti.datanode import DataNode, LazyDataNode
+
+# Eager: data held directly.
+node = DataNode(data=np.array([1.0, 2.0, 3.0]), attributes={"units": "mm"})
+
+# Lazy: data fetched on demand, freed when not needed.
+lazy = LazyDataNode(loader=lambda: np.load("displacement.npy"),
+                    attributes={"name": "displacement"})
+lazy.is_loaded          # False
+arr = lazy.load()       # loader runs once; cached thereafter
+lazy.release()          # frees the data; attributes remain
+```
+
+---
+
+## Dependencies
+
+- `numpy>=1.26` — used for array-aware value equality and repr.

vcti_datanode-1.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+vcti/datanode/__init__.py,sha256=9-PTZ4o1k7A4Rb1PVkESi4vcPmgsoEKVSVDjeFdGzhY,655
+vcti/datanode/lazy_node.py,sha256=dsv_VtJoqUwIEmO2l0MJgDE9B-kDmwqWVGonavy8faw,4623
+vcti/datanode/node.py,sha256=bYwIANZ4SQhXWY9Zy6uP8YpxhjWP7Me12Zgk8TzUkxk,5503
+vcti/datanode/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vcti_datanode-1.0.1.dist-info/licenses/LICENSE,sha256=gqRj-E4YRsT7mZ52W76LG6aTTFv6iEOK9QR_fV5EdrI,369
+vcti_datanode-1.0.1.dist-info/METADATA,sha256=xWVgCXxtKW-ywJ7I0UHcR-HGUGsKDWgY5GFqxDUJBWY,2296
+vcti_datanode-1.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+vcti_datanode-1.0.1.dist-info/top_level.txt,sha256=Jl6AIAI3Xhru_BFQAhD_13VeXLmZQd9BqBNUaAKNgKs,5
+vcti_datanode-1.0.1.dist-info/RECORD,,

vcti_datanode-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vcti_datanode-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_datanode-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+vcti