vcti-tree-exporter 1.0.0__tar.gz

vcti_tree_exporter-1.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-1.0.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: vcti-tree-exporter
+Version: 1.0.0
+Summary: Format-agnostic exporters for vcti trees: an Exporter protocol and registry, with per-format writers as plugins.
+Author: Visual Collaboration Technologies Inc.
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/vcollab/vcti-python-tree-exporter
+Project-URL: Repository, https://github.com/vcollab/vcti-python-tree-exporter
+Project-URL: Changelog, https://github.com/vcollab/vcti-python-tree-exporter/blob/main/CHANGELOG.md
+Keywords: tree,export,serialization,exporter,protocol,registry,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>=1.1.0
+Requires-Dist: vcti-datanode>=2.0.0
+Requires-Dist: vcti-plugin-catalog>=1.0.1
+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
+
+# Tree Exporter
+
+Format-agnostic exporters for vcti trees: an `Exporter` protocol and a plugin catalog, with per-format writers as plugins.
+
+`vcti-tree-exporter` defines *what an exporter is* and *how to catalogue and
+look one up*. It implements no file format itself — concrete writers (HDF5,
+JSON, CSV, NumPy, …) live in separate plugin packages and are registered by the
+consumer. The thing being exported is 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 (data + attributes), so one tree can be written to any registered
+format without the producer knowing about serialization.
+
+Cataloguing and lookup are built on
+[`vcti-plugin-catalog`](https://github.com/vcollab/vcti-python-plugin-catalog)
+(`Descriptor` + `Registry`).
+
+## Installation
+
+```bash
+pip install vcti-tree-exporter
+```
+
+The base package is intentionally small. Install a format plugin for each
+format you need:
+
+```bash
+pip install vcti-tree-exporter-hdf5    # single .h5 file
+pip install vcti-tree-exporter-json    # single .json document
+pip install vcti-tree-exporter-npz     # single .npz archive
+pip install vcti-tree-exporter-csv     # directory tree of CSV tables
+```
+
+## Core concepts
+
+| Piece | Role |
+|---|---|
+| `Exporter` | Structural protocol — a single `export(tree, path, *, overwrite=False)` method. Pure behavior; format name and extension are **not** on the exporter. |
+| `ExporterDescriptor` | A `vcti-plugin-catalog` `Descriptor[Exporter]`: the exporter is its `instance`; `format`, `extension`, and any other metadata are filterable `attributes`. |
+| `get_exporter_descriptor()` | Factory each plugin package provides, returning its `ExporterDescriptor`. |
+| `build_registry(descriptors)` | Build a plugin-catalog `Registry` from those descriptors. |
+| `get_exporter(registry, id)` | Resolve an exporter instance by descriptor id. |
+
+## Quick Start
+
+Register the descriptors your application uses, then resolve one and write a
+tree:
+
+```python
+from pathlib import Path
+from vcti.treeexporter import build_registry, get_exporter
+from vcti.treeexporter_hdf5 import get_exporter_descriptor as hdf5_descriptor
+from vcti.treeexporter_json import get_exporter_descriptor as json_descriptor
+
+registry = build_registry([hdf5_descriptor(), json_descriptor()])
+get_exporter(registry, "hdf5").export(tree, Path("model.h5"), overwrite=True)
+```
+
+`registry` is an ordinary `vcti.plugincatalog.Registry`, so the general way to
+select an exporter is to filter by attributes, then use the matching id — the
+same pattern as the rest of the ecosystem:
+
+```python
+from vcti.lookup import Rule
+from vcti.treeexporter import EXTENSION_ATTR
+
+(desc,) = registry.lookup.filter([Rule(EXTENSION_ATTR, "==", ".h5")])
+desc.exporter.export(tree, Path("model.h5"))
+```
+
+Exporter ids are a small, fixed, well-known set, so using `get_exporter(registry,
+"hdf5")` directly is also fine.
+
+## Writing a format plugin
+
+A plugin's exporter only has to satisfy the protocol — one `export` method, no
+base class — and ship a `get_exporter_descriptor()` factory carrying its
+metadata:
+
+```python
+from pathlib import Path
+from vcti.treeexporter import EXTENSION_ATTR, FORMAT_ATTR, ExporterDescriptor
+
+class JsonExporter:
+    def export(self, tree, path: Path, *, overwrite: bool = False) -> None:
+        ...   # walk the tree (node.name, node.attributes, node.load()), write JSON
+
+def get_exporter_descriptor() -> ExporterDescriptor:
+    return ExporterDescriptor(
+        id="json", name="JSON Exporter", exporter=JsonExporter(),
+        attributes={FORMAT_ATTR: "json", EXTENSION_ATTR: ".json"},
+    )
+```
+
+Ship it in its own package (with its own format dependencies, e.g. `h5py` for
+HDF5). The consuming application decides which descriptors to register — there
+is no implicit global discovery.
+
+## Dependencies
+
+- [vcti-tree](https://github.com/vcollab/vcti-python-tree) — the tree protocols the exporter reads.
+- [vcti-datanode](https://github.com/vcollab/vcti-python-datanode) — the node payload type.
+- [vcti-plugin-catalog](https://github.com/vcollab/vcti-python-plugin-catalog) — the `Descriptor` / `Registry` catalog.
+
+(No heavy/runtime format dependencies live here — those belong to the per-format plugin packages.)

vcti_tree_exporter-1.0.0/README.md

@@ -0,0 +1,105 @@
+# Tree Exporter
+
+Format-agnostic exporters for vcti trees: an `Exporter` protocol and a plugin catalog, with per-format writers as plugins.
+
+`vcti-tree-exporter` defines *what an exporter is* and *how to catalogue and
+look one up*. It implements no file format itself — concrete writers (HDF5,
+JSON, CSV, NumPy, …) live in separate plugin packages and are registered by the
+consumer. The thing being exported is 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 (data + attributes), so one tree can be written to any registered
+format without the producer knowing about serialization.
+
+Cataloguing and lookup are built on
+[`vcti-plugin-catalog`](https://github.com/vcollab/vcti-python-plugin-catalog)
+(`Descriptor` + `Registry`).
+
+## Installation
+
+```bash
+pip install vcti-tree-exporter
+```
+
+The base package is intentionally small. Install a format plugin for each
+format you need:
+
+```bash
+pip install vcti-tree-exporter-hdf5    # single .h5 file
+pip install vcti-tree-exporter-json    # single .json document
+pip install vcti-tree-exporter-npz     # single .npz archive
+pip install vcti-tree-exporter-csv     # directory tree of CSV tables
+```
+
+## Core concepts
+
+| Piece | Role |
+|---|---|
+| `Exporter` | Structural protocol — a single `export(tree, path, *, overwrite=False)` method. Pure behavior; format name and extension are **not** on the exporter. |
+| `ExporterDescriptor` | A `vcti-plugin-catalog` `Descriptor[Exporter]`: the exporter is its `instance`; `format`, `extension`, and any other metadata are filterable `attributes`. |
+| `get_exporter_descriptor()` | Factory each plugin package provides, returning its `ExporterDescriptor`. |
+| `build_registry(descriptors)` | Build a plugin-catalog `Registry` from those descriptors. |
+| `get_exporter(registry, id)` | Resolve an exporter instance by descriptor id. |
+
+## Quick Start
+
+Register the descriptors your application uses, then resolve one and write a
+tree:
+
+```python
+from pathlib import Path
+from vcti.treeexporter import build_registry, get_exporter
+from vcti.treeexporter_hdf5 import get_exporter_descriptor as hdf5_descriptor
+from vcti.treeexporter_json import get_exporter_descriptor as json_descriptor
+
+registry = build_registry([hdf5_descriptor(), json_descriptor()])
+get_exporter(registry, "hdf5").export(tree, Path("model.h5"), overwrite=True)
+```
+
+`registry` is an ordinary `vcti.plugincatalog.Registry`, so the general way to
+select an exporter is to filter by attributes, then use the matching id — the
+same pattern as the rest of the ecosystem:
+
+```python
+from vcti.lookup import Rule
+from vcti.treeexporter import EXTENSION_ATTR
+
+(desc,) = registry.lookup.filter([Rule(EXTENSION_ATTR, "==", ".h5")])
+desc.exporter.export(tree, Path("model.h5"))
+```
+
+Exporter ids are a small, fixed, well-known set, so using `get_exporter(registry,
+"hdf5")` directly is also fine.
+
+## Writing a format plugin
+
+A plugin's exporter only has to satisfy the protocol — one `export` method, no
+base class — and ship a `get_exporter_descriptor()` factory carrying its
+metadata:
+
+```python
+from pathlib import Path
+from vcti.treeexporter import EXTENSION_ATTR, FORMAT_ATTR, ExporterDescriptor
+
+class JsonExporter:
+    def export(self, tree, path: Path, *, overwrite: bool = False) -> None:
+        ...   # walk the tree (node.name, node.attributes, node.load()), write JSON
+
+def get_exporter_descriptor() -> ExporterDescriptor:
+    return ExporterDescriptor(
+        id="json", name="JSON Exporter", exporter=JsonExporter(),
+        attributes={FORMAT_ATTR: "json", EXTENSION_ATTR: ".json"},
+    )
+```
+
+Ship it in its own package (with its own format dependencies, e.g. `h5py` for
+HDF5). The consuming application decides which descriptors to register — there
+is no implicit global discovery.
+
+## Dependencies
+
+- [vcti-tree](https://github.com/vcollab/vcti-python-tree) — the tree protocols the exporter reads.
+- [vcti-datanode](https://github.com/vcollab/vcti-python-datanode) — the node payload type.
+- [vcti-plugin-catalog](https://github.com/vcollab/vcti-python-plugin-catalog) — the `Descriptor` / `Registry` catalog.
+
+(No heavy/runtime format dependencies live here — those belong to the per-format plugin packages.)

vcti_tree_exporter-1.0.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-tree-exporter"
+version = "1.0.0"
+description = "Format-agnostic exporters for vcti trees: an Exporter protocol and registry, with per-format writers as plugins."
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+requires-python = ">=3.12,<3.15"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+keywords = ["tree", "export", "serialization", "exporter", "protocol", "registry", "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>=1.1.0",
+    "vcti-datanode>=2.0.0",
+    "vcti-plugin-catalog>=1.0.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/vcollab/vcti-python-tree-exporter"
+Repository = "https://github.com/vcollab/vcti-python-tree-exporter"
+Changelog = "https://github.com/vcollab/vcti-python-tree-exporter/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.treeexporter", "vcti.treeexporter.*"]
+
+[tool.setuptools.package-data]
+"vcti.treeexporter" = ["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.treeexporter --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-1.0.0/setup.cfg

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

vcti_tree_exporter-1.0.0/src/vcti/treeexporter/__init__.py

@@ -0,0 +1,46 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.treeexporter — format-agnostic exporters for vcti trees.
+
+Defines the :class:`Exporter` protocol — the contract a per-format writer
+satisfies to serialize a ``vcti.tree`` tree of ``vcti.datanode.DataNode``
+payloads — and the plugin-catalog integration for cataloguing exporters.
+Concrete writers (HDF5, JSON, CSV, NumPy, …) ship as separate plugin packages,
+each providing an :class:`ExporterDescriptor` through a
+``get_exporter_descriptor()`` factory; a consumer registers the ones it needs
+with :func:`build_registry` and resolves one by id with :func:`get_exporter` or
+by attribute lookup over the registry.
+"""
+
+from importlib.metadata import version
+
+from vcti.plugincatalog import DuplicateEntryError, EntryNotFoundError, RegistryError
+
+from .exceptions import ExportError, UnrepresentableNodeError
+from .protocol import Exporter
+from .registry import (
+    EXTENSION_ATTR,
+    FORMAT_ATTR,
+    ExporterDescriptor,
+    ExporterRegistry,
+    build_registry,
+    get_exporter,
+)
+
+__version__ = version("vcti-tree-exporter")
+
+__all__ = [
+    "EXTENSION_ATTR",
+    "FORMAT_ATTR",
+    "DuplicateEntryError",
+    "EntryNotFoundError",
+    "ExportError",
+    "Exporter",
+    "ExporterDescriptor",
+    "ExporterRegistry",
+    "RegistryError",
+    "UnrepresentableNodeError",
+    "__version__",
+    "build_registry",
+    "get_exporter",
+]

vcti_tree_exporter-1.0.0/src/vcti/treeexporter/exceptions.py

@@ -0,0 +1,28 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Exceptions raised while exporting a tree.
+
+These types are part of the :class:`~vcti.treeexporter.protocol.Exporter`
+contract: a conforming exporter signals export-time failures with
+:class:`ExportError` or a subclass, so a caller can ``except ExportError`` to
+handle any exporter failure regardless of which format plugin produced it.
+
+Built-in errors that are not export-specific are left as-is — e.g. ``export``
+raises the standard ``FileExistsError`` when the destination already exists and
+``overwrite`` is false.
+"""
+
+from __future__ import annotations
+
+
+class ExportError(Exception):
+    """Base class for any failure while exporting a tree."""
+
+
+class UnrepresentableNodeError(ExportError):
+    """A node's shape cannot be expressed in the target format.
+
+    Raised when an exporter meets a node the format has no way to represent —
+    for example an HDF5 group that would have to carry both child nodes and
+    array data.
+    """

vcti_tree_exporter-1.0.0/src/vcti/treeexporter/protocol.py

@@ -0,0 +1,62 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""The ``Exporter`` protocol — the contract every format writer satisfies.
+
+An exporter serializes a tree to exactly one output format. The tree is any
+``vcti.tree`` tree (e.g. ``DictTree``) whose node payloads are
+``vcti.datanode.DataNode`` — a node's structural identity lives in
+``node.intrinsic`` (notably ``name``), its free-form metadata in
+``node.attributes``, and its optional array behind ``node.data`` /
+``node.load()``. Concrete exporters live in separate per-format plugin packages
+(HDF5, JSON, CSV, NumPy, …) and are catalogued as
+:class:`~vcti.treeexporter.registry.ExporterDescriptor`.
+
+The protocol is structural (PEP 544) — an exporter need only provide an
+``export`` method; it does not have to inherit from anything. Format identity
+and metadata (format name, default extension, …) are recorded on the exporter's
+:class:`~vcti.treeexporter.registry.ExporterDescriptor`, not on the exporter
+instance, so they are discoverable through the registry's attribute lookup.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from vcti.datanode import DataNode
+    from vcti.tree import ReadOnlyTree
+
+
+@runtime_checkable
+class Exporter(Protocol):
+    """Serialize a tree of ``DataNode`` payloads to one output format.
+
+    An exporter is pure behavior: a single :meth:`export` method. Its format
+    name, default extension, and any other metadata are recorded on its
+    :class:`~vcti.treeexporter.registry.ExporterDescriptor` and resolved
+    through the registry — they are not read off the exporter instance.
+    """
+
+    def export(
+        self,
+        tree: ReadOnlyTree[DataNode, Any],
+        path: Path,
+        *,
+        overwrite: bool = False,
+    ) -> None:
+        """Write ``tree`` to ``path``.
+
+        Args:
+            tree: The tree to serialize (read-only access is sufficient).
+            path: Destination file or directory path.
+            overwrite: If ``False`` and ``path`` already exists, raise
+                ``FileExistsError`` rather than replacing it.
+
+        Raises:
+            FileExistsError: ``path`` exists and ``overwrite`` is ``False``.
+            ExportError: The tree cannot be written — e.g.
+                :class:`~vcti.treeexporter.exceptions.UnrepresentableNodeError`
+                for a node the format cannot represent.
+        """
+        ...

vcti_tree_exporter-1.0.0/src/vcti/treeexporter/registry.py

@@ -0,0 +1,99 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Plugin-catalog integration for exporters.
+
+Each exporter is catalogued as an :class:`ExporterDescriptor` — a
+``vcti-plugin-catalog`` ``Descriptor`` whose ``instance`` is the
+:class:`~vcti.treeexporter.protocol.Exporter` and whose ``attributes`` hold the
+filterable metadata (format name, default extension, …). Descriptors are
+collected in an :data:`ExporterRegistry`.
+
+A consumer resolves an exporter either directly by id (:func:`get_exporter`) or
+— the way that generalises to externally-sourced catalogs — by filtering the
+registry's attribute lookup to find the matching id first::
+
+    from vcti.lookup import Rule
+    from vcti.treeexporter import EXTENSION_ATTR
+
+    (desc,) = registry.lookup.filter([Rule(EXTENSION_ATTR, "==", ".h5")])
+    desc.exporter.export(tree, path)
+
+Exporter ids are a small, fixed, internally-controlled set, so using them
+directly is fine; the attribute-lookup path is supported for consistency with
+the rest of the ecosystem.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from vcti.plugincatalog import Descriptor, Registry
+
+from .protocol import Exporter
+
+#: Descriptor-attribute key holding an exporter's format name.
+FORMAT_ATTR = "format"
+
+#: Descriptor-attribute key holding an exporter's default output extension.
+EXTENSION_ATTR = "extension"
+
+
+class ExporterDescriptor(Descriptor[Exporter]):
+    """A plugin-catalog descriptor whose ``instance`` is an :class:`Exporter`.
+
+    Mirrors the ``LoaderDescriptor`` shape: ``instance`` carries the exporter,
+    and ``attributes`` carry the filterable metadata (see :data:`FORMAT_ATTR`
+    and :data:`EXTENSION_ATTR`). :attr:`exporter` is a readable alias for
+    ``instance``.
+    """
+
+    def __init__(
+        self,
+        id: str,
+        name: str,
+        exporter: Exporter,
+        description: str | None = None,
+        attributes: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(
+            id=id,
+            name=name,
+            instance=exporter,
+            description=description,
+            attributes=attributes,
+        )
+
+    @property
+    def exporter(self) -> Exporter:
+        """The exporter instance."""
+        return self.instance
+
+    def __repr__(self) -> str:
+        return f"<ExporterDescriptor id={self.id!r} name={self.name!r}>"
+
+
+#: A plugin-catalog registry of exporter descriptors.
+ExporterRegistry = Registry[ExporterDescriptor]
+
+
+def build_registry(descriptors: Iterable[ExporterDescriptor]) -> ExporterRegistry:
+    """Build a registry from exporter descriptors.
+
+    Each plugin package provides its descriptor via a ``get_exporter_descriptor()``
+    factory; pass those here. Raises ``vcti.plugincatalog.DuplicateEntryError``
+    if two descriptors share an id.
+    """
+    # plugin-catalog's Registry.__init__ lacks a `-> None` annotation, which
+    # trips mypy's strict no-untyped-call; safe to ignore here.
+    registry: ExporterRegistry = ExporterRegistry()  # type: ignore[no-untyped-call]
+    registry.register_many(descriptors)
+    return registry
+
+
+def get_exporter(registry: ExporterRegistry, exporter_id: str) -> Exporter:
+    """Return the exporter registered under ``exporter_id``.
+
+    Raises ``vcti.plugincatalog.EntryNotFoundError`` if no descriptor matches.
+    """
+    return registry.get(exporter_id).exporter

vcti_tree_exporter-1.0.0/src/vcti_tree_exporter.egg-info/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: vcti-tree-exporter
+Version: 1.0.0
+Summary: Format-agnostic exporters for vcti trees: an Exporter protocol and registry, with per-format writers as plugins.
+Author: Visual Collaboration Technologies Inc.
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/vcollab/vcti-python-tree-exporter
+Project-URL: Repository, https://github.com/vcollab/vcti-python-tree-exporter
+Project-URL: Changelog, https://github.com/vcollab/vcti-python-tree-exporter/blob/main/CHANGELOG.md
+Keywords: tree,export,serialization,exporter,protocol,registry,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>=1.1.0
+Requires-Dist: vcti-datanode>=2.0.0
+Requires-Dist: vcti-plugin-catalog>=1.0.1
+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
+
+# Tree Exporter
+
+Format-agnostic exporters for vcti trees: an `Exporter` protocol and a plugin catalog, with per-format writers as plugins.
+
+`vcti-tree-exporter` defines *what an exporter is* and *how to catalogue and
+look one up*. It implements no file format itself — concrete writers (HDF5,
+JSON, CSV, NumPy, …) live in separate plugin packages and are registered by the
+consumer. The thing being exported is 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 (data + attributes), so one tree can be written to any registered
+format without the producer knowing about serialization.
+
+Cataloguing and lookup are built on
+[`vcti-plugin-catalog`](https://github.com/vcollab/vcti-python-plugin-catalog)
+(`Descriptor` + `Registry`).
+
+## Installation
+
+```bash
+pip install vcti-tree-exporter
+```
+
+The base package is intentionally small. Install a format plugin for each
+format you need:
+
+```bash
+pip install vcti-tree-exporter-hdf5    # single .h5 file
+pip install vcti-tree-exporter-json    # single .json document
+pip install vcti-tree-exporter-npz     # single .npz archive
+pip install vcti-tree-exporter-csv     # directory tree of CSV tables
+```
+
+## Core concepts
+
+| Piece | Role |
+|---|---|
+| `Exporter` | Structural protocol — a single `export(tree, path, *, overwrite=False)` method. Pure behavior; format name and extension are **not** on the exporter. |
+| `ExporterDescriptor` | A `vcti-plugin-catalog` `Descriptor[Exporter]`: the exporter is its `instance`; `format`, `extension`, and any other metadata are filterable `attributes`. |
+| `get_exporter_descriptor()` | Factory each plugin package provides, returning its `ExporterDescriptor`. |
+| `build_registry(descriptors)` | Build a plugin-catalog `Registry` from those descriptors. |
+| `get_exporter(registry, id)` | Resolve an exporter instance by descriptor id. |
+
+## Quick Start
+
+Register the descriptors your application uses, then resolve one and write a
+tree:
+
+```python
+from pathlib import Path
+from vcti.treeexporter import build_registry, get_exporter
+from vcti.treeexporter_hdf5 import get_exporter_descriptor as hdf5_descriptor
+from vcti.treeexporter_json import get_exporter_descriptor as json_descriptor
+
+registry = build_registry([hdf5_descriptor(), json_descriptor()])
+get_exporter(registry, "hdf5").export(tree, Path("model.h5"), overwrite=True)
+```
+
+`registry` is an ordinary `vcti.plugincatalog.Registry`, so the general way to
+select an exporter is to filter by attributes, then use the matching id — the
+same pattern as the rest of the ecosystem:
+
+```python
+from vcti.lookup import Rule
+from vcti.treeexporter import EXTENSION_ATTR
+
+(desc,) = registry.lookup.filter([Rule(EXTENSION_ATTR, "==", ".h5")])
+desc.exporter.export(tree, Path("model.h5"))
+```
+
+Exporter ids are a small, fixed, well-known set, so using `get_exporter(registry,
+"hdf5")` directly is also fine.
+
+## Writing a format plugin
+
+A plugin's exporter only has to satisfy the protocol — one `export` method, no
+base class — and ship a `get_exporter_descriptor()` factory carrying its
+metadata:
+
+```python
+from pathlib import Path
+from vcti.treeexporter import EXTENSION_ATTR, FORMAT_ATTR, ExporterDescriptor
+
+class JsonExporter:
+    def export(self, tree, path: Path, *, overwrite: bool = False) -> None:
+        ...   # walk the tree (node.name, node.attributes, node.load()), write JSON
+
+def get_exporter_descriptor() -> ExporterDescriptor:
+    return ExporterDescriptor(
+        id="json", name="JSON Exporter", exporter=JsonExporter(),
+        attributes={FORMAT_ATTR: "json", EXTENSION_ATTR: ".json"},
+    )
+```
+
+Ship it in its own package (with its own format dependencies, e.g. `h5py` for
+HDF5). The consuming application decides which descriptors to register — there
+is no implicit global discovery.
+
+## Dependencies
+
+- [vcti-tree](https://github.com/vcollab/vcti-python-tree) — the tree protocols the exporter reads.
+- [vcti-datanode](https://github.com/vcollab/vcti-python-datanode) — the node payload type.
+- [vcti-plugin-catalog](https://github.com/vcollab/vcti-python-plugin-catalog) — the `Descriptor` / `Registry` catalog.
+
+(No heavy/runtime format dependencies live here — those belong to the per-format plugin packages.)

vcti_tree_exporter-1.0.0/src/vcti_tree_exporter.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/vcti/treeexporter/__init__.py
+src/vcti/treeexporter/exceptions.py
+src/vcti/treeexporter/protocol.py
+src/vcti/treeexporter/py.typed
+src/vcti/treeexporter/registry.py
+src/vcti_tree_exporter.egg-info/PKG-INFO
+src/vcti_tree_exporter.egg-info/SOURCES.txt
+src/vcti_tree_exporter.egg-info/dependency_links.txt
+src/vcti_tree_exporter.egg-info/requires.txt
+src/vcti_tree_exporter.egg-info/top_level.txt
+src/vcti_tree_exporter.egg-info/zip-safe
+tests/test_registry.py
+tests/test_version.py

vcti_tree_exporter-1.0.0/src/vcti_tree_exporter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vcti_tree_exporter-1.0.0/src/vcti_tree_exporter.egg-info/requires.txt

@@ -0,0 +1,13 @@
+vcti-tree>=1.1.0
+vcti-datanode>=2.0.0
+vcti-plugin-catalog>=1.0.1
+
+[lint]
+ruff
+
+[test]
+pytest
+pytest-cov
+
+[typecheck]
+mypy

vcti_tree_exporter-1.0.0/src/vcti_tree_exporter.egg-info/top_level.txt

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

vcti_tree_exporter-1.0.0/src/vcti_tree_exporter.egg-info/zip-safe

@@ -0,0 +1 @@
+

vcti_tree_exporter-1.0.0/tests/test_registry.py

@@ -0,0 +1,128 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Tests for the Exporter protocol and the plugin-catalog integration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from vcti.lookup import Rule
+from vcti.plugincatalog import DuplicateEntryError, EntryNotFoundError
+
+from vcti.treeexporter import (
+    EXTENSION_ATTR,
+    FORMAT_ATTR,
+    Exporter,
+    ExporterDescriptor,
+    ExportError,
+    UnrepresentableNodeError,
+    build_registry,
+    get_exporter,
+)
+
+
+class _FakeExporter:
+    """A minimal structural Exporter for testing — pure behavior."""
+
+    def __init__(self) -> None:
+        self.calls: list[tuple] = []
+
+    def export(self, tree, path, *, overwrite: bool = False) -> None:
+        self.calls.append((tree, Path(path), overwrite))
+
+
+def _descriptor(exporter_id: str, fmt: str, extension: str, **attrs: object) -> ExporterDescriptor:
+    return ExporterDescriptor(
+        id=exporter_id,
+        name=exporter_id,
+        exporter=_FakeExporter(),
+        attributes={FORMAT_ATTR: fmt, EXTENSION_ATTR: extension, **attrs},
+    )
+
+
+def test_fake_satisfies_protocol():
+    assert isinstance(_FakeExporter(), Exporter)
+
+
+def test_object_missing_export_fails_protocol():
+    class NotAnExporter:
+        pass
+
+    assert not isinstance(NotAnExporter(), Exporter)
+
+
+def test_descriptor_exposes_exporter_and_attributes():
+    exporter = _FakeExporter()
+    desc = ExporterDescriptor(
+        id="hdf5",
+        name="HDF5",
+        exporter=exporter,
+        description="HDF5 writer",
+        attributes={FORMAT_ATTR: "hdf5", EXTENSION_ATTR: ".h5", "library": "h5py"},
+    )
+
+    assert desc.id == "hdf5"
+    assert desc.name == "HDF5"
+    assert desc.description == "HDF5 writer"
+    assert desc.exporter is exporter
+    assert desc.instance is exporter
+    assert desc.attributes[FORMAT_ATTR] == "hdf5"
+    assert desc.attributes[EXTENSION_ATTR] == ".h5"
+    assert desc.attributes["library"] == "h5py"
+
+
+def test_descriptor_repr_includes_id():
+    assert "hdf5" in repr(_descriptor("hdf5", "hdf5", ".h5"))
+
+
+def test_build_registry_and_resolve_by_id():
+    registry = build_registry(
+        [_descriptor("json", "json", ".json"), _descriptor("csv", "csv", "")]
+    )
+
+    assert set(registry.ids()) == {"json", "csv"}
+    assert get_exporter(registry, "json") is registry.get("json").exporter
+    assert registry.get("csv").attributes[EXTENSION_ATTR] == ""
+
+
+def test_lookup_by_extension_attribute():
+    registry = build_registry(
+        [_descriptor("hdf5", "hdf5", ".h5"), _descriptor("json", "json", ".json")]
+    )
+
+    matches = registry.lookup.filter([Rule(EXTENSION_ATTR, "==", ".h5")])
+    assert [d.id for d in matches] == ["hdf5"]
+
+
+def test_lookup_by_format_attribute_then_use_id():
+    registry = build_registry([_descriptor("hdf5", "hdf5", ".h5")])
+
+    (match,) = registry.lookup.filter([Rule(FORMAT_ATTR, "==", "hdf5")])
+    assert get_exporter(registry, match.id) is match.exporter
+
+
+def test_get_unknown_id_raises():
+    registry = build_registry([_descriptor("json", "json", ".json")])
+    with pytest.raises(EntryNotFoundError):
+        get_exporter(registry, "nope")
+
+
+def test_duplicate_id_raises():
+    with pytest.raises(DuplicateEntryError):
+        build_registry(
+            [_descriptor("json", "json", ".json"), _descriptor("json", "json", ".json")]
+        )
+
+
+def test_exception_hierarchy():
+    assert issubclass(UnrepresentableNodeError, ExportError)
+    assert issubclass(ExportError, Exception)
+    # not a ValueError — callers catch ExportError, not a broad builtin
+    assert not issubclass(ExportError, ValueError)
+
+
+def test_export_signature_round_trips():
+    exporter = _FakeExporter()
+    exporter.export("TREE", Path("out.json"), overwrite=True)
+    assert exporter.calls == [("TREE", Path("out.json"), True)]

vcti_tree_exporter-1.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."""
+
+import re
+
+import vcti.treeexporter
+
+
+class TestVersion:
+    def test_version_exists(self):
+        assert hasattr(vcti.treeexporter, "__version__")
+
+    def test_version_is_valid_semver(self):
+        assert re.match(r"^\d+\.\d+\.\d+", vcti.treeexporter.__version__)