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.
