surrealdb-orm 0.1.3__py3-none-any.whl → 0.5.0__py3-none-any.whl

surreal_sdk/protocol/rpc.py

@@ -0,0 +1,218 @@
+"""
+SurrealDB RPC Protocol Implementation.
+
+Handles the JSON-RPC style messaging format used by SurrealDB.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+import json
+
+
+@dataclass
+class RPCRequest:
+    """
+    RPC Request message format.
+
+    Attributes:
+        id: Unique request identifier for response matching
+        method: RPC method name (query, select, create, etc.)
+        params: Method parameters as list or dict
+    """
+
+    method: str
+    params: list[Any] | dict[str, Any] = field(default_factory=list)
+    id: int = 1
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "id": self.id,
+            "method": self.method,
+            "params": self.params if isinstance(self.params, list) else [self.params],
+        }
+
+    def to_json(self) -> str:
+        """Serialize to JSON string."""
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def query(cls, sql: str, vars: dict[str, Any] | None = None, request_id: int = 1) -> "RPCRequest":
+        """Create a query request."""
+        return cls(method="query", params=[sql, vars or {}], id=request_id)
+
+    @classmethod
+    def select(cls, thing: str, request_id: int = 1) -> "RPCRequest":
+        """Create a select request."""
+        return cls(method="select", params=[thing], id=request_id)
+
+    @classmethod
+    def create(cls, thing: str, data: dict[str, Any], request_id: int = 1) -> "RPCRequest":
+        """Create a create request."""
+        return cls(method="create", params=[thing, data], id=request_id)
+
+    @classmethod
+    def update(cls, thing: str, data: dict[str, Any], request_id: int = 1) -> "RPCRequest":
+        """Create an update request."""
+        return cls(method="update", params=[thing, data], id=request_id)
+
+    @classmethod
+    def merge(cls, thing: str, data: dict[str, Any], request_id: int = 1) -> "RPCRequest":
+        """Create a merge request."""
+        return cls(method="merge", params=[thing, data], id=request_id)
+
+    @classmethod
+    def delete(cls, thing: str, request_id: int = 1) -> "RPCRequest":
+        """Create a delete request."""
+        return cls(method="delete", params=[thing], id=request_id)
+
+    @classmethod
+    def signin(
+        cls,
+        user: str | None = None,
+        password: str | None = None,
+        namespace: str | None = None,
+        database: str | None = None,
+        access: str | None = None,
+        request_id: int = 1,
+    ) -> "RPCRequest":
+        """Create a signin request."""
+        params: dict[str, Any] = {}
+        if user:
+            params["user"] = user
+        if password:
+            params["pass"] = password
+        if namespace:
+            params["ns"] = namespace
+        if database:
+            params["db"] = database
+        if access:
+            params["ac"] = access
+        return cls(method="signin", params=params, id=request_id)
+
+    @classmethod
+    def use(cls, namespace: str, database: str, request_id: int = 1) -> "RPCRequest":
+        """Create a use request."""
+        return cls(method="use", params=[namespace, database], id=request_id)
+
+    @classmethod
+    def live(cls, table: str, diff: bool = False, request_id: int = 1) -> "RPCRequest":
+        """Create a live query request."""
+        sql = f"LIVE SELECT * FROM {table}"
+        if diff:
+            sql += " DIFF"
+        return cls(method="query", params=[sql, {}], id=request_id)
+
+    @classmethod
+    def kill(cls, live_id: str, request_id: int = 1) -> "RPCRequest":
+        """Create a kill request for a live query."""
+        return cls(method="kill", params=[live_id], id=request_id)
+
+
+@dataclass
+class RPCError:
+    """
+    RPC Error format.
+
+    Attributes:
+        code: Error code
+        message: Error message
+    """
+
+    code: int
+    message: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "RPCError":
+        """Create from dictionary."""
+        return cls(
+            code=data.get("code", -1),
+            message=data.get("message", "Unknown error"),
+        )
+
+
+@dataclass
+class RPCResponse:
+    """
+    RPC Response message format.
+
+    Attributes:
+        id: Request identifier this response matches
+        result: Query result data (if successful)
+        error: Error information (if failed)
+    """
+
+    id: int
+    result: Any = None
+    error: RPCError | None = None
+
+    @property
+    def is_error(self) -> bool:
+        """Check if response is an error."""
+        return self.error is not None
+
+    @property
+    def is_success(self) -> bool:
+        """Check if response is successful."""
+        return self.error is None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "RPCResponse":
+        """Parse from dictionary."""
+        error = None
+        if "error" in data:
+            error = RPCError.from_dict(data["error"])
+
+        return cls(
+            id=data.get("id", 0),
+            result=data.get("result"),
+            error=error,
+        )
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "RPCResponse":
+        """Parse from JSON string."""
+        data = json.loads(json_str)
+        return cls.from_dict(data)
+
+
+# RPC Method names as constants
+class RPCMethod:
+    """RPC method name constants."""
+
+    # Authentication
+    SIGNIN = "signin"
+    SIGNUP = "signup"
+    AUTHENTICATE = "authenticate"
+    INVALIDATE = "invalidate"
+    INFO = "info"
+
+    # Connection
+    USE = "use"
+    PING = "ping"
+    VERSION = "version"
+    RESET = "reset"
+
+    # CRUD
+    SELECT = "select"
+    CREATE = "create"
+    INSERT = "insert"
+    UPDATE = "update"
+    UPSERT = "upsert"
+    MERGE = "merge"
+    PATCH = "patch"
+    DELETE = "delete"
+    RELATE = "relate"
+
+    # Query
+    QUERY = "query"
+    GRAPHQL = "graphql"
+    RUN = "run"
+
+    # Live Queries (WebSocket only)
+    LIVE = "live"
+    KILL = "kill"
+
+    # Variables (WebSocket only)
+    LET = "let"
+    UNSET = "unset"

surreal_sdk/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "surreal-sdk"
+version = "0.5.0"
+description = "Custom Python SDK for SurrealDB with HTTP and WebSocket support. No dependency on official surrealdb package."
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+authors = [
+    { name = "Yannick Croteau", email = "yannick.croteau@gmail.com" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Operating System :: OS Independent",
+    "Framework :: AsyncIO",
+]
+
+dependencies = [
+    "httpx>=0.27.0",
+    "aiohttp>=3.9.0",
+]
+
+[project.optional-dependencies]
+# CBOR support for binary protocol
+cbor = [
+    "cbor2>=5.6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/EulogySnowfall/SurrealDB-ORM"
+Documentation = "https://github.com/EulogySnowfall/SurrealDB-ORM"
+Repository = "https://github.com/EulogySnowfall/SurrealDB-ORM.git"
+Issues = "https://github.com/EulogySnowfall/SurrealDB-ORM/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+
+[tool.hatch.build.targets.sdist]
+include = ["*.py", "py.typed", "README.md"]

surreal_sdk/streaming/__init__.py

@@ -0,0 +1,31 @@
+"""
+SurrealDB SDK Streaming Module.
+
+Provides Live Queries and Change Feeds streaming capabilities.
+"""
+
+from .change_feed import ChangeFeedStream
+from .live_query import LiveQuery, LiveQueryManager, LiveNotification, LiveAction
+from .live_select import (
+    LiveSelectStream,
+    LiveSelectManager,
+    LiveChange,
+    LiveAction as LiveSelectAction,
+    LiveSubscriptionParams,
+)
+
+__all__ = [
+    # Change Feeds
+    "ChangeFeedStream",
+    # Live Query (callback-based)
+    "LiveQuery",
+    "LiveQueryManager",
+    "LiveNotification",
+    "LiveAction",
+    # Live Select (async iterator)
+    "LiveSelectStream",
+    "LiveSelectManager",
+    "LiveChange",
+    "LiveSelectAction",
+    "LiveSubscriptionParams",
+]

surreal_sdk/streaming/change_feed.py

@@ -0,0 +1,278 @@
+"""
+Change Feed Streaming Implementation.
+
+Provides CDC (Change Data Capture) streaming via SurrealDB Change Feeds.
+This is stateless and ideal for microservices architectures.
+"""
+
+from typing import Any, AsyncGenerator, AsyncIterator
+from datetime import datetime
+import asyncio
+
+from ..connection.http import HTTPConnection
+from ..exceptions import ChangeFeedError
+
+
+class ChangeFeedStream:
+    """
+    Stream changes from a SurrealDB table using Change Feeds.
+
+    Change Feeds capture database modifications as a historic stream,
+    allowing replay from specific timestamps. This is ideal for:
+    - Microservices event streaming
+    - Data replication
+    - Audit trails
+    - Event sourcing
+
+    Usage:
+        async with HTTPConnection("http://localhost:8000", "ns", "db") as conn:
+            await conn.signin("root", "root")
+
+            stream = ChangeFeedStream(conn, "orders")
+
+            async for change in stream.stream():
+                print(f"Change: {change['changes']}")
+    """
+
+    def __init__(
+        self,
+        connection: HTTPConnection,
+        table: str,
+        poll_interval: float = 0.1,
+        batch_size: int = 100,
+    ):
+        """
+        Initialize Change Feed stream.
+
+        Args:
+            connection: HTTP connection to use
+            table: Table to stream changes from
+            poll_interval: Seconds between polls when no changes
+            batch_size: Maximum changes per poll
+        """
+        self.connection = connection
+        self.table = table
+        self.poll_interval = poll_interval
+        self.batch_size = batch_size
+        self._cursor: str | None = None
+        self._running = False
+
+    @property
+    def cursor(self) -> str | None:
+        """Current stream cursor (versionstamp or timestamp)."""
+        return self._cursor
+
+    async def define_changefeed(self, retention: str = "7d") -> None:
+        """
+        Define a change feed on the table.
+
+        Must be called before streaming if not already defined.
+
+        Args:
+            retention: How long to keep changes (e.g., "1h", "7d", "30d")
+        """
+        try:
+            await self.connection.query(f"DEFINE TABLE {self.table} CHANGEFEED {retention}")
+        except Exception as e:
+            raise ChangeFeedError(f"Failed to define change feed: {e}")
+
+    async def get_changes(
+        self,
+        since: str | datetime | None = None,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Get changes since a specific point.
+
+        Args:
+            since: Timestamp or versionstamp to start from
+            limit: Maximum number of changes to return
+
+        Returns:
+            List of change records
+        """
+        if since is None:
+            since = self._cursor or datetime.utcnow().isoformat() + "Z"
+        elif isinstance(since, datetime):
+            since = since.isoformat() + "Z"
+
+        limit = limit or self.batch_size
+
+        query = f"SHOW CHANGES FOR TABLE {self.table} SINCE '{since}' LIMIT {limit}"
+
+        try:
+            response = await self.connection.query(query)
+
+            if response.results:
+                first_result = response.results[0]
+                if first_result.is_ok:
+                    result_data = first_result.result
+                    if isinstance(result_data, list):
+                        return result_data
+                    elif isinstance(result_data, dict):
+                        return [result_data]
+
+            return []
+
+        except Exception as e:
+            raise ChangeFeedError(f"Failed to get changes: {e}")
+
+    async def stream(
+        self,
+        since: str | datetime | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """
+        Stream changes continuously.
+
+        Args:
+            since: Starting point (timestamp or versionstamp)
+
+        Yields:
+            Change records as they become available
+        """
+        if since is None:
+            since = datetime.utcnow().isoformat() + "Z"
+        elif isinstance(since, datetime):
+            since = since.isoformat() + "Z"
+
+        self._cursor = since
+        self._running = True
+
+        while self._running:
+            try:
+                changes = await self.get_changes(since=self._cursor)
+
+                for change in changes:
+                    yield change
+
+                    # Update cursor with versionstamp if available
+                    versionstamp = change.get("versionstamp")
+                    if versionstamp:
+                        self._cursor = str(versionstamp)
+
+                if not changes:
+                    await asyncio.sleep(self.poll_interval)
+
+            except asyncio.CancelledError:
+                self._running = False
+                raise
+            except Exception:
+                # Log error but continue streaming
+                await asyncio.sleep(self.poll_interval)
+
+    def stop(self) -> None:
+        """Stop the stream."""
+        self._running = False
+
+    async def stream_batch(
+        self,
+        since: str | datetime | None = None,
+    ) -> AsyncIterator[list[dict[str, Any]]]:
+        """
+        Stream changes in batches.
+
+        More efficient for high-volume scenarios.
+
+        Args:
+            since: Starting point
+
+        Yields:
+            Batches of change records
+        """
+        if since is None:
+            since = datetime.utcnow().isoformat() + "Z"
+        elif isinstance(since, datetime):
+            since = since.isoformat() + "Z"
+
+        self._cursor = since
+        self._running = True
+
+        while self._running:
+            try:
+                changes = await self.get_changes(since=self._cursor)
+
+                if changes:
+                    yield changes
+
+                    # Update cursor with last versionstamp
+                    last_change = changes[-1]
+                    versionstamp = last_change.get("versionstamp")
+                    if versionstamp:
+                        self._cursor = str(versionstamp)
+                else:
+                    await asyncio.sleep(self.poll_interval)
+
+            except asyncio.CancelledError:
+                self._running = False
+                raise
+            except Exception:
+                await asyncio.sleep(self.poll_interval)
+
+
+class MultiTableChangeFeed:
+    """
+    Stream changes from multiple tables.
+
+    Useful for aggregating changes across related tables.
+    """
+
+    def __init__(
+        self,
+        connection: HTTPConnection,
+        tables: list[str],
+        poll_interval: float = 0.1,
+        batch_size: int = 100,
+    ):
+        """
+        Initialize multi-table change feed.
+
+        Args:
+            connection: HTTP connection to use
+            tables: List of tables to stream
+            poll_interval: Seconds between polls
+            batch_size: Maximum changes per table per poll
+        """
+        self.streams = {table: ChangeFeedStream(connection, table, poll_interval, batch_size) for table in tables}
+        self._running = False
+
+    async def stream(
+        self,
+        since: str | datetime | None = None,
+    ) -> AsyncIterator[tuple[str, dict[str, Any]]]:
+        """
+        Stream changes from all tables.
+
+        Yields:
+            Tuple of (table_name, change_record)
+        """
+        self._running = True
+
+        async def stream_table(table: str, stream: ChangeFeedStream) -> AsyncGenerator[tuple[str, dict[str, Any]], None]:
+            async for change in stream.stream(since):
+                yield table, change
+
+        # Create tasks for all tables
+        async def merged_stream() -> None:
+            # This is a simplified implementation
+            # A production version would use asyncio.Queue
+            for table, stream in self.streams.items():
+                _ = (table, stream)  # Placeholder for future implementation
+
+        # Simple round-robin implementation
+        while self._running:
+            for table, stream in self.streams.items():
+                try:
+                    changes = await stream.get_changes()
+                    for change in changes:
+                        yield table, change
+                except Exception:
+                    pass
+
+            if not any(stream._cursor for stream in self.streams.values()):
+                await asyncio.sleep(self.streams[list(self.streams.keys())[0]].poll_interval)
+
+    def stop(self) -> None:
+        """Stop all streams."""
+        self._running = False
+        for stream in self.streams.values():
+            stream.stop()