tina4-python 3.13.110__tar.gz → 3.13.111__tar.gz

{tina4_python-3.13.110 → tina4_python-3.13.111}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tina4-python
-Version: 3.13.110
+Version: 3.13.111
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT
@@ -12,8 +12,15 @@ Requires-Dist: psycopg2-binary>=2.9; extra == 'all-db'
 Requires-Dist: pymongo>=4.0; extra == 'all-db'
 Requires-Dist: pymssql>=2.3; extra == 'all-db'
 Requires-Dist: pyodbc>=5.0; extra == 'all-db'
+Provides-Extra: arango
+Requires-Dist: python-arango>=8.0; extra == 'arango'
 Provides-Extra: firebird
 Requires-Dist: firebird-driver>=1.10; extra == 'firebird'
+Provides-Extra: graph
+Requires-Dist: neo4j>=5.0; extra == 'graph'
+Requires-Dist: protobuf>=7.35.1; extra == 'graph'
+Requires-Dist: python-arango>=8.0; extra == 'graph'
+Requires-Dist: tina4-ultipa>=0.1; extra == 'graph'
 Provides-Extra: kafka
 Requires-Dist: confluent-kafka>=2.0; extra == 'kafka'
 Provides-Extra: memcache
@@ -24,6 +31,8 @@ Provides-Extra: mssql
 Requires-Dist: pymssql>=2.3; extra == 'mssql'
 Provides-Extra: mysql
 Requires-Dist: mysql-connector-python>=9.0; extra == 'mysql'
+Provides-Extra: neo4j
+Requires-Dist: neo4j>=5.0; extra == 'neo4j'
 Provides-Extra: odbc
 Requires-Dist: pyodbc>=5.0; extra == 'odbc'
 Provides-Extra: postgres
@@ -47,6 +56,9 @@ Requires-Dist: pymongo>=4.0; extra == 'test'
 Requires-Dist: pymssql>=2.3; extra == 'test'
 Requires-Dist: pyodbc>=5.0; extra == 'test'
 Requires-Dist: redis>=5.0; extra == 'test'
+Provides-Extra: ultipa
+Requires-Dist: protobuf>=7.35.1; extra == 'ultipa'
+Requires-Dist: tina4-ultipa>=0.1; extra == 'ultipa'
 Description-Content-Type: text/markdown
 
 <p align="center">

{tina4_python-3.13.110 → tina4_python-3.13.111}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.13.110"
+version = "3.13.111"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}
@@ -21,6 +21,13 @@ firebird = ["firebird-driver>=1.10"]
 mongo = ["pymongo>=4.0"]
 odbc = ["pyodbc>=5.0"]
 
+# Graph engine drivers — install what you need (loaded lazily on first use).
+# The graph core is zero-dependency; a driver is a cost paid only per engine.
+ultipa = ["tina4-ultipa>=0.1", "protobuf>=7.35.1"]  # gencode needs protobuf 7.x; floor pins the CVE-free runtime
+neo4j = ["neo4j>=5.0"]          # the Bolt driver also serves Memgraph
+arango = ["python-arango>=8.0"]
+graph = ["tina4-ultipa>=0.1", "protobuf>=7.35.1", "neo4j>=5.0", "python-arango>=8.0"]
+
 # Session backends — install what you need
 redis = ["redis>=5.0"]
 memcache = ["pymemcache>=4.0"]

{tina4_python-3.13.110 → tina4_python-3.13.111}/tina4_python/__init__.py

@@ -51,7 +51,7 @@ def _resolve_version() -> str:
     #
     # test_version_constant.py now asserts this literal equals the pyproject
     # version, so the release bump cannot leave it behind again.
-    return "3.13.110"
+    return "3.13.111"
 
 
 __version__ = _resolve_version()

tina4_python-3.13.111/tina4_python/graph/__init__.py

@@ -0,0 +1,114 @@
+# Tina4 graph data layer — a URL-selected graph database, shaped like Database.
+"""One factory (`GraphDatabase.create` / `.from_env`), one portable
+node/edge/traverse surface plus a raw `query`/`execute` pass-through, and neutral
+`GraphNode` / `GraphEdge` / `GraphResult` shapes — the exact mirror of the
+relational `Database` layer, for graph engines (Ultipa first). Engine drivers are
+OPTIONAL and imported only on first use, so the zero-dependency core is preserved.
+
+See ADR-0059 and tina4-documentation/plan/v3/features/139-graph-databases.md.
+"""
+import os
+
+from .graph_url import GraphUrl
+from .adapter import GraphDatabase, GraphAdapter, GraphError, GraphConnectTimeout
+
+# The graph connect bound — sibling of TINA4_DATABASE_CONNECT_TIMEOUT.
+GRAPH_CONNECT_TIMEOUT_VARIABLE = "TINA4_GRAPH_CONNECT_TIMEOUT"
+DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS = 10.0
+
+
+def resolve_graph_connect_timeout() -> float | None:
+    """Seconds a graph connect may block; None means unbounded (<= 0).
+
+    Mirrors resolve_connect_timeout: a value <= 0 disables the bound, a
+    non-number warns and falls back to the default rather than waiting forever.
+    """
+    raw = os.environ.get(GRAPH_CONNECT_TIMEOUT_VARIABLE, "").strip()
+    if not raw:
+        return DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS
+    try:
+        seconds = float(raw)
+    except ValueError:
+        from tina4_python.debug import Log
+        Log.warning(
+            f"{GRAPH_CONNECT_TIMEOUT_VARIABLE}={raw!r} is not a number of seconds — "
+            f"bounding graph connects at the {DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS:g}s default instead"
+        )
+        return DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS
+    return None if seconds <= 0 else seconds
+
+
+class GraphNode:
+    """Engine-neutral vertex: id, labels, properties."""
+
+    __slots__ = ("id", "labels", "properties")
+
+    def __init__(self, id, labels=None, properties=None):
+        self.id = id
+        self.labels = list(labels or [])
+        self.properties = dict(properties or {})
+
+    def to_dict(self) -> dict:
+        return {"id": self.id, "labels": self.labels, "properties": self.properties}
+
+    def __repr__(self):
+        return f"GraphNode(id={self.id!r}, labels={self.labels!r})"
+
+
+class GraphEdge:
+    """Engine-neutral edge: id, type, from/to node ids, properties."""
+
+    __slots__ = ("id", "type", "from_id", "to_id", "properties")
+
+    def __init__(self, id, type, from_id, to_id, properties=None):
+        self.id = id
+        self.type = type
+        self.from_id = from_id
+        self.to_id = to_id
+        self.properties = dict(properties or {})
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id, "type": self.type,
+            "from": self.from_id, "to": self.to_id,
+            "properties": self.properties,
+        }
+
+    def __repr__(self):
+        return f"GraphEdge(id={self.id!r}, type={self.type!r}, {self.from_id!r}->{self.to_id!r})"
+
+
+class GraphResult:
+    """A raw-query result — records + columns, same shape as DatabaseResult."""
+
+    __slots__ = ("records", "columns")
+
+    def __init__(self, records=None, columns=None):
+        self.records = list(records or [])
+        self.columns = list(columns or [])
+
+    def to_array(self) -> list:
+        return self.records
+
+    def scalar(self):
+        if not self.records:
+            return None
+        first = self.records[0]
+        if isinstance(first, dict):
+            return next(iter(first.values()), None)
+        return first[0] if first else None
+
+    def __iter__(self):
+        return iter(self.records)
+
+    def __len__(self):
+        return len(self.records)
+
+
+__all__ = [
+    "GraphDatabase", "GraphAdapter", "GraphUrl",
+    "GraphNode", "GraphEdge", "GraphResult",
+    "GraphError", "GraphConnectTimeout",
+    "resolve_graph_connect_timeout",
+    "GRAPH_CONNECT_TIMEOUT_VARIABLE", "DEFAULT_GRAPH_CONNECT_TIMEOUT_SECONDS",
+]

tina4_python-3.13.111/tina4_python/graph/adapter.py

@@ -0,0 +1,119 @@
+# GraphAdapter contract + the GraphDatabase URL-selected factory.
+"""Every engine adapter implements GraphAdapter; GraphDatabase.create picks one
+by URL scheme and imports its driver lazily — a missing driver raises an
+actionable install error, never a bare ImportError, and the core imports with no
+driver present (the zero-dependency-core rule).
+"""
+import os
+
+from .graph_url import GraphUrl
+
+
+class GraphError(Exception):
+    """A graph operation failed (bad statement, engine error)."""
+
+
+class GraphConnectTimeout(TimeoutError):
+    """A graph connect exceeded TINA4_GRAPH_CONNECT_TIMEOUT.
+
+    A subclass of the builtin TimeoutError, so ``except TimeoutError`` catches it
+    without importing anything from Tina4 — same as DatabaseConnectTimeout.
+    """
+
+
+# engine -> (module, class, install-package, install-command). Selected lazily so
+# importing tina4_python.graph pulls in NO engine driver.
+_ENGINE_ADAPTERS = {
+    "ultipa": ("tina4_python.graph.adapters.ultipa", "UltipaGraphAdapter",
+               "tina4-ultipa", "uv add tina4-ultipa   # or: pip install tina4-ultipa"),
+    "bolt": ("tina4_python.graph.adapters.bolt", "BoltGraphAdapter",
+             "neo4j", "uv add neo4j   # or: pip install neo4j"),
+    "arango": ("tina4_python.graph.adapters.arango", "ArangoGraphAdapter",
+               "python-arango", "uv add python-arango   # or: pip install python-arango"),
+}
+
+
+class GraphAdapter:
+    """The one surface every graph engine implements. Raising stubs — a driver
+    that does not override a method fails LOUDLY, naming itself and the method.
+    """
+
+    # -- portable node/edge/traverse core ----------------------------------
+    def add_node(self, label, properties=None):
+        raise NotImplementedError(f"{type(self).__name__} does not implement add_node")
+
+    def add_edge(self, from_id, to_id, type, properties=None):
+        raise NotImplementedError(f"{type(self).__name__} does not implement add_edge")
+
+    def get_node(self, node_id):
+        raise NotImplementedError(f"{type(self).__name__} does not implement get_node")
+
+    def update_node(self, node_id, properties):
+        raise NotImplementedError(f"{type(self).__name__} does not implement update_node")
+
+    def delete_node(self, node_id):
+        raise NotImplementedError(f"{type(self).__name__} does not implement delete_node")
+
+    def neighbors(self, node_id, direction="both", edge_type=None, limit=100):
+        raise NotImplementedError(f"{type(self).__name__} does not implement neighbors")
+
+    def traverse(self, start_id, depth=1, direction="both", edge_type=None, limit=1000):
+        raise NotImplementedError(f"{type(self).__name__} does not implement traverse")
+
+    # -- raw pass-through (engine-native dialect) --------------------------
+    def query(self, text, params=None):
+        raise NotImplementedError(f"{type(self).__name__} does not implement query")
+
+    def execute(self, text, params=None):
+        raise NotImplementedError(f"{type(self).__name__} does not implement execute")
+
+    # -- lifecycle ---------------------------------------------------------
+    def close(self):
+        raise NotImplementedError(f"{type(self).__name__} does not implement close")
+
+    def get_error(self):
+        """Cause of the last failed operation, or None."""
+        return getattr(self, "_last_error", None)
+
+
+class GraphDatabase:
+    """URL-selected graph factory — the GraphDatabase sibling of Database."""
+
+    @staticmethod
+    def create(url: str, username: str = "", password: str = "") -> GraphAdapter:
+        """Parse the URL, pick the engine adapter, connect lazily.
+
+        The engine driver is imported only here (first use of that engine); if it
+        is absent the error names the package and the install command.
+        """
+        graph_url = GraphUrl(url)
+        registration = _ENGINE_ADAPTERS.get(graph_url.engine)
+        if registration is None:
+            raise GraphError(
+                f"No graph adapter for engine {graph_url.engine!r} yet "
+                f"(scheme {graph_url.scheme!r}). Available: "
+                f"{', '.join(sorted(_ENGINE_ADAPTERS))}."
+            )
+        module_path, class_name, package, install_cmd = registration
+        try:
+            import importlib
+            module = importlib.import_module(module_path)
+        except ImportError as exc:
+            # The adapter module imports its driver at module top; a missing
+            # driver surfaces here as an actionable install error.
+            raise GraphError(
+                f"The graph driver for {graph_url.engine!r} is not installed "
+                f"({package}). Install it with:\n    {install_cmd}"
+            ) from exc
+        adapter_class = getattr(module, class_name)
+        return adapter_class(graph_url, username=username, password=password)
+
+    @staticmethod
+    def from_env(env_key: str = "TINA4_GRAPH_URL") -> "GraphAdapter | None":
+        """Build from TINA4_GRAPH_URL (+ TINA4_GRAPH_USERNAME/_PASSWORD)."""
+        url = os.environ.get(env_key)
+        if not url:
+            return None
+        username = os.environ.get("TINA4_GRAPH_USERNAME", "")
+        password = os.environ.get("TINA4_GRAPH_PASSWORD", "")
+        return GraphDatabase.create(url, username=username, password=password)

tina4_python-3.13.111/tina4_python/graph/adapters/__init__.py

@@ -0,0 +1 @@
+# Graph engine adapters — imported lazily by GraphDatabase.create (one per engine).

tina4_python-3.13.111/tina4_python/graph/adapters/arango.py

@@ -0,0 +1,145 @@
+# ArangoDB graph adapter — the document/AQL engine behind the same surface.
+"""Wraps the community `python-arango` driver (an OPTIONAL dependency — imported
+here, so `import tina4_python.graph` stays driver-free). Arango is a document
+store, not a labelled-property graph, so the portable core maps onto ONE vertex
+collection + ONE edge collection: a node's `labels` and an edge's `type` are
+stored as document fields, ids are Arango `_id` handles (e.g. `tina4_nodes/123`),
+and traversal uses AQL `FOR v IN 1..N OUTBOUND ...`. Raw query()/execute() take
+AQL directly.
+"""
+from arango import ArangoClient
+from arango.exceptions import ArangoError, ArangoClientError, ArangoServerError
+
+from tina4_python.graph import (
+    GraphNode, GraphEdge, GraphResult, resolve_graph_connect_timeout,
+)
+from tina4_python.graph.adapter import GraphAdapter, GraphError, GraphConnectTimeout
+
+VERTEX_COLLECTION = "tina4_nodes"
+EDGE_COLLECTION = "tina4_edges"
+_RESERVED = {"_id", "_key", "_rev", "_from", "_to", "_labels", "_type"}
+
+
+def _clean_props(doc):
+    return {k: v for k, v in doc.items() if k not in _RESERVED}
+
+
+class ArangoGraphAdapter(GraphAdapter):
+    def __init__(self, graph_url, username="", password=""):
+        self._url = graph_url
+        self._last_error = None
+        timeout = resolve_graph_connect_timeout()
+        scheme = "https" if graph_url.use_tls else "http"
+        self._client = ArangoClient(
+            hosts=f"{scheme}://{graph_url.host}:{graph_url.port}",
+            request_timeout=timeout,
+        )
+        user = graph_url.username or username or "root"
+        pwd = graph_url.password or password or ""
+        database = graph_url.graph or "_system"
+        try:
+            self._db = self._client.db(database, username=user, password=pwd)
+            if not self._db.has_collection(VERTEX_COLLECTION):
+                self._db.create_collection(VERTEX_COLLECTION)
+            if not self._db.has_collection(EDGE_COLLECTION):
+                self._db.create_collection(EDGE_COLLECTION, edge=True)
+        except (ArangoClientError, ArangoServerError) as exc:
+            self._last_error = str(exc)
+            raise self._connect_or_error(exc)
+
+    def _connect_or_error(self, exc):
+        text = str(exc).lower()
+        if "timed out" in text or "connection" in text or "max retries" in text:
+            return GraphConnectTimeout(
+                f"Graph connect to {self._url.host}:{self._url.port} timed out "
+                f"(TINA4_GRAPH_CONNECT_TIMEOUT). Raise it if the server is simply "
+                f"slow, or set it to 0 to wait indefinitely."
+            )
+        return GraphError(str(exc))
+
+    def _aql(self, query, bind=None):
+        try:
+            return list(self._db.aql.execute(query, bind_vars=bind or {}))
+        except (ArangoClientError, ArangoServerError) as exc:
+            self._last_error = str(exc)
+            err = self._connect_or_error(exc)
+            raise err
+        except ArangoError as exc:
+            self._last_error = str(exc)
+            raise GraphError(str(exc)) from exc
+
+    def query(self, text, params=None):
+        rows = self._aql(text, params)
+        columns = list(rows[0].keys()) if rows and isinstance(rows[0], dict) else []
+        return GraphResult(records=rows, columns=columns)
+
+    def execute(self, text, params=None):
+        return self.query(text, params)
+
+    def _node(self, doc):
+        if doc is None:
+            return None
+        return GraphNode(id=doc.get("_id"), labels=doc.get("_labels") or [],
+                         properties=_clean_props(doc))
+
+    def add_node(self, label, properties=None):
+        doc = dict(properties or {})
+        doc["_labels"] = [label]
+        rows = self._aql(
+            f"INSERT @doc INTO {VERTEX_COLLECTION} RETURN NEW", {"doc": doc})
+        return self._node(rows[0]) if rows else None
+
+    def add_edge(self, from_id, to_id, type, properties=None):
+        doc = dict(properties or {})
+        doc.update({"_from": from_id, "_to": to_id, "_type": type})
+        rows = self._aql(
+            f"INSERT @doc INTO {EDGE_COLLECTION} RETURN NEW", {"doc": doc})
+        if not rows:
+            return None
+        r = rows[0]
+        return GraphEdge(id=r.get("_id"), type=r.get("_type"), from_id=r.get("_from"),
+                         to_id=r.get("_to"), properties=_clean_props(r))
+
+    def get_node(self, node_id):
+        rows = self._aql("RETURN DOCUMENT(@id)", {"id": node_id})
+        return self._node(rows[0]) if rows and rows[0] else None
+
+    def update_node(self, node_id, properties):
+        rows = self._aql(
+            f"UPDATE PARSE_IDENTIFIER(@id).key WITH @props IN {VERTEX_COLLECTION} RETURN NEW",
+            {"id": node_id, "props": properties or {}})
+        return self._node(rows[0]) if rows else None
+
+    def delete_node(self, node_id):
+        # remove the node and any edges touching it, so a re-read is a clean miss.
+        self._aql(
+            f"FOR e IN {EDGE_COLLECTION} FILTER e._from == @id OR e._to == @id "
+            f"REMOVE e IN {EDGE_COLLECTION}", {"id": node_id})
+        self._aql(
+            f"REMOVE PARSE_IDENTIFIER(@id).key IN {VERTEX_COLLECTION}", {"id": node_id})
+        return True
+
+    def neighbors(self, node_id, direction="both", edge_type=None, limit=100):
+        arango_dir = {"out": "OUTBOUND", "in": "INBOUND", "both": "ANY"}.get(direction, "ANY")
+        type_filter = "FILTER e._type == @etype " if edge_type else ""
+        bind = {"start": node_id, "limit": int(limit)}
+        if edge_type:
+            bind["etype"] = edge_type
+        rows = self._aql(
+            f"FOR v, e IN 1..1 {arango_dir} @start {EDGE_COLLECTION} "
+            f"{type_filter}LIMIT @limit RETURN DISTINCT v", bind)
+        return [self._node(v) for v in rows]
+
+    def traverse(self, start_id, depth=1, direction="both", edge_type=None, limit=1000):
+        arango_dir = {"out": "OUTBOUND", "in": "INBOUND", "both": "ANY"}.get(direction, "ANY")
+        type_filter = "FILTER e._type == @etype " if edge_type else ""
+        bind = {"start": start_id, "limit": int(limit)}
+        if edge_type:
+            bind["etype"] = edge_type
+        rows = self._aql(
+            f"FOR v, e IN 1..{int(depth)} {arango_dir} @start {EDGE_COLLECTION} "
+            f"{type_filter}LIMIT @limit RETURN DISTINCT v", bind)
+        return [self._node(v) for v in rows]
+
+    def close(self):
+        self._client.close()

tina4_python-3.13.111/tina4_python/graph/adapters/bolt.py

@@ -0,0 +1,127 @@
+# Bolt graph adapter — Neo4j AND Memgraph (both speak Bolt + Cypher).
+"""Wraps the community `neo4j` Python driver (an OPTIONAL dependency — imported
+here, so `import tina4_python.graph` stays driver-free). Neo4j and Memgraph share
+this ONE adapter; the URL scheme only picks the engine label and default port.
+
+Cypher note (verified against live Neo4j + Memgraph): `id(n)` is the portable
+node/edge id (an integer on both — Neo4j's `elementId` is Neo4j-only, Memgraph
+has no `elementId`); variable-length traversal is Cypher's `[*1..N]` (the
+opposite of Ultipa's GQL `{1,N}`); `SET n += $props` merges.
+"""
+from neo4j import GraphDatabase as _Neo4jDriver
+from neo4j.exceptions import Neo4jError, ServiceUnavailable, DriverError
+
+from tina4_python.graph import (
+    GraphNode, GraphEdge, GraphResult, resolve_graph_connect_timeout,
+)
+from tina4_python.graph.adapter import GraphAdapter, GraphError, GraphConnectTimeout
+
+
+class BoltGraphAdapter(GraphAdapter):
+    def __init__(self, graph_url, username="", password=""):
+        self._url = graph_url
+        self._database = graph_url.graph or None
+        self._last_error = None
+        user = graph_url.username or username or "neo4j"
+        pwd = graph_url.password or password or ""
+        scheme = "bolt+s" if graph_url.use_tls else "bolt"
+        uri = f"{scheme}://{graph_url.host}:{graph_url.port}"
+        timeout = resolve_graph_connect_timeout()
+        cfg = {}
+        if timeout is not None:
+            cfg["connection_timeout"] = timeout
+            cfg["connection_acquisition_timeout"] = timeout
+            cfg["max_transaction_retry_time"] = timeout
+        self._driver = _Neo4jDriver.driver(uri, auth=(user, pwd), **cfg)
+
+    def _run(self, cypher, params=None):
+        try:
+            with self._driver.session(database=self._database) as session:
+                result = session.run(cypher, parameters=params or {})
+                return [record.data() for record in result]
+        except (ServiceUnavailable, DriverError) as exc:
+            self._last_error = str(exc)
+            # An unreachable host surfaces here as a service-unavailable/timeout.
+            if "timed out" in str(exc).lower() or isinstance(exc, ServiceUnavailable):
+                raise GraphConnectTimeout(
+                    f"Graph connect to {self._url.host}:{self._url.port} timed out "
+                    f"(TINA4_GRAPH_CONNECT_TIMEOUT). Raise it if the server is simply "
+                    f"slow, or set it to 0 to wait indefinitely."
+                ) from exc
+            raise GraphError(str(exc)) from exc
+        except Neo4jError as exc:
+            self._last_error = str(exc)
+            raise GraphError(str(exc)) from exc
+
+    def query(self, text, params=None):
+        rows = self._run(text, params)
+        columns = list(rows[0].keys()) if rows else []
+        return GraphResult(records=rows, columns=columns)
+
+    def execute(self, text, params=None):
+        return self.query(text, params)
+
+    def _node(self, row):
+        if row is None:
+            return None
+        return GraphNode(id=row.get("id"), labels=row.get("labels"),
+                         properties=row.get("props") or {})
+
+    def add_node(self, label, properties=None):
+        cypher = (f"CREATE (n:`{label}` $props) "
+                  f"RETURN id(n) AS id, labels(n) AS labels, properties(n) AS props")
+        rows = self._run(cypher, {"props": properties or {}})
+        return self._node(rows[0]) if rows else None
+
+    def add_edge(self, from_id, to_id, type, properties=None):
+        cypher = (f"MATCH (a), (b) WHERE id(a) = $from_id AND id(b) = $to_id "
+                  f"CREATE (a)-[e:`{type}` $props]->(b) "
+                  f"RETURN id(e) AS id, type(e) AS type, id(a) AS f, id(b) AS t, "
+                  f"properties(e) AS props")
+        rows = self._run(cypher, {"from_id": from_id, "to_id": to_id, "props": properties or {}})
+        if not rows:
+            return None
+        r = rows[0]
+        return GraphEdge(id=r.get("id"), type=r.get("type"), from_id=r.get("f"),
+                         to_id=r.get("t"), properties=r.get("props") or {})
+
+    def get_node(self, node_id):
+        cypher = ("MATCH (n) WHERE id(n) = $id "
+                  "RETURN id(n) AS id, labels(n) AS labels, properties(n) AS props")
+        rows = self._run(cypher, {"id": node_id})
+        return self._node(rows[0]) if rows else None
+
+    def update_node(self, node_id, properties):
+        cypher = ("MATCH (n) WHERE id(n) = $id SET n += $props "
+                  "RETURN id(n) AS id, labels(n) AS labels, properties(n) AS props")
+        rows = self._run(cypher, {"id": node_id, "props": properties or {}})
+        return self._node(rows[0]) if rows else None
+
+    def delete_node(self, node_id):
+        self._run("MATCH (n) WHERE id(n) = $id DETACH DELETE n", {"id": node_id})
+        return True
+
+    def neighbors(self, node_id, direction="both", edge_type=None, limit=100):
+        edge = f":`{edge_type}`" if edge_type else ""
+        pattern = {
+            "out": f"(n)-[{edge}]->(m)",
+            "in": f"(n)<-[{edge}]-(m)",
+            "both": f"(n)-[{edge}]-(m)",
+        }.get(direction, f"(n)-[{edge}]-(m)")
+        cypher = (f"MATCH {pattern} WHERE id(n) = $id "
+                  f"RETURN DISTINCT id(m) AS id, labels(m) AS labels, properties(m) AS props "
+                  f"LIMIT {int(limit)}")
+        return [self._node(r) for r in self._run(cypher, {"id": node_id})]
+
+    def traverse(self, start_id, depth=1, direction="both", edge_type=None, limit=1000):
+        # Cypher variable-length path `[*1..N]` — Neo4j AND Memgraph.
+        edge = f":`{edge_type}`" if edge_type else ""
+        arrow = {"out": f"-[{edge}*1..{int(depth)}]->", "in": f"<-[{edge}*1..{int(depth)}]-",
+                 "both": f"-[{edge}*1..{int(depth)}]-"}.get(direction, f"-[{edge}*1..{int(depth)}]-")
+        cypher = (f"MATCH (n){arrow}(m) WHERE id(n) = $start "
+                  f"RETURN DISTINCT id(m) AS id, labels(m) AS labels, properties(m) AS props "
+                  f"LIMIT {int(limit)}")
+        return [self._node(r) for r in self._run(cypher, {"start": start_id})]
+
+    def close(self):
+        self._driver.close()