Metadata-Version: 2.4
Name: vcti-tree-exporter-json
Version: 2.0.0
Summary: JSON exporter plugin for vcti-tree-exporter: writes a vcti tree to a single .json document (nested nodes carrying name, attributes, and light arrays as JSON lists).
Author: Visual Collaboration Technologies Inc.
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/vcollab/vcti-python-tree-exporter-json
Project-URL: Repository, https://github.com/vcollab/vcti-python-tree-exporter-json
Project-URL: Changelog, https://github.com/vcollab/vcti-python-tree-exporter-json/blob/main/CHANGELOG.md
Keywords: tree,export,json,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
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

# JSON Tree Exporter

JSON exporter plugin for [`vcti-tree-exporter`](https://github.com/vcollab/vcti-python-tree-exporter): writes a vcti tree to a single `.json` document.

`JsonExporter` 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 one JSON document that mirrors the tree, and ships a
`get_exporter_descriptor()` factory so a consumer registers it in a catalog and
resolves it by id (`"json"`) or by attribute lookup.

JSON is a natural fit for **structure, metadata, and light arrays** — simulation
settings, CAE metadata, input decks — that load straight into tooling. It is a
poor fit for large numeric arrays (they become bulky nested lists); use HDF5 or
NPZ for heavy data.

## Installation

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

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

## Tree → JSON mapping

Each node becomes an object; the document root is the tree's root node:

```json
{
  "name": "model",
  "attributes": {"solver": "abaqus"},
  "children": [
    {"name": "info", "attributes": {"count": 7}},
    {"name": "displacement", "attributes": {}, "data": [1.0, 2.0, 3.0]}
  ]
}
```

| Tree node part | JSON |
|---|---|
| `node.name` | `"name"` (the structural name; `null` if unset) |
| `node.attributes` | `"attributes"` object (always present) |
| `node.load()` array | `"data"` as nested lists (present only for data nodes) |
| children | `"children"` array (present only when non-empty) |

A node may carry both `data` and `children`. Attribute values are JSON-encoded
(bytes decoded, numpy scalars/arrays converted to numbers/lists); anything not
natively serializable falls back to its `str()`. Array dtype is not preserved —
the export is one-way.

## Usage

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

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

Or use the exporter directly:

```python
from vcti.tree.exporter.json import JsonExporter
JsonExporter().export(tree, Path("model.json"))
```

## 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.
- numpy. (JSON encoding itself uses only the standard library.)
