mygraph-client 0.1.0__py3-none-any.whl

mygraph/__init__.py

@@ -0,0 +1,46 @@
+"""Python client for the MyGraph server.
+
+    from mygraph import connect
+
+    with connect("localhost", 6660) as db:
+        alice = db.create_node("User", {"name": "Alice"})
+        for user in db.find_nodes("User", {"name": "Alice"}):
+            print(user.id, user.properties)
+
+The client speaks MyGraph protocol v1 (``docs/PROTOCOL.md``) over TCP and
+needs nothing outside the Python standard library.
+"""
+
+from .client import Client, connect
+from .errors import (
+    AlreadyExistsError,
+    ConnectionClosedError,
+    CypherSyntaxError,
+    MyGraphError,
+    NotFoundError,
+    ProtocolError,
+    QueryError,
+    TransactionError,
+)
+from .transaction import Transaction
+from .types import Node, Relationship, Result, Stats
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AlreadyExistsError",
+    "Client",
+    "ConnectionClosedError",
+    "CypherSyntaxError",
+    "MyGraphError",
+    "Node",
+    "NotFoundError",
+    "ProtocolError",
+    "QueryError",
+    "Relationship",
+    "Result",
+    "Stats",
+    "Transaction",
+    "TransactionError",
+    "connect",
+]

mygraph/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+import sys
+
+sys.exit(main())

mygraph/_ops.py

@@ -0,0 +1,195 @@
+"""Node and relationship helpers built on ``run``.
+
+The helpers generate Cypher. Values always travel as parameters. Labels,
+relationship types and property keys are written as backtick-quoted
+identifiers, so any name is safe to pass.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Mapping, Sequence
+
+from .types import Node, Relationship, Result
+
+
+def quote(name: str) -> str:
+    """Backtick-quotes an identifier (label, type or property key)."""
+    if not isinstance(name, str) or not name:
+        raise ValueError(f"invalid identifier: {name!r}")
+    return "`" + name.replace("`", "``") + "`"
+
+
+def _labels(labels: str | Sequence[str] | None) -> str:
+    if labels is None:
+        return ""
+    if isinstance(labels, str):
+        labels = [labels]
+    return "".join(":" + quote(label) for label in labels)
+
+
+def _where(var: str, properties: Mapping[str, Any] | None, params: dict, extra: Iterable[str] = ()) -> str:
+    conds = list(extra)
+    for i, (key, value) in enumerate((properties or {}).items()):
+        if value is None:
+            conds.append(f"{var}.{quote(key)} IS NULL")
+        else:
+            params[f"p{i}"] = value
+            conds.append(f"{var}.{quote(key)} = $p{i}")
+    return " WHERE " + " AND ".join(conds) if conds else ""
+
+
+def _paging(skip: int | None, limit: int | None) -> str:
+    out = ""
+    for word, n in (("SKIP", skip), ("LIMIT", limit)):
+        if n is not None:
+            if isinstance(n, bool) or not isinstance(n, int) or n < 0:
+                raise ValueError(f"{word.lower()} must be a non-negative int")
+            out += f" {word} {n}"
+    return out
+
+
+class CypherOps:
+    """CRUD helpers. Subclasses provide ``run``."""
+
+    def run(self, query: str, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Result:
+        raise NotImplementedError
+
+    # ------------------------------------------------------------ nodes
+
+    def create_node(self, labels: str | Sequence[str] | None = None, properties: Mapping[str, Any] | None = None) -> Node:
+        """Creates a node and returns it."""
+        r = self.run(f"CREATE (n{_labels(labels)}) SET n = $props RETURN n", {"props": dict(properties or {})})
+        return r.value()
+
+    def get_node(self, node_id: int) -> Node | None:
+        """The node with that id, or ``None``."""
+        return self.run("MATCH (n) WHERE id(n) = $id RETURN n", {"id": node_id}).value()
+
+    def find_nodes(
+        self,
+        labels: str | Sequence[str] | None = None,
+        properties: Mapping[str, Any] | None = None,
+        *,
+        skip: int | None = None,
+        limit: int | None = None,
+        order_by: str | None = None,
+        descending: bool = False,
+    ) -> list[Node]:
+        """Nodes with all the given labels whose properties equal the given
+        values (``None`` matches a missing property)."""
+        params: dict[str, Any] = {}
+        q = f"MATCH (n{_labels(labels)}){_where('n', properties, params)} RETURN n"
+        if order_by is not None:
+            q += f" ORDER BY n.{quote(order_by)}" + (" DESC" if descending else "")
+        return self.run(q + _paging(skip, limit), params).values(0)
+
+    def count_nodes(self, labels: str | Sequence[str] | None = None, properties: Mapping[str, Any] | None = None) -> int:
+        params: dict[str, Any] = {}
+        q = f"MATCH (n{_labels(labels)}){_where('n', properties, params)} RETURN count(n)"
+        return self.run(q, params).value()
+
+    def update_node(
+        self,
+        node_id: int,
+        properties: Mapping[str, Any] | None = None,
+        *,
+        replace: bool = False,
+        add_labels: str | Sequence[str] | None = None,
+        remove_labels: str | Sequence[str] | None = None,
+    ) -> Node | None:
+        """Updates a node and returns it, or ``None`` if it does not exist.
+
+        By default ``properties`` are merged (``SET n += $props``; a ``None``
+        value removes that property). With ``replace=True`` they replace all
+        existing properties (``SET n = $props``).
+        """
+        clauses = []
+        params: dict[str, Any] = {"id": node_id}
+        if properties is not None or replace:
+            params["props"] = dict(properties or {})
+            clauses.append("SET n = $props" if replace else "SET n += $props")
+        if add_labels:
+            clauses.append(f"SET n{_labels(add_labels)}")
+        if remove_labels:
+            clauses.append(f"REMOVE n{_labels(remove_labels)}")
+        q = "MATCH (n) WHERE id(n) = $id " + " ".join(clauses) + " RETURN n"
+        return self.run(q, params).value()
+
+    def delete_node(self, node_id: int, *, detach: bool = True) -> bool:
+        """Deletes a node. With ``detach=True`` (default) its relationships
+        are deleted too; otherwise a node with relationships raises.
+        Returns whether a node was deleted."""
+        verb = "DETACH DELETE" if detach else "DELETE"
+        r = self.run(f"MATCH (n) WHERE id(n) = $id {verb} n", {"id": node_id})
+        return r.stats.nodes_deleted > 0
+
+    def delete_nodes(
+        self,
+        labels: str | Sequence[str] | None = None,
+        properties: Mapping[str, Any] | None = None,
+        *,
+        detach: bool = True,
+    ) -> int:
+        """Deletes every matching node. Returns how many were deleted."""
+        params: dict[str, Any] = {}
+        verb = "DETACH DELETE" if detach else "DELETE"
+        r = self.run(f"MATCH (n{_labels(labels)}){_where('n', properties, params)} {verb} n", params)
+        return r.stats.nodes_deleted
+
+    # ------------------------------------------------------------ relationships
+
+    def create_relationship(
+        self,
+        start_id: int,
+        end_id: int,
+        rel_type: str,
+        properties: Mapping[str, Any] | None = None,
+    ) -> Relationship | None:
+        """Creates ``(start)-[:rel_type]->(end)`` and returns it, or ``None``
+        if either node does not exist."""
+        q = (
+            "MATCH (a) WHERE id(a) = $start MATCH (b) WHERE id(b) = $end "
+            f"CREATE (a)-[r:{quote(rel_type)}]->(b) SET r = $props RETURN r"
+        )
+        params = {"start": start_id, "end": end_id, "props": dict(properties or {})}
+        return self.run(q, params).value()
+
+    def get_relationship(self, rel_id: int) -> Relationship | None:
+        return self.run("MATCH ()-[r]->() WHERE id(r) = $id RETURN r", {"id": rel_id}).value()
+
+    def find_relationships(
+        self,
+        rel_type: str | None = None,
+        properties: Mapping[str, Any] | None = None,
+        *,
+        start_id: int | None = None,
+        end_id: int | None = None,
+        skip: int | None = None,
+        limit: int | None = None,
+    ) -> list[Relationship]:
+        """Relationships of a type (any if ``None``) whose properties equal
+        the given values, optionally from/to specific nodes."""
+        params: dict[str, Any] = {}
+        extra = []
+        if start_id is not None:
+            params["start"] = start_id
+            extra.append("id(a) = $start")
+        if end_id is not None:
+            params["end"] = end_id
+            extra.append("id(b) = $end")
+        t = f":{quote(rel_type)}" if rel_type else ""
+        q = f"MATCH (a)-[r{t}]->(b){_where('r', properties, params, extra)} RETURN r"
+        return self.run(q + _paging(skip, limit), params).values(0)
+
+    def update_relationship(
+        self, rel_id: int, properties: Mapping[str, Any], *, replace: bool = False
+    ) -> Relationship | None:
+        """Merges (or with ``replace=True`` replaces) a relationship's
+        properties. Returns it, or ``None`` if it does not exist."""
+        op = "=" if replace else "+="
+        q = f"MATCH ()-[r]->() WHERE id(r) = $id SET r {op} $props RETURN r"
+        return self.run(q, {"id": rel_id, "props": dict(properties)}).value()
+
+    def delete_relationship(self, rel_id: int) -> bool:
+        r = self.run("MATCH ()-[r]->() WHERE id(r) = $id DELETE r", {"id": rel_id})
+        return r.stats.relationships_deleted > 0

mygraph/_protocol.py

@@ -0,0 +1,222 @@
+"""MyGraph protocol v1: framing and value codec (see docs/PROTOCOL.md).
+
+Frame header, little-endian: u8 version, u8 message type, u32 request id,
+u32 payload length. The payload is one encoded MAP (count + key/value pairs,
+no tag).
+"""
+
+from __future__ import annotations
+
+import socket
+import struct
+from typing import Any
+
+from .errors import ConnectionClosedError, ProtocolError
+from .types import Node, Relationship
+
+PROTOCOL_VERSION = 1
+MAX_PAYLOAD = 64 * 1024 * 1024
+MAX_DEPTH = 64
+
+_HEADER = struct.Struct("<BBII")
+_U32 = struct.Struct("<I")
+_U64 = struct.Struct("<Q")
+_I64 = struct.Struct("<q")
+_F64 = struct.Struct("<d")
+
+# Message types
+HELLO = 0x01
+AUTH = 0x02
+QUERY = 0x10
+QUERY_RESULT = 0x11
+BEGIN = 0x20
+COMMIT = 0x21
+ROLLBACK = 0x22
+OK = 0x23
+PING = 0x30
+PONG = 0x31
+GOODBYE = 0x40
+ERROR = 0x7F
+
+# Value tags
+T_NULL, T_BOOL, T_INT, T_FLOAT, T_STRING, T_BYTES, T_LIST, T_MAP, T_NODE, T_REL = range(10)
+
+_I64_MIN, _I64_MAX = -(2**63), 2**63 - 1
+
+
+# ---------------------------------------------------------------- encoding
+
+
+def _len(buf: bytearray, n: int) -> None:
+    if n > 0xFFFFFFFF:
+        raise ValueError("value too large to encode")
+    buf += _U32.pack(n)
+
+
+def _bytes(buf: bytearray, b: bytes) -> None:
+    _len(buf, len(b))
+    buf += b
+
+
+def encode_value(buf: bytearray, v: Any, depth: int = 0) -> None:
+    if depth > MAX_DEPTH:
+        raise ValueError("value nesting too deep")
+    if v is None:
+        buf.append(T_NULL)
+    elif isinstance(v, bool):  # before int: bool is a subclass of int
+        buf.append(T_BOOL)
+        buf.append(1 if v else 0)
+    elif isinstance(v, int):
+        if not _I64_MIN <= v <= _I64_MAX:
+            raise ValueError(f"integer {v} does not fit in 64 bits")
+        buf.append(T_INT)
+        buf += _I64.pack(v)
+    elif isinstance(v, float):
+        buf.append(T_FLOAT)
+        buf += _F64.pack(v)
+    elif isinstance(v, str):
+        buf.append(T_STRING)
+        _bytes(buf, v.encode("utf-8"))
+    elif isinstance(v, (bytes, bytearray, memoryview)):
+        buf.append(T_BYTES)
+        _bytes(buf, bytes(v))
+    elif isinstance(v, (list, tuple)):
+        buf.append(T_LIST)
+        _len(buf, len(v))
+        for item in v:
+            encode_value(buf, item, depth + 1)
+    elif isinstance(v, dict):
+        buf.append(T_MAP)
+        encode_map(buf, v, depth + 1)
+    elif isinstance(v, (Node, Relationship)):
+        raise TypeError(f"{type(v).__name__} values cannot be sent as parameters; pass its id instead")
+    else:
+        raise TypeError(f"cannot send a value of type {type(v).__name__}")
+
+
+def encode_map(buf: bytearray, m: dict, depth: int = 0) -> None:
+    _len(buf, len(m))
+    for k, v in m.items():
+        if not isinstance(k, str):
+            raise TypeError(f"map keys must be str, got {type(k).__name__}")
+        _bytes(buf, k.encode("utf-8"))
+        encode_value(buf, v, depth)
+
+
+def encode_payload(payload: dict) -> bytes:
+    buf = bytearray()
+    encode_map(buf, payload)
+    return bytes(buf)
+
+
+# ---------------------------------------------------------------- decoding
+
+
+class Decoder:
+    def __init__(self, data: bytes):
+        self.data = memoryview(data)
+        self.pos = 0
+
+    def _take(self, n: int) -> memoryview:
+        if len(self.data) - self.pos < n:
+            raise ProtocolError("unexpected end of payload")
+        s = self.data[self.pos : self.pos + n]
+        self.pos += n
+        return s
+
+    def _u8(self) -> int:
+        return self._take(1)[0]
+
+    def _u32(self) -> int:
+        return _U32.unpack(self._take(4))[0]
+
+    def _u64(self) -> int:
+        return _U64.unpack(self._take(8))[0]
+
+    def _count(self) -> int:
+        n = self._u32()
+        if n > len(self.data) - self.pos:
+            raise ProtocolError("element count exceeds payload size")
+        return n
+
+    def _str(self) -> str:
+        n = self._u32()
+        try:
+            return str(self._take(n), "utf-8")
+        except UnicodeDecodeError as e:
+            raise ProtocolError("invalid UTF-8 string") from e
+
+    def value(self, depth: int = 0) -> Any:
+        if depth > MAX_DEPTH:
+            raise ProtocolError("value nesting too deep")
+        t = self._u8()
+        if t == T_NULL:
+            return None
+        if t == T_BOOL:
+            return self._u8() != 0
+        if t == T_INT:
+            return _I64.unpack(self._take(8))[0]
+        if t == T_FLOAT:
+            return _F64.unpack(self._take(8))[0]
+        if t == T_STRING:
+            return self._str()
+        if t == T_BYTES:
+            return bytes(self._take(self._u32()))
+        if t == T_LIST:
+            return [self.value(depth + 1) for _ in range(self._count())]
+        if t == T_MAP:
+            return self.map(depth + 1)
+        if t == T_NODE:
+            node_id = self._u64()
+            labels = [self._str() for _ in range(self._count())]
+            return Node(node_id, labels, self.map(depth + 1))
+        if t == T_REL:
+            rel_id, start, end = self._u64(), self._u64(), self._u64()
+            return Relationship(rel_id, start, end, self._str(), self.map(depth + 1))
+        raise ProtocolError(f"unknown value tag {t}")
+
+    def map(self, depth: int = 0) -> dict:
+        out = {}
+        for _ in range(self._count()):
+            k = self._str()
+            out[k] = self.value(depth)
+        return out
+
+
+def decode_payload(data: bytes) -> dict:
+    d = Decoder(data)
+    m = d.map()
+    if d.pos != len(d.data):
+        raise ProtocolError("trailing bytes after payload")
+    return m
+
+
+# ---------------------------------------------------------------- framing
+
+
+def encode_frame(message_type: int, request_id: int, payload: bytes) -> bytes:
+    if len(payload) > MAX_PAYLOAD:
+        raise ValueError("payload too large")
+    return _HEADER.pack(PROTOCOL_VERSION, message_type, request_id, len(payload)) + payload
+
+
+def _recv_exact(sock: socket.socket, n: int) -> bytes:
+    chunks = []
+    while n:
+        chunk = sock.recv(min(n, 1 << 20))
+        if not chunk:
+            raise ConnectionClosedError("connection closed by the server")
+        chunks.append(chunk)
+        n -= len(chunk)
+    return b"".join(chunks)
+
+
+def read_frame(sock: socket.socket) -> tuple[int, int, bytes]:
+    """Reads one frame: ``(message_type, request_id, payload)``."""
+    version, message_type, request_id, length = _HEADER.unpack(_recv_exact(sock, _HEADER.size))
+    if version != PROTOCOL_VERSION:
+        raise ProtocolError(f"server answered with protocol version {version}, expected {PROTOCOL_VERSION}")
+    if length > MAX_PAYLOAD:
+        raise ProtocolError(f"payload of {length} bytes exceeds the limit")
+    return message_type, request_id, _recv_exact(sock, length) if length else b""
+

mygraph/cli.py

@@ -0,0 +1,78 @@
+"""``mygraph-client`` command: run Cypher against a MyGraph server.
+
+    mygraph-client [--host HOST] [--port PORT] [--json] "MATCH (n) RETURN n;"
+    echo "MATCH (n) RETURN n;" | mygraph-client
+
+Without a query argument the script is read from standard input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import sys
+from typing import Any
+
+from .client import DEFAULT_PORT, connect
+from .errors import MyGraphError
+from .types import Node, Relationship
+
+
+def _plain(value: Any) -> Any:
+    if isinstance(value, (Node, Relationship)):
+        return dataclasses.asdict(value)
+    if isinstance(value, list):
+        return [_plain(v) for v in value]
+    if isinstance(value, dict):
+        return {k: _plain(v) for k, v in value.items()}
+    return value
+
+
+def _show(value: Any) -> str:
+    if isinstance(value, Node):
+        labels = "".join(f":{label}" for label in value.labels)
+        return f"({value.id}{labels} {json.dumps(value.properties, ensure_ascii=False)})"
+    if isinstance(value, Relationship):
+        props = json.dumps(value.properties, ensure_ascii=False)
+        return f"({value.start_node})-[{value.id}:{value.type} {props}]->({value.end_node})"
+    if isinstance(value, str):
+        return value
+    return json.dumps(_plain(value), ensure_ascii=False)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="mygraph-client", description="Run Cypher against a MyGraph server."
+    )
+    parser.add_argument("query", nargs="?", help="Cypher script (default: read stdin)")
+    parser.add_argument("--host", default="localhost")
+    parser.add_argument("--port", type=int, default=DEFAULT_PORT)
+    parser.add_argument("--json", action="store_true", help="print records as JSON lines")
+    args = parser.parse_args(argv)
+
+    query = args.query if args.query is not None else sys.stdin.read()
+    if not query.strip():
+        parser.error("empty query")
+
+    try:
+        with connect(args.host, args.port) as db:
+            result = db.run(query)
+    except MyGraphError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        for record in result:
+            print(json.dumps(_plain(record), ensure_ascii=False))
+    else:
+        if result.columns:
+            print("\t".join(result.columns))
+        for row in result.rows:
+            print("\t".join(_show(v) for v in row))
+        print(f"({len(result)} rows)", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mygraph/client.py

@@ -0,0 +1,179 @@
+"""Connection to a MyGraph server."""
+
+from __future__ import annotations
+
+import socket
+import threading
+from typing import Any, Mapping
+
+from . import _protocol as p
+from ._ops import CypherOps, quote
+from .errors import ConnectionClosedError, ProtocolError, TransactionError, error_from_payload
+from .transaction import Transaction
+from .types import Result, Stats
+
+DEFAULT_PORT = 6660
+
+
+class Client(CypherOps):
+    """One TCP connection to a MyGraph server.
+
+    Requests on one client are sent one at a time (a lock serializes them),
+    so a client can be shared between threads, but they all share its current
+    database and its open transaction. Use one client per thread for
+    independent work.
+    """
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port: int = DEFAULT_PORT,
+        *,
+        user: str | None = None,
+        password: str | None = None,
+        timeout: float | None = 30.0,
+        client_name: str = "mygraph-python/0.1.0",
+    ):
+        self.host, self.port = host, port
+        self._lock = threading.Lock()
+        self._next_id = 1
+        self._transaction: Transaction | None = None
+        try:
+            self._sock: socket.socket | None = socket.create_connection((host, port), timeout=timeout)
+        except OSError as e:
+            raise ConnectionClosedError(f"cannot connect to {host}:{port}: {e}") from e
+        self._sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+        try:
+            hello = self._request(p.HELLO, {"client": client_name}, expect=p.HELLO)
+            self.server_info: dict[str, Any] = hello
+            if user is not None:
+                self._request(p.AUTH, {"user": user, "password": password or ""})
+        except BaseException:
+            self._close_socket()
+            raise
+
+    # ------------------------------------------------------------ transport
+
+    def _request(self, message_type: int, payload: dict, expect: int = p.OK) -> dict:
+        with self._lock:
+            if self._sock is None:
+                raise ConnectionClosedError("the client is closed")
+            request_id = self._next_id
+            self._next_id = (self._next_id + 1) & 0xFFFFFFFF or 1
+            try:
+                self._sock.sendall(p.encode_frame(message_type, request_id, p.encode_payload(payload)))
+                kind, response_id, body = p.read_frame(self._sock)
+            except (OSError, ConnectionClosedError) as e:
+                # The stream position is unknown now; the connection cannot be reused.
+                self._close_socket()
+                if isinstance(e, ConnectionClosedError):
+                    raise
+                raise ConnectionClosedError(f"connection lost: {e}") from e
+            except ProtocolError:
+                self._close_socket()
+                raise
+        if response_id != request_id:
+            self.close()
+            raise ProtocolError(f"response id {response_id} does not match request id {request_id}")
+        data = p.decode_payload(body)
+        if kind == p.ERROR:
+            raise error_from_payload(data)
+        if kind != expect:
+            raise ProtocolError(f"unexpected message type 0x{kind:02x} (expected 0x{expect:02x})")
+        return data
+
+    def _close_socket(self) -> None:
+        sock, self._sock = self._sock, None
+        if sock is not None:
+            try:
+                sock.close()
+            except OSError:
+                pass
+
+    # ------------------------------------------------------------ queries
+
+    def run(self, query: str, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Result:
+        """Runs a Cypher script (one or more ``;``-separated statements) and
+        returns the last statement's rows. Parameters are referenced as
+        ``$name`` and may be given as a dict, keyword arguments, or both."""
+        all_params = {**(params or {}), **kwargs}
+        data = self._request(p.QUERY, {"query": query, "params": all_params}, expect=p.QUERY_RESULT)
+        return Result(
+            columns=list(data.get("columns", [])),
+            rows=list(data.get("rows", [])),
+            stats=Stats.from_map(data.get("stats", {})),
+            database=data.get("database", ""),
+            schema=data.get("schema", ""),
+            in_transaction=bool(data.get("in_transaction", False)),
+        )
+
+    def transaction(self) -> Transaction:
+        """Begins an explicit transaction (``BEGIN``)."""
+        if self._transaction is not None and self._transaction.is_open:
+            raise TransactionError("Transaction", "a transaction is already open on this client")
+        self._request(p.BEGIN, {})
+        self._transaction = Transaction(self)
+        return self._transaction
+
+    begin = transaction
+
+    def ping(self) -> None:
+        self._request(p.PING, {}, expect=p.PONG)
+
+    # ------------------------------------------------------------ databases and schemas
+
+    def use_database(self, name: str) -> None:
+        self.run(f"USE DATABASE {quote(name)}")
+
+    def use_schema(self, name: str) -> None:
+        self.run(f"USE SCHEMA {quote(name)}")
+
+    def create_database(self, name: str, *, if_not_exists: bool = True) -> None:
+        self.run(f"CREATE DATABASE {'IF NOT EXISTS ' if if_not_exists else ''}{quote(name)}")
+
+    def drop_database(self, name: str, *, if_exists: bool = True) -> None:
+        self.run(f"DROP DATABASE {'IF EXISTS ' if if_exists else ''}{quote(name)}")
+
+    def create_schema(self, name: str, *, if_not_exists: bool = True) -> None:
+        self.run(f"CREATE SCHEMA {'IF NOT EXISTS ' if if_not_exists else ''}{quote(name)}")
+
+    def drop_schema(self, name: str, *, if_exists: bool = True) -> None:
+        self.run(f"DROP SCHEMA {'IF EXISTS ' if if_exists else ''}{quote(name)}")
+
+    def databases(self) -> list[dict[str, Any]]:
+        return self.run("SHOW DATABASES").records()
+
+    def schemas(self) -> list[dict[str, Any]]:
+        return self.run("SHOW SCHEMAS").records()
+
+    # ------------------------------------------------------------ lifecycle
+
+    @property
+    def closed(self) -> bool:
+        return self._sock is None
+
+    def close(self) -> None:
+        """Says GOODBYE and closes the socket. An open transaction is rolled
+        back by the server."""
+        if self._sock is None:
+            return
+        try:
+            self._request(p.GOODBYE, {})
+        except Exception:
+            pass
+        self._close_socket()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        state = "closed" if self.closed else "open"
+        return f"<mygraph.Client {self.host}:{self.port} {state}>"
+
+
+def connect(host: str = "localhost", port: int = DEFAULT_PORT, **kwargs: Any) -> Client:
+    """Opens a connection. Same arguments as :class:`Client`."""
+    return Client(host, port, **kwargs)

mygraph/errors.py

@@ -0,0 +1,62 @@
+"""Exceptions raised by the client."""
+
+from __future__ import annotations
+
+
+class MyGraphError(Exception):
+    """Base class for every error raised by this library."""
+
+
+class ProtocolError(MyGraphError):
+    """The server sent something that does not follow protocol v1, or
+    rejected a malformed request."""
+
+
+class ConnectionClosedError(MyGraphError):
+    """The connection is closed or was lost."""
+
+
+class QueryError(MyGraphError):
+    """The server could not run a statement. ``code`` is the engine error
+    kind (``Syntax``, ``NotFound``, ``Transaction``, ``Type``, ...)."""
+
+    def __init__(self, code: str, message: str, line: int | None = None, column: int | None = None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.line = line
+        self.column = column
+
+
+class CypherSyntaxError(QueryError):
+    """Invalid Cypher. ``line`` and ``column`` point at the problem."""
+
+
+class NotFoundError(QueryError):
+    """A database, schema or other named object does not exist."""
+
+
+class AlreadyExistsError(QueryError):
+    """A database or schema with that name already exists."""
+
+
+class TransactionError(QueryError):
+    """Invalid transaction use, such as COMMIT with no open transaction."""
+
+
+_BY_CODE: dict[str, type[QueryError]] = {
+    "Syntax": CypherSyntaxError,
+    "NotFound": NotFoundError,
+    "AlreadyExists": AlreadyExistsError,
+    "Transaction": TransactionError,
+}
+
+
+def error_from_payload(payload: dict) -> MyGraphError:
+    """Builds the exception for an ERROR message payload."""
+    code = str(payload.get("code", "Unknown"))
+    message = str(payload.get("message", "unknown error"))
+    if code == "Protocol":
+        return ProtocolError(message)
+    cls = _BY_CODE.get(code, QueryError)
+    return cls(code, message, payload.get("line"), payload.get("column"))

mygraph/transaction.py

@@ -0,0 +1,67 @@
+"""Explicit transactions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Mapping
+
+from . import _protocol as p
+from ._ops import CypherOps
+from .errors import TransactionError
+from .types import Result
+
+if TYPE_CHECKING:
+    from .client import Client
+
+
+class Transaction(CypherOps):
+    """A transaction on one connection. Use it as a context manager:
+
+        with db.transaction() as tx:
+            tx.create_node("User", {"name": "Carol"})
+
+    Leaving the block commits; an exception rolls back. While it is open,
+    every statement on the same client runs inside it. In MyGraph v0.1 an open
+    transaction blocks all other connections, so keep it short.
+    """
+
+    def __init__(self, client: "Client"):
+        self._client = client
+        self._open = True
+
+    @property
+    def is_open(self) -> bool:
+        return self._open
+
+    def run(self, query: str, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Result:
+        self._check()
+        return self._client.run(query, params, **kwargs)
+
+    def commit(self) -> None:
+        self._finish(p.COMMIT)
+
+    def rollback(self) -> None:
+        self._finish(p.ROLLBACK)
+
+    def _check(self) -> None:
+        if not self._open:
+            raise TransactionError("Transaction", "the transaction is already finished")
+
+    def _finish(self, message_type: int) -> None:
+        self._check()
+        self._open = False
+        self._client._request(message_type, {})
+        self._client._transaction = None
+
+    def __enter__(self) -> "Transaction":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if not self._open:
+            return
+        if exc_type is None:
+            self.commit()
+        else:
+            try:
+                self.rollback()
+            except Exception:
+                pass  # keep the original exception

mygraph/types.py

@@ -0,0 +1,103 @@
+"""Values returned by queries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterator
+
+
+@dataclass(frozen=True)
+class Node:
+    id: int
+    labels: list[str] = field(default_factory=list)
+    properties: dict[str, Any] = field(default_factory=dict)
+
+    def __getitem__(self, key: str) -> Any:
+        return self.properties[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.properties.get(key, default)
+
+
+@dataclass(frozen=True)
+class Relationship:
+    id: int
+    start_node: int
+    end_node: int
+    type: str
+    properties: dict[str, Any] = field(default_factory=dict)
+
+    def __getitem__(self, key: str) -> Any:
+        return self.properties[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.properties.get(key, default)
+
+
+@dataclass(frozen=True)
+class Stats:
+    """Update counters of a statement."""
+
+    nodes_created: int = 0
+    nodes_deleted: int = 0
+    relationships_created: int = 0
+    relationships_deleted: int = 0
+    properties_set: int = 0
+    labels_added: int = 0
+    labels_removed: int = 0
+
+    @classmethod
+    def from_map(cls, m: dict[str, Any]) -> "Stats":
+        known = cls.__dataclass_fields__
+        return cls(**{k: int(v) for k, v in m.items() if k in known})
+
+    @property
+    def contains_updates(self) -> bool:
+        return self != Stats()
+
+
+@dataclass
+class Result:
+    """Rows of a statement plus its update counters.
+
+    ``database`` and ``schema`` are the connection's current ones after the
+    statement ran (so ``USE DATABASE`` is visible here).
+    """
+
+    columns: list[str]
+    rows: list[list[Any]]
+    stats: Stats
+    database: str = ""
+    schema: str = ""
+    in_transaction: bool = False
+
+    def __len__(self) -> int:
+        return len(self.rows)
+
+    def __iter__(self) -> Iterator[dict[str, Any]]:
+        return iter(self.records())
+
+    def records(self) -> list[dict[str, Any]]:
+        """Rows as ``{column: value}`` dicts."""
+        return [dict(zip(self.columns, row)) for row in self.rows]
+
+    def single(self) -> dict[str, Any] | None:
+        """The only record, ``None`` if there are no rows. Raises
+        ``ValueError`` if there is more than one."""
+        if not self.rows:
+            return None
+        if len(self.rows) > 1:
+            raise ValueError(f"expected at most one row, got {len(self.rows)}")
+        return self.records()[0]
+
+    def value(self, column: str | int = 0, default: Any = None) -> Any:
+        """A value of the first row, by column name or index."""
+        if not self.rows:
+            return default
+        idx = column if isinstance(column, int) else self.columns.index(column)
+        return self.rows[0][idx]
+
+    def values(self, column: str | int = 0) -> list[Any]:
+        """One column of every row."""
+        idx = column if isinstance(column, int) else self.columns.index(column)
+        return [row[idx] for row in self.rows]

mygraph_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: mygraph-client
+Version: 0.1.0
+Summary: Python client for the MyGraph server (protocol v1)
+Author: Julio Contreras
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/julioacontreras/my-graph
+Project-URL: Repository, https://github.com/julioacontreras/my-graph
+Project-URL: Issues, https://github.com/julioacontreras/my-graph/issues
+Keywords: graph,database,client,mygraph
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mygraph-client (Python)
+
+Python client for the MyGraph server. It talks to the server over TCP using
+MyGraph protocol v1 ([docs/PROTOCOL.md](https://github.com/julioacontreras/my-graph/blob/main/docs/PROTOCOL.md))
+and needs only the standard library (Python ≥ 3.10).
+
+## Install
+
+```bash
+pip install mygraph-client
+```
+
+The import name is `mygraph`:
+
+```python
+import mygraph
+```
+
+For development, from the repository root:
+
+```bash
+pip install -e python/
+```
+
+## Start a server
+
+```bash
+cargo run -p mygraph-server -- start                      # 127.0.0.1:6660, in memory
+cargo run -p mygraph-server -- start --port 6660 --data ./data
+```
+
+## Command line client
+
+`pip install` also installs the `mygraph-client` command. With a server on
+port 6660 (for example `docker compose up -d`):
+
+```bash
+mygraph-client "MATCH (n) RETURN n;"
+```
+
+```text
+n
+(0:User {"age": 25, "name": "Alice"})
+(1:User {"name": "Bob"})
+```
+
+Without a query argument the script is read from stdin, so multi-line
+queries work too:
+
+```bash
+mygraph-client <<'CYPHER'
+MATCH (n)
+RETURN n;
+CYPHER
+```
+
+| Option | Default | |
+|---|---|---|
+| `--host HOST` | `localhost` | Server host |
+| `--port PORT` | `6660` | Server port |
+| `--json` | off | One JSON object per record |
+
+Without installing, `python3 -m mygraph` does the same. On error it prints
+the message to stderr and exits with status 1.
+
+## Usage
+
+```python
+import mygraph
+
+with mygraph.connect("localhost", 6660) as db:
+    # Any Cypher, with parameters as a dict and/or keyword arguments
+    r = db.run("MATCH (u:User) WHERE u.age > $min RETURN u.name AS name", min=18)
+    for record in r:                # records are dicts
+        print(record["name"])
+    r.value("name"); r.values("name"); r.single(); r.stats.nodes_created
+
+    # Create
+    alice = db.create_node("User", {"name": "Alice", "age": 25})          # -> Node
+    bob = db.create_node(["User", "Admin"], {"name": "Bob"})
+    knows = db.create_relationship(alice.id, bob.id, "KNOWS", {"since": 2020})
+
+    # Search
+    db.get_node(alice.id)                                                 # Node | None
+    db.find_nodes("User", {"name": "Alice"}, order_by="age", limit=10)    # list[Node]
+    db.count_nodes("User")
+    db.find_relationships("KNOWS", start_id=alice.id)                     # list[Relationship]
+
+    # Update
+    db.update_node(alice.id, {"age": 26})                  # merge: SET n += $props (None removes a key)
+    db.update_node(alice.id, {"name": "Alicia"}, replace=True)   # SET n = $props
+    db.update_node(alice.id, add_labels="VIP", remove_labels="Admin")
+    db.update_relationship(knows.id, {"since": 2021})
+
+    # Delete
+    db.delete_relationship(knows.id)
+    db.delete_node(alice.id)                      # DETACH DELETE by default
+    db.delete_nodes("User", {"name": "Bob"})     # returns how many
+
+    # Transactions: commit on exit, rollback on exception
+    with db.transaction() as tx:
+        tx.create_node("User", {"name": "Carol"})
+        tx.run("MATCH (u:User {name: 'Carol'}) SET u.vip = true")
+
+    # Databases and schemas (the current one is per connection)
+    db.create_database("shop"); db.use_database("shop"); db.databases()
+```
+
+`Node` has `id`, `labels`, `properties` (and `node["key"]`). `Relationship`
+has `id`, `start_node`, `end_node`, `type`, `properties`.
+
+Helpers write labels, types and property keys as backtick-quoted
+identifiers, and always send values as parameters, so user input is never
+spliced into the query text.
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `CypherSyntaxError` | Invalid Cypher (`.line`, `.column`) |
+| `NotFoundError`, `AlreadyExistsError` | Unknown or duplicate database/schema |
+| `TransactionError` | e.g. COMMIT with no open transaction |
+| `QueryError` | Base class of the above; `.code` holds the engine error kind |
+| `ProtocolError` | The server or the client broke protocol v1 |
+| `ConnectionClosedError` | Cannot connect, or the connection was lost/closed |
+
+An error in a statement does not close the connection.
+
+## Notes for MyGraph v0.1
+
+- An open transaction blocks every other connection until it commits or rolls
+  back. Keep transactions short.
+- While a transaction is open, everything sent on that client runs inside it.
+- A client serializes its requests with a lock. Threads that share one
+  client also share its current database and transaction, so use one client
+  per thread for independent work.
+- `AUTH` is accepted but not checked yet (no users or roles on the server).
+
+## Tests
+
+```bash
+cd python
+python3 -m unittest discover -s tests -t .
+```
+
+The integration tests build `mygraph-server` with cargo and start it on a
+free port. Set `MYGRAPH_SERVER_BIN` to use an existing binary instead.

mygraph_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+mygraph/__init__.py,sha256=y9ItbM6lp7fLv4gD6sKAhYcyJ1ieVpvakFBzoIUQEKk,1060
+mygraph/__main__.py,sha256=xs0ncFDq0tEcmLfLq5Gtp9GeSVyV5Mht4fmq8rIFHTg,51
+mygraph/_ops.py,sha256=I-305JWdJamIFMzymECl7CivHZUOTsRo-AgQgl5z2iY,7988
+mygraph/_protocol.py,sha256=w4hNEcmL-SsZsEXZoWzOpPwSG-FPLB0oCffnmcmzP2k,6706
+mygraph/cli.py,sha256=FG_0lK2hieMNsTFB8LGJICeoRi33qSGdXyPKJ0hmg0g,2556
+mygraph/client.py,sha256=a-FdfFp5RJWLSQmhYwy-TS3TggrAKzptfehe8qXV8F8,6924
+mygraph/errors.py,sha256=ZuNi3t9zw351mZilU6uQawrH37hMj73bqfbMNK1Ir4k,1853
+mygraph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mygraph/transaction.py,sha256=bmaxkpRBSeGXX09GPbRgJ07BJcNY235q4GIGpxKctcQ,1876
+mygraph/types.py,sha256=ndTaOKZFg3OH69sDSjyIKa5fGTpJT6AJR4tcIX2YR3A,2981
+mygraph_client-0.1.0.dist-info/licenses/LICENSE,sha256=9IeScmE-6XAFux8NdJsLpTQ8cb4IfrqzEj8cVSrPfUE,1072
+mygraph_client-0.1.0.dist-info/METADATA,sha256=pFr7x3VI4YeRiTtzDOwbZQ4YcfvwOYjEtiYIyux4N5w,5447
+mygraph_client-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+mygraph_client-0.1.0.dist-info/entry_points.txt,sha256=2MIOzdJhMB0bcleRgslHNn73iPpE_eh7GSGn3PFmM28,52
+mygraph_client-0.1.0.dist-info/top_level.txt,sha256=uSRT9RPr435_xnYwe6T1aYDGjTUD3JuWLH9bCtudRKo,8
+mygraph_client-0.1.0.dist-info/RECORD,,

mygraph_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mygraph_client-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mygraph-client = mygraph.cli:main

mygraph_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julio Contreras
+
+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.

mygraph_client-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mygraph