vcti-tree-exporter-csv 2.0.0__tar.gz

vcti_tree_exporter_csv-2.0.0/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_tree_exporter_csv-2.0.0/PKG-INFO

@@ -0,0 +1,94 @@
+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.)

vcti_tree_exporter_csv-2.0.0/README.md

@@ -0,0 +1,60 @@
+# 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.)

vcti_tree_exporter_csv-2.0.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-tree-exporter-csv"
+version = "2.0.0"
+description = "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."
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+requires-python = ">=3.12,<3.15"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+keywords = ["tree", "export", "csv", "serialization", "exporter", "plugin"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "vcti-tree-exporter>=2.0.0",
+    "vcti-tree>=2.0.0",
+    "vcti-datanode>=2.0.0",
+    "numpy>=1.24",
+]
+
+[project.urls]
+Homepage = "https://github.com/vcollab/vcti-python-tree-exporter-csv"
+Repository = "https://github.com/vcollab/vcti-python-tree-exporter-csv"
+Changelog = "https://github.com/vcollab/vcti-python-tree-exporter-csv/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.tree.exporter.csv", "vcti.tree.exporter.csv.*"]
+
+[tool.setuptools.package-data]
+"vcti.tree.exporter.csv" = ["py.typed"]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+lint = ["ruff"]
+typecheck = ["mypy"]
+
+[tool.setuptools]
+zip-safe = true
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.tree.exporter.csv --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_tree_exporter_csv-2.0.0/setup.cfg

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

vcti_tree_exporter_csv-2.0.0/src/vcti/tree/exporter/csv/__init__.py

@@ -0,0 +1,22 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.tree.exporter.csv — CSV exporter plugin for vcti-tree-exporter.
+
+Provides :class:`CsvExporter`, which serializes a ``vcti.tree`` tree of
+``vcti.datanode.DataNode`` payloads as a directory tree of CSV tables mirroring
+the hierarchy, with each node's attributes in a JSON sidecar, and
+:func:`get_exporter_descriptor`, the catalog factory a consumer registers with
+``vcti.tree.exporter.core.build_registry``.
+"""
+
+from importlib.metadata import version
+
+from .exporter import CsvExporter, get_exporter_descriptor
+
+__version__ = version("vcti-tree-exporter-csv")
+
+__all__ = [
+    "CsvExporter",
+    "__version__",
+    "get_exporter_descriptor",
+]

vcti_tree_exporter_csv-2.0.0/src/vcti/tree/exporter/csv/exporter.py

@@ -0,0 +1,232 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""CSV exporter — write a vcti tree as a directory tree of CSV tables.
+
+Layout: the output path is a directory mirroring the tree. A node with children
+is a sub-directory; a data leaf is a ``<name>.csv`` table. Each node's free-form
+``attributes`` are written next to it as a JSON sidecar — ``<name>.attributes.json``
+for a leaf, and the reserved ``_attributes.json`` / ``_data.csv`` inside a
+directory for a group node's own attributes/array.
+
+CSV suits 2-D tables of settings and metadata that load straight into pandas.
+It does not preserve dtype, and an array with more than two dimensions (or a
+structured array that is not 1-D) raises ``UnrepresentableNodeError``. The
+export is one-way (no matching importer).
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import re
+import shutil
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+from numpy.typing import NDArray
+from vcti.datanode import DataNode
+from vcti.tree.exporter.core import (
+    EXTENSION_ATTR,
+    FORMAT_ATTR,
+    ExporterDescriptor,
+    UnrepresentableNodeError,
+)
+
+if TYPE_CHECKING:
+    from vcti.tree.core import ReadOnlyTree
+
+#: Fixed, well-known id for the CSV exporter descriptor.
+EXPORTER_ID = "csv"
+
+#: Reserved file names for a group/root node's own array and attributes.
+DATA_FILE = "_data.csv"
+ATTRS_FILE = "_attributes.json"
+
+_UNSAFE = re.compile(r"[^A-Za-z0-9._-]")
+
+
+def _json_default(value: Any) -> Any:
+    """Coerce a value JSON cannot serialize natively into a JSON-safe form."""
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace").rstrip("\x00")
+    if isinstance(value, np.generic):
+        return value.item()
+    if isinstance(value, np.ndarray):
+        return value.tolist()
+    return str(value)
+
+
+def _csv_value(value: Any) -> Any:
+    """Coerce a single cell value into a CSV-friendly form.
+
+    ``csv.writer`` already stringifies numpy scalars sensibly; only ``bytes``
+    need decoding so they are not written as a ``b'...'`` repr.
+    """
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace").rstrip("\x00")
+    return value
+
+
+def _safe_name(name: str) -> str:
+    """Sanitize a node name into a filesystem-safe path segment.
+
+    Replaces characters outside ``[A-Za-z0-9._-]`` and strips leading/trailing
+    dots and spaces, so a name such as ``".."`` or ``"../x"`` cannot escape the
+    output directory (path traversal) and Windows trailing-dot/space trimming
+    cannot silently collide two names.
+    """
+    safe = _UNSAFE.sub("_", name).strip(". ")
+    return safe or "node"
+
+
+def _write_attrs(attrs: dict[str, Any], path: Path) -> None:
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(attrs, f, indent=2, ensure_ascii=False, default=_json_default)
+
+
+def _write_csv(array: NDArray[Any], path: Path) -> None:
+    """Write a 1-D/2-D (or structured 1-D) array as a CSV table."""
+    names = array.dtype.names
+    if array.ndim > 2 or (names is not None and array.ndim > 1):
+        raise UnrepresentableNodeError(
+            f"array with shape {array.shape} and dtype {array.dtype} "
+            "cannot be written as a 2-D CSV table"
+        )
+    with path.open("w", newline="", encoding="utf-8") as f:
+        writer = csv.writer(f)
+        if names is not None:
+            writer.writerow(names)
+            for record in np.atleast_1d(array):
+                writer.writerow([_csv_value(v) for v in record])
+        elif array.ndim == 2:
+            for row in array:
+                writer.writerow([_csv_value(v) for v in row])
+        else:  # 0-D or 1-D plain
+            for value in np.atleast_1d(array):
+                writer.writerow([_csv_value(value)])
+
+
+class CsvExporter:
+    """Serialize a vcti tree as a directory tree of CSV tables.
+
+    Satisfies the ``vcti.tree.exporter.core.Exporter`` protocol structurally. Format
+    name and (empty) default extension live on its descriptor
+    (:func:`get_exporter_descriptor`), not on this class.
+    """
+
+    def export(
+        self,
+        tree: ReadOnlyTree[DataNode, Any],
+        path: Path,
+        *,
+        overwrite: bool = False,
+    ) -> None:
+        path = Path(path)
+        if path.exists():
+            if not overwrite:
+                raise FileExistsError(f"Output path already exists: {path}")
+            self._remove(path)
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.mkdir()
+        self._render_dir(tree, tree.root_handle, path)
+
+    @staticmethod
+    def _remove(path: Path) -> None:
+        if path.is_dir():
+            shutil.rmtree(path)
+        else:
+            path.unlink()
+
+    def _render_dir(
+        self,
+        tree: ReadOnlyTree[DataNode, Any],
+        handle: Any,
+        directory: Path,
+    ) -> None:
+        """Write a group/root node's own content into ``directory``, then children."""
+        payload = tree.payload(handle)
+        if isinstance(payload, DataNode):
+            self._write_own(payload, directory)
+
+        used: set[str] = {"_data", "_attributes"}  # reserved stems in this directory
+        for index, child in enumerate(tree.children(handle)):
+            self._render_child(tree, child, directory, index, used)
+
+    def _write_own(self, payload: DataNode, directory: Path) -> None:
+        """Write a group/root node's reserved ``_attributes.json`` / ``_data.csv``."""
+        attrs = dict(payload.attributes)
+        if attrs:
+            _write_attrs(attrs, directory / ATTRS_FILE)
+        array = self._take_array(payload)
+        if array is not None:
+            _write_csv(array, directory / DATA_FILE)
+
+    def _render_child(
+        self,
+        tree: ReadOnlyTree[DataNode, Any],
+        handle: Any,
+        parent_dir: Path,
+        index: int,
+        used: set[str],
+    ) -> None:
+        payload = tree.payload(handle)
+        if not isinstance(payload, DataNode):
+            return
+
+        stem = _unique_stem(_safe_name(payload.name or f"node_{index}"), used)
+        children = list(tree.children(handle))
+
+        if children:
+            subdir = parent_dir / stem
+            subdir.mkdir()
+            self._render_dir(tree, handle, subdir)
+            return
+
+        attrs = dict(payload.attributes)
+        array = self._take_array(payload)
+        if array is not None:
+            _write_csv(array, parent_dir / f"{stem}.csv")
+            if attrs:
+                _write_attrs(attrs, parent_dir / f"{stem}.attributes.json")
+        elif attrs:
+            _write_attrs(attrs, parent_dir / f"{stem}.attributes.json")
+
+    @staticmethod
+    def _take_array(payload: DataNode) -> NDArray[Any] | None:
+        """Materialise the node's array, releasing a lazy source we loaded."""
+        was_loaded = payload.is_loaded
+        array = payload.load()
+        if array is not None and not was_loaded:
+            payload.unload()
+        return array
+
+
+def _unique_stem(name: str, used: set[str]) -> str:
+    """Return ``name`` (or a ``name~N`` variant) unused in this directory.
+
+    Comparison is case-insensitive so two siblings differing only in case do
+    not collide on a case-insensitive filesystem.
+    """
+    candidate = name
+    n = 1
+    while candidate.lower() in used:
+        candidate = f"{name}~{n}"
+        n += 1
+    used.add(candidate.lower())
+    return candidate
+
+
+def get_exporter_descriptor() -> ExporterDescriptor:
+    """Create the :class:`ExporterDescriptor` for the CSV exporter."""
+    return ExporterDescriptor(
+        id=EXPORTER_ID,
+        name="CSV Exporter",
+        exporter=CsvExporter(),
+        description="Writes a vcti tree as a directory of CSV tables with JSON sidecars.",
+        attributes={
+            FORMAT_ATTR: "csv",
+            EXTENSION_ATTR: "",  # writes a directory, not a single file
+        },
+    )

vcti_tree_exporter_csv-2.0.0/src/vcti_tree_exporter_csv.egg-info/PKG-INFO

@@ -0,0 +1,94 @@
+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.)

vcti_tree_exporter_csv-2.0.0/src/vcti_tree_exporter_csv.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/vcti/tree/exporter/csv/__init__.py
+src/vcti/tree/exporter/csv/exporter.py
+src/vcti/tree/exporter/csv/py.typed
+src/vcti_tree_exporter_csv.egg-info/PKG-INFO
+src/vcti_tree_exporter_csv.egg-info/SOURCES.txt
+src/vcti_tree_exporter_csv.egg-info/dependency_links.txt
+src/vcti_tree_exporter_csv.egg-info/requires.txt
+src/vcti_tree_exporter_csv.egg-info/top_level.txt
+src/vcti_tree_exporter_csv.egg-info/zip-safe
+tests/test_exporter.py
+tests/test_version.py

vcti_tree_exporter_csv-2.0.0/src/vcti_tree_exporter_csv.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vcti_tree_exporter_csv-2.0.0/src/vcti_tree_exporter_csv.egg-info/requires.txt

@@ -0,0 +1,14 @@
+vcti-tree-exporter>=2.0.0
+vcti-tree>=2.0.0
+vcti-datanode>=2.0.0
+numpy>=1.24
+
+[lint]
+ruff
+
+[test]
+pytest
+pytest-cov
+
+[typecheck]
+mypy

vcti_tree_exporter_csv-2.0.0/src/vcti_tree_exporter_csv.egg-info/top_level.txt

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

vcti_tree_exporter_csv-2.0.0/src/vcti_tree_exporter_csv.egg-info/zip-safe

@@ -0,0 +1 @@
+

vcti_tree_exporter_csv-2.0.0/tests/test_exporter.py

@@ -0,0 +1,230 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Tests for the CSV exporter."""
+
+from __future__ import annotations
+
+import csv
+import json
+
+import numpy as np
+import pytest
+from vcti.datanode import DataNode, EagerDataSource, LazyDataSource
+from vcti.lookup import Rule
+from vcti.tree.core import DictTree
+from vcti.tree.exporter.core import (
+    EXTENSION_ATTR,
+    FORMAT_ATTR,
+    Exporter,
+    UnrepresentableNodeError,
+    build_registry,
+    get_exporter,
+)
+
+from vcti.tree.exporter.csv import CsvExporter, get_exporter_descriptor
+
+
+def _data(array: np.ndarray, *, name: str) -> DataNode:
+    return DataNode(name=name, data_source=EagerDataSource(array))
+
+
+def _read_csv(path):
+    with path.open(newline="", encoding="utf-8") as f:
+        return list(csv.reader(f))
+
+
+def _read_json(path):
+    with path.open(encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _sample_tree() -> DictTree:
+    tree: DictTree = DictTree(DataNode(name="model", source_attributes={"solver": "abaqus"}))
+    root = tree.root_handle
+
+    # metadata-only leaf -> sidecar only
+    tree.create_child(root, DataNode(name="info", source_attributes={"count": np.int64(7)}))
+
+    # group with a structured-table leaf carrying attributes
+    materials = tree.create_child(root, DataNode(name="materials"))
+    table = np.array([("Steel", 210.0), ("Al", 70.0)], dtype=[("name", "U8"), ("E", "f8")])
+    tree.create_child(
+        materials,
+        DataNode(
+            name="props",
+            data_source=EagerDataSource(table),
+            source_attributes={"unit": "GPa"},
+        ),
+    )
+
+    # plain 1-D and 2-D leaves at the root
+    tree.create_child(root, _data(np.array([1.0, 2.0, 3.0]), name="vec"))
+    tree.create_child(root, _data(np.arange(6).reshape(2, 3), name="grid"))
+
+    # empty leaf writes nothing; non-DataNode payload is skipped
+    tree.create_child(root, DataNode(name="empty"))
+    tree.create_child(root, "not-a-datanode")
+    return tree
+
+
+def _export(tmp_path, tree, name="out"):
+    out = tmp_path / name
+    CsvExporter().export(tree, out)
+    return out
+
+
+def test_protocol_conformance():
+    assert isinstance(CsvExporter(), Exporter)
+
+
+def test_descriptor_factory_records_metadata():
+    desc = get_exporter_descriptor()
+    assert desc.id == "csv"
+    assert isinstance(desc.exporter, CsvExporter)
+    assert desc.attributes[FORMAT_ATTR] == "csv"
+    assert desc.attributes[EXTENSION_ATTR] == ""  # directory output
+
+
+def test_root_attributes_and_directory_layout(tmp_path):
+    out = _export(tmp_path, _sample_tree())
+    # root attributes -> reserved sidecar in the top directory
+    assert _read_json(out / "_attributes.json") == {"solver": "abaqus"}
+    # group node -> sub-directory
+    assert (out / "materials").is_dir()
+    # empty leaf produced nothing
+    assert not (out / "empty.csv").exists()
+    assert not (out / "empty.attributes.json").exists()
+
+
+def test_metadata_only_leaf_writes_sidecar_only(tmp_path):
+    out = _export(tmp_path, _sample_tree())
+    assert not (out / "info.csv").exists()
+    assert _read_json(out / "info.attributes.json") == {"count": 7}
+
+
+def test_structured_table_has_header_and_sidecar(tmp_path):
+    out = _export(tmp_path, _sample_tree())
+    rows = _read_csv(out / "materials" / "props.csv")
+    assert rows[0] == ["name", "E"]  # field-name header
+    assert rows[1] == ["Steel", "210.0"]
+    assert _read_json(out / "materials" / "props.attributes.json") == {"unit": "GPa"}
+
+
+def test_plain_1d_and_2d_arrays(tmp_path):
+    out = _export(tmp_path, _sample_tree())
+    assert _read_csv(out / "vec.csv") == [["1.0"], ["2.0"], ["3.0"]]
+    assert _read_csv(out / "grid.csv") == [["0", "1", "2"], ["3", "4", "5"]]
+
+
+def test_node_with_both_data_and_children(tmp_path):
+    tree: DictTree = DictTree(DataNode(name="root"))
+    parent = tree.create_child(
+        tree.root_handle,
+        DataNode(name="parent", data_source=EagerDataSource(np.array([9]))),
+    )
+    tree.create_child(parent, DataNode(name="kid", source_attributes={"k": 1}))
+    out = _export(tmp_path, tree)
+    # the group's own array lands in the reserved _data.csv inside its directory
+    assert _read_csv(out / "parent" / "_data.csv") == [["9"]]
+    assert _read_json(out / "parent" / "kid.attributes.json") == {"k": 1}
+
+
+def test_attribute_values_are_json_encoded(tmp_path):
+    tree: DictTree = DictTree(DataNode(name="root"))
+    tree.create_child(
+        tree.root_handle,
+        DataNode(
+            name="n",
+            source_attributes={
+                "label": b"ABAQUS",  # bytes -> decoded
+                "vec": np.array([1.0, 2.0]),  # ndarray -> list
+                "tags": {"a", "b"},  # set -> str() fallback
+            },
+        ),
+    )
+    out = _export(tmp_path, tree)
+    attrs = _read_json(out / "n.attributes.json")
+    assert attrs["label"] == "ABAQUS"
+    assert attrs["vec"] == [1.0, 2.0]
+    assert isinstance(attrs["tags"], str)
+
+
+def test_bytes_cells_are_decoded(tmp_path):
+    tree: DictTree = DictTree(DataNode(name="root"))
+    tree.create_child(tree.root_handle, _data(np.array([b"mm", b"t"]), name="units"))
+    out = _export(tmp_path, tree)
+    assert _read_csv(out / "units.csv") == [["mm"], ["t"]]
+
+
+def test_traversal_names_are_neutralised(tmp_path):
+    tree: DictTree = DictTree(DataNode(name="root"))
+    tree.create_child(tree.root_handle, _data(np.array([1]), name=".."))
+    tree.create_child(tree.root_handle, _data(np.array([2]), name="../escape"))
+    out = _export(tmp_path, tree)
+
+    # nothing escaped the output directory
+    assert list(out.parent.iterdir()) == [out]
+    assert sorted(p.name for p in out.glob("*.csv")) == ["_escape.csv", "node.csv"]
+
+
+def test_non_datanode_root_writes_empty_directory(tmp_path):
+    tree: DictTree = DictTree("not-a-datanode")
+    out = _export(tmp_path, tree)
+    assert out.is_dir()
+    assert list(out.iterdir()) == []
+
+
+def test_more_than_2d_raises(tmp_path):
+    tree: DictTree = DictTree(DataNode(name="root"))
+    tree.create_child(tree.root_handle, _data(np.zeros((2, 2, 2)), name="cube"))
+    with pytest.raises(UnrepresentableNodeError, match="2-D CSV table"):
+        CsvExporter().export(tree, tmp_path / "out")
+
+
+def test_name_sanitised_and_case_collision_deduped(tmp_path):
+    tree: DictTree = DictTree(DataNode(name="root"))
+    tree.create_child(tree.root_handle, _data(np.array([1]), name="a/b"))  # unsafe '/'
+    tree.create_child(tree.root_handle, _data(np.array([2]), name="Mat"))
+    tree.create_child(tree.root_handle, _data(np.array([3]), name="mat"))  # case-collides
+    out = _export(tmp_path, tree)
+    names = sorted(p.name for p in out.glob("*.csv"))
+    assert names == ["Mat.csv", "a_b.csv", "mat~1.csv"]
+
+
+def test_lazy_node_materialised_then_released(tmp_path):
+    tree: DictTree = DictTree(DataNode(name="root"))
+    node = DataNode(name="lazy", data_source=LazyDataSource(lambda: np.array([5, 6]), shape=(2,)))
+    tree.create_child(tree.root_handle, node)
+    assert not node.is_loaded
+    out = _export(tmp_path, tree)
+    assert _read_csv(out / "lazy.csv") == [["5"], ["6"]]
+    assert not node.is_loaded  # restored
+
+
+def test_overwrite_behavior(tmp_path):
+    tree = _sample_tree()
+    out = tmp_path / "out"
+    CsvExporter().export(tree, out)
+    with pytest.raises(FileExistsError):
+        CsvExporter().export(tree, out)
+    CsvExporter().export(tree, out, overwrite=True)  # replaces the directory
+
+
+def test_overwrite_replaces_a_file_at_the_path(tmp_path):
+    out = tmp_path / "out"
+    out.write_text("i am a file")
+    CsvExporter().export(_sample_tree(), out, overwrite=True)
+    assert out.is_dir()
+
+
+def test_creates_parent_directories(tmp_path):
+    out = tmp_path / "nested" / "deep" / "out"
+    CsvExporter().export(_sample_tree(), out)
+    assert (out / "_attributes.json").exists()
+
+
+def test_registry_integration():
+    registry = build_registry([get_exporter_descriptor()])
+    assert isinstance(get_exporter(registry, "csv"), CsvExporter)
+    (desc,) = registry.lookup.filter([Rule(FORMAT_ATTR, "==", "csv")])
+    assert desc.id == "csv"

vcti_tree_exporter_csv-2.0.0/tests/test_version.py

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