Metadata-Version: 2.4
Name: vcti-tree-exporter-hdf5
Version: 2.0.0
Summary: HDF5 exporter plugin for vcti-tree-exporter: writes a vcti tree to an .h5 file (groups, datasets, attributes).
Author: Visual Collaboration Technologies Inc.
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/vcollab/vcti-python-tree-exporter-hdf5
Project-URL: Repository, https://github.com/vcollab/vcti-python-tree-exporter-hdf5
Project-URL: Changelog, https://github.com/vcollab/vcti-python-tree-exporter-hdf5/blob/main/CHANGELOG.md
Keywords: tree,export,hdf5,h5py,serialization,exporter,plugin
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: vcti-tree-exporter>=2.0.0
Requires-Dist: vcti-tree>=2.0.0
Requires-Dist: vcti-datanode>=2.0.0
Requires-Dist: numpy>=1.24
Requires-Dist: h5py>=3.0
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

# HDF5 Tree Exporter

HDF5 exporter plugin for [`vcti-tree-exporter`](https://github.com/vcollab/vcti-python-tree-exporter): writes a vcti tree to an `.h5` file (groups, datasets, attributes).

`HdfExporter` serializes any [`vcti-tree`](https://github.com/vcollab/vcti-python-tree)
tree whose node payloads are
[`vcti-datanode`](https://github.com/vcollab/vcti-python-datanode) `DataNode`s
to a single HDF5 file. It satisfies the `vcti.tree.exporter.core.Exporter` protocol
and ships a `get_exporter_descriptor()` factory, so a consumer registers it in a
catalog and resolves it by id (`"hdf5"`) or by attribute lookup.

## Installation

```bash
pip install vcti-tree-exporter-hdf5
```

This pulls in `vcti-tree-exporter` (the protocol/catalog) and `h5py`.

## Tree → HDF5 mapping

| Tree node | HDF5 object |
|---|---|
| internal node (has children) | HDF5 group |
| data leaf (`node.load()` yields an array) | HDF5 dataset (plain or, for a structured array, compound) |
| metadata-only leaf (no data, no children) | HDF5 group with attributes |
| a node's `node.name` | the group/dataset name (falls back to `node_<index>`) |
| a node's `node.attributes` | HDF5 attributes on the group/dataset |

A node's structural name comes from `node.name` (the `vcti-datanode` intrinsic),
and its free-form `node.attributes` are written verbatim — intrinsic identity
lives in its own namespace, so nothing needs filtering. NumPy Unicode (`U<n>`)
fields inside a compound dtype are stored as h5py variable-length UTF-8 strings
(h5py has no fixed-width Unicode in compound types). Attribute values are
coerced for h5py (bytes decoded, numpy scalars via `.item()`); anything h5py
can't store natively falls back to its `str()`.

## Usage

```python
from pathlib import Path
from vcti.tree.exporter.core import build_registry, get_exporter
from vcti.tree.exporter.hdf5 import get_exporter_descriptor

registry = build_registry([get_exporter_descriptor()])   # plus any other format plugins
get_exporter(registry, "hdf5").export(tree, Path("model.h5"), overwrite=True)
```

Or use the exporter directly:

```python
from vcti.tree.exporter.hdf5 import HdfExporter
HdfExporter().export(tree, Path("model.h5"))
```

## Dependencies

- [vcti-tree-exporter](https://github.com/vcollab/vcti-python-tree-exporter) — the `Exporter` protocol and the `ExporterDescriptor` catalog.
- [vcti-tree](https://github.com/vcollab/vcti-python-tree) / [vcti-datanode](https://github.com/vcollab/vcti-python-datanode) — the tree and payload types.
- [h5py](https://www.h5py.org/) — the HDF5 backend.
- numpy.
