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

fastapi_factory_utilities/core/services/status/services.py

@@ -0,0 +1,218 @@
+"""Provides status services."""
+
+import datetime
+
+from fastapi import Request
+from reactivex import Subject
+from structlog.stdlib import BoundLogger, get_logger
+
+from .enums import ComponentTypeEnum, HealthStatusEnum, ReadinessStatusEnum
+from .exceptions import ComponentRegistrationError
+from .health_calculator_strategies import (
+    HealthCalculatorStrategy,
+    HealthSimpleCalculatorStrategy,
+)
+from .readiness_calculator_strategies import (
+    ReadinessCalculatorStrategy,
+    ReadinessSimpleCalculatorStrategy,
+)
+from .types import (
+    ComponentInstanceKey,
+    ComponentInstanceType,
+    Status,
+    StatusUpdateEvent,
+)
+
+logger: BoundLogger = get_logger(__package__)
+
+
+class StatusService:
+    """Status service.
+
+    It's responsible for managing the status of the components and determine the health and readiness status of the
+    application.
+    """
+
+    def __init__(
+        self,
+        health_calculator_strategy: type[HealthCalculatorStrategy] = HealthSimpleCalculatorStrategy,
+        readiness_calculator_strategy: type[ReadinessCalculatorStrategy] = ReadinessSimpleCalculatorStrategy,
+    ) -> None:
+        """Initialize the status service."""
+        # Status
+        self._health_status: HealthStatusEnum = HealthStatusEnum.HEALTHY
+        self._health_calculator_strategy: type[HealthCalculatorStrategy] = health_calculator_strategy
+        self._readiness_status: ReadinessStatusEnum = ReadinessStatusEnum.NOT_READY
+        self._readiness_calculator_strategy: type[ReadinessCalculatorStrategy] = readiness_calculator_strategy
+        # Components
+        self._components: dict[str, ComponentInstanceType] = {}
+        self._components_status: dict[ComponentInstanceKey, Status] = {}
+        self._components_subjects: dict[ComponentInstanceKey, Subject[Status]] = {}
+        # Observers
+        self._status_subject: Subject[StatusUpdateEvent] = Subject()
+
+    def _compute_status(self) -> None:
+        """Compute the status."""
+        # Health
+        previous_health: HealthStatusEnum = self._health_status
+        new_health: HealthStatusEnum = self._health_calculator_strategy(
+            components_status=self._components_status
+        ).calculate()
+        # Readiness
+        previous_readiness: ReadinessStatusEnum = self._readiness_status
+        new_readiness: ReadinessStatusEnum = self._readiness_calculator_strategy(
+            components_status=self._components_status
+        ).calculate()
+        # Update the status if needed
+        if previous_health != new_health or previous_readiness != new_readiness:
+            logger.info(
+                "Status updated: health=%s, readiness=%s",
+                new_health,
+                new_readiness,
+            )
+            self._health_status = new_health
+            self._readiness_status = new_readiness
+            self._status_subject.on_next(
+                StatusUpdateEvent(
+                    health_status=new_health,
+                    previous_health_status=previous_health,
+                    readiness_status=new_readiness,
+                    previous_readiness_status=previous_readiness,
+                    triggered_at=datetime.datetime.now(),
+                )
+            )
+
+    def get_status(self) -> Status:
+        """Get the status.
+
+        Returns:
+            Status: The status.
+        """
+        return Status(
+            health=self._health_status,
+            readiness=self._readiness_status,
+        )
+
+    def get_components_status_by_type(self) -> dict[ComponentTypeEnum, dict[ComponentInstanceKey, Status]]:
+        """Get the components status.
+
+        Returns:
+            dict[str, dict[str, Status]]: The components status.
+        """
+        result: dict[ComponentTypeEnum, dict[ComponentInstanceKey, Status]] = {}
+        for component_instance in self._components.values():
+            component_type: ComponentTypeEnum = component_instance.component_type
+            if component_type not in result:
+                result[component_type] = {}
+            result[component_type][component_instance.key] = self._components_status[component_instance.key]
+        return result
+
+    def _on_next_for_component_instance(self, component_instance: ComponentInstanceType, event: Status) -> None:
+        """On next subscribe for all component instances updates.
+
+        Args:
+            component_instance (ComponentInstanceType): The component instance.
+            event (Status): The status event.
+
+        Raises:
+            ComponentRegistrationError: If the component instance is not registered.
+        """
+        # Check if the component instance is registered
+        if component_instance.key not in self._components_status:
+            raise ComponentRegistrationError(component_instance=component_instance)
+
+        # Update the component instance status
+        self._components_status[component_instance.key] = Status(
+            health=event["health"],
+            readiness=event["readiness"],
+        )
+
+        # Compute the status
+        self._compute_status()
+
+    def _register_component_instance_internaly(self, component_instance: ComponentInstanceType) -> None:
+        """Register the component instance internally.
+
+        Args:
+            component_instance (ComponentInstanceType): The component instance.
+
+        Raises:
+            ComponentRegistrationError: If the component instance is already registered.
+        """
+        # Check if the component instance is already registered
+        if component_instance.key in self._components:
+            raise ComponentRegistrationError(component_instance=component_instance)
+        # Register the component instance
+        self._components[component_instance.key] = component_instance
+        # Register the component instance status
+        self._components_status[component_instance.key] = Status(
+            health=HealthStatusEnum.HEALTHY,
+            readiness=ReadinessStatusEnum.NOT_READY,
+        )
+
+    def _create_and_subscribe_to_component_instance_subject(
+        self, component_instance: ComponentInstanceType
+    ) -> Subject[Status]:
+        """Create and subscribe to the component instance subject.
+
+        Args:
+            component_instance (ComponentInstanceType): The component instance.
+
+        Returns:
+            Subject[Status]: The observer.
+
+        Raises:
+            ComponentRegistrationError: If the component instance is already registered.
+        """
+
+        # Setup the subject and subscribe to the subject
+        def on_next(event: Status) -> None:
+            """Currying the on_next method for the component instance and delegate to the service method."""
+            self._on_next_for_component_instance(
+                component_instance=component_instance,
+                event=event,
+            )
+
+        subject: Subject[Status] = Subject()
+        # Check if the component instance is already registered
+        if component_instance.key in self._components_subjects:
+            raise ComponentRegistrationError(component_instance=component_instance)
+        # Register the component instance subject
+        self._components_subjects[component_instance.key] = subject
+        subject.subscribe(on_next=on_next)
+
+        return subject
+
+    def register_component_instance(
+        self,
+        component_instance: ComponentInstanceType,
+    ) -> Subject[Status]:
+        """Register the component instance to the status service.
+
+        It will create a subject for the component instance to share status update and
+        the status service will subscribe automatically to it.
+
+        Args:
+            component_instance (ComponentInstanceType): The component instance.
+
+        Returns:
+            Subject[Status]: The observer.
+
+        Raises:
+            ComponentRegistrationError: If the component instance is already registered.
+        """
+        self._register_component_instance_internaly(component_instance=component_instance)
+        subject: Subject[Status] = self._create_and_subscribe_to_component_instance_subject(
+            component_instance=component_instance
+        )
+        logger.debug(
+            "Component instance registered to the status service key=%s",
+            component_instance.key,
+            component_instance=component_instance,
+        )
+        return subject
+
+
+def depends_status_service(request: Request) -> StatusService:
+    """Get the status service, through fastapi depends."""
+    return request.app.state.status_service

fastapi_factory_utilities/core/services/status/types.py

@@ -0,0 +1,128 @@
+"""Provides the status types for the service."""
+
+import datetime
+from typing import ClassVar, NewType, TypedDict, cast
+
+from pydantic import BaseModel, ConfigDict
+
+from .enums import ComponentTypeEnum, HealthStatusEnum, ReadinessStatusEnum
+
+ComponentInstanceKey = NewType("ComponentInstanceKey", str)
+
+
+class ComponentInstanceType:
+    """Component instance type.
+
+    Attributes:
+        component_type (ComponentTypeEnum): The component type.
+        identifier (str | None): The identifier.
+        key (ComponentInstanceKey): The key based on the component type and identifier.
+    """
+
+    def _generate_key(self) -> ComponentInstanceKey:
+        """Generate the key identifier for the component instance.
+
+        It is based on the component type and identifier.
+
+        Returns:
+            str: The key.
+
+        """
+        key: str = (
+            f"{self._component_type.value}:{self._identifier}" if self._identifier else self._component_type.value
+        )
+        return cast(ComponentInstanceKey, key)
+
+    def __init__(self, component_type: ComponentTypeEnum, identifier: str | None = None) -> None:
+        """Initialize the component instance type.
+
+        Args:
+            component_type (ComponentTypeEnum): The component type.
+            identifier (str, optional): The identifier. Defaults to None.
+
+        """
+        self._component_type: ComponentTypeEnum = component_type
+        self._identifier: str | None = identifier
+        self._key: ComponentInstanceKey = self._generate_key()
+
+    @property
+    def component_type(self) -> ComponentTypeEnum:
+        """Get the component type.
+
+        Returns:
+            ComponentTypeEnum: The component type.
+
+        """
+        return self._component_type
+
+    @property
+    def identifier(self) -> str | None:
+        """Get the identifier.
+
+        Returns:
+            str | None: The identifier.
+
+        """
+        return self._identifier
+
+    @property
+    def key(self) -> ComponentInstanceKey:
+        """Get the key.
+
+        Returns:
+            str: The key.
+
+        """
+        return self._key
+
+
+class Status(TypedDict):
+    """Status type.
+
+    Attributes:
+        health (HealthStatusEnum): The health status.
+        readiness (ReadinessStatusEnum): The readiness status.
+    """
+
+    health: HealthStatusEnum
+    readiness: ReadinessStatusEnum
+
+
+class StatusUpdateEvent(BaseModel):
+    """Status update event."""
+
+    # Pydantic config
+    model_config: ClassVar[ConfigDict] = {"frozen": True}
+
+    # Health status
+    health_status: HealthStatusEnum
+    previous_health_status: HealthStatusEnum
+
+    # Readiness status
+    readiness_status: ReadinessStatusEnum
+    previous_readiness_status: ReadinessStatusEnum
+
+    # Timestamp
+    triggered_at: datetime.datetime
+
+
+class ComponentInstanceStatusUpdateEvent(BaseModel):
+    """Component instance status update event."""
+
+    # Pydantic config
+    model_config: ClassVar[ConfigDict] = {
+        "frozen": True,
+        "arbitrary_types_allowed": True,  # Needed for the ComponentInstanceType
+    }
+
+    # Component instance
+    component_instance: ComponentInstanceType
+
+    # Health status
+    health_status: HealthStatusEnum
+
+    # Readiness status
+    readiness_status: ReadinessStatusEnum
+
+    # Timestamp
+    triggered_at: datetime.datetime

fastapi_factory_utilities/core/utils/configs.py

@@ -41,7 +41,7 @@ def build_config_from_file_in_package(
     package_name: str,
     filename: str,
     config_class: type[GenericConfigBaseModelType],
-    yaml_base_key: str,
+    yaml_base_key: str | None = None,
 ) -> GenericConfigBaseModelType:
     """Build a configuration object from a file in a package.
 

fastapi_factory_utilities/core/utils/status.py

@@ -0,0 +1,71 @@
+"""Provides the monitored abstract class for monitoring the status of the application.
+
+```python
+# Example of using the MonitoredAbstract
+
+class MyMonitored(MonitoredAbstract):
+    def __init__(self, status_service: StatusService) -> None:
+        super().__init__(
+            component_instance=ComponentInstanceType(
+                component_type=ComponentTypeEnum.APPLICATION,
+                component_name="MyMonitored",
+            ),
+            status_service=status_service,
+        )
+
+    def my_method(self) -> None:
+        self.update_monitoring_status(
+            Status(
+                status_type=StatusTypeEnum.INFO,
+                status_message="My method is running.",
+            )
+        )
+```
+
+"""
+
+from abc import ABC
+
+from reactivex import Subject
+
+from fastapi_factory_utilities.core.services.status import (
+    ComponentInstanceType,
+    ComponentTypeEnum,
+    Status,
+    StatusService,
+)
+
+
+class MonitoredAbstract(ABC):
+    """Monitored abstract class."""
+
+    def __init__(self, component_instance: ComponentInstanceType, status_service: StatusService) -> None:
+        """Initialize the monitored.
+
+        Args:
+            component_instance (ComponentInstanceType): The component instance.
+            status_service (StatusService): The status service.
+
+        """
+        self._monit_component_instance: ComponentInstanceType = component_instance
+        self._monit_status_service_subject: Subject[Status] = status_service.register_component_instance(
+            component_instance=component_instance
+        )
+
+    def update_monitoring_status(self, status: Status) -> None:
+        """Update the monitoring status.
+
+        Args:
+            status (Status): The status.
+
+        """
+        self._monit_status_service_subject.on_next(status)
+
+
+__all__: list[str] = [
+    "MonitoredAbstract",
+    "ComponentInstanceType",
+    "ComponentTypeEnum",
+    "Status",
+    "StatusService",
+]

fastapi_factory_utilities/core/utils/uvicorn.py

@@ -3,24 +3,23 @@
 import uvicorn
 import uvicorn.server
 
-from fastapi_factory_utilities.core.protocols import BaseApplicationProtocol
+from fastapi_factory_utilities.core.protocols import ApplicationAbstractProtocol
 from fastapi_factory_utilities.core.utils.log import clean_uvicorn_logger
 
 
 class UvicornUtils:
     """Provides utilities for Uvicorn."""
 
-    def __init__(self, app: BaseApplicationProtocol) -> None:
+    def __init__(self, app: ApplicationAbstractProtocol) -> None:
         """Instantiate the factory.
 
         Args:
             app (BaseApplication): The application.
-            config (AppConfigAbstract): The application configuration.
 
         Returns:
             None
         """
-        self._app: BaseApplicationProtocol = app
+        self._app: ApplicationAbstractProtocol = app
 
     def build_uvicorn_config(self) -> uvicorn.Config:
         """Build the Uvicorn configuration.
@@ -30,10 +29,10 @@ class UvicornUtils:
         """
         config = uvicorn.Config(
             app=self._app.get_asgi_app(),
-            host=self._app.get_config().host,
-            port=self._app.get_config().port,
-            reload=self._app.get_config().reload,
-            workers=self._app.get_config().workers,
+            host=self._app.get_config().server.host,
+            port=self._app.get_config().server.port,
+            reload=self._app.get_config().development.reload,
+            workers=self._app.get_config().server.workers,
         )
         clean_uvicorn_logger()
         return config

fastapi_factory_utilities/example/__init__.py

@@ -1,11 +1,11 @@
 """Python Factory Example."""
 
-from fastapi_factory_utilities.example.app import App
+from fastapi_factory_utilities.example.app import AppBuilder
 
 
 def main() -> None:
     """Main function."""
-    App.main()
+    AppBuilder().build_and_serve()
 
 
-__all__: list[str] = ["App", "main"]
+__all__: list[str] = ["main"]

fastapi_factory_utilities/example/api/books/routes.py

@@ -3,11 +3,13 @@
 from typing import cast
 from uuid import UUID
 
-from fastapi import APIRouter, Depends, Request
+from fastapi import APIRouter, Depends
 
 from fastapi_factory_utilities.example.entities.books import BookEntity
-from fastapi_factory_utilities.example.models.books.repository import BookRepository
-from fastapi_factory_utilities.example.services.books import BookService
+from fastapi_factory_utilities.example.services.books import (
+    BookService,
+    depends_book_service,
+)
 
 from .responses import BookListReponse, BookResponseModel
 
@@ -15,14 +17,9 @@ api_v1_books_router: APIRouter = APIRouter(prefix="/books")
 api_v2_books_router: APIRouter = APIRouter(prefix="/books")
 
 
-def get_book_service(request: Request) -> BookService:
-    """Provide Book Service."""
-    return BookService(book_repository=BookRepository(request.app.state.odm_client))
-
-
 @api_v1_books_router.get(path="", response_model=BookListReponse)
 def get_books(
-    books_service: BookService = Depends(get_book_service),
+    books_service: BookService = Depends(depends_book_service),
 ) -> BookListReponse:
     """Get all books.
 
@@ -46,7 +43,7 @@ def get_books(
 @api_v1_books_router.get(path="/{book_id}", response_model=BookResponseModel)
 def get_book(
     book_id: UUID,
-    books_service: BookService = Depends(get_book_service),
+    books_service: BookService = Depends(depends_book_service),
 ) -> BookResponseModel:
     """Get a book.
 

fastapi_factory_utilities/example/app.py

@@ -0,0 +1,50 @@
+"""Provides the concrete application class."""
+
+from typing import ClassVar
+
+from beanie import Document
+
+from fastapi_factory_utilities.core.app.application import ApplicationAbstract
+from fastapi_factory_utilities.core.app.builder import ApplicationGenericBuilder
+from fastapi_factory_utilities.core.app.config import RootConfig
+from fastapi_factory_utilities.core.plugins import PluginsEnum
+from fastapi_factory_utilities.example.models.books.document import BookDocument
+
+
+class AppRootConfig(RootConfig):
+    """Application configuration class."""
+
+    pass
+
+
+class App(ApplicationAbstract):
+    """Concrete application class."""
+
+    CONFIG_CLASS: ClassVar[type[RootConfig]] = AppRootConfig
+
+    PACKAGE_NAME: ClassVar[str] = "fastapi_factory_utilities.example"
+
+    ODM_DOCUMENT_MODELS: ClassVar[list[type[Document]]] = [BookDocument]
+
+    DEFAULT_PLUGINS_ACTIVATED: ClassVar[list[PluginsEnum]] = [PluginsEnum.OPENTELEMETRY_PLUGIN, PluginsEnum.ODM_PLUGIN]
+
+    def configure(self) -> None:
+        """Configure the application."""
+        # Prevent circular import
+        from .api import api_router  # pylint: disable=import-outside-toplevel
+
+        self.get_asgi_app().include_router(router=api_router)
+
+    async def on_startup(self) -> None:
+        """Actions to perform on application startup."""
+        pass
+
+    async def on_shutdown(self) -> None:
+        """Actions to perform on application shutdown."""
+        pass
+
+
+class AppBuilder(ApplicationGenericBuilder[App]):
+    """Application builder for the App application."""
+
+    pass

fastapi_factory_utilities/example/application.yaml

@@ -1,19 +1,15 @@
 ---
 application:
-  service_name: fastapi_factory_utilities_example
-  service_namespace: fastapi_factory_utilities_example
-  title: Python Factory Example
-  description: An example application for Python Factory
+  service_name: Example Application
+  service_namespace: fastapi_factory_utilities
+  description: An example application using fastapi-factory-utilities
   version: 0.1.0
   environment: ${ENVIRONMENT:development}
+
+development:
   debug: ${APPLICATION_DEBUG:false}
   reload: ${APPLICATION_RELOAD:false}
 
-plugins:
-  activate:
-    - opentelemetry_plugin
-    - odm_plugin
-
 opentelemetry:
   activate: "${OTEL_ACTIVE:false}"
 

fastapi_factory_utilities/example/services/books/__init__.py

@@ -1,5 +1,5 @@
 """Provide Books Service."""
 
-from .services import BookService
+from .services import BookService, depends_book_service
 
-__all__: list[str] = ["BookService"]
+__all__: list[str] = ["BookService", "depends_book_service"]

fastapi_factory_utilities/example/services/books/services.py

@@ -3,8 +3,12 @@
 from typing import ClassVar
 from uuid import UUID
 
+from fastapi import Request
 from opentelemetry import metrics
 
+from fastapi_factory_utilities.core.plugins.odm_plugin.depends import (
+    depends_odm_database,
+)
 from fastapi_factory_utilities.core.plugins.opentelemetry_plugin.helpers import (
     trace_span,
 )
@@ -165,3 +169,8 @@ class BookService:
         self.book_store[book.id] = book
 
         self.METER_COUNTER_BOOK_UPDATE.add(amount=1)
+
+
+def depends_book_service(request: Request) -> BookService:
+    """Provide Book Service."""
+    return BookService(book_repository=BookRepository(database=depends_odm_database(request=request)))

{fastapi_factory_utilities-0.1.0.dist-info → fastapi_factory_utilities-0.2.0.dist-info}/METADATA

@@ -1,8 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: fastapi_factory_utilities
-Version: 0.1.0
+Version: 0.2.0
 Summary: Consolidate libraries and utilities to create microservices in Python with FastAPI, Beanie, Httpx, AioPika and OpenTelemetry.
-Home-page: https://github.com/miragecentury/fastapi_factory_utilities
 License: MIT
 Keywords: python,fastapi,beanie,httpx,opentelemetry,microservices
 Author: miragecentury
@@ -27,11 +26,14 @@ Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.49b1,<0.50)
 Requires-Dist: opentelemetry-instrumentation-pymongo (>=0.49b2,<0.50)
 Requires-Dist: opentelemetry-propagator-b3 (>=1.26.0,<2.0.0)
 Requires-Dist: opentelemetry-sdk (>=1.26.0,<2.0.0)
+Requires-Dist: pyaml (>=25.1.0,<26.0.0)
 Requires-Dist: pydantic (>=2.8.2,<3.0.0)
 Requires-Dist: pymongo (>=4.9.2,<4.10.0)
-Requires-Dist: structlog (>=24.1.0,<25.0.0)
+Requires-Dist: reactivex (>=4.0.4,<5.0.0)
+Requires-Dist: structlog (>=24.1,<26.0)
 Requires-Dist: typer (>=0.15.1,<0.16.0)
 Requires-Dist: uvicorn (>=0.32.0,<0.33.0)
+Project-URL: Homepage, https://github.com/miragecentury/fastapi_factory_utilities
 Project-URL: Repository, https://github.com/miragecentury/fastapi_factory_utilities
 Description-Content-Type: text/markdown