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

surreal_orm/surreal_function.py

@@ -0,0 +1,95 @@
+from enum import StrEnum
+
+
+class SurealFunction(StrEnum): ...
+
+
+# XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+class SurrealArrayFunction(SurealFunction):
+    APPEND = "array::append"
+
+
+# https://surrealdb.com/docs/surrealql/functions/database/time
+class SurrealTimeFunction(SurealFunction):
+    CEIL = "time::ceil"
+    DAY = "time::day"
+    FLOOR = "time::floor"
+    FORMAT = "time::format"
+    GROUP = "time::group"
+    HOUR = "time::hour"
+    MAX = "time::max"
+    MICROS = "time::micros"
+    MILLIS = "time::millis"
+    MIN = "time::min"
+    MINUTE = "time::minute"
+    MONTH = "time::month"
+    NANOS = "time::nanos"
+    NOW = "time::now"
+    ROUND = "time::round"
+    SECOND = "time::second"
+    TIMEZONE = "time::timezone"
+    UNIX = "time::unix"
+    WEEK = "time::week"
+    YDAY = "time::yday"
+    YEAR = "time::year"
+    IS_LEAP_YEAR = "time::is::leap_year"
+    FROM_MICROS = "time::from::micros"
+    FROM_MILLIS = "time::from::millis"
+    FROM_NANOS = "time::from::nanos"
+    FROM_SECONDS = "time::from::seconds"
+    FROM_UNIX = "time::from::unix"
+    FROM_ULID = "time::from::ulid"
+    FROM_UUID = "time::from::uuid"
+
+
+# https://surrealdb.com/docs/surrealql/functions/database/math
+class SurrealMathFunction(SurealFunction):
+    ABS = "math::abs"
+    ACOS = "math::acos"
+    ACOT = "math::acot"
+    ASIN = "math::asin"
+    ATAN = "math::atan"
+    BOTTOM = "math::bottom"
+    CEIL = "math::ceil"
+    CLAAMP = "math::clamp"
+    COS = "math::cos"
+    COT = "math::cot"
+    COUNT = "count"  # https://surrealdb.com/docs/surrealql/functions/database/count
+    DEG2RAD = "math::deg2rad"
+    E = "math::e"
+    FIXED = "math::fixed"
+    FLOOR = "math::floor"
+    FRAC_1_PI = "math::frac_1_pi"
+    FRAC_1_SQRT_2 = "math::frac_1_sqrt_2"
+    FRAC_2_PI = "math::frac_2_pi"
+    FRAC_2_SQRT_PI = "math::frac_2_sqrt_pi"
+    FRAC_PI_2 = "math::frac_pi_2"
+    FRAC_PI_3 = "math::frac_pi_3"
+    FRAC_PI_4 = "math::frac_pi_4"
+    FRAC_PI_6 = "math::frac_pi_6"
+    FRAC_PI_8 = "math::frac_pi_8"
+    INF = "math::inf"
+    INTERQUARTILE = "math::interquartile"
+    LERP = "math::lerp"
+    LERPANGLE = "math::lerpangle"
+    LN = "math::ln"
+    LN_10 = "math::ln_10"
+    LN_2 = "math::ln_2"
+    LOG = "math::log"
+    LOG10 = "math::log10"
+    LOG10_2 = "math::log10_2"
+    LOG10_E = "math::log10_e"
+    LOG2 = "math::log2"
+    LOG2_10 = "math::log2_20"
+    LOG2_E = "math::log2_e"
+    ###
+    PI = "math::pi"
+    POW = "math::pow"
+    ROUND = "math::round"
+    SIGN = "math::sign"
+    SIN = "math::sin"
+    SINH = "math::sinh"
+    SQRT = "math::sqrt"
+    TAN = "math::tan"
+    TANH = "math::tanh"
+    TRUNC = "math::trunc"

surreal_orm/surreal_ql.py

@@ -0,0 +1,113 @@
+from typing import Any, Self
+from .connection_manager import SurrealDBConnectionManager
+from .utils import remove_quotes_for_variables
+from surreal_sdk import HTTPConnection
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class SurrealQL:
+    def __init__(self) -> None:
+        self._variables: dict[str, Any] = {}
+        self.related_models: list[Any] = []
+        self._query: str = ""
+
+    """
+    Class for interacting with SurrealDB using SQL-like commands.
+    """
+
+    def select(self, fields: str | list[str] | None) -> Self:
+        if fields is None:
+            self._query += "SELECT "
+        elif isinstance(fields, list):
+            fields = ", ".join(fields)
+            self._query += f"SELECT {fields}"
+        else:
+            self._query += f"SELECT {fields}"
+
+        return self
+
+    def related(self, record_table: str) -> Self:
+        """
+        Placeholder method for defining related models.
+        """
+        self._query += f"RELATE {record_table}"
+
+        return self
+
+    def to_related(self, table_or_record_table: str) -> Self:
+        """
+        Placeholder method for defining the target table for a query.
+        """
+        self._query += f"->{table_or_record_table}"
+
+        return self
+
+    def from_related(self, table_or_record_table: str) -> Self:
+        """
+        Placeholder method for defining the source table for a query.
+        """
+        self._query += f"<-{table_or_record_table}"
+
+        return self
+
+    def from_tables(self, tables: str | list[str]) -> Self:
+        """
+        Placeholder method for defining the source table for a query.
+        """
+        if isinstance(tables, list):
+            tables = ", ".join(tables)
+        self._query += f"FROM {tables}"
+
+        return self
+
+    async def _execute_query(self, query: str) -> list[Any]:
+        """
+        Execute the given SQL query using the SurrealDB client.
+
+        This internal method handles the execution of the compiled SQL query and returns the raw results
+        from the database.
+
+        Args:
+            query (str): The SQL query string to execute.
+
+        Returns:
+            list[Any]: A list of query result objects.
+
+        Raises:
+            SurrealDbError: If there is an issue executing the query.
+
+        Example:
+            ```python
+            results = await self._execute_query("SELECT * FROM users;")
+            ```
+        """
+        client = await SurrealDBConnectionManager.get_client()
+        return await self._run_query_on_client(client, query)
+
+    async def _run_query_on_client(self, client: HTTPConnection, query: str) -> list[Any]:
+        """
+        Run the SQL query on the provided SurrealDB client.
+
+        This internal method sends the query to the SurrealDB client along with any predefined variables
+        and returns the raw query responses.
+
+        Args:
+            client (HTTPConnection): The active SurrealDB client instance.
+            query (str): The SQL query string to execute.
+
+        Returns:
+            list[Any]: A list of query result objects.
+
+        Raises:
+            SurrealDbError: If there is an issue executing the query.
+
+        Example:
+            ```python
+            results = await self._run_query_on_client(client, "SELECT * FROM users;")
+            ```
+        """
+        result = await client.query(remove_quotes_for_variables(query), self._variables)
+        return result.all_records

surreal_orm/types.py

@@ -0,0 +1,86 @@
+"""
+Type definitions for SurrealDB ORM.
+
+This module contains enums and type definitions used throughout the ORM
+for table types, schema modes, and field types.
+"""
+
+from enum import StrEnum
+
+
+class TableType(StrEnum):
+    """
+    Table type classification for migration behavior and connection preferences.
+
+    Each table type has specific characteristics:
+    - NORMAL: Standard table with default behavior
+    - USER: Authentication table with enforced SCHEMAFULL, required password field
+    - STREAM: Real-time optimized table with CHANGEFEED enabled, WebSocket preferred
+    - HASH: Lookup/cache table, SCHEMALESS by default
+    """
+
+    NORMAL = "normal"
+    USER = "user"
+    STREAM = "stream"
+    HASH = "hash"
+
+
+class SchemaMode(StrEnum):
+    """
+    Schema enforcement mode for SurrealDB tables.
+
+    - SCHEMAFULL: Strict schema enforcement, only defined fields allowed
+    - SCHEMALESS: Flexible schema, any fields accepted
+    """
+
+    SCHEMAFULL = "SCHEMAFULL"
+    SCHEMALESS = "SCHEMALESS"
+
+
+class FieldType(StrEnum):
+    """
+    SurrealDB field types for schema definitions.
+
+    Maps to SurrealDB's native type system.
+    """
+
+    STRING = "string"
+    INT = "int"
+    FLOAT = "float"
+    BOOL = "bool"
+    DATETIME = "datetime"
+    DURATION = "duration"
+    DECIMAL = "decimal"
+    ARRAY = "array"
+    OBJECT = "object"
+    RECORD = "record"
+    GEOMETRY = "geometry"
+    ANY = "any"
+    OPTION = "option"
+    BYTES = "bytes"
+    UUID = "uuid"
+
+
+class EncryptionAlgorithm(StrEnum):
+    """
+    Supported encryption algorithms for password hashing.
+
+    All algorithms use SurrealDB's built-in crypto functions.
+    """
+
+    ARGON2 = "argon2"
+    BCRYPT = "bcrypt"
+    PBKDF2 = "pbkdf2"
+    SCRYPT = "scrypt"
+
+
+# Type mapping from Python types to SurrealDB types
+PYTHON_TO_SURREAL_TYPE: dict[type, FieldType] = {
+    str: FieldType.STRING,
+    int: FieldType.INT,
+    float: FieldType.FLOAT,
+    bool: FieldType.BOOL,
+    list: FieldType.ARRAY,
+    dict: FieldType.OBJECT,
+    bytes: FieldType.BYTES,
+}

surreal_sdk/README.md

@@ -0,0 +1,79 @@
+# Surreal SDK
+
+A custom Python SDK for SurrealDB with HTTP and WebSocket support.
+
+**No dependency on the official `surrealdb` package** - this is a standalone implementation.
+
+## Installation
+
+```bash
+pip install surreal-sdk
+```
+
+## Quick Start
+
+### HTTP Connection (Stateless)
+
+```python
+from surreal_sdk import SurrealDB
+
+async with SurrealDB.http("http://localhost:8000", "namespace", "database") as db:
+    await db.signin("root", "root")
+
+    # Query
+    result = await db.query("SELECT * FROM users WHERE age > $min_age", {"min_age": 18})
+    print(result.all_records)
+
+    # CRUD
+    user = await db.create("users", {"name": "Alice", "age": 30})
+    await db.update("users:alice", {"age": 31})
+    await db.delete("users:alice")
+```
+
+### WebSocket Connection (Stateful, Real-time)
+
+```python
+from surreal_sdk import SurrealDB
+
+async with SurrealDB.ws("ws://localhost:8000", "namespace", "database") as db:
+    await db.signin("root", "root")
+
+    # Live Query
+    async def on_change(data):
+        print(f"Change detected: {data}")
+
+    live_id = await db.live("users", on_change)
+    # ... do work ...
+    await db.kill(live_id)
+```
+
+### Connection Pool
+
+```python
+from surreal_sdk import SurrealDB
+
+async with SurrealDB.pool("http://localhost:8000", "ns", "db", size=10) as pool:
+    await pool.set_credentials("root", "root")
+
+    async with pool.acquire() as conn:
+        result = await conn.query("SELECT * FROM users")
+```
+
+## Features
+
+- **HTTPConnection** - Stateless, ideal for microservices and serverless
+- **WebSocketConnection** - Stateful, for real-time features and Live Queries
+- **ConnectionPool** - Connection pooling for high-throughput scenarios
+- **Typed Responses** - `QueryResponse`, `RecordResponse`, `RecordsResponse`, etc.
+- **Live Queries** - Real-time subscriptions (WebSocket only)
+- **Change Feeds** - CDC pattern for stateless architectures (HTTP)
+
+## Requirements
+
+- Python 3.12+
+- httpx
+- aiohttp
+
+## License
+
+MIT

surreal_sdk/__init__.py

@@ -0,0 +1,151 @@
+"""
+SurrealDB SDK - A custom Python SDK for SurrealDB.
+
+This SDK provides direct connection to SurrealDB via HTTP and WebSocket
+without depending on the official surrealdb package.
+
+Supports:
+- HTTP connections (stateless, ideal for microservices)
+- WebSocket connections (stateful, for real-time features)
+- Live Queries (WebSocket only)
+- Live Select Streams (async iterator pattern)
+- Change Feeds streaming (HTTP, stateless)
+- Typed function calls
+"""
+
+from typing import Any
+
+from .connection.base import BaseSurrealConnection
+from .connection.http import HTTPConnection
+from .connection.websocket import WebSocketConnection
+from .connection.pool import ConnectionPool
+from .streaming.change_feed import ChangeFeedStream
+from .streaming.live_query import LiveQuery, LiveQueryManager, LiveNotification
+from .streaming.live_select import (
+    LiveSelectStream,
+    LiveSelectManager,
+    LiveChange,
+    LiveAction,
+    LiveSubscriptionParams,
+)
+from .protocol.rpc import RPCRequest, RPCResponse, RPCError
+from .types import (
+    ResponseStatus,
+    QueryResult,
+    QueryResponse,
+    RecordResponse,
+    RecordsResponse,
+    AuthResponse,
+    InfoResponse,
+    LiveQueryId,
+    DeleteResponse,
+)
+from .exceptions import (
+    SurrealDBError,
+    ConnectionError,
+    AuthenticationError,
+    QueryError,
+    TimeoutError,
+    TransactionError,
+)
+from .transaction import (
+    BaseTransaction,
+    HTTPTransaction,
+    WebSocketTransaction,
+    TransactionStatement,
+)
+from .functions import (
+    FunctionCall,
+    FunctionNamespace,
+    MathFunctions,
+    TimeFunctions,
+    ArrayFunctions,
+    StringFunctions,
+    CryptoFunctions,
+)
+
+__version__ = "0.5.0"
+__all__ = [
+    # Connections
+    "BaseSurrealConnection",
+    "HTTPConnection",
+    "WebSocketConnection",
+    "ConnectionPool",
+    # Streaming - Live Query (callback-based)
+    "ChangeFeedStream",
+    "LiveQuery",
+    "LiveQueryManager",
+    "LiveNotification",
+    # Streaming - Live Select (async iterator)
+    "LiveSelectStream",
+    "LiveSelectManager",
+    "LiveChange",
+    "LiveAction",
+    "LiveSubscriptionParams",
+    # Protocol
+    "RPCRequest",
+    "RPCResponse",
+    "RPCError",
+    # Response Types
+    "ResponseStatus",
+    "QueryResult",
+    "QueryResponse",
+    "RecordResponse",
+    "RecordsResponse",
+    "AuthResponse",
+    "InfoResponse",
+    "LiveQueryId",
+    "DeleteResponse",
+    # Transactions
+    "BaseTransaction",
+    "HTTPTransaction",
+    "WebSocketTransaction",
+    "TransactionStatement",
+    # Functions
+    "FunctionCall",
+    "FunctionNamespace",
+    "MathFunctions",
+    "TimeFunctions",
+    "ArrayFunctions",
+    "StringFunctions",
+    "CryptoFunctions",
+    # Exceptions
+    "SurrealDBError",
+    "ConnectionError",
+    "AuthenticationError",
+    "QueryError",
+    "TimeoutError",
+    "TransactionError",
+]
+
+
+class SurrealDB:
+    """
+    Factory class for creating SurrealDB connections.
+
+    Usage:
+        # HTTP connection (stateless)
+        async with SurrealDB.http("http://localhost:8000", "ns", "db") as db:
+            await db.signin("root", "root")
+            result = await db.query("SELECT * FROM users")
+
+        # WebSocket connection (stateful)
+        async with SurrealDB.ws("ws://localhost:8000", "ns", "db") as db:
+            await db.signin("root", "root")
+            await db.live("users", callback=on_change)
+    """
+
+    @staticmethod
+    def http(url: str, namespace: str, database: str, **kwargs: Any) -> HTTPConnection:
+        """Create an HTTP connection (stateless)."""
+        return HTTPConnection(url, namespace, database, **kwargs)
+
+    @staticmethod
+    def ws(url: str, namespace: str, database: str, **kwargs: Any) -> WebSocketConnection:
+        """Create a WebSocket connection (stateful)."""
+        return WebSocketConnection(url, namespace, database, **kwargs)
+
+    @staticmethod
+    def pool(url: str, namespace: str, database: str, size: int = 10, **kwargs: Any) -> ConnectionPool:
+        """Create a connection pool."""
+        return ConnectionPool(url, namespace, database, size=size, **kwargs)

surreal_sdk/connection/__init__.py

@@ -0,0 +1,17 @@
+"""
+SurrealDB SDK Connection Module.
+
+Provides HTTP and WebSocket connection implementations.
+"""
+
+from .base import BaseSurrealConnection
+from .http import HTTPConnection
+from .websocket import WebSocketConnection
+from .pool import ConnectionPool
+
+__all__ = [
+    "BaseSurrealConnection",
+    "HTTPConnection",
+    "WebSocketConnection",
+    "ConnectionPool",
+]