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

fastapi_factory_utilities/__main__.py

@@ -0,0 +1,6 @@
+"""Re-Use the main function from the example module."""
+
+from fastapi_factory_utilities.example import main
+
+if __name__ == "__main__":
+    main()

fastapi_factory_utilities/core/__init__.py

@@ -0,0 +1 @@
+"""Python Factory Core Module."""

fastapi_factory_utilities/core/api/__init__.py

@@ -0,0 +1,25 @@
+"""Define the API for the Python Factory."""
+
+from fastapi import APIRouter
+
+from .tags import TagEnum
+from .v1.sys import api_v1_sys
+
+api: APIRouter = APIRouter(prefix="/api")
+
+### API v1 ###
+# Prefix the API with /api/v1
+api_v1: APIRouter = APIRouter(prefix="/v1")
+api_v1.include_router(router=api_v1_sys)
+
+
+### API v2 ###
+# Prefix the API with /api/v2
+api_v2: APIRouter = APIRouter(prefix="/v2")
+
+
+### Include the API routers ###
+api.include_router(router=api_v1)
+api.include_router(router=api_v2)
+
+__all__: list[str] = ["api", "TagEnum"]

fastapi_factory_utilities/core/api/tags.py

@@ -0,0 +1,9 @@
+"""Provides the Tag as Enum."""
+
+from enum import StrEnum, auto
+
+
+class TagEnum(StrEnum):
+    """Define Tag for OpenAPI Description."""
+
+    SYS = auto()

fastapi_factory_utilities/core/api/v1/sys/__init__.py

@@ -0,0 +1,12 @@
+"""Package for system related API endpoints."""
+
+from fastapi import APIRouter
+
+from .health import api_v1_sys_health
+from .readiness import api_v1_sys_readiness
+
+api_v1_sys = APIRouter(prefix="/sys")
+api_v1_sys.include_router(router=api_v1_sys_health)
+api_v1_sys.include_router(router=api_v1_sys_readiness)
+
+__all__: list[str] = ["api_v1_sys"]

fastapi_factory_utilities/core/api/v1/sys/health.py

@@ -0,0 +1,53 @@
+"""API v1 sys health module.
+
+Provide the Get health endpoint
+"""
+
+from enum import StrEnum
+from http import HTTPStatus
+
+from fastapi import APIRouter, Response
+from pydantic import BaseModel
+
+api_v1_sys_health = APIRouter(prefix="/health")
+
+
+class HealthStatusEnum(StrEnum):
+    """Health status enum."""
+
+    HEALTHY = "healthy"
+    UNHEALTHY = "unhealthy"
+
+
+class HealthResponseModel(BaseModel):
+    """Health response schema."""
+
+    status: HealthStatusEnum
+
+
+@api_v1_sys_health.get(
+    path="",
+    tags=["sys"],
+    response_model=HealthResponseModel,
+    responses={
+        HTTPStatus.OK.value: {
+            "model": HealthResponseModel,
+            "description": "Health status.",
+        },
+        HTTPStatus.INTERNAL_SERVER_ERROR.value: {
+            "model": HealthResponseModel,
+            "description": "Internal server error.",
+        },
+    },
+)
+def get_api_v1_sys_health(response: Response) -> HealthResponseModel:
+    """Get the health of the system.
+
+    Args:
+        response (Response): The response object.
+
+    Returns:
+        HealthResponse: The health status.
+    """
+    response.status_code = HTTPStatus.OK
+    return HealthResponseModel(status=HealthStatusEnum.HEALTHY)

fastapi_factory_utilities/core/api/v1/sys/readiness.py

@@ -0,0 +1,53 @@
+"""API v1 sys readiness module.
+
+Provide the Get readiness endpoint
+"""
+
+from enum import StrEnum
+from http import HTTPStatus
+
+from fastapi import APIRouter, Response
+from pydantic import BaseModel
+
+api_v1_sys_readiness = APIRouter(prefix="/readiness")
+
+
+class ReadinessStatusEnum(StrEnum):
+    """Readiness status enum."""
+
+    READY = "ready"
+    NOT_READY = "not_ready"
+
+
+class ReadinessResponseModel(BaseModel):
+    """Readiness response schema."""
+
+    status: ReadinessStatusEnum
+
+
+@api_v1_sys_readiness.get(
+    path="",
+    tags=["sys"],
+    response_model=ReadinessResponseModel,
+    responses={
+        HTTPStatus.OK.value: {
+            "model": ReadinessResponseModel,
+            "description": "Readiness status.",
+        },
+        HTTPStatus.INTERNAL_SERVER_ERROR.value: {
+            "model": ReadinessResponseModel,
+            "description": "Internal server error.",
+        },
+    },
+)
+def get_api_v1_sys_readiness(response: Response) -> ReadinessResponseModel:
+    """Get the readiness of the system.
+
+    Args:
+        response (Response): The response object.
+
+    Returns:
+        ReadinessResponse: The readiness status.
+    """
+    response.status_code = HTTPStatus.OK
+    return ReadinessResponseModel(status=ReadinessStatusEnum.READY)

fastapi_factory_utilities/core/app/__init__.py

@@ -0,0 +1,19 @@
+"""Provides the core application module for the Python Factory."""
+
+from .base import (
+    AppConfigAbstract,
+    ApplicationConfigFactoryException,
+    ApplicationFactoryException,
+    BaseApplication,
+    BaseApplicationException,
+)
+from .enums import EnvironmentEnum
+
+__all__: list[str] = [
+    "BaseApplication",
+    "AppConfigAbstract",
+    "EnvironmentEnum",
+    "ApplicationConfigFactoryException",
+    "ApplicationFactoryException",
+    "BaseApplicationException",
+]

fastapi_factory_utilities/core/app/base/__init__.py

@@ -0,0 +1,17 @@
+"""Package for the base application, abstract config classes and related exceptions."""
+
+from .application import BaseApplication
+from .config_abstract import AppConfigAbstract
+from .exceptions import (
+    ApplicationConfigFactoryException,
+    ApplicationFactoryException,
+    BaseApplicationException,
+)
+
+__all__: list[str] = [
+    "BaseApplication",
+    "AppConfigAbstract",
+    "ApplicationConfigFactoryException",
+    "ApplicationFactoryException",
+    "BaseApplicationException",
+]

fastapi_factory_utilities/core/app/base/application.py

@@ -0,0 +1,123 @@
+"""Provides the abstract class for the application."""
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import ClassVar, Self, cast
+
+import starlette.types
+from beanie import Document
+from fastapi import FastAPI
+
+from fastapi_factory_utilities.core.api import api
+from fastapi_factory_utilities.core.utils.log import LogModeEnum, setup_log
+
+from .config_abstract import AppConfigAbstract, AppConfigBuilder
+from .fastapi_application_abstract import FastAPIAbstract
+from .plugins_manager_abstract import (
+    ApplicationPluginManagerAbstract,
+    PluginsActivationList,
+)
+
+
+class BaseApplication(FastAPIAbstract, ApplicationPluginManagerAbstract):
+    """Application abstract class."""
+
+    PACKAGE_NAME: str = ""
+
+    CONFIG_CLASS: ClassVar[type[AppConfigAbstract]] = AppConfigAbstract
+
+    ODM_DOCUMENT_MODELS: ClassVar[list[type[Document]]] = []
+
+    def __init__(self, config: AppConfigAbstract, plugin_activation_list: PluginsActivationList | None = None) -> None:
+        """Instantiate the application.
+
+        Args:
+            config (AppConfigAbstract): The application configuration.
+            plugin_activation_list (PluginsActivationList | None, optional): The plugins activation list.
+
+        Returns:
+            None
+
+        Raises:
+            ValueError: If the package name is not set.
+        """
+        if self.PACKAGE_NAME == "":
+            raise ValueError("The package name must be set in the concrete application class.")
+
+        self._config: AppConfigAbstract = config
+        FastAPIAbstract.__init__(
+            self=cast(FastAPIAbstract, self),
+            config=self._config,
+            api_router=api,
+            lifespan=cast(starlette.types.StatelessLifespan[starlette.types.ASGIApp], self.fastapi_lifespan),
+        )
+        ApplicationPluginManagerAbstract.__init__(
+            self=cast(ApplicationPluginManagerAbstract, self), plugin_activation_list=plugin_activation_list
+        )
+        self._on_load()
+
+    @classmethod
+    def main(cls) -> None:
+        """Main function.
+
+        This must be the same for all applications.
+        """
+        from fastapi_factory_utilities.core.utils.uvicorn import (  # pylint: disable=import-outside-toplevel
+            UvicornUtils,
+        )
+
+        setup_log(mode=LogModeEnum.CONSOLE)
+        application: BaseApplication = cls.build()
+        uvicorn_utils = UvicornUtils(app=application)
+
+        try:
+            uvicorn_utils.serve()
+        except KeyboardInterrupt:
+            pass
+
+    @classmethod
+    def build_config(cls) -> AppConfigAbstract:
+        """Build the application configuration.
+
+        Returns:
+            AppConfigAbstract: The application configuration.
+        """
+        config_builder: AppConfigBuilder = AppConfigBuilder(
+            package_name=cls.PACKAGE_NAME, config_class=cls.CONFIG_CLASS
+        )
+        return config_builder.build()
+
+    @classmethod
+    def build(
+        cls, config: AppConfigAbstract | None = None, plugin_activation_list: PluginsActivationList | None = None
+    ) -> Self:
+        """Build the application.
+
+        Args:
+            config (AppConfigAbstract | None, optional): The application configuration. Defaults to None.
+            plugin_activation_list (PluginsActivationList | None, optional): The plugins activation list.
+            Defaults to None.
+        """
+        if config is None:
+            config = cls.build_config()
+
+        return cls(config=config, plugin_activation_list=plugin_activation_list)
+
+    @asynccontextmanager
+    async def fastapi_lifespan(self, fastapi_application: FastAPI) -> AsyncGenerator[None, None]:
+        """Provide the lifespan context manager for FastAPI.
+
+        Args:
+            fastapi_application (FastAPI): The FastAPI application.
+
+        Returns:
+            AsyncGenerator[None]: The lifespan context manager.
+        """
+        del fastapi_application
+        await self.plugins_on_startup()
+        yield
+        await self.plugins_on_shutdown()
+
+    def get_config(self) -> AppConfigAbstract:
+        """Get the application configuration."""
+        return self._config

fastapi_factory_utilities/core/app/base/config_abstract.py

@@ -0,0 +1,78 @@
+"""Provide the configuration for the app server."""
+
+from pydantic import Field
+
+from fastapi_factory_utilities.core.app.base.exceptions import (
+    ApplicationConfigFactoryException,
+)
+from fastapi_factory_utilities.core.app.base.plugins_manager_abstract import (
+    PluginsActivationList,
+)
+from fastapi_factory_utilities.core.utils.configs import (
+    UnableToReadConfigFileError,
+    ValueErrorConfigError,
+    build_config_from_file_in_package,
+)
+from fastapi_factory_utilities.core.utils.log import LoggingConfig
+
+from ..enums import EnvironmentEnum
+from .fastapi_application_abstract import FastAPIConfigAbstract
+
+
+class AppConfigAbstract(FastAPIConfigAbstract, PluginsActivationList):
+    """Application configuration abstract class."""
+
+    environment: EnvironmentEnum
+    service_name: str
+    service_namespace: str
+
+    logging: list[LoggingConfig] = Field(default_factory=list, description="Logging configuration.")
+
+
+class AppConfigBuilder:
+    """Application configuration builder."""
+
+    DEFAULT_FILENAME: str = "application.yaml"
+    DEFAULT_YAML_BASE_KEY: str = "application"
+
+    def __init__(
+        self,
+        package_name: str,
+        config_class: type[AppConfigAbstract],
+        filename: str = DEFAULT_FILENAME,
+        yaml_base_key: str = DEFAULT_YAML_BASE_KEY,
+    ) -> None:
+        """Instantiate the builder.
+
+        Args:
+            package_name (str): The package name.
+            config_class (Type[AppConfigAbstract]): The configuration class.
+            filename (str, optional): The filename. Defaults to DEFAULT_FILENAME.
+            yaml_base_key (str, optional): The YAML base key. Defaults to DEFAULT_YAML_BASE_KEY.
+        """
+        self.package_name: str = package_name
+        self.config_class: type[AppConfigAbstract] = config_class
+        self.filename: str = filename
+        self.yaml_base_key: str = yaml_base_key
+
+    def build(self) -> AppConfigAbstract:
+        """Build the configuration.
+
+        Returns:
+            AppConfigAbstract: The configuration.
+        """
+        try:
+            config: AppConfigAbstract = build_config_from_file_in_package(
+                package_name=self.package_name,
+                config_class=self.config_class,
+                filename=self.filename,
+                yaml_base_key=self.yaml_base_key,
+            )
+        except UnableToReadConfigFileError as exception:
+            raise ApplicationConfigFactoryException("Unable to read the application configuration file.") from exception
+        except ValueErrorConfigError as exception:
+            raise ApplicationConfigFactoryException(
+                "Unable to create the application configuration model."
+            ) from exception
+
+        return config

fastapi_factory_utilities/core/app/base/exceptions.py

@@ -0,0 +1,25 @@
+"""Provides the exceptions for the application factory."""
+
+
+class BaseApplicationException(BaseException):
+    """Base application exception."""
+
+    pass
+
+
+class ApplicationFactoryException(BaseApplicationException):
+    """Application factory exception."""
+
+    pass
+
+
+class ApplicationConfigFactoryException(BaseApplicationException):
+    """Application configuration factory exception."""
+
+    pass
+
+
+class ApplicationPluginManagerException(BaseApplicationException):
+    """Application plugin manager exception."""
+
+    pass

fastapi_factory_utilities/core/app/base/fastapi_application_abstract.py

@@ -0,0 +1,88 @@
+"""Provides an abstract class for FastAPI application integration."""
+
+from abc import ABC
+from typing import Any
+
+import starlette.types
+from fastapi import APIRouter, FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FastAPIConfigAbstract(ABC, BaseModel):
+    """Partial configuration for FastAPI."""
+
+    model_config = ConfigDict(strict=False)
+
+    # Application metadata
+    title: str
+    description: str
+    version: str
+
+    # Host configuration
+    host: str = Field(default="0.0.0.0")
+    port: int = Field(default=8000)
+
+    # Root configuration
+    root_path: str = Field(default="")
+
+    # Debug mode
+    debug: bool = Field(default=False, strict=False)
+
+    # Uvicorn configuration
+    reload: bool = Field(default=False, strict=False)
+    workers: int = Field(default=1, strict=False)
+
+
+class FastAPIAbstract(ABC):
+    """Application integration with FastAPI.
+
+    TODO: Replace by a Factory pattern.
+    """
+
+    def __init__(
+        self,
+        config: FastAPIConfigAbstract,
+        api_router: APIRouter | None = None,
+        lifespan: starlette.types.StatelessLifespan[starlette.types.ASGIApp] | None = None,
+    ) -> None:
+        """Instanciate the FastAPI application.
+
+        Args:
+            config (FastAPIConfigAbstract): The FastAPI configuration.
+            api_router (APIRouter, optional): The API router to include.
+                Defaults to None.
+            lifespan (AsyncGenerator[None, None], optional): The lifespan
+
+        Returns:
+            None
+
+        """
+        self._fastapi_app: FastAPI = FastAPI(
+            title=config.title,
+            description=config.description,
+            version=config.version,
+            root_path=config.root_path,
+            debug=config.debug,
+            lifespan=lifespan,
+        )
+
+        # TODO: Add CORS middleware Configuration
+        self._fastapi_app.add_middleware(
+            middleware_class=CORSMiddleware,
+            allow_origins=["*"],
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+        if api_router is not None:
+            self._fastapi_app.include_router(router=api_router)
+
+    def get_asgi_app(self) -> FastAPI:
+        """Get the ASGI application."""
+        return self._fastapi_app
+
+    async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
+        """Forward the call to the FastAPI app."""
+        return await self._fastapi_app.__call__(scope=scope, receive=receive, send=send)

fastapi_factory_utilities/core/app/base/plugins_manager_abstract.py

@@ -0,0 +1,136 @@
+"""Plugins manager abstract module."""
+
+from abc import ABC
+from importlib import import_module
+from types import ModuleType
+from typing import cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from fastapi_factory_utilities.core.plugins import PluginsEnum
+from fastapi_factory_utilities.core.protocols import (
+    BaseApplicationProtocol,
+    PluginProtocol,
+)
+from fastapi_factory_utilities.core.utils.configs import (
+    UnableToReadConfigFileError,
+    ValueErrorConfigError,
+    build_config_from_file_in_package,
+)
+
+from .exceptions import ApplicationPluginManagerException
+
+
+class PluginsActivationList(BaseModel):
+    """Model for the plugins activation list."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    activate: list[PluginsEnum] = Field(default=list())
+
+
+class ApplicationPluginManagerAbstract(ABC):
+    """Abstract class for the application plugin manager.
+
+    Responsibilities:
+    - Retrieve the plugins for the application.
+    - Check the pre-conditions for the plugins.
+    - Perform actions on startup for the plugins.
+    - Perform actions on shutdown for the plugins.
+    """
+
+    PACKAGE_NAME: str = ""
+
+    PLUGIN_PACKAGE_NAME: str = "fastapi_factory_utilities.core.plugins"
+
+    def __init__(self, plugin_activation_list: PluginsActivationList | None = None) -> None:
+        """Instanciate the application plugin manager."""
+        if self.PACKAGE_NAME == "":
+            raise ValueError("The package name must be set in the concrete plugin manager class.")
+
+        self._plugins: list[PluginProtocol] = []
+        self._plugins_activation_list: PluginsActivationList
+        if plugin_activation_list is not None:
+            self._plugins_activation_list = plugin_activation_list
+        else:
+            self._plugins_activation_list = self._build_plugins_activation_list()
+
+        self._check_pre_conditions()
+
+    def _check_pre_conditions(self) -> None:
+        """Check the pre-conditions for the plugins.
+
+        Raises:
+            ApplicationPluginManagerException: If a plugin is not
+            activated.
+
+        """
+        for plugin in self._plugins_activation_list.activate:
+            try:
+                plugin_module: ModuleType = import_module(name=f"{self.PLUGIN_PACKAGE_NAME}.{plugin.value}")
+            except ImportError as exception:
+                raise ApplicationPluginManagerException(f"Unable to import the plugin {plugin.value}") from exception
+
+            if not isinstance(plugin_module, PluginProtocol):
+                raise ApplicationPluginManagerException(
+                    f"The plugin {plugin.value} does not implement the PluginProtocol"
+                )
+
+            if not plugin_module.pre_conditions_check(application=cast(BaseApplicationProtocol, self)):
+                raise ApplicationPluginManagerException(f"The plugin {plugin.value} does not meet the pre-conditions")
+
+            self._plugins.append(plugin_module)
+
+    def _on_load(self) -> None:
+        """Actions to perform on load for the plugins."""
+        for plugin in self._plugins:
+            plugin.on_load(application=cast(BaseApplicationProtocol, self))
+
+    def _build_plugins_activation_list(self) -> PluginsActivationList:
+        """Build the plugins activation list.
+
+        Returns:
+            PluginsActivationList: The plugins activation list.
+
+        Raises:
+            ApplicationPluginManagerException: If there is an error
+            reading the configuration file.
+            ApplicationPluginManagerException: If there is an error
+            creating the configuration model.
+
+        """
+        try:
+            config: PluginsActivationList = build_config_from_file_in_package(
+                package_name=self.PACKAGE_NAME,
+                filename="application.yaml",
+                config_class=PluginsActivationList,
+                yaml_base_key="plugins",
+            )
+        except UnableToReadConfigFileError as exception:
+            raise ApplicationPluginManagerException("Unable to read the application configuration file") from exception
+        except ValueErrorConfigError as exception:
+            raise ApplicationPluginManagerException(
+                "Unable to create the application configuration model"
+            ) from exception
+
+        return config
+
+    async def plugins_on_startup(self) -> None:
+        """Actions to perform on startup for the plugins."""
+        for plugin in self._plugins:
+            try:
+                await plugin.on_startup(application=cast(BaseApplicationProtocol, self))
+            except Exception as exception:
+                raise ApplicationPluginManagerException(
+                    f"Error during the startup of the plugin {plugin.__class__.__name__}"
+                ) from exception
+
+    async def plugins_on_shutdown(self) -> None:
+        """Actions to perform on shutdown for the plugins."""
+        for plugin in self._plugins:
+            try:
+                await plugin.on_shutdown(application=cast(BaseApplicationProtocol, self))
+            except Exception as exception:
+                raise ApplicationPluginManagerException(
+                    f"Error during the shutdown of the plugin {plugin.__class__.__name__}"
+                ) from exception

fastapi_factory_utilities/core/app/enums.py

@@ -0,0 +1,11 @@
+"""Provides enums for the app module."""
+
+from enum import StrEnum
+
+
+class EnvironmentEnum(StrEnum):
+    """Represents the environment."""
+
+    DEVELOPMENT = "development"
+    STAGING = "staging"
+    PRODUCTION = "production"

fastapi_factory_utilities/core/plugins/__init__.py

@@ -0,0 +1,15 @@
+"""Package for plugins."""
+
+from enum import StrEnum, auto
+
+
+class PluginsEnum(StrEnum):
+    """Enumeration for the plugins."""
+
+    OPENTELEMETRY_PLUGIN = auto()
+    ODM_PLUGIN = auto()
+
+
+__all__: list[str] = [
+    "PluginsEnum",
+]