vcti-datanode 1.0.1__tar.gz

vcti_datanode-1.0.1/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,65 @@
+# 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/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-datanode"
+version = "1.0.1"
+description = "Lightweight data-plus-attributes node containers, with an optional lazily-loaded variant for out-of-core data."
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+requires-python = ">=3.12,<3.15"
+dependencies = [
+    "numpy>=1.26",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.datanode", "vcti.datanode.*"]
+
+[tool.setuptools.package-data]
+"vcti.datanode" = ["py.typed"]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+lint = ["ruff"]
+typecheck = ["mypy"]
+
+# zip-safe must be false for a py.typed package: type checkers (PEP 561)
+# cannot read the marker or stubs from a zip-imported distribution.
+[tool.setuptools]
+zip-safe = false
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.datanode --cov-report=term-missing --cov-fail-under=95"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src"]
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = ["src"]
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_also = [
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "@(abc\\.)?abstractmethod",
+    "\\.\\.\\.",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]

vcti_datanode-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vcti_datanode-1.0.1/src/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-1.0.1/src/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-1.0.1/src/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/src/vcti_datanode.egg-info/PKG-INFO

@@ -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/src/vcti_datanode.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/vcti/datanode/__init__.py
+src/vcti/datanode/lazy_node.py
+src/vcti/datanode/node.py
+src/vcti/datanode/py.typed
+src/vcti_datanode.egg-info/PKG-INFO
+src/vcti_datanode.egg-info/SOURCES.txt
+src/vcti_datanode.egg-info/dependency_links.txt
+src/vcti_datanode.egg-info/not-zip-safe
+src/vcti_datanode.egg-info/requires.txt
+src/vcti_datanode.egg-info/top_level.txt
+tests/test_lazy_node.py
+tests/test_node.py
+tests/test_version.py

vcti_datanode-1.0.1/src/vcti_datanode.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vcti_datanode-1.0.1/src/vcti_datanode.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

vcti_datanode-1.0.1/src/vcti_datanode.egg-info/requires.txt

@@ -0,0 +1,11 @@
+numpy>=1.26
+
+[lint]
+ruff
+
+[test]
+pytest
+pytest-cov
+
+[typecheck]
+mypy

vcti_datanode-1.0.1/src/vcti_datanode.egg-info/top_level.txt

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

vcti_datanode-1.0.1/tests/test_lazy_node.py

@@ -0,0 +1,157 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Tests for LazyDataNode."""
+
+import numpy as np
+import pytest
+
+from vcti.datanode import LazyDataNode
+
+
+class TestConstruction:
+    def test_starts_unloaded(self):
+        n = LazyDataNode(loader=lambda: np.array([1, 2, 3]))
+        assert n.is_loaded is False
+        assert n.data is None
+
+    def test_with_attributes(self):
+        n = LazyDataNode(
+            loader=lambda: np.array([1, 2, 3]),
+            attributes={"units": "mm"},
+        )
+        assert n.attributes == {"units": "mm"}
+
+    def test_with_preloaded_data(self):
+        arr = np.array([1, 2, 3])
+        n = LazyDataNode(loader=lambda: None, data=arr)
+        assert n.is_loaded is True
+        assert n.data is arr
+
+
+class TestLoad:
+    def test_load_returns_data(self):
+        arr = np.array([1, 2, 3])
+        n = LazyDataNode(loader=lambda: arr)
+        result = n.load()
+        assert result is arr
+        assert n.is_loaded is True
+
+    def test_load_idempotent(self):
+        calls = [0]
+
+        def loader():
+            calls[0] += 1
+            return np.array([1, 2, 3])
+
+        n = LazyDataNode(loader=loader)
+        n.load()
+        n.load()
+        n.load()
+        assert calls[0] == 1  # only called once
+
+    def test_loader_returning_none_raises(self):
+        n = LazyDataNode(loader=lambda: None)
+        with pytest.raises(RuntimeError, match="returned None"):
+            n.load()
+        assert n.is_loaded is False  # raised before assignment; stays unloaded
+
+    def test_loader_exception_propagates_unchanged(self):
+        # The loader's own exception type must propagate so callers can
+        # handle distinct failures distinctly.
+        def bad_loader():
+            raise FileNotFoundError("file not found")
+
+        n = LazyDataNode(loader=bad_loader)
+        with pytest.raises(FileNotFoundError, match="file not found"):
+            n.load()
+
+    def test_loader_exception_leaves_node_unloaded(self):
+        def bad_loader():
+            raise OSError("boom")
+
+        n = LazyDataNode(loader=bad_loader)
+        with pytest.raises(OSError):
+            n.load()
+        assert n.is_loaded is False
+
+
+class TestRelease:
+    def test_release_clears_data(self):
+        n = LazyDataNode(loader=lambda: np.array([1, 2, 3]))
+        n.load()
+        assert n.is_loaded is True
+        n.release()
+        assert n.is_loaded is False
+        assert n.data is None
+
+    def test_reload_after_release(self):
+        calls = [0]
+
+        def loader():
+            calls[0] += 1
+            return np.array([calls[0]])
+
+        n = LazyDataNode(loader=loader)
+        n.load()
+        n.release()
+        n.load()
+        assert calls[0] == 2  # called twice after release
+
+
+class TestRepr:
+    def test_repr_when_unloaded(self):
+        n = LazyDataNode(loader=lambda: np.array([1, 2, 3]))
+        assert "unloaded" in repr(n)
+
+    def test_repr_when_loaded(self):
+        n = LazyDataNode(loader=lambda: np.array([1, 2, 3]))
+        n.load()
+        r = repr(n)
+        assert "shape" in r or "dtype" in r
+
+
+class TestStr:
+    def test_str_when_unloaded(self):
+        n = LazyDataNode(loader=lambda: np.array([1, 2, 3]))
+        s = str(n)
+        assert "unloaded" in s
+
+    def test_str_when_loaded(self):
+        n = LazyDataNode(loader=lambda: np.array([1, 2, 3]))
+        n.load()
+        s = str(n)
+        assert "Data shape" in s
+
+
+class TestInheritance:
+    def test_is_a_datanode(self):
+        from vcti.datanode import DataNode
+
+        assert isinstance(LazyDataNode(loader=lambda: 1), DataNode)
+
+    def test_is_unhashable(self):
+        # Inherits DataNode's __eq__, so __hash__ is None here too.
+        with pytest.raises(TypeError):
+            hash(LazyDataNode(loader=lambda: 1))
+
+
+class TestEquality:
+    def test_two_loaded_lazy_nodes_equal(self):
+        a = LazyDataNode(loader=lambda: None, data=np.array([1, 2, 3]))
+        b = LazyDataNode(loader=lambda: None, data=np.array([1, 2, 3]))
+        assert a == b
+
+    def test_unloaded_lazy_nodes_with_same_attributes_equal(self):
+        # Equality uses inherited DataNode semantics (data + attributes);
+        # the loader is not part of identity.
+        a = LazyDataNode(loader=lambda: np.array([1]), attributes={"u": "mm"})
+        b = LazyDataNode(loader=lambda: np.array([2]), attributes={"u": "mm"})
+        assert a == b
+
+    def test_lazy_node_equals_plain_datanode_with_same_payload(self):
+        from vcti.datanode import DataNode
+
+        lazy = LazyDataNode(loader=lambda: None, data=np.array([1, 2, 3]))
+        plain = DataNode(data=np.array([1, 2, 3]))
+        assert lazy == plain
+        assert plain == lazy

vcti_datanode-1.0.1/tests/test_node.py

@@ -0,0 +1,194 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Tests for DataNode."""
+
+import numpy as np
+import pytest
+
+from vcti.datanode import DataNode
+
+
+class TestConstruction:
+    def test_empty_defaults(self):
+        n = DataNode()
+        assert n.data is None
+        assert n.attributes == {}
+
+    def test_with_data(self):
+        arr = np.array([1.0, 2.0, 3.0])
+        n = DataNode(data=arr)
+        assert n.data is arr
+        assert n.attributes == {}
+
+    def test_with_attributes(self):
+        n = DataNode(attributes={"units": "mm"})
+        assert n.data is None
+        assert n.attributes == {"units": "mm"}
+
+    def test_with_both(self):
+        arr = np.array([1, 2])
+        n = DataNode(data=arr, attributes={"k": "v"})
+        assert n.data is arr
+        assert n.attributes == {"k": "v"}
+
+
+class TestEquality:
+    def test_empty_nodes_equal(self):
+        assert DataNode() == DataNode()
+
+    def test_different_attributes_unequal(self):
+        assert DataNode(attributes={"a": 1}) != DataNode(attributes={"a": 2})
+
+    def test_same_data_arrays_equal(self):
+        a = DataNode(data=np.array([1, 2, 3]))
+        b = DataNode(data=np.array([1, 2, 3]))
+        assert a == b
+
+    def test_different_data_arrays_unequal(self):
+        a = DataNode(data=np.array([1, 2, 3]))
+        b = DataNode(data=np.array([1, 2, 4]))
+        assert a != b
+
+    def test_different_shape_unequal(self):
+        a = DataNode(data=np.array([1, 2, 3]))
+        b = DataNode(data=np.array([1, 2]))
+        assert a != b
+
+    def test_one_data_none_unequal(self):
+        a = DataNode(data=np.array([1, 2]))
+        b = DataNode()
+        assert a != b
+
+    def test_compared_with_non_node_returns_notimplemented(self):
+        assert DataNode().__eq__("not a node") is NotImplemented
+
+    def test_non_array_data_equal(self):
+        a = DataNode(data="hello")
+        b = DataNode(data="hello")
+        assert a == b
+
+    def test_ndarray_vs_list_unequal_without_raising(self):
+        # Mixed kind (ndarray vs list) must compare unequal, never raise.
+        a = DataNode(data=np.array([1, 2, 3]))
+        b = DataNode(data=[1, 2, 3])
+        assert a != b
+        assert b != a
+
+    def test_ndarray_vs_tuple_unequal_without_raising(self):
+        a = DataNode(data=np.array([1, 2, 3]))
+        b = DataNode(data=(1, 2, 3))
+        assert a != b
+
+    def test_equal_lists_equal(self):
+        # Non-ndarray array-likes fall back to == and reduce to a bool.
+        assert DataNode(data=[1, 2, 3]) == DataNode(data=[1, 2, 3])
+        assert DataNode(data=[1, 2, 3]) != DataNode(data=[1, 2, 4])
+
+    def test_nan_arrays_unequal(self):
+        # np.array_equal treats NaN != NaN, so NaN-bearing arrays are unequal.
+        a = DataNode(data=np.array([1.0, np.nan]))
+        b = DataNode(data=np.array([1.0, np.nan]))
+        assert a != b
+
+    def test_masked_arrays_compare_by_underlying_data(self):
+        a = DataNode(data=np.ma.array([1, 2, 3], mask=[0, 1, 0]))
+        b = DataNode(data=np.ma.array([1, 2, 3], mask=[0, 1, 0]))
+        assert a == b
+
+    def test_masked_arrays_ignore_the_mask(self):
+        # Equality compares the underlying data only; the mask is NOT
+        # consulted (np.array_equal drops it). Same data + different masks
+        # therefore compare EQUAL...
+        a = DataNode(data=np.ma.array([1, 2, 3], mask=[0, 0, 0]))
+        b = DataNode(data=np.ma.array([1, 2, 3], mask=[0, 1, 0]))
+        assert a == b
+
+    def test_masked_arrays_compare_data_under_the_mask(self):
+        # ...and data that differs under a masked-out cell still compares
+        # UNEQUAL, because the underlying values are what is compared.
+        a = DataNode(data=np.ma.array([1, 2, 9], mask=[0, 0, 1]))
+        b = DataNode(data=np.ma.array([1, 2, 3], mask=[0, 0, 1]))
+        assert a != b
+
+    def test_attribute_mismatch_short_circuits_before_data(self):
+        # Differing attributes => unequal regardless of data.
+        a = DataNode(data=np.array([1, 2, 3]), attributes={"a": 1})
+        b = DataNode(data=np.array([1, 2, 3]), attributes={"a": 2})
+        assert a != b
+
+    def test_non_ndarray_arraylike_with_vector_eq_reduces_to_bool(self):
+        # An array-like (not an ndarray) whose __eq__ returns a non-scalar
+        # must still resolve to a plain bool, not raise.
+        class ArrayLike:
+            def __init__(self, values):
+                self.values = values
+
+            def __eq__(self, other):
+                return np.asarray(self.values) == np.asarray(other.values)
+
+        assert DataNode(data=ArrayLike([1, 2, 3])) == DataNode(data=ArrayLike([1, 2, 3]))
+        assert DataNode(data=ArrayLike([1, 2, 3])) != DataNode(data=ArrayLike([1, 2, 4]))
+
+
+class TestHashing:
+    def test_datanode_is_unhashable(self):
+        # Defining __eq__ on a mutable container drops __hash__ by design.
+        with pytest.raises(TypeError):
+            hash(DataNode())
+
+
+class TestRepr:
+    def test_repr_includes_class_name(self):
+        n = DataNode()
+        assert "DataNode" in repr(n)
+
+    def test_repr_with_array_data(self):
+        n = DataNode(data=np.array([1, 2, 3]))
+        r = repr(n)
+        assert "shape" in r or "dtype" in r
+
+    def test_repr_with_non_array_data(self):
+        n = DataNode(data="hello")
+        assert "type=str" in repr(n)
+
+
+class TestStr:
+    def test_str_includes_class_name(self):
+        n = DataNode()
+        assert "DataNode" in str(n)
+
+    def test_str_with_attributes(self):
+        n = DataNode(attributes={"name": "x", "units": "mm"})
+        s = str(n)
+        assert "Attributes" in s
+        assert "name" in s
+
+    def test_str_truncates_long_values(self):
+        n = DataNode(attributes={"k": "x" * 200})
+        s = str(n)
+        # Truncated values end with ellipsis.
+        assert "..." in s
+
+    def test_str_truncates_many_attributes(self):
+        attrs = {f"k{i}": i for i in range(10)}
+        n = DataNode(attributes=attrs)
+        s = str(n)
+        assert "more" in s
+
+    def test_str_with_array_data(self):
+        n = DataNode(data=np.array([1, 2, 3]))
+        s = str(n)
+        assert "Data shape" in s
+        assert "Data dtype" in s
+
+    def test_str_with_non_array_data(self):
+        n = DataNode(data="hello")
+        s = str(n)
+        assert "Data type" in s
+
+
+class TestSlots:
+    def test_no_extra_attributes_allowed(self):
+        n = DataNode()
+        with pytest.raises(AttributeError):
+            n.extra = "x"  # type: ignore[attr-defined]

vcti_datanode-1.0.1/tests/test_version.py

@@ -0,0 +1,15 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Version tests for vcti-datanode."""
+
+import re
+
+import vcti.datanode
+
+
+class TestVersion:
+    def test_version_exists(self):
+        assert hasattr(vcti.datanode, "__version__")
+
+    def test_version_is_valid_semver(self):
+        assert re.match(r"^\d+\.\d+\.\d+", vcti.datanode.__version__)