fastapi-factory-utilities 0.2.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

fastapi_factory_utilities/core/plugins/odm_plugin/__init__.py

@@ -1,154 +1,26 @@
-"""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 reactivex import Subject
-from structlog.stdlib import BoundLogger, get_logger
-
-from fastapi_factory_utilities.core.plugins import PluginState
-from fastapi_factory_utilities.core.protocols import ApplicationAbstractProtocol
-from fastapi_factory_utilities.core.services.status.enums import (
-    ComponentTypeEnum,
-    HealthStatusEnum,
-    ReadinessStatusEnum,
-)
-from fastapi_factory_utilities.core.services.status.services import StatusService
-from fastapi_factory_utilities.core.services.status.types import (
-    ComponentInstanceType,
-    Status,
+"""ODM Plugin Module."""
+
+from .depends import depends_odm_client, depends_odm_database
+from .documents import BaseDocument
+from .exceptions import (
+    ODMPluginBaseException,
+    ODMPluginConfigError,
+    OperationError,
+    UnableToCreateEntityDueToDuplicateKeyError,
 )
-
-from .builder import ODMBuilder
-
-_logger: BoundLogger = get_logger()
-
-
-def pre_conditions_check(application: ApplicationAbstractProtocol) -> 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: ApplicationAbstractProtocol,
-) -> list["PluginState"] | 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: ApplicationAbstractProtocol,
-) -> list["PluginState"] | None:
-    """Actions to perform on startup for the ODM plugin.
-
-    Args:
-        application (BaseApplicationProtocol): The application.
-        odm_config (ODMConfig): The ODM configuration.
-
-    Returns:
-        None
-    """
-    states: list[PluginState] = []
-
-    status_service: StatusService = application.get_status_service()
-    component_instance: ComponentInstanceType = ComponentInstanceType(
-        component_type=ComponentTypeEnum.DATABASE, identifier="MongoDB"
-    )
-    monitoring_subject: Subject[Status] = status_service.register_component_instance(
-        component_instance=component_instance
-    )
-
-    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}")
-        # TODO: Report the error to the status_service
-        # this will report the application as unhealthy
-        monitoring_subject.on_next(
-            value=Status(health=HealthStatusEnum.UNHEALTHY, readiness=ReadinessStatusEnum.NOT_READY)
-        )
-        return states
-
-    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}"
-        )
-        # TODO: Report the error to the status_service
-        # this will report the application as unhealthy
-        monitoring_subject.on_next(
-            value=Status(health=HealthStatusEnum.UNHEALTHY, readiness=ReadinessStatusEnum.NOT_READY)
-        )
-        return states
-
-    # Add the ODM client and database to the application state
-    states.append(
-        PluginState(key="odm_client", value=odm_factory.odm_client),
-    )
-    states.append(
-        PluginState(
-            key="odm_database",
-            value=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, a dynamis import ?
-    try:
-        await init_beanie(
-            database=odm_factory.odm_database,
-            document_models=application.ODM_DOCUMENT_MODELS,
-        )
-    except Exception as exception:  # pylint: disable=broad-except
-        _logger.error(f"ODM plugin failed to start. {exception}")
-        # TODO: Report the error to the status_service
-        # this will report the application as unhealthy
-        monitoring_subject.on_next(
-            value=Status(health=HealthStatusEnum.UNHEALTHY, readiness=ReadinessStatusEnum.NOT_READY)
-        )
-        return states
-
-    _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}"
-    )
-
-    monitoring_subject.on_next(value=Status(health=HealthStatusEnum.HEALTHY, readiness=ReadinessStatusEnum.READY))
-
-    return states
-
-
-async def on_shutdown(application: ApplicationAbstractProtocol) -> None:
-    """Actions to perform on shutdown for the ODM plugin.
-
-    Args:
-        application (BaseApplicationProtocol): The application.
-
-    Returns:
-        None
-    """
-    # Skip if the ODM plugin was not started correctly
-    if not hasattr(application.get_asgi_app().state, "odm_client"):
-        return
-
-    client: AsyncIOMotorClient[Any] = application.get_asgi_app().state.odm_client
-    client.close()
-    _logger.debug("ODM plugin shutdown.")
+from .helpers import PersistedEntity
+from .plugins import ODMPlugin
+from .repositories import AbstractRepository
+
+__all__: list[str] = [
+    "AbstractRepository",
+    "BaseDocument",
+    "ODMPlugin",
+    "ODMPluginBaseException",
+    "ODMPluginConfigError",
+    "OperationError",
+    "PersistedEntity",
+    "UnableToCreateEntityDueToDuplicateKeyError",
+    "depends_odm_client",
+    "depends_odm_database",
+]

fastapi_factory_utilities/core/plugins/odm_plugin/builder.py

@@ -1,9 +1,10 @@
 """Provides the module for the ODM plugin."""
 
-import time
 from typing import Any, ClassVar, Self
 
+from bson import CodecOptions
 from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
+from pymongo.server_api import ServerApi, ServerApiVersion
 from structlog.stdlib import get_logger
 
 from fastapi_factory_utilities.core.protocols import ApplicationAbstractProtocol
@@ -124,31 +125,34 @@ class ODMBuilder:
             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_s: int) -> None:
-        """Wait for the ODM client to be ready.
-
-        Args:
-            client (AsyncIOMotorClient): The ODM client.
-            timeout_s (int): The timeout in seconds.
-
-        Raises:
-            TimeoutError: If the ODM client is not ready in the given timeout.
-        """
-        start_time: float = time.time()
-        message_time: float = time.time()
-        while (time.time() - start_time) < (timeout_s):
-            if len(client.nodes) > 0:  # type: ignore
-                _logger.info(f"Waiting {(time.time() - start_time)*cls.MS_TO_S}ms for the ODM client to be ready.")
-                return
-
-            if (time.time() - message_time) > 1:
-                elaps_time: float = time.time() - start_time
-                _logger.debug(f"Waiting for the ODM client to be ready. (from {int(elaps_time)}s) ")
-                message_time = time.time()
-            time.sleep(cls.SLEEP_TIME_S)
-
-        raise TimeoutError("The ODM client is not ready in the given timeout.")
+    # ======
+    # KEEP IT, Waiting for additional tests
+    # @classmethod
+    # def _wait_client_to_be_ready(cls, client: AsyncIOMotorClient[Any], timeout_s: int) -> None:
+    #     """Wait for the ODM client to be ready.
+
+    #     Args:
+    #         client (AsyncIOMotorClient): The ODM client.
+    #         timeout_s (int): The timeout in seconds.
+
+    #     Raises:
+    #         TimeoutError: If the ODM client is not ready in the given timeout.
+    #     """
+    #     start_time: float = time.time()
+    #     message_time: float = time.time()
+    #     while (time.time() - start_time) < (timeout_s):
+    #         if len(client.nodes) > 0:  # type: ignore
+    #             _logger.info(f"Waiting {(time.time() - start_time)*cls.MS_TO_S}ms for the ODM client to be ready.")
+    #             return
+
+    #         if (time.time() - message_time) > 1:
+    #             elaps_time: float = time.time() - start_time
+    #             _logger.debug(f"Waiting for the ODM client to be ready. (from {int(elaps_time)}s) ")
+    #             message_time = time.time()
+    #         time.sleep(cls.SLEEP_TIME_S)
+
+    #     raise TimeoutError("The ODM client is not ready in the given timeout.")
+    # ======
 
     def build_client(
         self,
@@ -173,11 +177,14 @@ class ODMBuilder:
         self._odm_client = AsyncIOMotorClient(
             host=self._config.uri,
             connect=True,
-            connectTimeoutMS=self._config.connection_timeout_s,
-            serverSelectionTimeoutMS=self._config.connection_timeout_s,
+            connectTimeoutMS=self._config.connection_timeout_ms,
+            serverSelectionTimeoutMS=self._config.connection_timeout_ms,
+            server_api=ServerApi(version=ServerApiVersion.V1),
+            tz_aware=True,
         )
 
-        self._wait_client_to_be_ready(client=self._odm_client, timeout_s=self._config.connection_timeout_s)
+        # KEEP IT, Waiting for additional tests
+        # self._wait_client_to_be_ready(client=self._odm_client, timeout_s=self._config.connection_timeout_s)
 
         return self
 
@@ -208,10 +215,15 @@ class ODMBuilder:
 
         if self._odm_client is None:
             raise ODMPluginConfigError(
-                "ODM client is not set. Provide the ODM client using " "build_client method or through parameter."
+                "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)
+        self._odm_database = self._odm_client.get_database(
+            name=database_name,
+            codec_options=CodecOptions(  # pyright: ignore[reportUnknownArgumentType]
+                tz_aware=True,
+            ),
+        )
 
         return self
 
@@ -229,3 +241,19 @@ class ODMBuilder:
         self.build_database()
 
         return self
+
+    async def wait_ping(self) -> None:
+        """Wait for the ODM client to be ready.
+
+        Returns:
+            Self: The ODM factory.
+        """
+        if self._odm_client is None:
+            raise ODMPluginConfigError(
+                "ODM client is not set. Provide the ODM client using build_client method or through parameter."
+            )
+
+        try:
+            await self._odm_client.admin.command("ping")
+        except Exception as exception:  # pylint: disable=broad-except
+            raise ODMPluginConfigError("Unable to ping the ODM client.") from exception

fastapi_factory_utilities/core/plugins/odm_plugin/configs.py

@@ -12,4 +12,4 @@ class ODMConfig(BaseModel):
 
     database: str = "test"
 
-    connection_timeout_s: int = 10
+    connection_timeout_ms: int = 4000

fastapi_factory_utilities/core/plugins/odm_plugin/documents.py

@@ -13,10 +13,11 @@ class BaseDocument(Document):
     """Base document class."""
 
     # To be agnostic of MongoDN, we use UUID as the document ID.
-    id: UUID = Field(  # pyright: ignore[reportIncompatibleVariableOverride]
+    id: UUID = Field(  # type: ignore
         default_factory=uuid4, description="The document ID."
     )
 
+    revision_id: UUID | None = Field(default=None, exclude=False)
     created_at: Annotated[datetime.datetime, Indexed(index_type=DESCENDING)] = Field(  # pyright: ignore
         default_factory=lambda: datetime.datetime.now(tz=datetime.UTC), description="Creation timestamp."
     )

fastapi_factory_utilities/core/plugins/odm_plugin/helpers.py

@@ -0,0 +1,16 @@
+"""Helper functions for ODM plugins."""
+
+import datetime
+import uuid
+
+from pydantic import BaseModel, Field
+
+
+class PersistedEntity(BaseModel):
+    """Base class for persisted entities."""
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)
+
+    revision_id: uuid.UUID | None = Field(default=None)
+    created_at: datetime.datetime = Field(default_factory=datetime.datetime.now)
+    updated_at: datetime.datetime = Field(default_factory=datetime.datetime.now)

fastapi_factory_utilities/core/plugins/odm_plugin/plugins.py

@@ -0,0 +1,155 @@
+"""Oriented Data Model (ODM) plugin package."""
+
+from logging import INFO, Logger, getLogger
+from typing import Any, Self
+
+from beanie import Document, init_beanie  # pyright: ignore[reportUnknownVariableType]
+from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
+from reactivex import Subject
+from structlog.stdlib import BoundLogger, get_logger
+
+from fastapi_factory_utilities.core.plugins.abstracts import PluginAbstract
+from fastapi_factory_utilities.core.protocols import ApplicationAbstractProtocol
+from fastapi_factory_utilities.core.services.status.enums import (
+    ComponentTypeEnum,
+    HealthStatusEnum,
+    ReadinessStatusEnum,
+)
+from fastapi_factory_utilities.core.services.status.services import StatusService
+from fastapi_factory_utilities.core.services.status.types import (
+    ComponentInstanceType,
+    Status,
+)
+
+from .builder import ODMBuilder
+from .configs import ODMConfig
+from .depends import depends_odm_client, depends_odm_database
+from .documents import BaseDocument
+from .exceptions import OperationError, UnableToCreateEntityDueToDuplicateKeyError
+from .helpers import PersistedEntity
+from .repositories import AbstractRepository
+
+_logger: BoundLogger = get_logger()
+
+
+class ODMPlugin(PluginAbstract):
+    """ODM plugin."""
+
+    def __init__(
+        self, document_models: list[type[Document]] | None = None, odm_config: ODMConfig | None = None
+    ) -> None:
+        """Initialize the ODM plugin."""
+        super().__init__()
+        self._component_instance: ComponentInstanceType | None = None
+        self._monitoring_subject: Subject[Status] | None = None
+        self._document_models: list[type[Document]] | None = document_models
+        self._odm_config: ODMConfig | None = odm_config
+        self._odm_client: AsyncIOMotorClient[Any] | None = None
+        self._odm_database: AsyncIOMotorDatabase[Any] | None = None
+
+    def set_application(self, application: ApplicationAbstractProtocol) -> Self:
+        """Set the application."""
+        self._document_models = self._document_models or application.ODM_DOCUMENT_MODELS
+        return super().set_application(application)
+
+    def on_load(self) -> None:
+        """Actions to perform on load for the ODM plugin."""
+        # Configure the pymongo logger to INFO level
+
+        pymongo_logger: Logger = getLogger("pymongo")
+        pymongo_logger.setLevel(INFO)
+        _logger.debug("ODM plugin loaded.")
+
+    def _setup_status(self) -> None:
+        assert self._application is not None
+        status_service: StatusService = self._application.get_status_service()
+        self._component_instance = ComponentInstanceType(
+            component_type=ComponentTypeEnum.DATABASE, identifier="MongoDB"
+        )
+        self._monitoring_subject = status_service.register_component_instance(
+            component_instance=self._component_instance
+        )
+
+    async def _setup_beanie(self) -> None:
+        assert self._application is not None
+        assert self._odm_database is not None
+        assert self._document_models is not None
+        assert self._monitoring_subject is not None
+        # TODO: Find a better way to initialize beanie with the document models of the concrete application
+        # through an hook in the application, a dynamis import ?
+        try:
+            await init_beanie(
+                database=self._odm_database,
+                document_models=self._document_models,
+            )
+        except Exception as exception:  # pylint: disable=broad-except
+            _logger.error(f"ODM plugin failed to start. {exception}")
+            # TODO: Report the error to the status_service
+            # this will report the application as unhealthy
+            self._monitoring_subject.on_next(
+                value=Status(health=HealthStatusEnum.UNHEALTHY, readiness=ReadinessStatusEnum.NOT_READY)
+            )
+
+    async def on_startup(self) -> None:
+        """Actions to perform on startup for the ODM plugin."""
+        assert self._application is not None
+        self._setup_status()
+        assert self._monitoring_subject is not None
+        assert self._component_instance is not None
+
+        try:
+            odm_factory: ODMBuilder = ODMBuilder(application=self._application, odm_config=self._odm_config).build_all()
+            await odm_factory.wait_ping()
+            self._odm_database = odm_factory.odm_database
+            self._odm_client = odm_factory.odm_client
+        except Exception as exception:  # pylint: disable=broad-except
+            _logger.error(f"ODM plugin failed to start. {exception}")
+            # TODO: Report the error to the status_service
+            # this will report the application as unhealthy
+            self._monitoring_subject.on_next(
+                value=Status(health=HealthStatusEnum.UNHEALTHY, readiness=ReadinessStatusEnum.NOT_READY)
+            )
+            return None
+
+        if self._odm_database is None or self._odm_client is None:
+            _logger.error(
+                f"ODM plugin failed to start. Database: {odm_factory.odm_database} - Client: {odm_factory.odm_client}"
+            )
+            # TODO: Report the error to the status_service
+            # this will report the application as unhealthy
+            self._monitoring_subject.on_next(
+                value=Status(health=HealthStatusEnum.UNHEALTHY, readiness=ReadinessStatusEnum.NOT_READY)
+            )
+            return None
+
+        self._add_to_state(key="odm_client", value=odm_factory.odm_client)
+        self._add_to_state(key="odm_database", value=odm_factory.odm_database)
+
+        await self._setup_beanie()
+
+        _logger.info(
+            f"ODM plugin started. Database: {self._odm_database.name} - "
+            f"Client: {self._odm_client.address} - "
+            f"Document models: {self._application.ODM_DOCUMENT_MODELS}"
+        )
+
+        self._monitoring_subject.on_next(
+            value=Status(health=HealthStatusEnum.HEALTHY, readiness=ReadinessStatusEnum.READY)
+        )
+
+    async def on_shutdown(self) -> None:
+        """Actions to perform on shutdown for the ODM plugin."""
+        if self._odm_client is not None:
+            self._odm_client.close()
+        _logger.debug("ODM plugin shutdown.")
+
+
+__all__: list[str] = [
+    "AbstractRepository",
+    "BaseDocument",
+    "OperationError",
+    "PersistedEntity",
+    "UnableToCreateEntityDueToDuplicateKeyError",
+    "depends_odm_client",
+    "depends_odm_database",
+]

fastapi_factory_utilities/core/plugins/odm_plugin/repositories.py

@@ -1,11 +1,13 @@
 """Provides the abstract classes for the repositories."""
 
+import datetime
 from abc import ABC
-from collections.abc import AsyncGenerator, Callable
+from collections.abc import AsyncGenerator, Callable, Mapping
 from contextlib import asynccontextmanager
 from typing import Any, Generic, TypeVar, get_args
 from uuid import UUID
 
+from beanie import SortDirection
 from motor.motor_asyncio import AsyncIOMotorClientSession, AsyncIOMotorDatabase
 from pydantic import BaseModel
 from pymongo.errors import DuplicateKeyError, PyMongoError
@@ -77,13 +79,18 @@ class AbstractRepository(ABC, Generic[DocumentGenericType, EntityGenericType]):
             UnableToCreateEntityDueToDuplicateKeyError: If the entity cannot be created due to a duplicate key error.
             OperationError: If the operation fails.
         """
+        insert_time: datetime.datetime = datetime.datetime.now(tz=datetime.UTC)
         try:
-            document: DocumentGenericType = self._document_type(**entity.model_dump())
+            entity_dump: dict[str, Any] = entity.model_dump()
+            entity_dump["created_at"] = insert_time
+            entity_dump["updated_at"] = insert_time
+            document: DocumentGenericType = self._document_type(**entity_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)
+            document_created: DocumentGenericType = await document.insert(session=session)
         except DuplicateKeyError as error:
             raise UnableToCreateEntityDueToDuplicateKeyError(f"Failed to insert document: {error}") from error
         except PyMongoError as error:
@@ -96,6 +103,44 @@ class AbstractRepository(ABC, Generic[DocumentGenericType, EntityGenericType]):
 
         return entity_created
 
+    @managed_session()
+    async def update(
+        self, entity: EntityGenericType, session: AsyncIOMotorClientSession | None = None
+    ) -> EntityGenericType:
+        """Update the entity in the database.
+
+        Args:
+            entity (EntityGenericType): The entity to update.
+            session (AsyncIOMotorClientSession | None): The session to use. Defaults to None. (managed by decorator)
+
+        Returns:
+            EntityGenericType: The updated entity.
+
+        Raises:
+            ValueError: If the entity cannot be created from the document.
+            OperationError: If the operation fails.
+        """
+        update_time: datetime.datetime = datetime.datetime.now(tz=datetime.UTC)
+        try:
+            entity_dump: dict[str, Any] = entity.model_dump()
+            entity_dump["updated_at"] = update_time
+            document: DocumentGenericType = self._document_type(**entity_dump)
+
+        except ValueError as error:
+            raise ValueError(f"Failed to create document from entity: {error}") from error
+
+        try:
+            document_updated: DocumentGenericType = await document.save(session=session)
+        except PyMongoError as error:
+            raise OperationError(f"Failed to update document: {error}") from error
+
+        try:
+            entity_updated: EntityGenericType = self._entity_type(**document_updated.model_dump())
+        except ValueError as error:
+            raise ValueError(f"Failed to create entity from document: {error}") from error
+
+        return entity_updated
+
     @managed_session()
     async def get_one_by_id(
         self,
@@ -170,3 +215,67 @@ class AbstractRepository(ABC, Generic[DocumentGenericType, EntityGenericType]):
             return
 
         raise OperationError("Failed to delete document.")
+
+    @managed_session()
+    async def find(  # noqa: PLR0913
+        self,
+        *args: Mapping[str, Any] | bool,
+        projection_model: None = None,
+        skip: int | None = None,
+        limit: int | None = None,
+        sort: None | str | list[tuple[str, SortDirection]] = None,
+        session: AsyncIOMotorClientSession | None = None,
+        ignore_cache: bool = False,
+        fetch_links: bool = False,
+        lazy_parse: bool = False,
+        nesting_depth: int | None = None,
+        nesting_depths_per_field: dict[str, int] | None = None,
+        **pymongo_kwargs: Any,
+    ) -> list[EntityGenericType]:
+        """Find documents in the database.
+
+        Args:
+            *args: The arguments to pass to the find method.
+            projection_model: The projection model to use.
+            skip: The number of documents to skip.
+            limit: The number of documents to return.
+            sort: The sort order.
+            session: The session to use.
+            ignore_cache: Whether to ignore the cache.
+            fetch_links: Whether to fetch links.
+            lazy_parse: Whether to lazy parse the documents.
+            nesting_depth: The nesting depth.
+            nesting_depths_per_field: The nesting depths per field.
+            **pymongo_kwargs: Additional keyword arguments to pass to the find method.
+
+        Returns:
+            list[EntityGenericType]: The list of entities.
+
+        Raises:
+            OperationError: If the operation fails.
+            ValueError: If the entity cannot be created from the document.
+        """
+        try:
+            documents: list[DocumentGenericType] = await self._document_type.find(
+                *args,
+                projection_model=projection_model,
+                skip=skip,
+                limit=limit,
+                sort=sort,
+                session=session,
+                ignore_cache=ignore_cache,
+                fetch_links=fetch_links,
+                lazy_parse=lazy_parse,
+                nesting_depth=nesting_depth,
+                nesting_depths_per_field=nesting_depths_per_field,
+                **pymongo_kwargs,
+            ).to_list()
+        except PyMongoError as error:
+            raise OperationError(f"Failed to find documents: {error}") from error
+
+        try:
+            entities: list[EntityGenericType] = [self._entity_type(**document.model_dump()) for document in documents]
+        except ValueError as error:
+            raise ValueError(f"Failed to create entity from document: {error}") from error
+
+        return entities