fastapi-factory-utilities 0.1.0__py3-none-any.whl

fastapi_factory_utilities/core/plugins/odm_plugin/__init__.py

@@ -0,0 +1,97 @@
+"""Oriented Data Model (ODM) plugin package."""
+
+from logging import INFO, Logger, getLogger
+from typing import Any
+
+from beanie import init_beanie  # pyright: ignore[reportUnknownVariableType]
+from motor.motor_asyncio import AsyncIOMotorClient
+from structlog.stdlib import BoundLogger, get_logger
+
+from fastapi_factory_utilities.core.protocols import BaseApplicationProtocol
+
+from .builder import ODMBuilder
+
+_logger: BoundLogger = get_logger()
+
+
+def pre_conditions_check(application: BaseApplicationProtocol) -> bool:
+    """Check the pre-conditions for the OpenTelemetry plugin.
+
+    Args:
+        application (BaseApplicationProtocol): The application.
+
+    Returns:
+        bool: True if the pre-conditions are met, False otherwise.
+    """
+    del application
+    return True
+
+
+def on_load(
+    application: BaseApplicationProtocol,
+) -> None:
+    """Actions to perform on load for the OpenTelemetry plugin.
+
+    Args:
+        application (BaseApplicationProtocol): The application.
+    """
+    del application
+    # Configure the pymongo logger to INFO level
+    pymongo_logger: Logger = getLogger("pymongo")
+    pymongo_logger.setLevel(INFO)
+    _logger.debug("ODM plugin loaded.")
+
+
+async def on_startup(
+    application: BaseApplicationProtocol,
+) -> None:
+    """Actions to perform on startup for the ODM plugin.
+
+    Args:
+        application (BaseApplicationProtocol): The application.
+        odm_config (ODMConfig): The ODM configuration.
+
+    Returns:
+        None
+    """
+    try:
+        odm_factory: ODMBuilder = ODMBuilder(application=application).build_all()
+    except Exception as exception:  # pylint: disable=broad-except
+        _logger.error(f"ODM plugin failed to start. {exception}")
+        return
+
+    if odm_factory.odm_database is None or odm_factory.odm_client is None:
+        _logger.error(
+            f"ODM plugin failed to start. Database: {odm_factory.odm_database} - " f"Client: {odm_factory.odm_client}"
+        )
+        return
+    # TODO: Find a way to add type to the state
+    application.get_asgi_app().state.odm_client = odm_factory.odm_client
+    application.get_asgi_app().state.odm_database = odm_factory.odm_database
+
+    # TODO: Find a better way to initialize beanie with the document models of the concrete application
+    # through an hook in the application ?
+    await init_beanie(
+        database=odm_factory.odm_database,
+        document_models=application.ODM_DOCUMENT_MODELS,
+    )
+
+    _logger.info(
+        f"ODM plugin started. Database: {odm_factory.odm_database.name} - "
+        f"Client: {odm_factory.odm_client.address} - "
+        f"Document models: {application.ODM_DOCUMENT_MODELS}"
+    )
+
+
+async def on_shutdown(application: BaseApplicationProtocol) -> None:
+    """Actions to perform on shutdown for the ODM plugin.
+
+    Args:
+        application (BaseApplicationProtocol): The application.
+
+    Returns:
+        None
+    """
+    client: AsyncIOMotorClient[Any] = application.get_asgi_app().state.odm_client
+    client.close()
+    _logger.debug("ODM plugin shutdown.")

fastapi_factory_utilities/core/plugins/odm_plugin/builder.py

@@ -0,0 +1,239 @@
+"""Provides the module for the ODM plugin."""
+
+import asyncio
+import time
+from typing import Any, Self
+
+from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
+from structlog.stdlib import get_logger
+
+from fastapi_factory_utilities.core.protocols import BaseApplicationProtocol
+from fastapi_factory_utilities.core.utils.importlib import get_path_file_in_package
+from fastapi_factory_utilities.core.utils.yaml_reader import (
+    UnableToReadYamlFileError,
+    YamlFileReader,
+)
+
+from .configs import ODMConfig
+from .exceptions import ODMPluginConfigError
+
+_logger = get_logger()
+
+
+class ODMBuilder:
+    """Factory to create the resources for the ODM plugin.
+
+    The factory is responsible for creating the resources for the ODM plugin.
+    - The ODM configuration.
+    - The ODM client.
+    - The ODM database.
+
+    ```python
+    # Example of using the ODMFactory
+    odm_factory: ODMFactory = ODMFactory(application=application)
+    odm_factory.build_all()
+    # Access the ODM database created
+    database: AsyncIOMotorDatabase[Any] = odm_factory.database
+    ```
+
+    """
+
+    def __init__(
+        self,
+        application: BaseApplicationProtocol,
+        odm_config: ODMConfig | None = None,
+        odm_client: AsyncIOMotorClient[Any] | None = None,
+        odm_database: AsyncIOMotorDatabase[Any] | None = None,
+    ) -> None:
+        """Initialize the ODMFactory.
+
+        Args:
+            application (BaseApplicationProtocol): The application.
+            odm_config (ODMConfig): The ODM configuration for injection. (Default is None)
+            odm_client (AsyncIOMotorClient): The ODM client for injection. (Default is None)
+            odm_database (AsyncIOMotorDatabase): The ODM database for injection. (Default is None)
+
+        """
+        self._application: BaseApplicationProtocol = application
+        self._config: ODMConfig | None = odm_config
+        self._odm_client: AsyncIOMotorClient[Any] | None = odm_client
+        self._odm_database: AsyncIOMotorDatabase[Any] | None = odm_database
+
+    @property
+    def config(self) -> ODMConfig | None:
+        """Provide the ODM configuration object.
+
+        Returns:
+            ODMConfig: The ODM configuration object.
+        """
+        return self._config
+
+    @property
+    def odm_client(self) -> AsyncIOMotorClient[Any] | None:
+        """Provide the ODM client.
+
+        Returns:
+            AsyncIOMotorClient | None: The ODM client.
+        """
+        return self._odm_client
+
+    @property
+    def odm_database(self) -> AsyncIOMotorDatabase[Any] | None:
+        """Provide the ODM database.
+
+        Returns:
+            AsyncIOMotorDatabase | None: The ODM database.
+        """
+        return self._odm_database
+
+    def build_odm_config(
+        self,
+    ) -> Self:
+        """Build the ODM configuration object.
+
+        Returns:
+            Self: The ODM factory.
+
+        Raises:
+            ODMPluginConfigError: If the package name is not set or the configuration file is not found.
+        """
+        if self._config is not None:
+            return self
+
+        if self._application.PACKAGE_NAME == "":
+            raise ODMPluginConfigError("The package name must be set in the concrete application class.")
+        # Read the application configuration file
+        try:
+            yaml_file_content: dict[str, Any] = YamlFileReader(
+                file_path=get_path_file_in_package(
+                    filename="application.yaml",
+                    package=self._application.PACKAGE_NAME,
+                ),
+                yaml_base_key="odm",
+                use_environment_injection=True,
+            ).read()
+        except (FileNotFoundError, ImportError, UnableToReadYamlFileError) as exception:
+            raise ODMPluginConfigError("Unable to read the application configuration file.") from exception
+
+        # Create the application configuration model
+        try:
+            self._config = ODMConfig(**yaml_file_content)
+        except ValueError as exception:
+            raise ODMPluginConfigError("Unable to create the application configuration model.") from exception
+        return self
+
+    @classmethod
+    def _wait_client_to_be_ready(cls, client: AsyncIOMotorClient[Any], timeout_ms: int) -> None:
+        """Wait for the ODM client to be ready.
+
+        Args:
+            client (AsyncIOMotorClient): The ODM client.
+            timeout_ms (int): The timeout in milliseconds.
+
+        Raises:
+            ODMPluginConfigError: If the ODM client is not ready.
+        """
+        start_timer = time.monotonic()
+
+        async def is_connected(client: AsyncIOMotorClient[Any]) -> bool:
+            """Check if the client is connected."""
+            try:
+                await client.admin.command(
+                    command="ping",
+                )  # pyright: ignore
+                return True
+            except Exception:  # pylint: disable=broad-except
+                _logger.debug("ODM client is not ready.")
+                return False
+
+        loop: asyncio.AbstractEventLoop = asyncio.get_event_loop()
+
+        while not loop.run_in_executor(None, asyncio.Task(is_connected(client))) and (  # type: ignore
+            (time.monotonic() - start_timer) < timeout_ms
+        ):
+            if time.monotonic() - start_timer > timeout_ms:
+                raise ODMPluginConfigError("ODM client is not ready.")
+            time.sleep(0.01)
+
+        if not loop.run_in_executor(None, asyncio.Task(is_connected(client))):  # type: ignore
+            raise ODMPluginConfigError("ODM client is not ready.")
+
+    def build_client(
+        self,
+    ) -> Self:
+        """Build the ODM client.
+
+        Returns:
+            Self: The ODM factory.
+
+        Raises:
+            ODMPluginConfigError: If the ODM configuration is not build or provided.
+        """
+        if self._odm_client is not None:
+            return self
+
+        if self._config is None:
+            raise ODMPluginConfigError(
+                "ODM configuration is not set. Provide the ODM configuration using "
+                "build_odm_config method or through parameter."
+            )
+
+        self._odm_client = AsyncIOMotorClient(
+            host=self._config.uri,
+            connect=True,
+            connectTimeoutMS=self._config.connection_timeout_ms,
+            serverSelectionTimeoutMS=self._config.connection_timeout_ms,
+        )
+
+        self._wait_client_to_be_ready(client=self._odm_client, timeout_ms=self._config.connection_timeout_ms)
+
+        return self
+
+    def build_database(
+        self,
+    ) -> Self:
+        """Build the ODM database.
+
+        The ODM client and ODM configuration are recommended to be provided through call to the build_client and
+        build_odm_config methods.
+
+        Returns:
+            Any: The ODM database.
+
+        Raises:
+            ODMPluginConfigError: If the ODM configuration is not build or provided.
+        """
+        if self._odm_database is not None:
+            return self
+
+        if self._config is None:
+            raise ODMPluginConfigError(
+                "ODM configuration is not set. Provide the ODM configuration using "
+                "build_odm_config method or through parameter."
+            )
+
+        database_name: str = self._config.database
+
+        if self._odm_client is None:
+            raise ODMPluginConfigError(
+                "ODM client is not set. Provide the ODM client using " "build_client method or through parameter."
+            )
+
+        self._odm_database = self._odm_client.get_database(name=database_name)
+
+        return self
+
+    def build_all(self) -> Self:
+        """Build all the resources for the ODM plugin.
+
+        Returns:
+            Self: The ODM factory.
+
+        Raises:
+            ODMPluginConfigError: If the ODM configuration is not build or provided.
+        """
+        self.build_odm_config()
+        self.build_client()
+        self.build_database()
+
+        return self

fastapi_factory_utilities/core/plugins/odm_plugin/configs.py

@@ -0,0 +1,17 @@
+"""Provides the configuration for the ODM plugin."""
+
+from pydantic import BaseModel, ConfigDict
+
+S_TO_MS = 1000
+
+
+class ODMConfig(BaseModel):
+    """Provides the configuration model for the ODM plugin."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    uri: str
+
+    database: str = "test"
+
+    connection_timeout_ms: int = 1 * S_TO_MS

fastapi_factory_utilities/core/plugins/odm_plugin/documents.py

@@ -0,0 +1,31 @@
+"""Provides base document class for ODM plugins."""
+
+import datetime
+from typing import Annotated
+from uuid import UUID, uuid4
+
+from beanie import Document, Indexed  # pyright: ignore[reportUnknownVariableType]
+from pydantic import Field
+from pymongo import DESCENDING
+
+
+class BaseDocument(Document):
+    """Base document class."""
+
+    # To be agnostic of MongoDN, we use UUID as the document ID.
+    id: UUID = Field(  # pyright: ignore[reportIncompatibleVariableOverride]
+        default_factory=uuid4, description="The document ID."
+    )
+
+    created_at: Annotated[datetime.datetime, Indexed(index_type=DESCENDING)] = Field(  # pyright: ignore
+        default_factory=lambda: datetime.datetime.now(tz=datetime.UTC), description="Creation timestamp."
+    )
+
+    updated_at: Annotated[datetime.datetime, Indexed(index_type=DESCENDING)] = Field(  # pyright: ignore
+        default_factory=lambda: datetime.datetime.now(tz=datetime.UTC), description="Last update timestamp."
+    )
+
+    class Settings:
+        """Meta class for BaseDocument."""
+
+        use_revision = True

fastapi_factory_utilities/core/plugins/odm_plugin/exceptions.py

@@ -0,0 +1,25 @@
+"""Provides the exceptions for the ODM_Plugin."""
+
+
+class ODMPluginBaseException(BaseException):
+    """Base exception for the ODM_Plugin."""
+
+    pass
+
+
+class ODMPluginConfigError(ODMPluginBaseException):
+    """Exception for the ODM_Plugin configuration."""
+
+    pass
+
+
+class UnableToCreateEntityDueToDuplicateKeyError(ODMPluginBaseException):
+    """Exception for when the entity cannot be created due to a duplicate key error."""
+
+    pass
+
+
+class OperationError(ODMPluginBaseException):
+    """Exception for when an operation fails."""
+
+    pass

fastapi_factory_utilities/core/plugins/odm_plugin/repositories.py

@@ -0,0 +1,172 @@
+"""Provides the abstract classes for the repositories."""
+
+from abc import ABC
+from collections.abc import AsyncGenerator, Callable
+from contextlib import asynccontextmanager
+from typing import Any, Generic, TypeVar, get_args
+from uuid import UUID
+
+from motor.motor_asyncio import AsyncIOMotorClientSession, AsyncIOMotorDatabase
+from pydantic import BaseModel
+from pymongo.errors import DuplicateKeyError, PyMongoError
+from pymongo.results import DeleteResult
+
+from .documents import BaseDocument
+from .exceptions import OperationError, UnableToCreateEntityDueToDuplicateKeyError
+
+DocumentGenericType = TypeVar("DocumentGenericType", bound=BaseDocument)  # pylint: disable=invalid-name
+EntityGenericType = TypeVar("EntityGenericType", bound=BaseModel)  # pylint: disable=invalid-name
+
+
+def managed_session() -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator to manage the session.
+
+    It will introspect the function arguments and check if the session is passed as a keyword argument.
+    If it is not, it will create a new session and pass it to the function.
+    """
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            if "session" in kwargs:
+                return await func(*args, **kwargs)
+
+            async with args[0].get_session() as session:
+                return await func(*args, **kwargs, session=session)
+
+        return wrapper
+
+    return decorator
+
+
+class AbstractRepository(ABC, Generic[DocumentGenericType, EntityGenericType]):
+    """Abstract class for the repository."""
+
+    def __init__(self, database: AsyncIOMotorDatabase[Any]) -> None:
+        """Initialize the repository."""
+        super().__init__()
+        self._database: AsyncIOMotorDatabase[Any] = database
+        # Retrieve the generic concrete types
+        generic_args: tuple[Any, ...] = get_args(self.__orig_bases__[0])  # type: ignore
+        self._document_type: type[DocumentGenericType] = generic_args[0]
+        self._entity_type: type[EntityGenericType] = generic_args[1]
+
+    @asynccontextmanager
+    async def get_session(self) -> AsyncGenerator[AsyncIOMotorClientSession, None]:
+        """Yield a new session."""
+        try:
+            async with await self._database.client.start_session() as session:
+                yield session
+        except PyMongoError as error:
+            raise OperationError(f"Failed to create session: {error}") from error
+
+    @managed_session()
+    async def insert(
+        self, entity: EntityGenericType, session: AsyncIOMotorClientSession | None = None
+    ) -> EntityGenericType:
+        """Insert the entity into the database.
+
+        Args:
+            entity (EntityGenericType): The entity to insert.
+            session (AsyncIOMotorClientSession | None): The session to use. Defaults to None. (managed by decorator)
+
+        Returns:
+            EntityGenericType: The entity created.
+
+        Raises:
+            ValueError: If the entity cannot be created from the document.
+            UnableToCreateEntityDueToDuplicateKeyError: If the entity cannot be created due to a duplicate key error.
+            OperationError: If the operation fails.
+        """
+        try:
+            document: DocumentGenericType = self._document_type(**entity.model_dump())
+        except ValueError as error:
+            raise ValueError(f"Failed to create document from entity: {error}") from error
+
+        try:
+            document_created: DocumentGenericType = await document.save(session=session)
+        except DuplicateKeyError as error:
+            raise UnableToCreateEntityDueToDuplicateKeyError(f"Failed to insert document: {error}") from error
+        except PyMongoError as error:
+            raise OperationError(f"Failed to insert document: {error}") from error
+
+        try:
+            entity_created: EntityGenericType = self._entity_type(**document_created.model_dump())
+        except ValueError as error:
+            raise ValueError(f"Failed to create entity from document: {error}") from error
+
+        return entity_created
+
+    @managed_session()
+    async def get_one_by_id(
+        self,
+        entity_id: UUID,
+        session: AsyncIOMotorClientSession | None = None,
+    ) -> EntityGenericType | None:
+        """Get the entity by its ID.
+
+        Args:
+            entity_id (UUID): The ID of the entity.
+            session (AsyncIOMotorClientSession | None): The session to use. Defaults to None. (managed by decorator)
+
+        Returns:
+            EntityGenericType | None: The entity or None if not found.
+
+        Raises:
+            OperationError: If the operation fails.
+
+        """
+        try:
+            document: DocumentGenericType | None = await self._document_type.get(document_id=entity_id, session=session)
+        except PyMongoError as error:
+            raise OperationError(f"Failed to get document: {error}") from error
+
+        # If no document is found, return None
+        if document is None:
+            return None
+
+        # Convert the document to an entity
+        try:
+            entity: EntityGenericType = self._entity_type(**document.model_dump())
+        except ValueError as error:
+            raise ValueError(f"Failed to create entity from document: {error}") from error
+
+        return entity
+
+    @managed_session()
+    async def delete_one_by_id(
+        self, entity_id: UUID, raise_if_not_found: bool = False, session: AsyncIOMotorClientSession | None = None
+    ) -> None:
+        """Delete a document by its ID.
+
+        Args:
+            entity_id (UUID): The ID of the entity.
+            raise_if_not_found (bool, optional): Raise an exception if the document is not found. Defaults to False.
+            session (AsyncIOMotorClientSession | None, optional): The session to use.
+            Defaults to None. (managed by decorator)
+
+        Raises:
+            ValueError: If the document is not found and raise_if_not_found is True.
+            OperationError: If the operation fails.
+
+        """
+        try:
+            document_to_delete: DocumentGenericType | None = await self._document_type.get(
+                document_id=entity_id, session=session
+            )
+        except PyMongoError as error:
+            raise OperationError(f"Failed to get document to delete: {error}") from error
+
+        if document_to_delete is None:
+            if raise_if_not_found:
+                raise ValueError(f"Failed to find document with ID {entity_id}")
+            return
+
+        try:
+            delete_result: DeleteResult | None = await document_to_delete.delete()
+        except PyMongoError as error:
+            raise OperationError(f"Failed to delete document: {error}") from error
+
+        if delete_result is not None and delete_result.deleted_count == 1 and delete_result.acknowledged:
+            return
+
+        raise OperationError("Failed to delete document.")