surreal-orm-lite 0.2.0__py3-none-any.whl

surreal_orm_lite/__init__.py

@@ -0,0 +1,24 @@
+from .connection_manager import SurrealDBConnectionManager
+from .enum import OrderBy
+from .exceptions import (
+    SurrealDbConnectionError,
+    SurrealDbError,
+    SurrealDbNotFoundError,
+    SurrealDbValidationError,
+    SurrealORMError,
+)
+from .model_base import BaseSurrealModel, SurrealConfigDict
+from .query_set import QuerySet
+
+__all__ = [
+    "SurrealDBConnectionManager",
+    "BaseSurrealModel",
+    "QuerySet",
+    "OrderBy",
+    "SurrealConfigDict",
+    "SurrealORMError",
+    "SurrealDbError",
+    "SurrealDbConnectionError",
+    "SurrealDbValidationError",
+    "SurrealDbNotFoundError",
+]

surreal_orm_lite/connection_manager.py

@@ -0,0 +1,313 @@
+import contextlib
+import logging
+from typing import Any
+
+from surrealdb import AsyncSurreal
+
+from .exceptions import SurrealDbConnectionError
+
+logger = logging.getLogger(__name__)
+
+
+class SurrealDBConnectionManager:
+    __url: str | None = None
+    __user: str | None = None
+    __password: str | None = None
+    __namespace: str | None = None
+    __database: str | None = None
+    __client: Any = None
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await SurrealDBConnectionManager.close_connection()
+
+    async def __aenter__(self) -> Any:
+        return await SurrealDBConnectionManager.get_client()
+
+    @classmethod
+    def set_connection(cls, url: str, user: str, password: str, namespace: str, database: str) -> None:
+        """
+        Set the connection kwargs for the SurrealDB instance.
+
+        :param kwargs: The connection kwargs for the SurrealDB instance.
+        """
+        cls.__url = url
+        cls.__user = user
+        cls.__password = password
+        cls.__namespace = namespace
+        cls.__database = database
+
+    @classmethod
+    async def unset_connection(cls) -> None:
+        """
+        Set the connection kwargs for the SurrealDB instance.
+
+        :param kwargs: The connection kwargs for the SurrealDB instance.
+        """
+        cls.__url = None
+        cls.__user = None
+        cls.__password = None
+        cls.__namespace = None
+        cls.__database = None
+        await cls.close_connection()
+
+    @classmethod
+    def is_connection_set(cls) -> bool:
+        """
+        Check if the connection kwargs are set.
+
+        :return: True if the connection kwargs are set, False otherwise.
+        """
+        return all([cls.__url, cls.__user, cls.__password, cls.__namespace, cls.__database])
+
+    @classmethod
+    async def get_client(cls) -> Any:
+        """
+        Connect to the SurrealDB instance.
+
+        :return: The SurrealDB instance.
+        """
+
+        if cls.__client is not None:
+            return cls.__client
+
+        if not cls.is_connection_set():
+            raise ValueError("Connection not been set.")
+
+        # After is_connection_set(), these are guaranteed to be non-None
+        assert cls.__url is not None
+        assert cls.__namespace is not None
+        assert cls.__database is not None
+        assert cls.__user is not None
+        assert cls.__password is not None
+
+        # Établir la connexion
+        try:
+            url = cls.__url
+            _client = AsyncSurreal(url)
+
+            # WebSocket connections require explicit connect()
+            if url.startswith(("ws://", "wss://")):
+                await _client.connect(url)
+
+            await _client.use(cls.__namespace, cls.__database)
+            await _client.signin({"username": cls.__user, "password": cls.__password})
+
+            cls.__client = _client
+            return cls.__client
+        except Exception as e:
+            logger.warning(f"Can't get connection: {e}")
+            if cls.__client is not None:  # pragma: no cover
+                with contextlib.suppress(NotImplementedError):
+                    await cls.__client.close()
+                cls.__client = None
+            raise SurrealDbConnectionError("Can't connect to the database.") from None
+
+    @classmethod
+    async def close_connection(cls) -> None:
+        """
+        Close the connection to the SurrealDB instance.
+        """
+        # Fermer la connexion
+
+        if cls.__client is None:
+            return
+
+        with contextlib.suppress(NotImplementedError):
+            await cls.__client.close()
+        cls.__client = None
+
+    @classmethod
+    async def reconnect(cls) -> Any:
+        """
+        Reconnect to the SurrealDB instance.
+        """
+        # Fermer la connexion
+        await cls.close_connection()
+        # Établir la connexion
+        return await cls.get_client()
+
+    @classmethod
+    async def validate_connection(cls) -> bool:
+        """
+        Validate the connection to the SurrealDB instance.
+
+        :return: True if the connection is valid, False otherwise.
+        """
+        # Valider la connexion
+        try:
+            await cls.reconnect()
+            return True
+        except SurrealDbConnectionError:
+            return False
+
+    @classmethod
+    def get_connection_string(cls) -> str | None:
+        """
+        Get the connection string for the SurrealDB instance.
+
+        :return: The connection string for the SurrealDB instance.
+        """
+        return cls.__url
+
+    @classmethod
+    def get_connection_kwargs(cls) -> dict[str, str | None]:
+        """
+        Get the connection kwargs for the SurrealDB instance.
+
+        :return: The connection kwargs for the SurrealDB instance.
+        """
+        return {
+            "url": cls.__url,
+            "user": cls.__user,
+            "namespace": cls.__namespace,
+            "database": cls.__database,
+        }
+
+    @classmethod
+    async def set_url(cls, url: str, reconnect: bool = False) -> bool:
+        """
+        Set the URL for the SurrealDB instance.
+
+        :param url: The URL of the SurrealDB instance.
+        """
+
+        if not cls.is_connection_set():
+            raise ValueError("You can't change the URL when the others setting are not already set.")
+
+        cls.__url = url
+
+        if reconnect and not await cls.validate_connection():  # pragma: no cover
+            cls.__url = None
+            return False
+
+        return True
+
+    @classmethod
+    async def set_user(cls, user: str, reconnect: bool = False) -> bool:
+        """
+        Set the username for authentication.
+
+        :param user: The username for authentication.
+        """
+
+        if not cls.is_connection_set():
+            raise ValueError("You can't change the User when the others setting are not already set.")
+
+        cls.__user = user
+
+        if reconnect and not await cls.validate_connection():  # pragma: no cover
+            cls.__user = None
+            return False
+
+        return True
+
+    @classmethod
+    async def set_password(cls, password: str, reconnect: bool = False) -> bool:
+        """
+        Set the password for authentication.
+
+        :param password: The password for authentication.
+        """
+
+        if not cls.is_connection_set():
+            raise ValueError("You can't change the password when the others setting are not already set.")
+
+        cls.__password = password
+
+        if reconnect and not await cls.validate_connection():  # pragma: no cover
+            cls.__password = None
+            return False
+
+        return True
+
+    @classmethod
+    async def set_namespace(cls, namespace: str, reconnect: bool = False) -> bool:
+        """
+        Set the namespace to use.
+
+        :param namespace: The namespace to use.
+        """
+
+        if not cls.is_connection_set():
+            raise ValueError("You can't change the namespace when the others setting are not already set.")
+
+        cls.__namespace = namespace
+
+        if reconnect and not await cls.validate_connection():  # pragma: no cover
+            cls.__namespace = None
+            return False
+
+        return True
+
+    @classmethod
+    async def set_database(cls, database: str, reconnect: bool = False) -> bool:
+        """
+        Set the database to use.
+
+        :param database: The database to use.
+        """
+        if not cls.is_connection_set():
+            raise ValueError("You can't change the database when the others setting are not already set.")
+
+        cls.__database = database
+
+        if reconnect and not await cls.validate_connection():  # pragma: no cover
+            cls.__database = None
+            return False
+
+        return True
+
+    @classmethod
+    def get_url(cls) -> str | None:
+        """
+        Get the URL of the SurrealDB instance.
+
+        :return: The URL of the SurrealDB instance.
+        """
+        return cls.__url
+
+    @classmethod
+    def get_user(cls) -> str | None:
+        """
+        Get the username for authentication.
+
+        :return: The username for authentication.
+        """
+        return cls.__user
+
+    @classmethod
+    def get_namespace(cls) -> str | None:
+        """
+        Get the namespace to use.
+
+        :return: The namespace to use.
+        """
+        return cls.__namespace
+
+    @classmethod
+    def get_database(cls) -> str | None:
+        """
+        Get the database to use.
+
+        :return: The database to use.
+        """
+        return cls.__database
+
+    @classmethod
+    def is_password_set(cls) -> bool:
+        """
+        Get the database to use.
+
+        :return: The database to use.
+        """
+        return cls.__password is not None
+
+    @classmethod
+    def is_connected(cls) -> bool:
+        """
+        Check if the connection to the SurrealDB instance is established.
+
+        :return: True if the connection is established, False otherwise.
+        """
+
+        return cls.__client is not None

surreal_orm_lite/constants.py

@@ -0,0 +1,20 @@
+LOOKUP_OPERATORS = {
+    "exact": "=",
+    "gt": ">",
+    "gte": ">=",
+    "lt": "<",
+    "lte": "<=",
+    "in": "IN",
+    "like": "LIKE",
+    "ilike": "ILIKE",
+    "contains": "CONTAINS",
+    "icontains": "CONTAINS",
+    "startswith": "STARTSWITH",
+    "istartswith": "STARTSWITH",
+    "endswith": "ENDSWITH",
+    "iendswith": "ENDSWITH",
+    "match": "MATCH",
+    "regex": "REGEX",
+    "iregex": "REGEX",
+    "isnull": "IS",
+}

surreal_orm_lite/enum.py

@@ -0,0 +1,12 @@
+from enum import StrEnum
+
+
+class OrderBy(StrEnum):
+    ASC = "ASC"
+    DESC = "DESC"
+
+
+class Operator(StrEnum):
+    AND = "AND"
+    OR = "OR"
+    NOT = "NOT"

surreal_orm_lite/exceptions.py

@@ -0,0 +1,54 @@
+"""
+Custom exceptions for SurrealDB ORM.
+
+These exceptions provide a consistent error handling interface
+for the ORM, independent of the underlying SDK error types.
+"""
+
+
+class SurrealORMError(Exception):
+    """Base exception for all SurrealDB ORM errors."""
+
+    pass
+
+
+class SurrealDbError(SurrealORMError):
+    """
+    General database error.
+
+    Raised when a database operation fails for reasons
+    like invalid data, constraint violations, etc.
+    """
+
+    pass
+
+
+class SurrealDbConnectionError(SurrealORMError):
+    """
+    Connection error.
+
+    Raised when the connection to SurrealDB cannot be established
+    or when an existing connection is lost.
+    """
+
+    pass
+
+
+class SurrealDbValidationError(SurrealORMError):
+    """
+    Validation error.
+
+    Raised when data validation fails before sending to the database.
+    """
+
+    pass
+
+
+class SurrealDbNotFoundError(SurrealORMError):
+    """
+    Not found error.
+
+    Raised when a requested record or resource is not found.
+    """
+
+    pass

surreal_orm_lite/model_base.py

@@ -0,0 +1,212 @@
+import logging
+from typing import Any, Self
+
+from pydantic import BaseModel, ConfigDict, model_validator
+from surrealdb import RecordID
+
+from .connection_manager import SurrealDBConnectionManager
+from .exceptions import SurrealDbError
+
+logger = logging.getLogger(__name__)
+
+
+class SurrealConfigDict(ConfigDict):
+    """
+    SurrealConfigDict is a configuration dictionary for SurrealDB models.
+
+    Attributes:
+        primary_key (str | None): The primary key field name for the model.
+    """
+
+    primary_key: str | None
+    " The primary key field name for the model. "
+
+
+class BaseSurrealModel(BaseModel):
+    """
+    Base class for models interacting with SurrealDB.
+    """
+
+    @classmethod
+    def get_table_name(cls) -> str:
+        """
+        Get the table name for the model.
+        """
+        return cls.__name__
+
+    @classmethod
+    def get_index_primary_key(cls) -> str | None:
+        """
+        Get the primary key field name for the model.
+        """
+        if hasattr(cls, "model_config"):  # pragma: no cover
+            primary_key = cls.model_config.get("primary_key", None)
+            if isinstance(primary_key, str):
+                return primary_key
+
+        return None
+
+    def get_id(self) -> None | str | RecordID:
+        """
+        Get the ID of the model instance.
+        """
+        if hasattr(self, "id"):
+            id_value = self.id
+            return str(id_value) if id_value is not None else None
+
+        if hasattr(self, "model_config"):
+            primary_key = self.model_config.get("primary_key", None)
+            if isinstance(primary_key, str) and hasattr(self, primary_key):
+                primary_key_value = getattr(self, primary_key)
+                return str(primary_key_value) if primary_key_value is not None else None
+
+        return None  # pragma: no cover
+
+    @classmethod
+    def from_db(cls, record: dict | list) -> Self | list[Self]:
+        """
+        Create an instance from a SurrealDB record.
+        """
+        if isinstance(record, list):
+            return [cls.from_db(rs) for rs in record]  # type: ignore
+
+        return cls(**record)
+
+    @model_validator(mode="before")
+    @classmethod
+    def set_data(cls, data: Any) -> Any:
+        """
+        Set the ID of the model instance.
+        """
+        if isinstance(data, dict):  # pragma: no cover
+            if "id" in data and isinstance(data["id"], RecordID):
+                data["id"] = str(data["id"]).split(":")[1]
+            return data
+
+    async def refresh(self) -> None:
+        """
+        Refresh the model instance from the database.
+        """
+        if not self.get_id():
+            raise SurrealDbError("Can't refresh data, not recorded yet.")  # pragma: no cover
+
+        client = await SurrealDBConnectionManager.get_client()
+        record = await client.select(f"{self.get_table_name()}:{self.get_id()}")
+
+        if record is None:
+            raise SurrealDbError("Can't refresh data, no record found.")  # pragma: no cover
+
+        self.from_db(record)
+        return None
+
+    async def save(self) -> Self:
+        """
+        Save the model instance to the database.
+        """
+        client = await SurrealDBConnectionManager.get_client()
+        data = self.model_dump(exclude={"id"})
+        id = self.get_id()
+        table = self.get_table_name()
+
+        if id is not None:
+            # Escape special characters in ID
+            escaped_id = f"`{id}`" if any(c in str(id) for c in "@#$%^&*()") else id
+            thing = f"{table}:{escaped_id}"
+            result = await client.create(thing, data)
+            # SDK 1.0.8 returns error message as string instead of raising exception
+            if isinstance(result, str) and "already exists" in result:
+                raise SurrealDbError(f"There was a problem with the database: {result}")
+            return self
+
+        # Auto-generate the ID
+        record = await client.create(table, data)  # pragma: no cover
+
+        # SDK 1.0.8 returns error message as string
+        if isinstance(record, str):
+            raise SurrealDbError(f"Can't save data: {record}")  # pragma: no cover
+
+        if isinstance(record, list):
+            raise SurrealDbError("Can't save data, multiple records returned.")  # pragma: no cover
+
+        if record is None:
+            raise SurrealDbError("Can't save data, no record returned.")  # pragma: no cover
+
+        obj = self.from_db(record)
+        if isinstance(obj, type(self)):
+            self = obj
+            return self
+
+        raise SurrealDbError("Can't save data, no record returned.")  # pragma: no cover
+
+    async def update(self) -> Any:
+        """
+        Update the model instance to the database.
+        """
+        client = await SurrealDBConnectionManager.get_client()
+
+        data = self.model_dump(exclude={"id"})
+        id = self.get_id()
+        if id is not None:
+            thing = f"{self.__class__.__name__}:{id}"
+            test = await client.update(thing, data)
+            return test
+        raise SurrealDbError("Can't update data, no id found.")
+
+    async def merge(self, **data: Any) -> Any:
+        """
+        Update the model instance to the database.
+        """
+
+        client = await SurrealDBConnectionManager.get_client()
+        data_set = dict(data.items())
+
+        id = self.get_id()
+        if id:
+            thing = f"{self.get_table_name()}:{id}"
+
+            await client.merge(thing, data_set)
+            await self.refresh()
+            return
+
+        raise SurrealDbError(f"No Id for the data to merge: {data}")
+
+    async def delete(self) -> None:
+        """
+        Delete the model instance from the database.
+        """
+
+        client = await SurrealDBConnectionManager.get_client()
+
+        id = self.get_id()
+
+        thing = f"{self.get_table_name()}:{id}"
+
+        deleted = await client.delete(thing)
+
+        if not deleted:
+            raise SurrealDbError(f"Can't delete Record id -> '{id}' not found!")
+
+        logger.info(f"Record deleted -> {deleted}.")
+        del self
+
+    @model_validator(mode="after")
+    def check_config(self) -> Self:
+        """
+        Check the model configuration.
+        """
+
+        if not self.get_index_primary_key() and not hasattr(self, "id"):
+            raise SurrealDbError(  # pragma: no cover
+                "Can't create model, the model need either 'id' field or primirary_key in 'model_config'."
+            )
+
+        return self
+
+    @classmethod
+    def objects(cls) -> Any:
+        """
+        Return a QuerySet for the model class.
+        """
+        from .query_set import QuerySet
+
+        return QuerySet(cls)