strgraph 1.1.0__tar.gz

strgraph-1.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: strgraph
+Version: 1.1.0
+Summary: Python client for StratiGraph — Yjs real-time collaboration via Node.js sidecar
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+
+# stratigraph-sync
+
+Python client for `@stratigraph/sync` — real-time multi-user editing powered by Yjs CRDTs.
+
+Connects to the `sync-sidecar` Node.js binary over stdio JSON-RPC. Requires Node.js to be installed.
+
+## Quick Start
+
+```python
+from stratigraph_sync import SyncClient, InitConfig
+
+client = SyncClient()
+snapshot = client.init(InitConfig(room_id="trench-5-west"))
+print(snapshot.data)  # {"contexts": {}, "observations": {}, ...}
+
+# Register event handlers
+def on_change(msg):
+    print(f"Remote change: {msg}")
+
+client.on("remote_patch", on_change)
+
+# Read and write data
+client.add("contexts", {"id": "ctx-1", "type": "fill", "description": "Clay layer"})
+client.patch("contexts", "ctx-1", {"description": "Sandy clay"})
+all_contexts = client.query("contexts")
+single = client.query("contexts", "ctx-1")
+full = client.snapshot()
+
+client.leave()
+client.close()
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `remote_patch` | `{collection, id, fields, by}` | Remote document update |
+| `remote_delete` | `{collection, id, by}` | Remote document deletion |
+| `remote_add` | `{collection, document, by}` | Remote document addition |
+| `awareness` | `{users: [...]}` | User presence update |
+| `sync_status` | `{state, pending}` | Connection status change |

strgraph-1.1.0/README.md

@@ -0,0 +1,41 @@
+# stratigraph-sync
+
+Python client for `@stratigraph/sync` — real-time multi-user editing powered by Yjs CRDTs.
+
+Connects to the `sync-sidecar` Node.js binary over stdio JSON-RPC. Requires Node.js to be installed.
+
+## Quick Start
+
+```python
+from stratigraph_sync import SyncClient, InitConfig
+
+client = SyncClient()
+snapshot = client.init(InitConfig(room_id="trench-5-west"))
+print(snapshot.data)  # {"contexts": {}, "observations": {}, ...}
+
+# Register event handlers
+def on_change(msg):
+    print(f"Remote change: {msg}")
+
+client.on("remote_patch", on_change)
+
+# Read and write data
+client.add("contexts", {"id": "ctx-1", "type": "fill", "description": "Clay layer"})
+client.patch("contexts", "ctx-1", {"description": "Sandy clay"})
+all_contexts = client.query("contexts")
+single = client.query("contexts", "ctx-1")
+full = client.snapshot()
+
+client.leave()
+client.close()
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `remote_patch` | `{collection, id, fields, by}` | Remote document update |
+| `remote_delete` | `{collection, id, by}` | Remote document deletion |
+| `remote_add` | `{collection, document, by}` | Remote document addition |
+| `awareness` | `{users: [...]}` | User presence update |
+| `sync_status` | `{state, pending}` | Connection status change |

strgraph-1.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "strgraph"
+version = "1.1.0"
+description = "Python client for StratiGraph — Yjs real-time collaboration via Node.js sidecar"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

strgraph-1.1.0/setup.cfg

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

strgraph-1.1.0/stratigraph_sync/__init__.py

@@ -0,0 +1,4 @@
+from .client import SyncClient
+from .models import InitConfig, SyncStatus, AwarenessUser, RemoteChange, StateSnapshot
+
+__all__ = ["SyncClient", "InitConfig", "SyncStatus", "AwarenessUser", "RemoteChange", "StateSnapshot"]

strgraph-1.1.0/stratigraph_sync/client.py

@@ -0,0 +1,209 @@
+"""
+SyncClient — spawns sync-sidecar Node.js binary, communicates via stdio JSON-RPC.
+
+Usage:
+    client = SyncClient()
+    client.init(InitConfig(room_id="my-room"))
+    client.patch("contexts", "ctx-1", {"description": "new text"})
+    snapshot = client.snapshot()
+    client.leave()
+"""
+
+import json
+import subprocess
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from queue import Queue
+from typing import Any, Callable, Optional
+
+from .models import AwarenessUser, InitConfig, RemoteChange, StateSnapshot, SyncStatus
+
+
+class SyncClient:
+    """Manages a sync-sidecar subprocess and provides JSON-RPC communication."""
+
+    def __init__(self, sidecar_path: Optional[str] = None):
+        self._proc: Optional[subprocess.Popen] = None
+        self._reader_thread: Optional[threading.Thread] = None
+        self._running = False
+        self._callbacks: dict[str, list[Callable]] = {
+            "remote_patch": [],
+            "remote_delete": [],
+            "remote_add": [],
+            "awareness": [],
+            "sync_status": [],
+            "error": [],
+        }
+        self._response_queue: Queue = Queue()
+        self._sidecar_path = sidecar_path or self._find_sidecar()
+
+    def _find_sidecar(self) -> str:
+        """Locate the sync-sidecar binary, searching common locations."""
+        # Check PATH first
+        import shutil
+        path = shutil.which("sync-sidecar")
+        if path:
+            return path
+
+        # Check relative to this package (monorepo development)
+        pkg_dir = Path(__file__).resolve().parent.parent.parent
+        candidates = [
+            pkg_dir / "sync-sidecar" / "bin" / "sync-sidecar",
+            pkg_dir / ".." / ".." / "sync-sidecar" / "bin" / "sync-sidecar",
+        ]
+        for c in candidates:
+            if c.exists():
+                return str(c)
+
+        # Check npm global
+        npm_path = Path.home() / "node_modules" / ".bin" / "sync-sidecar"
+        if npm_path.exists():
+            return str(npm_path)
+
+        raise FileNotFoundError(
+            "sync-sidecar binary not found. Install with: cd packages/sync-sidecar && npm link"
+        )
+
+    @property
+    def connected(self) -> bool:
+        return self._running and self._proc is not None and self._proc.poll() is None
+
+    def init(self, config: InitConfig, timeout: float = 10.0) -> StateSnapshot:
+        """Initialize a collaboration room. Returns the initial state snapshot."""
+        self._start_process()
+
+        params: dict[str, Any] = {
+            "roomId": config.room_id,
+            "userId": config.user_id,
+            "displayName": config.display_name,
+        }
+        if config.encryption_key:
+            params["encryptionKey"] = config.encryption_key
+        if config.sync_server:
+            params["providers"] = [{"type": "websocket", "url": config.sync_server}]
+
+        self._send({"method": "init", "params": params})
+        response = self._wait_for_response(timeout)
+        if response and response.get("type") == "state_snapshot":
+            return StateSnapshot(data=response.get("data", {}))
+        raise RuntimeError(f"init failed: {response}")
+
+    def patch(self, collection: str, doc_id: str, fields: dict[str, Any]) -> None:
+        """Update specific fields on a document."""
+        self._send({
+            "method": "patch",
+            "params": {"collection": collection, "id": doc_id, "fields": fields},
+        })
+
+    def add(self, collection: str, document: dict[str, Any]) -> None:
+        """Add a new document to a collection."""
+        self._send({
+            "method": "add",
+            "params": {"collection": collection, "document": document},
+        })
+
+    def delete(self, collection: str, doc_id: str) -> None:
+        """Remove a document from a collection."""
+        self._send({
+            "method": "delete",
+            "params": {"collection": collection, "id": doc_id},
+        })
+
+    def query(self, collection: str, doc_id: Optional[str] = None,
+              timeout: float = 5.0) -> dict[str, Any]:
+        """Query documents in a collection. Returns the state_snapshot data."""
+        params: dict[str, Any] = {"collection": collection}
+        if doc_id:
+            params["id"] = doc_id
+        self._send({"method": "query", "params": params})
+        response = self._wait_for_response(timeout)
+        if response and response.get("type") == "state_snapshot":
+            return response.get("data", {})
+        raise RuntimeError(f"query failed: {response}")
+
+    def snapshot(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Get the full state snapshot."""
+        self._send({"method": "snapshot"})
+        response = self._wait_for_response(timeout)
+        if response and response.get("type") == "state_snapshot":
+            return response.get("data", {})
+        raise RuntimeError(f"snapshot failed: {response}")
+
+    def leave(self) -> None:
+        """Disconnect from the room but keep the subprocess alive."""
+        if self.connected:
+            self._send({"method": "leave"})
+
+    def close(self) -> None:
+        """Shut down the sidecar process."""
+        self._running = False
+        if self._proc:
+            try:
+                self._send({"method": "leave"})
+                self._proc.wait(timeout=3)
+            except Exception:
+                self._proc.kill()
+            self._proc = None
+
+    def on(self, event: str, callback: Callable) -> None:
+        """Register a callback for sidecar events.
+
+        Events: 'remote_patch', 'remote_delete', 'remote_add', 'awareness', 'sync_status', 'error'
+        """
+        if event in self._callbacks:
+            self._callbacks[event].append(callback)
+
+    # ── Internal ──────────────────────────────────────────────────────────
+
+    def _start_process(self) -> None:
+        if self._proc is not None:
+            return
+
+        self._proc = subprocess.Popen(
+            [self._sidecar_path],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+        )
+        self._running = True
+        self._reader_thread = threading.Thread(target=self._reader_loop, daemon=True)
+        self._reader_thread.start()
+
+    def _send(self, msg: dict[str, Any]) -> None:
+        if not self.connected:
+            raise RuntimeError("Sidecar not connected")
+        line = json.dumps(msg, ensure_ascii=False) + "\n"
+        self._proc.stdin.write(line)  # type: ignore
+        self._proc.stdin.flush()  # type: ignore
+
+    def _reader_loop(self) -> None:
+        while self._running and self._proc and self._proc.stdout:
+            line = self._proc.stdout.readline()
+            if not line:
+                break
+            try:
+                msg = json.loads(line.strip())
+            except json.JSONDecodeError:
+                continue
+
+            msg_type = msg.get("type")
+            if msg_type == "state_snapshot":
+                self._response_queue.put(msg)
+            elif msg_type in self._callbacks:
+                for cb in self._callbacks[msg_type]:
+                    cb(msg)
+
+    def _wait_for_response(self, timeout: float) -> Optional[dict[str, Any]]:
+        try:
+            return self._response_queue.get(timeout=timeout)
+        except Exception:
+            return None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

strgraph-1.1.0/stratigraph_sync/models.py

@@ -0,0 +1,38 @@
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class SyncStatus:
+    state: str  # 'disconnected' | 'connecting' | 'connected' | 'synced'
+    pending: int = 0
+
+
+@dataclass
+class AwarenessUser:
+    user_id: str
+    name: str
+    color: str
+
+
+@dataclass
+class RemoteChange:
+    type: str  # 'add' | 'update' | 'delete'
+    collection: str
+    id: str
+    fields: dict[str, Any] = field(default_factory=dict)
+    by: str = ""
+
+
+@dataclass
+class StateSnapshot:
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class InitConfig:
+    room_id: str
+    user_id: str = "python-client"
+    display_name: str = "Python Client"
+    encryption_key: Optional[str] = None
+    sync_server: Optional[str] = None

strgraph-1.1.0/strgraph.egg-info/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: strgraph
+Version: 1.1.0
+Summary: Python client for StratiGraph — Yjs real-time collaboration via Node.js sidecar
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+
+# stratigraph-sync
+
+Python client for `@stratigraph/sync` — real-time multi-user editing powered by Yjs CRDTs.
+
+Connects to the `sync-sidecar` Node.js binary over stdio JSON-RPC. Requires Node.js to be installed.
+
+## Quick Start
+
+```python
+from stratigraph_sync import SyncClient, InitConfig
+
+client = SyncClient()
+snapshot = client.init(InitConfig(room_id="trench-5-west"))
+print(snapshot.data)  # {"contexts": {}, "observations": {}, ...}
+
+# Register event handlers
+def on_change(msg):
+    print(f"Remote change: {msg}")
+
+client.on("remote_patch", on_change)
+
+# Read and write data
+client.add("contexts", {"id": "ctx-1", "type": "fill", "description": "Clay layer"})
+client.patch("contexts", "ctx-1", {"description": "Sandy clay"})
+all_contexts = client.query("contexts")
+single = client.query("contexts", "ctx-1")
+full = client.snapshot()
+
+client.leave()
+client.close()
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `remote_patch` | `{collection, id, fields, by}` | Remote document update |
+| `remote_delete` | `{collection, id, by}` | Remote document deletion |
+| `remote_add` | `{collection, document, by}` | Remote document addition |
+| `awareness` | `{users: [...]}` | User presence update |
+| `sync_status` | `{state, pending}` | Connection status change |

strgraph-1.1.0/strgraph.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+stratigraph_sync/__init__.py
+stratigraph_sync/client.py
+stratigraph_sync/models.py
+strgraph.egg-info/PKG-INFO
+strgraph.egg-info/SOURCES.txt
+strgraph.egg-info/dependency_links.txt
+strgraph.egg-info/requires.txt
+strgraph.egg-info/top_level.txt
+tests/__init__.py
+tests/test_client.py

strgraph-1.1.0/strgraph.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

strgraph-1.1.0/strgraph.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.24

strgraph-1.1.0/strgraph.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+dist
+stratigraph_sync
+tests

strgraph-1.1.0/tests/test_client.py

@@ -0,0 +1,99 @@
+"""Integration tests for the SyncClient.
+
+These tests require the sync-sidecar binary to be available.
+Run: pytest tests/ -v
+"""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from stratigraph_sync import SyncClient, InitConfig
+
+
+def find_sidecar() -> str:
+    """Locate the sync-sidecar binary for testing."""
+    # Check common locations
+    candidates = [
+        Path(__file__).resolve().parent.parent.parent
+        / "sync-sidecar" / "bin" / "sync-sidecar",
+        Path(__file__).resolve().parent.parent.parent.parent
+        / "sync-sidecar" / "bin" / "sync-sidecar",
+    ]
+    for c in candidates:
+        if c.exists():
+            return str(c)
+    pytest.skip("sync-sidecar binary not found for integration tests")
+    return ""
+
+
+class TestSyncClientIntegration:
+    def test_init_creates_room(self):
+        sidecar = find_sidecar()
+        client = SyncClient(sidecar_path=sidecar)
+        try:
+            snapshot = client.init(InitConfig(room_id="test-py-room"))
+            assert isinstance(snapshot.data, dict)
+            assert "contexts" in snapshot.data
+            assert "observations" in snapshot.data
+            assert snapshot.data["contexts"] == {}
+        finally:
+            client.close()
+
+    def test_patch_updates_field(self):
+        sidecar = find_sidecar()
+        client = SyncClient(sidecar_path=sidecar)
+        try:
+            client.init(InitConfig(room_id="test-py-patch"))
+            client.add("contexts", {"id": "ctx-1", "type": "fill"})
+            client.patch("contexts", "ctx-1", {"description": "Clay layer"})
+            data = client.query("contexts", "ctx-1")
+            ctx = data.get("contexts", {}).get("ctx-1", {})
+            assert ctx.get("description") == "Clay layer"
+            assert ctx.get("type") == "fill"
+        finally:
+            client.close()
+
+    def test_snapshot_returns_all_data(self):
+        sidecar = find_sidecar()
+        client = SyncClient(sidecar_path=sidecar)
+        try:
+            client.init(InitConfig(room_id="test-py-snap"))
+            client.add("contexts", {"id": "ctx-1", "type": "fill"})
+            client.add("observations", {"id": "obs-1", "source": "ctx-1", "target": "ctx-2"})
+
+            data = client.snapshot()
+            assert "contexts" in data
+            assert "observations" in data
+            assert "ctx-1" in data["contexts"]
+        finally:
+            client.close()
+
+    def test_delete_removes_document(self):
+        sidecar = find_sidecar()
+        client = SyncClient(sidecar_path=sidecar)
+        try:
+            client.init(InitConfig(room_id="test-py-del"))
+            client.add("contexts", {"id": "ctx-1", "type": "fill"})
+            query_result = client.query("contexts")
+            assert "ctx-1" in query_result.get("contexts", {})
+            client.delete("contexts", "ctx-1")
+            query_result = client.query("contexts")
+            assert "ctx-1" not in query_result.get("contexts", {})
+        finally:
+            client.close()
+
+    def test_on_sync_status_callback(self):
+        sidecar = find_sidecar()
+        client = SyncClient(sidecar_path=sidecar)
+        events = []
+        client.on("sync_status", lambda m: events.append(m))
+        try:
+            client.init(InitConfig(room_id="test-py-status"))
+            assert len(events) >= 1
+            assert events[0].get("state") == "connected"
+        finally:
+            client.close()