nx-ladybug 0.1.0__tar.gz

nx_ladybug-0.1.0/LICENSE

@@ -0,0 +1,65 @@
+nx-arrow is distributed under the terms of either the MIT license or the
+3-clause BSD license, at your option (SPDX: BSD-3-Clause OR MIT).
+
+MIT License
+
+Copyright (c) 2025-2026 Ladybug Memory Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Portions of this software are derived from NetworkX
+(https://networkx.org/) and remain under its 3-clause BSD license:
+
+::
+
+   Copyright (c) 2004-2026, NetworkX Developers
+   Aric Hagberg <hagberg@lanl.gov>
+   Dan Schult <dschult@colgate.edu>
+   Pieter Swart <swart@lanl.gov>
+   All rights reserved.
+
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions are
+   met:
+
+     * Redistributions of source code must retain the above copyright
+       notice, this list of conditions and the following disclaimer.
+
+     * Redistributions in binary form must reproduce the above
+       copyright notice, this list of conditions and the following
+       disclaimer in the documentation and/or other materials provided
+       with the distribution.
+
+     * Neither the name of the NetworkX Developers nor the names of its
+       contributors may be used to endorse or promote products derived
+       from this software without specific prior written permission.
+
+   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nx_ladybug-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: nx-ladybug
+Version: 0.1.0
+Summary: LadybugDB storage provider for nx-arrow columnar graphs
+License-Expression: BSD-3-Clause OR MIT
+Project-URL: Homepage, https://github.com/Ladybug-Memory/nx-ladybug
+Project-URL: Source Code, https://github.com/Ladybug-Memory/nx-ladybug
+Keywords: networks,graph theory,apache arrow,networkx,columnar,ladybugdb
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nx-arrow>=0.1.0
+Requires-Dist: ladybug>=0.20
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# nx-ladybug
+
+LadybugDB storage provider for
+[nx-arrow](https://github.com/Ladybug-Memory/nx-arrow) columnar graphs.
+`nx-arrow` owns the Arrow-backed graph and the `arrow` NetworkX backend;
+this package only adds persistence into
+[LadybugDB](https://ladybugdb.com/). Build and analyze graphs with
+`nx-arrow` everywhere — the only `nxladybug` import is the persist step.
+
+## Install
+
+```bash
+pip install nx-arrow nx-ladybug
+```
+
+For development:
+
+```bash
+pip install -e ".[test]"
+```
+
+## Use
+
+```python
+import networkx as nx
+from nxladybug import LadybugStorageProvider, persist
+
+g = nx.DiGraph([(0, 1), (1, 2)], backend="arrow")
+
+nx.out_degree_centrality(g, backend="arrow")
+list(nx.topological_sort(g, backend="arrow"))
+```
+
+## Persist
+
+`persist()` bulk-loads per-type frames through a storage provider — pick
+LadybugDB or Parquet:
+
+```python
+from nxarrow.parquet import ParquetStorageProvider
+from nxladybug import LadybugStorageProvider, persist
+
+# LadybugDB: one unified node table (NxNode) + one relationship table
+# (NxEdge) + a meta table (NxMeta). Each frame is registered as an Arrow
+# staging table and bulk-copied natively — COPY <table> FROM (MATCH ...) —
+# so endpoints resolve through the node primary key inside the copy.
+provider = LadybugStorageProvider("graph.lbdb")  # or ":memory:"
+persist(g, provider, graph_attrs=g.graph)
+restored = provider.load_graph()  # full round-trip
+
+# ... or Parquet: one file per type plus a manifest.json
+parquet = ParquetStorageProvider("graph_store")
+persist(g, parquet, graph_attrs=g.graph)
+restored = parquet.load_graph()
+```
+
+The Ladybug provider drops and recreates its tables on every persist, so
+re-persisting a smaller graph leaves no stale rows. `:memory:` databases
+live as long as the provider; file paths reopen with
+`LadybugStorageProvider.load(path)`.
+
+Custom stores implement `store_nodes(frames)` / `store_edges(frames)` and
+register with `nxarrow.register_storage_provider`.
+
+## Develop
+
+```bash
+pytest
+```

nx_ladybug-0.1.0/README.md

@@ -0,0 +1,69 @@
+# nx-ladybug
+
+LadybugDB storage provider for
+[nx-arrow](https://github.com/Ladybug-Memory/nx-arrow) columnar graphs.
+`nx-arrow` owns the Arrow-backed graph and the `arrow` NetworkX backend;
+this package only adds persistence into
+[LadybugDB](https://ladybugdb.com/). Build and analyze graphs with
+`nx-arrow` everywhere — the only `nxladybug` import is the persist step.
+
+## Install
+
+```bash
+pip install nx-arrow nx-ladybug
+```
+
+For development:
+
+```bash
+pip install -e ".[test]"
+```
+
+## Use
+
+```python
+import networkx as nx
+from nxladybug import LadybugStorageProvider, persist
+
+g = nx.DiGraph([(0, 1), (1, 2)], backend="arrow")
+
+nx.out_degree_centrality(g, backend="arrow")
+list(nx.topological_sort(g, backend="arrow"))
+```
+
+## Persist
+
+`persist()` bulk-loads per-type frames through a storage provider — pick
+LadybugDB or Parquet:
+
+```python
+from nxarrow.parquet import ParquetStorageProvider
+from nxladybug import LadybugStorageProvider, persist
+
+# LadybugDB: one unified node table (NxNode) + one relationship table
+# (NxEdge) + a meta table (NxMeta). Each frame is registered as an Arrow
+# staging table and bulk-copied natively — COPY <table> FROM (MATCH ...) —
+# so endpoints resolve through the node primary key inside the copy.
+provider = LadybugStorageProvider("graph.lbdb")  # or ":memory:"
+persist(g, provider, graph_attrs=g.graph)
+restored = provider.load_graph()  # full round-trip
+
+# ... or Parquet: one file per type plus a manifest.json
+parquet = ParquetStorageProvider("graph_store")
+persist(g, parquet, graph_attrs=g.graph)
+restored = parquet.load_graph()
+```
+
+The Ladybug provider drops and recreates its tables on every persist, so
+re-persisting a smaller graph leaves no stale rows. `:memory:` databases
+live as long as the provider; file paths reopen with
+`LadybugStorageProvider.load(path)`.
+
+Custom stores implement `store_nodes(frames)` / `store_edges(frames)` and
+register with `nxarrow.register_storage_provider`.
+
+## Develop
+
+```bash
+pytest
+```

nx_ladybug-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = ["setuptools>=77"]
+
+[project]
+name = "nx-ladybug"
+version = "0.1.0"
+description = "LadybugDB storage provider for nx-arrow columnar graphs"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "BSD-3-Clause OR MIT"
+keywords = ["networks", "graph theory", "apache arrow", "networkx", "columnar", "ladybugdb"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "nx-arrow>=0.1.0",
+    "ladybug>=0.20",
+]
+
+[project.urls]
+Homepage = "https://github.com/Ladybug-Memory/nx-ladybug"
+"Source Code" = "https://github.com/Ladybug-Memory/nx-ladybug"
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nx_ladybug-0.1.0/setup.cfg

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

nx_ladybug-0.1.0/src/nx_ladybug.egg-info/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: nx-ladybug
+Version: 0.1.0
+Summary: LadybugDB storage provider for nx-arrow columnar graphs
+License-Expression: BSD-3-Clause OR MIT
+Project-URL: Homepage, https://github.com/Ladybug-Memory/nx-ladybug
+Project-URL: Source Code, https://github.com/Ladybug-Memory/nx-ladybug
+Keywords: networks,graph theory,apache arrow,networkx,columnar,ladybugdb
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nx-arrow>=0.1.0
+Requires-Dist: ladybug>=0.20
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# nx-ladybug
+
+LadybugDB storage provider for
+[nx-arrow](https://github.com/Ladybug-Memory/nx-arrow) columnar graphs.
+`nx-arrow` owns the Arrow-backed graph and the `arrow` NetworkX backend;
+this package only adds persistence into
+[LadybugDB](https://ladybugdb.com/). Build and analyze graphs with
+`nx-arrow` everywhere — the only `nxladybug` import is the persist step.
+
+## Install
+
+```bash
+pip install nx-arrow nx-ladybug
+```
+
+For development:
+
+```bash
+pip install -e ".[test]"
+```
+
+## Use
+
+```python
+import networkx as nx
+from nxladybug import LadybugStorageProvider, persist
+
+g = nx.DiGraph([(0, 1), (1, 2)], backend="arrow")
+
+nx.out_degree_centrality(g, backend="arrow")
+list(nx.topological_sort(g, backend="arrow"))
+```
+
+## Persist
+
+`persist()` bulk-loads per-type frames through a storage provider — pick
+LadybugDB or Parquet:
+
+```python
+from nxarrow.parquet import ParquetStorageProvider
+from nxladybug import LadybugStorageProvider, persist
+
+# LadybugDB: one unified node table (NxNode) + one relationship table
+# (NxEdge) + a meta table (NxMeta). Each frame is registered as an Arrow
+# staging table and bulk-copied natively — COPY <table> FROM (MATCH ...) —
+# so endpoints resolve through the node primary key inside the copy.
+provider = LadybugStorageProvider("graph.lbdb")  # or ":memory:"
+persist(g, provider, graph_attrs=g.graph)
+restored = provider.load_graph()  # full round-trip
+
+# ... or Parquet: one file per type plus a manifest.json
+parquet = ParquetStorageProvider("graph_store")
+persist(g, parquet, graph_attrs=g.graph)
+restored = parquet.load_graph()
+```
+
+The Ladybug provider drops and recreates its tables on every persist, so
+re-persisting a smaller graph leaves no stale rows. `:memory:` databases
+live as long as the provider; file paths reopen with
+`LadybugStorageProvider.load(path)`.
+
+Custom stores implement `store_nodes(frames)` / `store_edges(frames)` and
+register with `nxarrow.register_storage_provider`.
+
+## Develop
+
+```bash
+pytest
+```

nx_ladybug-0.1.0/src/nx_ladybug.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/nx_ladybug.egg-info/PKG-INFO
+src/nx_ladybug.egg-info/SOURCES.txt
+src/nx_ladybug.egg-info/dependency_links.txt
+src/nx_ladybug.egg-info/requires.txt
+src/nx_ladybug.egg-info/top_level.txt
+src/nxladybug/__init__.py
+src/nxladybug/ladybug_store.py
+tests/test_persist.py

nx_ladybug-0.1.0/src/nx_ladybug.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nx_ladybug-0.1.0/src/nx_ladybug.egg-info/requires.txt

@@ -0,0 +1,5 @@
+nx-arrow>=0.1.0
+ladybug>=0.20
+
+[test]
+pytest

nx_ladybug-0.1.0/src/nx_ladybug.egg-info/top_level.txt

@@ -0,0 +1 @@
+nxladybug

nx_ladybug-0.1.0/src/nxladybug/__init__.py

@@ -0,0 +1,33 @@
+"""LadybugDB storage provider for :mod:`nxarrow` columnar graphs.
+
+``nx-arrow`` owns the Arrow-backed graph and the ``arrow`` NetworkX
+backend; this package only adds persistence into LadybugDB. Build graphs
+the usual way and choose a store at :func:`persist` time::
+
+    import networkx as nx
+    from nxarrow.parquet import ParquetStorageProvider
+    from nxladybug import LadybugStorageProvider, persist
+
+    g = nx.DiGraph([(0, 1), (1, 2)], backend="arrow")
+    persist(g, LadybugStorageProvider("graph.lbdb"), graph_attrs=g.graph)
+    # ... or persist(g, ParquetStorageProvider("store"), graph_attrs=g.graph)
+"""
+
+from nxarrow.backend import (
+    get_storage_provider,
+    list_storage_providers,
+    persist,
+    register_storage_provider,
+    unregister_storage_provider,
+)
+
+from .ladybug_store import LadybugStorageProvider
+
+__all__ = [
+    "LadybugStorageProvider",
+    "persist",
+    "register_storage_provider",
+    "unregister_storage_provider",
+    "get_storage_provider",
+    "list_storage_providers",
+]

nx_ladybug-0.1.0/src/nxladybug/ladybug_store.py

@@ -0,0 +1,419 @@
+"""LadybugDB storage provider for arrow-backed graphs.
+
+Persists the per-type ``pyarrow.Table`` frames handed over by
+:func:`nxarrow.backend.persist` into a LadybugDB database with one
+unified node table and one unified relationship table::
+
+    NxNode(node, <attrs...>, node_type, _nx_order)
+    NxEdge(FROM NxNode TO NxNode, <attrs...>, edge_type, _nx_order)
+    NxMeta(key, value)   # JSON-encoded graph-level attributes
+
+Table names are configurable at construction. Every persist drops and
+recreates the tables, so re-persisting a smaller graph leaves no stale
+rows behind.
+
+Each frame is bulk-loaded in two steps — Arrow memory registration into
+a staging table, then a native bulk copy:
+
+.. code-block:: python
+
+    conn.create_arrow_table(stage, frame)          # register Arrow memory
+    conn.execute(f"COPY NxNode FROM "             # bulk copy out of it
+                 f"(MATCH (s:`{stage}`) RETURN s.`node`, ...)")
+
+Column mapping is positional (staging ``RETURN`` order matches the
+stored column order), mirroring the ``COPY <table> FROM $df`` convention
+used by the LDBC bulk loader. Endpoints resolve through the node primary
+key inside ``COPY``. Empty frames are skipped; a graph with no nodes or
+no edges simply leaves that table out (loads treat a missing table as
+empty).
+
+Round-trip::
+
+    provider = LadybugStorageProvider(":memory:")
+    persist(graph, provider, graph_attrs=graph.graph)
+    restored = provider.load_graph()
+
+``load_graph`` reads the tables back with ``MATCH ... RETURN`` (ordered
+by the internal sequence column, which is then dropped) and rebuilds an
+``ArrowDiGraph`` via :meth:`ArrowDiGraph.from_arrow`, so the restored
+graph compares equal to the persisted one.
+
+Fidelity notes. First, Arrow types map to Ladybug types: all integers to
+``INT64``, floats to ``DOUBLE``, booleans to ``BOOL``, strings to
+``STRING``, dates to ``DATE`` and timestamps to ``TIMESTAMP``; anything
+else (times, durations, binaries, nested types, ...) is cast to
+``STRING`` before the copy, which stringifies time keys in particular.
+Second, the node key column (``node``) becomes the Ladybug primary key,
+so key values must be unique, as they always are in a graph. Third,
+``graph_attrs`` must be JSON-serializable; it is forwarded through
+:func:`persist` keyword arguments and stored as one JSON document in the
+meta table. Fourth, ``_nx_order`` is a reserved column name used for the
+internal insertion sequence; graphs using it as an attribute are refused
+with a clear error.
+"""
+
+import json
+import uuid
+
+import pyarrow as pa
+
+from nxarrow.graph import ArrowDiGraph
+
+__all__ = ["LadybugStorageProvider"]
+
+DEFAULT_NODE_TABLE = "NxNode"
+DEFAULT_EDGE_TABLE = "NxEdge"
+DEFAULT_META_TABLE = "NxMeta"
+
+#: Reserved column holding the global insertion sequence. Lets loads
+#: restore exact node/edge order via ``ORDER BY`` regardless of storage
+#: order; it is stripped from the adopted tables so it never surfaces as
+#: an attribute.
+ORDER_COL = "_nx_order"
+
+
+def _quote(identifier):
+    """Quote an identifier with backticks (Ladybug escape: double them)."""
+    return "`" + str(identifier).replace("`", "``") + "`"
+
+
+def _literal(value):
+    """Quote a string literal with single quotes (escape: double them)."""
+    return "'" + str(value).replace("'", "''") + "'"
+
+
+def _ladybug_type(dtype):
+    """Map an Arrow type to a Ladybug column type (None: cast to STRING)."""
+    if pa.types.is_dictionary(dtype):
+        return _ladybug_type(dtype.value_type)
+    if pa.types.is_integer(dtype) or pa.types.is_unsigned_integer(dtype):
+        return "INT64"
+    if pa.types.is_floating(dtype):
+        return "DOUBLE"
+    if pa.types.is_boolean(dtype):
+        return "BOOL"
+    if pa.types.is_string(dtype) or pa.types.is_large_string(dtype):
+        return "STRING"
+    if pa.types.is_date(dtype):
+        return "DATE"
+    if pa.types.is_timestamp(dtype):
+        return "TIMESTAMP"
+    return None
+
+
+def _stage_frame(table):
+    """Cast unmapped columns to STRING so every column has a Ladybug type."""
+    names = table.column_names
+    if ORDER_COL in names:
+        raise ValueError(
+            f"attribute name {ORDER_COL!r} is reserved for Ladybug persistence; "
+            "rename the attribute before persisting"
+        )
+    out = table
+    for field in table.schema:
+        if _ladybug_type(field.type) is None:
+            idx = out.schema.get_field_index(field.name)
+            out = out.set_column(
+                idx, field.name, out.column(field.name).cast(pa.string())
+            )
+    return out
+
+
+def _unify(tables):
+    """Concatenate tables with heterogeneous columns, filling gaps with nulls."""
+    if len(tables) == 1:
+        return tables[0]
+    schema = pa.unify_schemas([t.schema for t in tables])
+    return pa.concat_tables([t.cast(schema) for t in tables])
+
+
+class LadybugStorageProvider:
+    """Store per-type Arrow frames in LadybugDB node/relationship tables.
+
+    Parameters
+    ----------
+    db_path:
+        LadybugDB database path, or ``":memory:"`` (default) for a
+        transient database that lives as long as this provider. File
+        paths persist across processes; reopen with
+        :meth:`LadybugStorageProvider.load`.
+    node_table, edge_table, meta_table:
+        Ladybug table names for nodes, edges and the graph-attrs sidecar.
+    """
+
+    def __init__(
+        self,
+        db_path=":memory:",
+        node_table=DEFAULT_NODE_TABLE,
+        edge_table=DEFAULT_EDGE_TABLE,
+        meta_table=DEFAULT_META_TABLE,
+    ):
+        self.db_path = str(db_path)
+        self.node_table = node_table
+        self.edge_table = edge_table
+        self.meta_table = meta_table
+        self._db = None
+        self._conn = None
+
+    # -- connection lifecycle --
+
+    @property
+    def conn(self):
+        """The live Ladybug connection, opened on first use."""
+        if self._conn is None:
+            import ladybug as lb
+
+            self._db = lb.Database(self.db_path)
+            self._conn = lb.Connection(self._db)
+        return self._conn
+
+    def close(self):
+        """Close the connection (and database). The provider is unusable after."""
+        if self._conn is not None:
+            try:
+                self._conn.close()
+            finally:
+                self._conn = None
+        if self._db is not None:
+            try:
+                self._db.close()
+            finally:
+                self._db = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+        return False
+
+    # -- storage provider protocol (see nxarrow.backend.persist) --
+
+    def store_nodes(self, frames, graph_attrs=None, **kwargs):
+        """Bulk-load node frames into the node table. Returns ``{table: rows}``."""
+        rows = [t.num_rows for t in frames.values()]
+        total = sum(rows)
+        conn = self.conn
+        # Drop the edge table first: it references the node table, and both
+        # are rebuilt on every persist so no stale rows survive re-persist.
+        conn.execute(f"DROP TABLE IF EXISTS {_quote(self.edge_table)}")
+        conn.execute(f"DROP TABLE IF EXISTS {_quote(self.node_table)}")
+        if total:
+            unified = _unify([_stage_frame(t) for t in frames.values()])
+            self._create_node_table(unified)
+            offset = 0
+            for table in frames.values():
+                offset = self._copy_node_frame(table, unified.schema, offset)
+        if graph_attrs is not None:
+            self._store_meta(dict(graph_attrs))
+        return {self.node_table: total} if total else {}
+
+    def store_edges(self, frames, graph_attrs=None, **kwargs):
+        """Bulk-load edge frames into the relationship table. Returns ``{table: rows}``."""
+        rows = [t.num_rows for t in frames.values()]
+        total = sum(rows)
+        conn = self.conn
+        conn.execute(f"DROP TABLE IF EXISTS {_quote(self.edge_table)}")
+        if total:
+            self._ensure_node_table_for_edges(frames)
+            unified = _unify([_stage_frame(t) for t in frames.values()])
+            self._create_edge_table(unified)
+            offset = 0
+            for table in frames.values():
+                offset = self._copy_edge_frame(table, unified.schema, offset)
+        if graph_attrs is not None:
+            self._store_meta(dict(graph_attrs))
+        return {self.edge_table: total} if total else {}
+
+    # -- loading --
+
+    def load_graph(self):
+        """Rebuild the persisted graph (tables, types, attrs, graph attrs)."""
+        nodes = self._load_table(self.node_table, endpoint=False)
+        edges = self._load_table(self.edge_table, endpoint=True)
+        graph = ArrowDiGraph.from_arrow(nodes, edges)
+        graph.graph.update(self._load_meta())
+        return graph
+
+    @classmethod
+    def load(cls, db_path, **kwargs):
+        """Open the database at ``db_path`` and rebuild the persisted graph."""
+        return cls(db_path, **kwargs).load_graph()
+
+    # -- DDL --
+
+    def _create_node_table(self, unified):
+        cols = [
+            f"{_quote(f.name)} {_ladybug_type(f.type)}" for f in unified.schema
+        ]
+        cols.append(f"{_quote(ORDER_COL)} INT64")
+        cols.append(f"PRIMARY KEY ({_quote('node')})")
+        self.conn.execute(
+            f"CREATE NODE TABLE {_quote(self.node_table)} ({', '.join(cols)})"
+        )
+
+    def _create_edge_table(self, unified):
+        props = [
+            f"{_quote(f.name)} {_ladybug_type(f.type)}"
+            for f in unified.schema
+            if f.name not in ("source", "target")
+        ]
+        props.append(f"{_quote(ORDER_COL)} INT64")
+        self.conn.execute(
+            f"CREATE REL TABLE {_quote(self.edge_table)} "
+            f"(FROM {_quote(self.node_table)} TO {_quote(self.node_table)}"
+            + (f", {', '.join(props)}" if props else "")
+            + ")"
+        )
+
+    def _ensure_node_table_for_edges(self, frames):
+        """Create a bare node table so a standalone edge store has a TO/FROM target.
+
+        :func:`persist` always stores nodes first, so this only triggers on
+        direct ``store_edges`` calls. The key type is inferred from the
+        ``source`` column of the unified edge frames.
+        """
+        names = {row[0] for row in self._table_names()}
+        if self.node_table in names:
+            return
+        unified = _unify([_stage_frame(t) for t in frames.values()])
+        key_type = _ladybug_type(unified.schema.field("source").type) or "STRING"
+        self.conn.execute(
+            f"CREATE NODE TABLE {_quote(self.node_table)} "
+            f"({_quote('node')} {key_type}, PRIMARY KEY ({_quote('node')}))"
+        )
+
+    # -- COPY --
+
+    def _copy_frame(self, dest_table, dest_cols, frame):
+        """Register ``frame`` as a staging table and bulk-copy it into ``dest_table``.
+
+        Column mapping is positional: the ``RETURN`` list follows
+        ``dest_cols`` order, matching the stored column order.
+        """
+        stage = f"_nx_stage_{uuid.uuid4().hex}"
+        conn = self.conn
+        conn.create_arrow_table(stage, frame)
+        try:
+            aliased = "s"
+            returns = ", ".join(
+                f"{_quote(aliased)}.{_quote(c)}" for c in dest_cols
+            )
+            conn.execute(
+                f"COPY {_quote(dest_table)} FROM "
+                f"(MATCH ({_quote(aliased)}:{_quote(stage)}) RETURN {returns})"
+            )
+        finally:
+            try:
+                conn.drop_arrow_table(stage)
+            except Exception:
+                pass
+
+    def _copy_node_frame(self, table, schema, offset):
+        if table.num_rows == 0:
+            return offset
+        staged = _stage_frame(table.cast(schema))
+        order = pa.array(
+            range(offset, offset + table.num_rows), type=pa.int64()
+        )
+        staged = staged.append_column(ORDER_COL, order)
+        self._copy_frame(self.node_table, [*schema.names, ORDER_COL], staged)
+        return offset + table.num_rows
+
+    def _copy_edge_frame(self, table, schema, offset):
+        if table.num_rows == 0:
+            return offset
+        staged = _stage_frame(table.cast(schema))
+        order = pa.array(
+            range(offset, offset + table.num_rows), type=pa.int64()
+        )
+        staged = staged.append_column(ORDER_COL, order)
+        self._copy_frame(self.edge_table, [*schema.names, ORDER_COL], staged)
+        return offset + table.num_rows
+
+    # -- graph attrs sidecar --
+
+    def _store_meta(self, graph_attrs):
+        import pyarrow as pa
+
+        conn = self.conn
+        conn.execute(f"DROP TABLE IF EXISTS {_quote(self.meta_table)}")
+        conn.execute(
+            f"CREATE NODE TABLE {_quote(self.meta_table)} "
+            f"({_quote('key')} STRING, {_quote('value')} STRING, "
+            f"PRIMARY KEY ({_quote('key')}))"
+        )
+        frame = pa.table(
+            {
+                "key": pa.array(["graph"], type=pa.string()),
+                "value": pa.array(
+                    [json.dumps(graph_attrs)], type=pa.string()
+                ),
+            }
+        )
+        self._copy_frame(self.meta_table, ["key", "value"], frame)
+
+    def _load_meta(self):
+        if self.meta_table not in {row[0] for row in self._table_names()}:
+            return {}
+        result = self.conn.execute(
+            f"MATCH (m:{_quote(self.meta_table)}) "
+            f"WHERE m.{_quote('key')} = 'graph' "
+            f"RETURN m.{_quote('value')} AS {_quote('value')}"
+        ).get_as_arrow()
+        if result.num_rows == 0:
+            return {}
+        return json.loads(result.column("value")[0].as_py())
+
+    # -- reads --
+
+    def _table_names(self):
+        result = self.conn.execute("CALL show_tables() RETURN *").get_as_arrow()
+        return list(
+            zip(result.column("name").to_pylist(), result.column("type").to_pylist())
+        )
+
+    def _table_columns(self, table):
+        """Stored column names of ``table`` in DDL order.
+
+        Relationship endpoints (``FROM``/``TO``) are not listed by
+        ``table_info`` — only real properties are — so no filtering for
+        them is needed.
+        """
+        result = self.conn.execute(
+            f"CALL table_info({_literal(table)}) RETURN *"
+        ).get_as_arrow()
+        return result.column("name").to_pylist()
+
+    def _load_table(self, table, endpoint):
+        if table not in {name for name, _ in self._table_names()}:
+            return None
+        columns = self._table_columns(table)
+        ordered = ORDER_COL in columns
+        if endpoint:
+            node, edge = _quote(self.node_table), _quote(table)
+            src, tgt = _quote("source"), _quote("target")
+            returns = [
+                f"a.{_quote('node')} AS {src}",
+                f"b.{_quote('node')} AS {tgt}",
+            ]
+            returns += [
+                f"e.{_quote(c)} AS {_quote(c)}"
+                for c in columns
+                if c != ORDER_COL
+            ]
+            query = (
+                f"MATCH (a:{node})-[e:{edge}]->(b:{node}) "
+                f"RETURN {', '.join(returns)}"
+            )
+            if ordered:
+                query += f" ORDER BY e.{_quote(ORDER_COL)}"
+        else:
+            returns = [f"n.{_quote(c)} AS {_quote(c)}" for c in columns if c != ORDER_COL]
+            query = f"MATCH (n:{_quote(table)}) RETURN {', '.join(returns)}"
+            if ordered:
+                query += f" ORDER BY n.{_quote(ORDER_COL)}"
+        result = self.conn.execute(query).get_as_arrow()
+        # get_as_arrow may chunk columns; combine for clean tables.
+        return result.combine_chunks() if result.num_columns else None

nx_ladybug-0.1.0/tests/test_persist.py

@@ -0,0 +1,253 @@
+"""Persistence tests: same ``arrow``-backend graphs, parquet or Ladybug store."""
+
+import datetime
+
+import pytest
+
+pa = pytest.importorskip("pyarrow")
+pytest.importorskip("ladybug")
+
+import networkx as nx
+from nxarrow.backend import persist
+from nxarrow.graph import ArrowDiGraph
+from nxarrow.parquet import ParquetStorageProvider
+
+from nxladybug import LadybugStorageProvider
+
+
+@pytest.fixture
+def typed_graph():
+    g = nx.DiGraph(backend="arrow")
+    g.add_node("alice", node_type="user", age=30)
+    g.add_node("bob", node_type="user", age=25)
+    g.add_node("post1", node_type="post", text="hello")
+    g.add_edge("alice", "post1", edge_type="authored")
+    g.add_edge("bob", "post1", edge_type="liked", weight=0.9)
+    g.add_edge("alice", "bob", edge_type="follows")
+    return g
+
+
+def _assert_graphs_equal(original, restored):
+    assert restored.node_types == original.node_types
+    assert restored.edge_types == original.edge_types
+    assert restored.nodes_table().num_rows == original.nodes_table().num_rows
+    assert restored.edges_table().num_rows == original.edges_table().num_rows
+    for node in original.nodes:
+        assert restored.has_node(node)
+        assert restored.node_attrs(node) == original.node_attrs(node)
+    for u, v in original.edges:
+        assert restored.has_edge(u, v)
+        assert restored.edge_attrs(u, v) == original.edge_attrs(u, v)
+    assert restored.graph == original.graph
+
+
+def _row_count(provider, query):
+    return provider.conn.execute(query).get_as_arrow().column(0)[0].as_py()
+
+
+# -- Ladybug store --
+
+
+def test_ladybug_provider_roundtrip(typed_graph):
+    typed_graph.graph["name"] = "roundtrip"
+    provider = LadybugStorageProvider()
+    try:
+        counts = persist(typed_graph, provider, graph_attrs=typed_graph.graph)
+        assert counts == {provider.node_table: 3, provider.edge_table: 3}
+        names = {name for name, _ in provider._table_names()}
+        assert {provider.node_table, provider.edge_table, provider.meta_table} <= names
+
+        restored = provider.load_graph()
+        _assert_graphs_equal(typed_graph, restored)
+        # insertion order survives the round-trip via the sequence column
+        assert restored.nodes == typed_graph.nodes
+        assert restored.edges == typed_graph.edges
+    finally:
+        provider.close()
+
+
+def test_ladybug_provider_roundtrip_untyped_and_empty():
+    provider = LadybugStorageProvider()
+    try:
+        g = nx.DiGraph(backend="arrow")
+        g.add_edge("a", "b", weight=1.5)
+        persist(g, provider)
+        restored = provider.load_graph()
+        _assert_graphs_equal(g, restored)
+        assert restored.nodes_table().column_names == ["node"]
+
+        persist(nx.DiGraph(backend="arrow"), provider)
+        empty = provider.load_graph()
+        assert empty.number_of_nodes() == 0
+        assert empty.number_of_edges() == 0
+    finally:
+        provider.close()
+
+
+def test_ladybug_provider_repersist_drops_stale_rows(typed_graph):
+    provider = LadybugStorageProvider()
+    try:
+        persist(typed_graph, provider)
+        assert _row_count(provider, "MATCH (n:NxNode) RETURN count(*)") == 3
+        assert _row_count(provider, "MATCH ()-[e:NxEdge]->() RETURN count(*)") == 3
+
+        typed_graph.remove_edge("alice", "bob")  # drops the only "follows" edge
+        typed_graph.remove_edge("bob", "post1")  # drops the only "liked" edge
+        persist(typed_graph, provider)
+        assert _row_count(provider, "MATCH ()-[e:NxEdge]->() RETURN count(*)") == 1
+        _assert_graphs_equal(typed_graph, provider.load_graph())
+    finally:
+        provider.close()
+
+
+def test_ladybug_provider_file_backed_reopen(tmp_path, typed_graph):
+    typed_graph.graph["name"] = "file-roundtrip"
+    db_path = tmp_path / "graph.lbdb"
+    provider = LadybugStorageProvider(db_path)
+    persist(typed_graph, provider, graph_attrs=typed_graph.graph)
+    provider.close()
+
+    restored = LadybugStorageProvider.load(db_path)
+    _assert_graphs_equal(typed_graph, restored)
+    assert restored.nodes == typed_graph.nodes
+
+
+def test_ladybug_roundtrip_preserves_int_keys():
+    g = nx.DiGraph(backend="arrow")
+    g.add_edge(0, 1, weight=2.5)
+    g.add_edge(1, 2)
+    provider = LadybugStorageProvider()
+    try:
+        persist(g, provider)
+        restored = provider.load_graph()
+        assert restored.nodes == [0, 1, 2]
+        assert restored.edges == [(0, 1), (1, 2)]
+        assert restored.edge_attrs(0, 1) == {"weight": 2.5}
+        assert restored.nodes_table().schema.field("node").type == pa.int64()
+    finally:
+        provider.close()
+
+
+def test_ladybug_roundtrip_native_key_types():
+    cases = [
+        ([0, 1, 2], pa.int64()),
+        ([0.5, 1.5, 2.5], pa.float64()),
+        (["a", "b", "c"], pa.string()),
+        (
+            [
+                datetime.date(2024, 1, 1),
+                datetime.date(2024, 1, 2),
+                datetime.date(2024, 1, 3),
+            ],
+            pa.date32(),
+        ),
+        (
+            [
+                datetime.datetime(2024, 1, 1, 1, 2),
+                datetime.datetime(2024, 1, 2),
+                datetime.datetime(2024, 1, 3, 4, 5),
+            ],
+            pa.timestamp("us"),
+        ),
+    ]
+    for keys, expected_type in cases:
+        g = nx.DiGraph(backend="arrow")
+        g.add_edge(keys[0], keys[1], weight=1.0)
+        g.add_edge(keys[1], keys[2])
+        provider = LadybugStorageProvider()
+        try:
+            persist(g, provider)
+            restored = provider.load_graph()
+            assert restored.nodes == keys
+            assert restored.edges == [(keys[0], keys[1]), (keys[1], keys[2])]
+            assert restored.edge_attrs(keys[0], keys[1]) == {"weight": 1.0}
+            assert restored.nodes_table().schema.field("node").type == expected_type
+        finally:
+            provider.close()
+
+
+def test_ladybug_lazy_persist_roundtrip(typed_graph):
+    # index-free adopted tables persist without materializing the index
+    nodes, edges = typed_graph.nodes_table(), typed_graph.edges_table()
+    lazy = ArrowDiGraph.from_arrow(nodes, edges, index=False)
+    provider = LadybugStorageProvider()
+    try:
+        counts = persist(lazy, provider)
+        assert lazy._index_built is False
+        assert sum(counts.values()) == 6
+        _assert_graphs_equal(typed_graph, provider.load_graph())
+    finally:
+        provider.close()
+
+
+# -- Parquet store (same graphs, alternative choice at persist() time) --
+
+
+def test_parquet_provider_roundtrip(tmp_path, typed_graph):
+    typed_graph.graph["name"] = "roundtrip"
+    provider = ParquetStorageProvider(tmp_path / "store")
+    counts = persist(typed_graph, provider, graph_attrs=typed_graph.graph)
+    assert sum(counts.values()) == 6
+    assert (tmp_path / "store" / "manifest.json").exists()
+
+    restored = provider.load_graph()
+    _assert_graphs_equal(typed_graph, restored)
+    # per-type files: 2 node types + 3 edge types
+    assert len(list((tmp_path / "store" / "nodes").glob("*.parquet"))) == 2
+    assert len(list((tmp_path / "store" / "edges").glob("*.parquet"))) == 3
+
+
+def test_parquet_provider_roundtrip_untyped_and_empty(tmp_path):
+    provider = ParquetStorageProvider(tmp_path / "store")
+    g = nx.DiGraph(backend="arrow")
+    g.add_edge("a", "b", weight=1.5)
+    persist(g, provider)
+    restored = provider.load_graph()
+    _assert_graphs_equal(g, restored)
+    assert restored.nodes_table().column_names == ["node"]
+
+    persist(nx.DiGraph(backend="arrow"), provider)
+    empty = provider.load_graph()
+    assert empty.number_of_nodes() == 0
+    assert empty.number_of_edges() == 0
+
+
+def test_parquet_provider_repersist_drops_stale_files(tmp_path, typed_graph):
+    provider = ParquetStorageProvider(tmp_path / "store")
+    persist(typed_graph, provider)
+    assert len(list((tmp_path / "store" / "edges").glob("*.parquet"))) == 3
+
+    typed_graph.remove_edge("alice", "bob")  # drops the only "follows" edge
+    typed_graph.remove_edge("bob", "post1")  # drops the only "liked" edge
+    persist(typed_graph, provider)
+    assert len(list((tmp_path / "store" / "edges").glob("*.parquet"))) == 1
+    _assert_graphs_equal(typed_graph, provider.load_graph())
+
+
+def test_parquet_roundtrip_preserves_int_keys(tmp_path):
+    g = nx.DiGraph(backend="arrow")
+    g.add_edge(0, 1, weight=2.5)
+    g.add_edge(1, 2)
+    provider = ParquetStorageProvider(tmp_path / "store")
+    persist(g, provider)
+    restored = provider.load_graph()
+    assert restored.nodes == [0, 1, 2]
+    assert restored.edges == [(0, 1), (1, 2)]
+    assert restored.edge_attrs(0, 1) == {"weight": 2.5}
+    assert restored.nodes_table().schema.field("node").type == pa.int64()
+
+
+# -- the choice itself: one graph, either store --
+
+
+def test_same_graph_persists_to_both_stores(tmp_path, typed_graph):
+    typed_graph.graph["name"] = "either-store"
+    ladybug = LadybugStorageProvider()
+    parquet = ParquetStorageProvider(tmp_path / "store")
+    try:
+        persist(typed_graph, ladybug, graph_attrs=typed_graph.graph)
+        persist(typed_graph, parquet, graph_attrs=typed_graph.graph)
+        _assert_graphs_equal(typed_graph, ladybug.load_graph())
+        _assert_graphs_equal(typed_graph, parquet.load_graph())
+    finally:
+        ladybug.close()