Metadata-Version: 2.4
Name: vcti-tree-exporter-csv
Version: 2.0.0
Summary: CSV exporter plugin for vcti-tree-exporter: writes a vcti tree as a directory tree of CSV tables mirroring the hierarchy, with each node's attributes in a JSON sidecar.
Author: Visual Collaboration Technologies Inc.
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/vcollab/vcti-python-tree-exporter-csv
Project-URL: Repository, https://github.com/vcollab/vcti-python-tree-exporter-csv
Project-URL: Changelog, https://github.com/vcollab/vcti-python-tree-exporter-csv/blob/main/CHANGELOG.md
Keywords: tree,export,csv,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

# CSV Tree Exporter

CSV exporter plugin for [`vcti-tree-exporter`](https://github.com/vcollab/vcti-python-tree-exporter): writes a vcti tree as a directory tree of CSV tables.

`CsvExporter` 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
as a directory of CSV tables mirroring the hierarchy, and ships a
`get_exporter_descriptor()` factory so a consumer registers it in a catalog and
resolves it by id (`"csv"`) or by attribute lookup.

CSV suits **light 2-D tables of settings and metadata** that load straight into
pandas — not heavy result arrays. Use HDF5 or NPZ for complete numeric data.

## Tree → CSV mapping

The output path is a directory:

```
out/
  _attributes.json          # the root node's attributes
  info.attributes.json      # a metadata-only leaf -> sidecar only
  materials/                # a group node -> sub-directory
    props.csv               # a structured-array leaf -> table with a header row
    props.attributes.json   # its attributes
  vec.csv                   # a plain 1-D array -> one value per row
  grid.csv                  # a plain 2-D array -> rows
```

| Tree node | On disk |
|---|---|
| node with children | sub-directory named after the node |
| data leaf | `<name>.csv` (structured → header + rows; plain 1-D/2-D → rows) |
| a node's `attributes` | `<name>.attributes.json` (leaf) or `_attributes.json` (group) |
| a group node's own array | `_data.csv` inside its directory |

Names are sanitized to filesystem-safe segments and de-collided case-insensitively
(`Mat`, `mat` → `Mat`, `mat~1`) so nothing is silently overwritten. An array with
more than two dimensions raises `UnrepresentableNodeError`. CSV does not preserve
dtype and 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.csv import get_exporter_descriptor

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

`overwrite=True` replaces the existing output directory — point it at a
dedicated path.

## 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. (CSV writing itself uses only the standard library.)
