mygraph-client 0.1.0__tar.gz

mygraph_client-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,147 @@
+# 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/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_client-0.1.0/mygraph/__main__.py

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

mygraph_client-0.1.0/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