patera-database 0.1.0__tar.gz

patera_database-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.3
+Name: patera-database
+Version: 0.1.0
+Requires-Dist: patera
+Requires-Dist: sqlalchemy
+Requires-Dist: aiosqlite
+Requires-Python: >=3.12

patera_database-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "patera-database"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+  "patera",
+  "sqlalchemy",
+  "aiosqlite",
+]
+
+[tool.uv.sources]
+patera = { workspace = true }
+
+[tool.uv.build-backend]
+module-name = "patera.database"
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"

patera_database-0.1.0/src/patera/database/nosql/__init__.py

@@ -0,0 +1,7 @@
+"""
+NoSQL Database Module
+"""
+
+from .nosql_database import NoSqlDatabase, NoSqlDatabaseConfig
+
+__all__ = ["NoSqlDatabase", "NoSqlDatabaseConfig"]

patera_database-0.1.0/src/patera/database/nosql/backends/__init__.py

@@ -0,0 +1,7 @@
+"""
+NoSQL database backends
+"""
+
+from .async_nosql_backend_protocol import AsyncNoSqlBackendBase
+
+__all__ = ["AsyncNoSqlBackendBase"]

patera_database-0.1.0/src/patera/database/nosql/backends/async_nosql_backend_protocol.py

@@ -0,0 +1,140 @@
+"""
+Protocls for async NoSQL backends.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, Callable, Any, Iterable, Mapping, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from patera import Patera
+
+
+class AsyncNoSqlBackendBase(ABC):
+    """
+    Minimal async adapter interface a backend must implement.
+    """
+
+    @classmethod
+    @abstractmethod
+    def configure_from_app(
+        cls, app: "Patera", configs: dict[str, Any]
+    ) -> "AsyncNoSqlBackendBase":
+        """
+        Classmethod to configure backend from app config.
+        Called during NoSqlDatabase.init_app().
+        """
+        ...
+
+    @abstractmethod
+    async def connect(self) -> None: ...
+
+    @abstractmethod
+    async def disconnect(self) -> None: ...
+
+    @abstractmethod
+    def database_handle(self) -> Any:
+        """
+        Returns an object representing the 'database' to use inside handlers.
+        For backends without a database concept, return a client/root handle.
+        """
+        ...
+
+    @abstractmethod
+    def supports_transactions(self) -> bool: ...
+
+    @abstractmethod
+    async def start_session(self) -> Any:
+        """
+        Return a session/context object usable in transactions (or None if unsupported).
+        """
+        ...
+
+    @abstractmethod
+    async def with_transaction(
+        self, fn: Callable[..., Any], *args, session: Any = None, **kwargs
+    ) -> Any:
+        """
+        Execute fn inside a transaction if supported; otherwise call fn directly.
+        """
+        ...
+
+    @abstractmethod
+    def get_collection(self, name: str) -> Any: ...
+
+    @abstractmethod
+    async def find_one(
+        self,
+        collection: str,
+        filter: Mapping[str, Any],
+        *,
+        session: Any = None,
+        **kwargs,
+    ) -> Any: ...
+
+    @abstractmethod
+    async def find_many(
+        self,
+        collection: str,
+        filter: Mapping[str, Any] | None = None,
+        *,
+        session: Any = None,
+        limit: Optional[int] = None,
+        skip: Optional[int] = None,
+        sort: Optional[Iterable[tuple[str, int]]] = None,
+        **kwargs,
+    ) -> list[Any]: ...
+
+    @abstractmethod
+    async def insert_one(
+        self, collection: str, doc: Mapping[str, Any], *, session: Any = None, **kwargs
+    ) -> Any: ...
+
+    @abstractmethod
+    async def insert_many(
+        self,
+        collection: str,
+        docs: Iterable[Mapping[str, Any]],
+        *,
+        session: Any = None,
+        **kwargs,
+    ) -> Any: ...
+
+    @abstractmethod
+    async def update_one(
+        self,
+        collection: str,
+        filter: Mapping[str, Any],
+        update: Mapping[str, Any],
+        *,
+        upsert: bool = False,
+        session: Any = None,
+        **kwargs,
+    ) -> Any: ...
+
+    @abstractmethod
+    async def delete_one(
+        self,
+        collection: str,
+        filter: Mapping[str, Any],
+        *,
+        session: Any = None,
+        **kwargs,
+    ) -> Any: ...
+
+    @abstractmethod
+    async def aggregate(
+        self,
+        collection: str,
+        pipeline: Iterable[Mapping[str, Any]],
+        *,
+        session: Any = None,
+        **kwargs,
+    ) -> list[Any]: ...
+
+    @abstractmethod
+    async def execute_raw(self, *args, **kwargs) -> Any:
+        """
+        Backend escape hatch for commands that don't fit the generic surface.
+        For MongoDB, this could be db.command(...), collection.bulk_write(...), etc.
+        """
+        ...

patera_database-0.1.0/src/patera/database/nosql/backends/mongo_backend.py

@@ -0,0 +1,197 @@
+"""
+MongoDB backend
+"""
+
+from typing import Optional, Callable, Any, Iterable, Mapping, TYPE_CHECKING, cast
+
+try:
+    from motor.motor_asyncio import AsyncIOMotorClient
+except Exception:
+    raise
+
+from .async_nosql_backend_protocol import AsyncNoSqlBackendBase
+
+if TYPE_CHECKING:
+    from patera import Patera
+
+
+class MongoBackend(AsyncNoSqlBackendBase):
+    def __init__(self, uri: str, database: Optional[str] = None) -> None:
+        self._client: Optional[Any] = None
+        self._db: Optional[Any] = None
+        self._uri: str = uri
+        self._database: Optional[str] = database
+
+    @classmethod
+    def configure_from_app(
+        cls, app: "Patera", configs: dict[str, Any]
+    ) -> "AsyncNoSqlBackendBase":
+        uri = cast(str, configs.get("DATABASE_URI"))
+        database = cast(str, configs.get("DATABASE"))
+        return cls(uri, database)
+
+    async def connect(self) -> None:
+        # Connect client
+        self._client = AsyncIOMotorClient(self._uri)
+        # Choose DB (or leave None; database_handle() will return client)
+        self._db = self._client[self._database] if self._database else None
+
+        # quick ping to verify connectivity
+        try:
+            await self._client.admin.command("ping")
+        except Exception as exc:  # pragma: no cover
+            raise RuntimeError(
+                f"Failed to connect to MongoDB at {self._uri}: {exc}"
+            ) from exc
+
+    async def disconnect(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+            self._db = None
+
+    def database_handle(self) -> Any:
+        # Prefer a db handle if configured; otherwise, return client
+        return self._db if self._db is not None else self._client
+
+    def supports_transactions(self) -> bool:
+        # Mongo supports transactions on replica sets / sharded clusters with WiredTiger.
+        return True
+
+    async def start_session(self) -> Any:
+        if not self._client:
+            raise RuntimeError("Mongo client not connected.")
+        return await self._client.start_session()
+
+    async def with_transaction(
+        self, fn: Callable[..., Any], *args, session: Any = None, **kwargs
+    ) -> Any:
+        # If session provided, run a transaction; else just call directly.
+        if session is None:
+            return await fn(*args, **kwargs)
+
+        async def runner(sess):
+            return await fn(*args, session=sess, **kwargs)
+
+        # Motor session has method 'with_transaction'
+        return await session.with_transaction(runner)
+
+    # ---- Collection / CRUD ----
+
+    def get_collection(self, name: str) -> Any:
+        db_or_client = self.database_handle()
+        if hasattr(db_or_client, "__getitem__"):  # db['collection']
+            return db_or_client[name]
+        # If only client exists but no db name given:
+        raise RuntimeError(
+            "No database selected. Set NOSQL_DATABASE or use database['<db>'][collection]."
+        )
+
+    async def find_one(
+        self,
+        collection: str,
+        filter: Mapping[str, Any],
+        *,
+        session: Any = None,
+        **kwargs,
+    ) -> Any:
+        coll = self.get_collection(collection)
+        return await coll.find_one(filter, session=session, **kwargs)
+
+    async def find_many(
+        self,
+        collection: str,
+        filter: Mapping[str, Any] | None = None,
+        *,
+        session: Any = None,
+        limit: Optional[int] = None,
+        skip: Optional[int] = None,
+        sort: Optional[Iterable[tuple[str, int]]] = None,
+        **kwargs,
+    ) -> list[Any]:
+        filter = filter or {}
+        coll = self.get_collection(collection)
+        cursor = coll.find(filter, session=session, **kwargs)
+        if sort:
+            cursor = cursor.sort(list(sort))
+        if skip:
+            cursor = cursor.skip(skip)
+        if limit:
+            cursor = cursor.limit(limit)
+        return await cursor.to_list(length=limit or 0)
+
+    async def insert_one(
+        self, collection: str, doc: Mapping[str, Any], *, session: Any = None, **kwargs
+    ) -> Any:
+        coll = self.get_collection(collection)
+        return await coll.insert_one(doc, session=session, **kwargs)
+
+    async def insert_many(
+        self,
+        collection: str,
+        docs: Iterable[Mapping[str, Any]],
+        *,
+        session: Any = None,
+        **kwargs,
+    ) -> Any:
+        coll = self.get_collection(collection)
+        return await coll.insert_many(list(docs), session=session, **kwargs)
+
+    async def update_one(
+        self,
+        collection: str,
+        filter: Mapping[str, Any],
+        update: Mapping[str, Any],
+        *,
+        upsert: bool = False,
+        session: Any = None,
+        **kwargs,
+    ) -> Any:
+        coll = self.get_collection(collection)
+        return await coll.update_one(
+            filter, update, upsert=upsert, session=session, **kwargs
+        )
+
+    async def delete_one(
+        self,
+        collection: str,
+        filter: Mapping[str, Any],
+        *,
+        session: Any = None,
+        **kwargs,
+    ) -> Any:
+        coll = self.get_collection(collection)
+        return await coll.delete_one(filter, session=session, **kwargs)
+
+    async def aggregate(
+        self,
+        collection: str,
+        pipeline: Iterable[Mapping[str, Any]],
+        *,
+        session: Any = None,
+        **kwargs,
+    ) -> list[Any]:
+        coll = self.get_collection(collection)
+        cursor = coll.aggregate(list(pipeline), session=session, **kwargs)
+        return await cursor.to_list(length=None)
+
+    async def execute_raw(self, *args, **kwargs) -> Any:
+        """
+        For MongoDB, you can call arbitrary db.command(...) via:
+            await db.execute_raw("command", {"ping": 1})
+        Or pass a callable to run with the database handle.
+        """
+        db = self.database_handle()
+        if callable(args[0]):
+            fn = args[0]
+            return await fn(db, *args[1:], **kwargs)
+
+        # Simple command passthrough:
+        if isinstance(args[0], str):
+            cmd = args[0]
+            arg = args[1] if len(args) > 1 else {}
+            return await db.command(
+                {cmd: arg} if not isinstance(arg, Mapping) else {cmd: 1, **arg}
+            )
+
+        raise TypeError("Unsupported execute_raw usage for MongoBackend.")

patera_database-0.1.0/src/patera/database/nosql/nosql_database.py

@@ -0,0 +1,241 @@
+"""
+NoSQL Database Module
+"""
+
+from pydantic import BaseModel, Field
+from typing import (
+    Optional,
+    Callable,
+    Any,
+    Iterable,
+    Mapping,
+    TYPE_CHECKING,
+    TypedDict,
+    cast,
+    Type,
+    NotRequired,
+)
+from functools import wraps
+
+from .backends.async_nosql_backend_protocol import AsyncNoSqlBackendBase
+from patera.base_extension import BaseExtension
+from patera.utilities import run_sync_or_async
+
+
+if TYPE_CHECKING:
+    from patera import Patera
+
+
+class _NoSqlDatabaseConfig(BaseModel):
+    """Configuration options for NoSqlDatabase extension."""
+
+    BACKEND: Type[AsyncNoSqlBackendBase] = Field(
+        description="Backend class implementing AsyncNoSqlBackendBase."
+    )
+    DATABASE_URI: str = Field(description="Connection string for the NoSQL backend.")
+    DATABASE_NAME: Optional[str] = Field(
+        default=None, description="Database / keyspace name (if backend uses it)."
+    )
+    DB_INJECT_NAME: Optional[str] = Field(
+        default="db", description="Kwarg name injected by decorators (database handle)."
+    )
+    SESSION_NAME: Optional[str] = Field(
+        default="session",
+        description="Kwarg name injected by @managed_database (session/transaction handle).",
+    )
+
+
+class NoSqlDatabaseConfig(TypedDict):
+    BACKEND: Type[AsyncNoSqlBackendBase]
+    DATABASE_URI: str
+    DATABASE_NAME: NotRequired[str]
+    INJECT_NAME: NotRequired[str]
+    SESSION_NAME: NotRequired[str]
+
+
+class NoSqlDatabase(BaseExtension):
+    """
+    A simple async NoSQL Database interface with pluggable backends.
+    """
+
+    def __init__(
+        self, db_name: str = "nosql", configs_name: str = "NOSQL_DATABASE"
+    ) -> None:
+        self._app: Optional["Patera"] = None
+        self._configs_name = configs_name
+        self._configs: dict[str, Any] = {}
+        self.__db_name__ = db_name
+
+        # Effective config
+        self.backend_name: Optional[str] = None
+        self.uri: Optional[str] = None
+        self.database: Optional[str] = None
+        self.inject_name: str = "db"
+        self.session_name: str = "session"
+
+        # Backend instance
+        self._backend: AsyncNoSqlBackendBase = cast(AsyncNoSqlBackendBase, None)
+
+    # ---- App lifecycle ----
+
+    def init_app(self, app: "Patera") -> None:
+        """
+        Initializes the NoSQL interface.
+        Required config keys (with optional variable_prefix):
+            - BACKEND
+            - DATABASE_URI
+        Optional:
+            - DATABASE
+            - INJECT_NAME (default "db")
+            - SESSION_NAME (default "session")
+        """
+        self._app = app
+        self._configs = app.get_conf(self._configs_name, None)
+        if self._configs is None:
+            raise ValueError(f"Missing {self._configs_name} configuration.")
+        self._configs = self.validate_configs(self._configs, _NoSqlDatabaseConfig)
+
+        self.backend_cls = self._configs.get("BACKEND")
+        self.uri = self._configs.get("DATABASE_URI")
+        self.database = self._configs.get("DATABASE_NAME")
+        self.inject_name = cast(str, self._configs.get("INJECT_NAME"))
+        self.session_name = cast(str, self._configs.get("SESSION_NAME"))
+
+        if not self.backend_cls or not self.uri:
+            raise RuntimeError(
+                "Missing NOSQL_BACKEND or NOSQL_DATABASE_URI configuration."
+            )
+        if not issubclass(self.backend_cls, AsyncNoSqlBackendBase):
+            raise RuntimeError(
+                "NOSQL_BACKEND must be a subclass of AsyncNoSqlBackendBase."
+            )
+
+        self._backend = cast(
+            AsyncNoSqlBackendBase, self.backend_cls
+        ).configure_from_app(app, self._configs)
+
+        app.add_extension(self)
+        app.add_on_startup_method(self.connect)
+        app.add_on_shutdown_method(self.disconnect)
+
+    async def connect(self) -> None:
+        """
+        Creates the backend client/connection. Runs on lifespan.start
+        """
+        if not self._backend:
+            raise RuntimeError("Backend not initialized. Call init_app() first.")
+        await self._backend.connect()
+
+    async def disconnect(self) -> None:
+        """
+        Disposes backend resources. Runs on lifespan.shutdown
+        """
+        if self._backend:
+            await self._backend.disconnect()
+
+    @property
+    def db_name(self) -> str:
+        return self.__db_name__
+
+    @property
+    def backend(self) -> AsyncNoSqlBackendBase:
+        if not self._backend:
+            raise RuntimeError("Backend not connected. Was init_app/connect called?")
+        return self._backend
+
+    def database_handle(self) -> Any:
+        return self.backend.database_handle()
+
+    def get_collection(self, name: str) -> Any:
+        return self.backend.get_collection(name)
+
+    async def find_one(
+        self, collection: str, filter: Mapping[str, Any], **kwargs
+    ) -> Any:
+        return await self.backend.find_one(collection, filter, **kwargs)
+
+    async def find_many(
+        self, collection: str, filter: Mapping[str, Any] | None = None, **kwargs
+    ) -> list[Any]:
+        return await self.backend.find_many(collection, filter, **kwargs)
+
+    async def insert_one(
+        self, collection: str, doc: Mapping[str, Any], **kwargs
+    ) -> Any:
+        return await self.backend.insert_one(collection, doc, **kwargs)
+
+    async def insert_many(
+        self, collection: str, docs: Iterable[Mapping[str, Any]], **kwargs
+    ) -> Any:
+        return await self.backend.insert_many(collection, docs, **kwargs)
+
+    async def update_one(
+        self,
+        collection: str,
+        filter: Mapping[str, Any],
+        update: Mapping[str, Any],
+        **kwargs,
+    ) -> Any:
+        return await self.backend.update_one(collection, filter, update, **kwargs)
+
+    async def delete_one(
+        self, collection: str, filter: Mapping[str, Any], **kwargs
+    ) -> Any:
+        return await self.backend.delete_one(collection, filter, **kwargs)
+
+    async def aggregate(
+        self, collection: str, pipeline: Iterable[Mapping[str, Any]], **kwargs
+    ) -> list[Any]:
+        return await self.backend.aggregate(collection, pipeline, **kwargs)
+
+    async def execute_raw(self, *args, **kwargs) -> Any:
+        """
+        Escape hatch for backend-specific commands. See MongoBackend.execute_raw docstring.
+        """
+        return await self.backend.execute_raw(*args, **kwargs)
+
+    @property
+    def managed_database(self) -> Callable:
+        """
+        Decorator that:
+        - Injects a database/client handle into handler kwargs under NOSQL_INJECT_NAME ("db" by default).
+        - If the backend supports transactions, opens a session+transaction for the duration
+          and commits/aborts automatically on exit.
+        """
+
+        def decorator(handler: Callable) -> Callable:
+            @wraps(handler)
+            async def wrapper(*args, **kwargs):
+                backend = self.backend
+                inject_key = self.inject_name
+                handle = backend.database_handle()
+
+                # default injection
+                kwargs[inject_key] = handle
+
+                if not backend.supports_transactions():
+                    # No transaction semantics; just run.
+                    return await run_sync_or_async(handler, *args, **kwargs)
+
+                # Transaction-capable flow
+                session = await backend.start_session()
+
+                async def _call_with_session(*_args, **_kwargs):
+                    # Some backends (Mongo) accept 'session' in calls; handlers can pass it through.
+                    _kwargs.setdefault(self.session_name, session)
+                    return await run_sync_or_async(handler, *_args, **_kwargs)
+
+                try:
+                    return await backend.with_transaction(
+                        _call_with_session, *args, **kwargs, session=session
+                    )
+                finally:
+                    # session ended in with_transaction, but just in case
+                    try:
+                        await session.end_session()  # type: ignore[attr-defined]
+                    except Exception:
+                        pass
+
+            return wrapper
+
+        return decorator

patera_database-0.1.0/src/patera/database/sql/__init__.py

@@ -0,0 +1,22 @@
+"""
+database module of patera
+"""
+
+# re-export of some commonly used sqlalchemy objects
+# and methods for convenience.
+from sqlalchemy import select, Select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .sql_database import SqlDatabase, SqlDatabaseConfig
+from .sqlalchemy_async_query import AsyncQuery
+from .declarative_base import DeclarativeBaseModel
+
+__all__ = [
+    "SqlDatabase",
+    "select",
+    "Select",
+    "AsyncSession",
+    "AsyncQuery",
+    "DeclarativeBaseModel",
+    "SqlDatabaseConfig",
+]