gestaltdb 0.3.0a0__tar.gz

gestaltdb-0.3.0a0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: gestaltdb
+Version: 0.3.0a0
+Summary: A pure Python GraphDB for attributed graphs.
+Requires-Python: <3.14,>=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: google>=3.0.0
+Requires-Dist: msgpack>=1.1.2
+Requires-Dist: plyvel>=1.5.1
+Requires-Dist: protobuf>=6.33.6
+Provides-Extra: lmdb
+Requires-Dist: lmdb; extra == "lmdb"
+Provides-Extra: leveldb
+Requires-Dist: plyvel; extra == "leveldb"
+Provides-Extra: msgpack
+Requires-Dist: msgpack; extra == "msgpack"
+Provides-Extra: protobuf
+Requires-Dist: protobuf; extra == "protobuf"
+Provides-Extra: bloom
+Requires-Dist: pybloom-live; extra == "bloom"
+Provides-Extra: coverage
+Requires-Dist: coverage; extra == "coverage"
+Requires-Dist: pytest; extra == "coverage"
+Provides-Extra: docs
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Provides-Extra: rocksdb
+Requires-Dist: pyrex-rocksdb>=0.3.0a0; extra == "rocksdb"
+Provides-Extra: arrow
+Requires-Dist: pyarrow; extra == "arrow"
+Provides-Extra: polars
+Requires-Dist: polars; extra == "polars"
+Requires-Dist: pyarrow; extra == "polars"
+Provides-Extra: fast-ingest
+Requires-Dist: pyarrow; extra == "fast-ingest"
+Requires-Dist: polars; extra == "fast-ingest"
+Requires-Dist: pyrex-rocksdb>=0.3.0a0; extra == "fast-ingest"
+Provides-Extra: all
+Requires-Dist: lmdb; extra == "all"
+Requires-Dist: msgpack; extra == "all"
+Requires-Dist: plyvel; extra == "all"
+Requires-Dist: protobuf; extra == "all"
+Requires-Dist: pybloom-live; extra == "all"
+Requires-Dist: pyrex-rocksdb>=0.3.0a0; extra == "all"
+Requires-Dist: pyarrow; extra == "all"
+Requires-Dist: polars; extra == "all"
+Provides-Extra: dev
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: furo; extra == "dev"
+Requires-Dist: lmdb; extra == "dev"
+Requires-Dist: msgpack; extra == "dev"
+Requires-Dist: myst-parser; extra == "dev"
+Requires-Dist: plyvel; extra == "dev"
+Requires-Dist: protobuf; extra == "dev"
+Requires-Dist: pybloom-live; extra == "dev"
+Requires-Dist: pyrex-rocksdb>=0.3.0a0; extra == "dev"
+Requires-Dist: pyarrow; extra == "dev"
+Requires-Dist: polars; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+
+# GestaltDB
+
+![Coverage](https://raw.githubusercontent.com/mylonasc/gestaltdb/refs/heads/main/assets/coverage_badge.svg)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://mylonasc.github.io/gestaltdb/)
+
+GestaltDB is a pure Python graph database toolkit for attributed graphs. It stores nodes, edges, labels, typed adjacency records, and property indexes on embedded key-value backends.
+
+Documentation: https://mylonasc.github.io/gestaltdb/
+
+## Install
+
+From a local checkout:
+
+```sh
+uv sync
+```
+
+Install into another project:
+
+```sh
+uv add /path/to/gestaltdb
+```
+
+With pip:
+
+```sh
+python -m pip install /path/to/gestaltdb
+```
+
+Optional extras include `lmdb`, `leveldb`, `rocksdb`, `arrow`, `polars`, `fast-ingest`, `msgpack`, `protobuf`, `bloom`, `docs`, `dev`, and `all`.
+
+## Quick Example
+
+```python
+from gestaltdb.graphdb import Edge, GraphDB, Node
+from gestaltdb.kvstores import LMDBStore
+from gestaltdb.serializers import PickleSerializer
+
+graph = GraphDB(LMDBStore(path="example_lmdb"), PickleSerializer())
+
+graph.put_node(Node(node_id="alice", labels=["Person"], properties={"name": "Alice"}))
+graph.put_node(Node(node_id="bob", labels=["Person"], properties={"name": "Bob"}))
+graph.put_edge(Edge(
+    edge_id="alice-knows-bob",
+    source="alice",
+    target="bob",
+    properties={"type": "knows", "since": 2024},
+))
+
+result = graph.query('MATCH (a:Person {name: "Alice"}) MATCH (a)-[:knows]->(b) RETURN a.id, b.name')
+print(result.records)
+
+graph.close()
+```
+
+## Features
+
+- Attributed `Node` and `Edge` objects with stable IDs.
+- Native node labels and typed edge traversal through `edge.properties["type"]`.
+- LMDB, LevelDB, and RocksDB/PyRex storage backends.
+- Pickle, JSON, MessagePack, and Protobuf serializers.
+- Label, relationship type, property, composite, and range indexes.
+- Read-only Cypher subset for indexed scans, typed traversal, filtering, ordering, limits, and chained `MATCH` clauses.
+- Bulk and columnar ingestion helpers.
+- Typed path and subgraph sampling.
+
+See the full documentation for backend selection, indexing, Cypher syntax, ingestion, sampling, and benchmarks.
+
+<details>
+<summary>Name origin</summary>
+
+The name GestaltDB is inspired by Gestalt psychology and the idea that the whole is something more than its parts.
+
+</details>

gestaltdb-0.3.0a0/README.md

@@ -0,0 +1,74 @@
+# GestaltDB
+
+![Coverage](https://raw.githubusercontent.com/mylonasc/gestaltdb/refs/heads/main/assets/coverage_badge.svg)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://mylonasc.github.io/gestaltdb/)
+
+GestaltDB is a pure Python graph database toolkit for attributed graphs. It stores nodes, edges, labels, typed adjacency records, and property indexes on embedded key-value backends.
+
+Documentation: https://mylonasc.github.io/gestaltdb/
+
+## Install
+
+From a local checkout:
+
+```sh
+uv sync
+```
+
+Install into another project:
+
+```sh
+uv add /path/to/gestaltdb
+```
+
+With pip:
+
+```sh
+python -m pip install /path/to/gestaltdb
+```
+
+Optional extras include `lmdb`, `leveldb`, `rocksdb`, `arrow`, `polars`, `fast-ingest`, `msgpack`, `protobuf`, `bloom`, `docs`, `dev`, and `all`.
+
+## Quick Example
+
+```python
+from gestaltdb.graphdb import Edge, GraphDB, Node
+from gestaltdb.kvstores import LMDBStore
+from gestaltdb.serializers import PickleSerializer
+
+graph = GraphDB(LMDBStore(path="example_lmdb"), PickleSerializer())
+
+graph.put_node(Node(node_id="alice", labels=["Person"], properties={"name": "Alice"}))
+graph.put_node(Node(node_id="bob", labels=["Person"], properties={"name": "Bob"}))
+graph.put_edge(Edge(
+    edge_id="alice-knows-bob",
+    source="alice",
+    target="bob",
+    properties={"type": "knows", "since": 2024},
+))
+
+result = graph.query('MATCH (a:Person {name: "Alice"}) MATCH (a)-[:knows]->(b) RETURN a.id, b.name')
+print(result.records)
+
+graph.close()
+```
+
+## Features
+
+- Attributed `Node` and `Edge` objects with stable IDs.
+- Native node labels and typed edge traversal through `edge.properties["type"]`.
+- LMDB, LevelDB, and RocksDB/PyRex storage backends.
+- Pickle, JSON, MessagePack, and Protobuf serializers.
+- Label, relationship type, property, composite, and range indexes.
+- Read-only Cypher subset for indexed scans, typed traversal, filtering, ordering, limits, and chained `MATCH` clauses.
+- Bulk and columnar ingestion helpers.
+- Typed path and subgraph sampling.
+
+See the full documentation for backend selection, indexing, Cypher syntax, ingestion, sampling, and benchmarks.
+
+<details>
+<summary>Name origin</summary>
+
+The name GestaltDB is inspired by Gestalt psychology and the idea that the whole is something more than its parts.
+
+</details>

gestaltdb-0.3.0a0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gestaltdb"
+version = "0.3.0a0"
+description = "A pure Python GraphDB for attributed graphs."
+readme = "README.md"
+requires-python = ">=3.9,<3.14"
+dependencies = [
+    "google>=3.0.0",
+    "msgpack>=1.1.2",
+    "plyvel>=1.5.1",
+    "protobuf>=6.33.6",
+]
+
+[project.optional-dependencies]
+lmdb = ["lmdb"]
+leveldb = ["plyvel"]
+msgpack = ["msgpack"]
+protobuf = ["protobuf"]
+bloom = ["pybloom-live"]
+coverage = ["coverage", "pytest"]
+docs = ["furo", "myst-parser", "sphinx"]
+rocksdb = ["pyrex-rocksdb>=0.3.0a0"]
+arrow = ["pyarrow"]
+polars = ["polars", "pyarrow"]
+fast-ingest = ["pyarrow", "polars", "pyrex-rocksdb>=0.3.0a0"]
+all = ["lmdb", "msgpack", "plyvel", "protobuf", "pybloom-live", "pyrex-rocksdb>=0.3.0a0", "pyarrow", "polars"]
+dev = ["coverage", "furo", "lmdb", "msgpack", "myst-parser", "plyvel", "protobuf", "pybloom-live", "pyrex-rocksdb>=0.3.0a0", "pyarrow", "polars", "pytest", "sphinx"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "coverage>=7.10.7",
+    "pytest>=8.0",
+]

gestaltdb-0.3.0a0/setup.cfg

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

gestaltdb-0.3.0a0/src/gestaltdb/__init__.py

@@ -0,0 +1,7 @@
+"""GestaltDB package."""
+
+from .sampling import SamplingHop, SamplingPattern
+from .ingestion import EdgeList, NodeList
+from .cypher import QueryResult
+
+__all__ = ["EdgeList", "NodeList", "QueryResult", "SamplingHop", "SamplingPattern"]

gestaltdb-0.3.0a0/src/gestaltdb/cypher.py

@@ -0,0 +1,104 @@
+"""Minimal read-only Cypher support for GestaltDB.
+
+The supported subset maps directly to existing typed adjacency and sampling APIs:
+
+    MATCH (a {id: "node-id"})-[:TYPE1]->(b)<-[:TYPE2]-(c) RETURN a.name, b LIMIT 10
+    CALL pg.sample_typed_paths(["node-id"], [{"edge_type": "TYPE", "sample_size": 2}]) YIELD path RETURN path
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .cypher_ast import MatchQuery, MultiMatchQuery, NodeScanQuery, RelationshipScanQuery, SampleTypedPathsCall
+from .cypher_plan import LogicalPlan, plan_query
+from .cypher_parser import parse as _parse_query, split_top_level_args as _split_top_level_args
+from .cypher_runtime import QueryContext, execute_match, execute_multi_match, execute_node_scan, execute_relationship_scan
+
+
+@dataclass(frozen=True)
+class QueryResult:
+    """Tabular query result returned by ``GraphDB.query``.
+
+    ``columns`` contains projected column names in return order. ``records`` is
+    a list of dictionaries keyed by column name.
+
+    Examples:
+        >>> result = QueryResult(columns=("n",), records=[{"n": "node"}])
+        >>> len(result)
+        1
+        >>> list(result)[0]["n"]
+        'node'
+    """
+
+    columns: tuple[str, ...]
+    records: list[dict[str, object]]
+
+    def __iter__(self):
+        """Iterate over result records."""
+        return iter(self.records)
+
+    def __len__(self):
+        """Return the number of result records."""
+        return len(self.records)
+
+
+def parse(query: str) -> MatchQuery | SampleTypedPathsCall | NodeScanQuery | RelationshipScanQuery | MultiMatchQuery:
+    """Parse the supported Cypher subset.
+
+    Args:
+        query: Cypher query text.
+
+    Returns:
+        Parsed query object.
+
+    Raises:
+        ValueError: If the query is outside the supported subset.
+
+    Examples:
+        >>> parse('MATCH (n:Drug) RETURN n').label
+        'Drug'
+    """
+    return _parse_query(query)
+
+
+def plan(query: str) -> LogicalPlan:
+    """Return the logical plan for a supported Cypher query."""
+    return plan_query(parse(query))
+
+
+def execute(graph, query: str, parameters: dict[str, object] | None = None) -> QueryResult:
+    """Execute a supported Cypher query against a ``GraphDB`` instance.
+
+    Args:
+        graph: ``GraphDB`` instance used for indexed lookups and traversal.
+        query: Cypher query text.
+
+    Returns:
+        ``QueryResult`` with projected records.
+
+    Examples:
+        >>> execute(graph_db, 'MATCH (n:Drug) RETURN n')  # doctest: +SKIP
+    """
+    parsed = parse(query)
+    plan_query(parsed)
+    parameters = parameters or {}
+    if isinstance(parsed, SampleTypedPathsCall):
+        paths = graph.sample_typed_paths(parsed.seed_ids, parsed.pattern)
+        if parsed.limit is not None:
+            paths = paths[:parsed.limit]
+        return QueryResult(
+            columns=parsed.returns,
+            records=[{"path": path} for path in paths],
+        )
+    if isinstance(parsed, NodeScanQuery):
+        records = execute_node_scan(parsed, QueryContext(graph=graph, parameters=parameters))
+        return QueryResult(columns=parsed.returns, records=records)
+    if isinstance(parsed, RelationshipScanQuery):
+        records = execute_relationship_scan(parsed, QueryContext(graph=graph, parameters=parameters))
+        return QueryResult(columns=parsed.returns, records=records)
+    if isinstance(parsed, MultiMatchQuery):
+        records = execute_multi_match(parsed, QueryContext(graph=graph, parameters=parameters))
+        return QueryResult(columns=parsed.returns, records=records)
+    records = execute_match(parsed, QueryContext(graph=graph, parameters=parameters))
+    return QueryResult(columns=parsed.returns, records=records)

gestaltdb-0.3.0a0/src/gestaltdb/cypher_ast.py

@@ -0,0 +1,180 @@
+"""AST objects for the GestaltDB Cypher subset."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Parameter:
+    """Cypher query parameter reference, such as ``$name``."""
+
+    name: str
+
+
+@dataclass(frozen=True)
+class PropertyRef:
+    """Reference to a variable property, such as ``n.name``."""
+
+    variable: str
+    property_name: str
+
+
+@dataclass(frozen=True)
+class ComparisonExpression:
+    """Binary comparison expression for the current Cypher subset."""
+
+    left: PropertyRef
+    operator: str
+    right: object
+
+
+@dataclass(frozen=True)
+class InExpression:
+    """Membership predicate, such as ``n.kind IN ["drug"]``."""
+
+    left: PropertyRef
+    values: object
+
+
+@dataclass(frozen=True)
+class NullPredicate:
+    """Null check predicate."""
+
+    expression: PropertyRef
+    negated: bool = False
+
+
+@dataclass(frozen=True)
+class AndExpression:
+    """Conjunction of boolean expressions."""
+
+    expressions: tuple[object, ...]
+
+
+@dataclass(frozen=True)
+class OrderItem:
+    """One ORDER BY item."""
+
+    expression: str
+    descending: bool = False
+
+
+@dataclass(frozen=True)
+class TraversalHop:
+    """One typed relationship expansion in a parsed ``MATCH`` pattern."""
+
+    rel_var: str | None
+    edge_type: str
+    target_var: str
+    direction: str = "out"
+    edge_types: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class MatchQuery:
+    """Parsed anchored typed path query."""
+
+    source_var: str
+    source_id: str
+    hops: tuple[TraversalHop, ...]
+    returns: tuple[str, ...]
+    limit: int | None = None
+    where: object | None = None
+    projections: tuple[str, ...] = ()
+    order_by: tuple[OrderItem, ...] = ()
+    skip: int | None = None
+    distinct: bool = False
+
+
+@dataclass(frozen=True)
+class NodePatternClause:
+    """One node pattern in a multi-clause ``MATCH`` query."""
+
+    variable: str
+    label: str | None = None
+    property_name: str | None = None
+    property_value: object = None
+    labels: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class RelationshipPatternClause:
+    """One relationship pattern in a multi-clause ``MATCH`` query."""
+
+    source_var: str
+    rel_var: str | None
+    edge_type: str
+    target_var: str
+    direction: str = "out"
+    edge_types: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class AnchoredPatternClause:
+    """One anchored traversal pattern in a multi-clause ``MATCH`` query."""
+
+    source_var: str
+    source_id: str
+    hops: tuple[TraversalHop, ...]
+
+
+@dataclass(frozen=True)
+class MultiMatchQuery:
+    """Parsed query containing multiple ``MATCH`` clauses."""
+
+    clauses: tuple[object, ...]
+    returns: tuple[str, ...]
+    where: object | None = None
+    projections: tuple[str, ...] = ()
+    order_by: tuple[OrderItem, ...] = ()
+    skip: int | None = None
+    limit: int | None = None
+    distinct: bool = False
+
+
+@dataclass(frozen=True)
+class SampleTypedPathsCall:
+    """Parsed ``pg.sample_typed_paths`` procedure call."""
+
+    seed_ids: list[str]
+    pattern: list[dict[str, object]]
+    returns: tuple[str, ...] = ("path",)
+    limit: int | None = None
+
+
+@dataclass(frozen=True)
+class NodeScanQuery:
+    """Parsed indexed node label scan query."""
+
+    variable: str
+    label: str | None
+    property_name: str | None
+    property_value: object
+    returns: tuple[str, ...]
+    limit: int | None = None
+    where: object | None = None
+    labels: tuple[str, ...] = ()
+    projections: tuple[str, ...] = ()
+    order_by: tuple[OrderItem, ...] = ()
+    skip: int | None = None
+    distinct: bool = False
+
+
+@dataclass(frozen=True)
+class RelationshipScanQuery:
+    """Parsed unanchored typed relationship scan query."""
+
+    source_var: str
+    rel_var: str | None
+    edge_type: str
+    target_var: str
+    returns: tuple[str, ...]
+    direction: str = "out"
+    edge_types: tuple[str, ...] = ()
+    where: object | None = None
+    projections: tuple[str, ...] = ()
+    order_by: tuple[OrderItem, ...] = ()
+    skip: int | None = None
+    limit: int | None = None
+    distinct: bool = False