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

fastapi_factory_utilities/core/utils/configs.py

@@ -0,0 +1,80 @@
+"""Provides utilities to handle configurations."""
+
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from fastapi_factory_utilities.core.utils.importlib import get_path_file_in_package
+from fastapi_factory_utilities.core.utils.yaml_reader import (
+    UnableToReadYamlFileError,
+    YamlFileReader,
+)
+
+GenericConfigBaseModelType = TypeVar("GenericConfigBaseModelType", bound=BaseModel)  # pylint: disable=invalid-name
+
+
+class ConfigBaseException(BaseException):
+    """Base exception for all the configuration exceptions."""
+
+    pass
+
+
+class UnableToReadConfigFileError(ConfigBaseException):
+    """Exception raised when the configuration file cannot be read.
+
+    Mainly used when the file is not found or the file is not a YAML file.
+    """
+
+    pass
+
+
+class ValueErrorConfigError(ConfigBaseException):
+    """Exception raised when the configuration object cannot be created.
+
+    Mainly used when validation fails when creating the configuration object.
+    """
+
+    pass
+
+
+def build_config_from_file_in_package(
+    package_name: str,
+    filename: str,
+    config_class: type[GenericConfigBaseModelType],
+    yaml_base_key: str,
+) -> GenericConfigBaseModelType:
+    """Build a configuration object from a file in a package.
+
+    Args:
+        package_name (str): The package name.
+        filename (str): The filename.
+        config_class (type[GenericConfigBaseModelType]): The configuration class.
+        yaml_base_key (str): The base key in the YAML file.
+
+    Returns:
+        GenericConfigBaseModelType: The configuration object.
+
+    Raises:
+        UnableToReadConfigFileError: If the configuration file cannot be read.
+        ValueErrorConfigError: If the configuration file is invalid.
+    """
+    # Read the application configuration file
+    try:
+        yaml_file_content: dict[str, Any] = YamlFileReader(
+            file_path=get_path_file_in_package(
+                filename=filename,
+                package=package_name,
+            ),
+            yaml_base_key=yaml_base_key,
+            use_environment_injection=True,
+        ).read()
+    except (FileNotFoundError, ImportError, UnableToReadYamlFileError) as exception:
+        raise UnableToReadConfigFileError("Unable to read the application configuration file.") from exception
+
+    # Create the application configuration model
+    try:
+        config: GenericConfigBaseModelType = config_class(**yaml_file_content)
+    except ValueError as exception:
+        raise ValueErrorConfigError("Unable to create the configuration model.") from exception
+
+    return config

fastapi_factory_utilities/core/utils/importlib.py

@@ -0,0 +1,28 @@
+"""Provide importlib functions."""
+
+from importlib.resources import files
+from pathlib import Path
+
+
+def get_path_file_in_package(filename: str, package: str) -> Path:
+    """Return Absolute Path of file in package.
+
+    Args:
+        filename (str): Filename to search
+        package (str): Package name
+
+    Returns:
+        Traversable: File
+
+    Raises:
+        FileNotFoundError: If file not found
+        ImportError: If package not found
+
+    """
+    try:
+        path: Path = Path(str(files(package).joinpath(filename)))
+    except FileNotFoundError as exception:
+        raise FileNotFoundError(f"File {filename} not found in package {package}") from exception
+    except ImportError as exception:
+        raise ImportError(f"Package {package} not found") from exception
+    return path

fastapi_factory_utilities/core/utils/log.py

@@ -0,0 +1,178 @@
+"""Provides a function to setup the logging configuration."""
+
+import logging
+import sys
+from enum import StrEnum, auto
+from typing import Annotated, Any
+
+import structlog
+from pydantic import BaseModel, BeforeValidator
+from structlog.types import EventDict
+
+_logger = structlog.getLogger(__package__)
+
+
+def ensure_logging_level(level: Any) -> int:
+    """Ensure the logging level.
+
+    Args:
+        level (Any): The logging level.
+
+    Returns:
+        int: The logging level.
+    """
+    if isinstance(level, int):
+        return level
+
+    if isinstance(level, str):
+        try:
+            return getattr(logging, str(level).upper())
+        except AttributeError as exception:
+            raise ValueError(f"Invalid logging level: {level}") from exception
+
+    raise ValueError(f"Invalid logging level: {level}")
+
+
+class LoggingConfig(BaseModel):
+    """Logging configuration."""
+
+    name: str
+    level: Annotated[int, BeforeValidator(ensure_logging_level)]
+
+
+class LogModeEnum(StrEnum):
+    """Defines the possible logging modes."""
+
+    CONSOLE = auto()
+    JSON = auto()
+
+
+# https://github.com/hynek/structlog/issues/35#issuecomment-591321744
+def _rename_event_key(_: Any, __: Any, event_dict: EventDict) -> EventDict:  # pylint: disable=invalid-name
+    """Renames the `event` key to `message` in the event dictionary.
+
+    Log entries keep the text message in the `event` field, but Datadog
+    uses the `message` field. This processor moves the value from one field to
+    the other.
+    See https://github.com/hynek/structlog/issues/35#issuecomment-591321744
+    """
+    event_dict["message"] = event_dict.pop("event")
+    return event_dict
+
+
+def clean_uvicorn_logger() -> None:
+    """Cleans the uvicorn loggers."""
+    for logger_name in ["uvicorn", "uvicorn.error", "uvicorn.access"]:
+        # Clear the log handlers for uvicorn loggers, and enable propagation
+        # so the messages are caught by our root logger and formatted correctly
+        # by structlog
+        logging.getLogger(logger_name).handlers.clear()
+        logging.getLogger(logger_name).propagate = True
+
+
+def _drop_color_message_key(_: Any, __: Any, event_dict: EventDict) -> EventDict:  # pylint: disable=invalid-name
+    """Cleans the `color_message` key from the event dictionary.
+
+    Uvicorn logs the message a second time in the extra `color_message`, but we don't
+    need it. This processor drops the key from the event dict if it exists.
+    """
+    event_dict.pop("color_message", None)
+    return event_dict
+
+
+def setup_log(
+    mode: LogModeEnum = LogModeEnum.CONSOLE, log_level: str = "DEBUG", logging_config: list[LoggingConfig] | None = None
+) -> None:
+    """Prepares the logging configuration.
+
+    Args:
+        mode (LogMode): The logging mode to use.
+        log_level (str): The log level to use.
+        logging_config (List[LoggingConfig], optional): The logging configuration. Defaults to None.
+
+    Returns:
+        None
+    """
+    processors: list[structlog.typing.Processor] = [
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.UnicodeDecoder(),
+        structlog.stdlib.PositionalArgumentsFormatter(),
+        structlog.stdlib.ExtraAdder(),
+        structlog.processors.CallsiteParameterAdder(
+            parameters={
+                structlog.processors.CallsiteParameter.MODULE: True,
+                structlog.processors.CallsiteParameter.FUNC_NAME: True,
+                structlog.processors.CallsiteParameter.LINENO: True,
+            }
+        ),
+        _drop_color_message_key,
+    ]
+
+    log_renderer: structlog.dev.ConsoleRenderer | structlog.processors.JSONRenderer
+    match mode:
+        case LogModeEnum.CONSOLE:
+            log_renderer = structlog.dev.ConsoleRenderer(
+                exception_formatter=structlog.dev.RichTracebackFormatter(),
+            )
+        case LogModeEnum.JSON:
+            # We rename the `event` key to `message` only in JSON logs,
+            # as Datadog looks for the
+            # `message` key but the pretty ConsoleRenderer looks for `event`
+            processors.append(_rename_event_key)
+            # Format the exception only for JSON logs, as we want
+            # to pretty-print them when
+            # using the ConsoleRenderer
+            processors.append(
+                structlog.processors.dict_tracebacks,
+            )
+            log_renderer = structlog.processors.JSONRenderer()
+
+    # Remove all existing loggers
+    structlog.reset_defaults()
+    structlog_processors: list[structlog.typing.Processor] = processors.copy()
+    structlog_processors.append(structlog.stdlib.ProcessorFormatter.wrap_for_formatter)
+    structlog.configure(
+        processors=structlog_processors,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+    formatter = structlog.stdlib.ProcessorFormatter(
+        # These run ONLY on `logging` entries that do NOT originate within
+        # structlog.
+        foreign_pre_chain=processors,
+        # These run on ALL entries after the pre_chain is done.
+        processors=[
+            # Remove _record & _from_structlog.
+            structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+            log_renderer,
+        ],
+    )
+
+    handler = logging.StreamHandler()
+    # Use OUR `ProcessorFormatter` to format all `logging` entries.
+    handler.setFormatter(formatter)
+    root_logger: logging.Logger = logging.getLogger()
+    root_logger.addHandler(handler)
+    root_logger.setLevel(log_level.upper())
+
+    for logging_config_item in logging_config or []:
+        logger = logging.getLogger(logging_config_item.name)
+        logger.setLevel(logging_config_item.level)
+
+    def handle_exception(exc_type: Any, exc_value: Any, exc_traceback: Any) -> None:
+        """Handle uncaught exceptions.
+
+        Log any uncaught exception instead of letting it be printed by Python
+        (but leave KeyboardInterrupt untouched to allow users to Ctrl+C to stop)
+        See https://stackoverflow.com/a/16993115/3641865
+        """
+        if issubclass(exc_type, KeyboardInterrupt):
+            sys.__excepthook__(exc_type, exc_value, exc_traceback)
+            return
+
+        _logger.error("Uncaught exception", exc_info=(exc_type, exc_value, exc_traceback))
+
+    sys.excepthook = handle_exception

fastapi_factory_utilities/core/utils/uvicorn.py

@@ -0,0 +1,45 @@
+"""Provides utilities for the application."""
+
+import uvicorn
+import uvicorn.server
+
+from fastapi_factory_utilities.core.protocols import BaseApplicationProtocol
+from fastapi_factory_utilities.core.utils.log import clean_uvicorn_logger
+
+
+class UvicornUtils:
+    """Provides utilities for Uvicorn."""
+
+    def __init__(self, app: BaseApplicationProtocol) -> None:
+        """Instantiate the factory.
+
+        Args:
+            app (BaseApplication): The application.
+            config (AppConfigAbstract): The application configuration.
+
+        Returns:
+            None
+        """
+        self._app: BaseApplicationProtocol = app
+
+    def build_uvicorn_config(self) -> uvicorn.Config:
+        """Build the Uvicorn configuration.
+
+        Returns:
+            uvicorn.Config: The Uvicorn configuration.
+        """
+        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,
+        )
+        clean_uvicorn_logger()
+        return config
+
+    def serve(self) -> None:
+        """Serve the application."""
+        config: uvicorn.Config = self.build_uvicorn_config()
+        server: uvicorn.Server = uvicorn.Server(config=config)
+        server.run()

fastapi_factory_utilities/core/utils/yaml_reader.py

@@ -0,0 +1,166 @@
+"""Provides a class for reading YAML files and converting them to Pydantic models."""
+
+# mypy: disable-error-code="unused-ignore"
+
+import os
+import re
+from pathlib import Path
+from typing import Any, cast
+
+from structlog.stdlib import BoundLogger, get_logger
+from yaml import SafeLoader
+
+logger: BoundLogger = get_logger()
+
+
+class UnableToReadYamlFileError(Exception):
+    """Raised when there is an error reading a YAML file."""
+
+    def __init__(self, file_path: Path | None = None, message: str = "") -> None:
+        """Initializes the exception.
+
+        Args:
+          file_path (str): The path to the YAML file.
+          message (str): The error message.
+        """
+        super().__init__(f"Error reading YAML file: {file_path} - {message}")
+
+
+class YamlFileReader:
+    """Handles reading YAML files and converting them to Pydantic models."""
+
+    re_pattern: re.Pattern[str] = re.compile(r"\${([A-Za-z0-9\-\_]+):?([A-Za-z0-9\-\_\/\:]*)?}")
+
+    def __init__(
+        self,
+        file_path: Path,
+        yaml_base_key: str | None = None,
+        use_environment_injection: bool = True,
+    ) -> None:
+        """Initializes the YAML file reader.
+
+        Args:
+          file_path (str): The path to the YAML file.
+          yaml_base_key (str | None, optional): The base key
+          in the YAML file to read from. Defaults to None.
+          use_environment_injection (bool, optional): Whether to use
+          environment injection. Defaults to True.
+        """
+        # Store the file path and base key for YAML reading
+        self._yaml_base_key: str | None = yaml_base_key
+        self._file_path: Path = file_path
+
+        # Store whether to use environment injection
+        self._use_environment_injection: bool = use_environment_injection
+
+    def _filter_data_with_base_key(self, yaml_data: dict[str, Any]) -> dict[str, Any] | None:
+        """Extracts the data from the YAML file with the base key.
+
+        Args:
+            yaml_data (dict): The data from the YAML file.
+
+        Returns:
+            dict: The filtered data from the YAML file.
+
+        Raises:
+            KeyError: If the base key is not found in the YAML file.
+        """
+        if self._yaml_base_key is not None:
+            keys: list[str] = self._yaml_base_key.split(".")
+            while len(keys) != 0:
+                key: str = keys.pop(0)
+                try:
+                    yaml_data = yaml_data[key]
+                except KeyError:
+                    logger.warning(f"Base key {key}" " not found in YAML file" + " from {self._yaml_base_key}")
+                    return dict()
+        return yaml_data
+
+    def _read_yaml_file(self, file_path: Path) -> dict[str, Any]:
+        """Reads the YAML file and returns the data as a dictionary.
+
+        Args:
+            file_path (Path): The path to the YAML file.
+
+        Returns:
+            dict: The data from the YAML file.
+
+        Raises:
+            ValueError: If there is an error reading the file.
+            FileNotFoundError: If the file is not found.
+        """
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        with open(file=file_path, encoding="UTF-8") as file:
+            loader = SafeLoader(file)
+
+            try:
+                yaml_data: dict[str, Any] = cast(
+                    dict[str, Any],
+                    loader.get_data(),  # type: ignore
+                )
+            except Exception as exception:
+                raise ValueError(f"Error reading YAML file: {file_path}") from exception
+
+            return yaml_data
+
+    def _inject_environment_variables(
+        self, yaml_data: dict[str, Any] | str | list[str] | bool | int
+    ) -> dict[str, Any] | str | list[str] | bool | int:
+        """Injects environment variables into the YAML data recursively.
+
+        Args:
+            yaml_data (dict | str | list | bool): The data from the YAML file.
+
+        Returns:
+            dict: The data from the YAML file
+            with environment variables injected.
+
+        Raises:
+            ValueError: If the YAML data is None.
+        """
+        if isinstance(yaml_data, dict):
+            for key, value in yaml_data.items():
+                yaml_data[key] = self._inject_environment_variables(value)
+        elif isinstance(yaml_data, list):
+            yaml_data = [cast(str, self._inject_environment_variables(yaml_data=value)) for value in yaml_data]
+        elif isinstance(yaml_data, bool) or isinstance(yaml_data, int):
+            return yaml_data
+        elif isinstance(yaml_data, str):  # type: ignore
+            while True:
+                match = self.re_pattern.search(yaml_data)
+                if match is None:
+                    break
+                env_key = match.group(1)
+                env_default = match.group(2)
+                env_value = os.getenv(env_key, env_default)
+                yaml_data = yaml_data.replace(match.group(0), env_value)
+        else:
+            raise ValueError(f"Type not supported: {type(yaml_data)}")
+        return yaml_data
+
+    def read(self) -> dict[str, Any]:
+        """Reads the YAML file and converts it to a Pydantic model with env injected.
+
+        Raises:
+            UnableToReadYamlFileError: If there is an error reading the file.
+        """
+        # Read the YAML file and filter the data with the base key
+        try:
+            yaml_data: dict[str, Any] | None = self._filter_data_with_base_key(
+                self._read_yaml_file(file_path=self._file_path)
+            )
+        except (FileNotFoundError, ValueError, KeyError) as exception:
+            raise UnableToReadYamlFileError(file_path=self._file_path, message=str(exception)) from exception
+
+        if yaml_data is None:
+            return dict()
+
+        if self._use_environment_injection:
+            yaml_data_with_env_injected: dict[str, Any] = cast(
+                dict[str, Any], self._inject_environment_variables(yaml_data)
+            )
+            return dict[str, Any](yaml_data_with_env_injected)
+        else:
+            return dict[str, Any](yaml_data)

fastapi_factory_utilities/example/__init__.py

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

fastapi_factory_utilities/example/__main__.py

@@ -0,0 +1,6 @@
+"""Main entry point for the application."""
+
+from fastapi_factory_utilities.example import main
+
+if __name__ == "__main__":
+    main()

fastapi_factory_utilities/example/api/__init__.py

@@ -0,0 +1,19 @@
+"""Provide the API for the example package."""
+
+from fastapi import APIRouter
+
+from .books import api_v1_books_router, api_v2_books_router
+
+api_router: APIRouter = APIRouter(prefix="/api")
+
+# -- API v1
+api_router_v1: APIRouter = APIRouter(prefix="/v1")
+api_router_v1.include_router(router=api_v1_books_router)
+
+# -- API v2
+api_router_v2: APIRouter = APIRouter(prefix="/v2")
+api_router_v2.include_router(router=api_v2_books_router)
+
+# -- Include API versions
+api_router.include_router(router=api_router_v1)
+api_router.include_router(router=api_router_v2)

fastapi_factory_utilities/example/api/books/__init__.py

@@ -0,0 +1,5 @@
+"""Package for books API."""
+
+from .routes import api_v1_books_router, api_v2_books_router
+
+__all__: list[str] = ["api_v1_books_router", "api_v2_books_router"]

fastapi_factory_utilities/example/api/books/responses.py

@@ -0,0 +1,26 @@
+"""Provides the response objects for the books API."""
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict
+
+from fastapi_factory_utilities.example.entities.books import BookName, BookType
+
+
+class BookResponseModel(BaseModel):
+    """Book response model."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: UUID
+    title: BookName
+    book_type: BookType
+
+
+class BookListReponse(BaseModel):
+    """Book list response."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    books: list[BookResponseModel]
+    size: int

fastapi_factory_utilities/example/api/books/routes.py

@@ -0,0 +1,62 @@
+"""Provides the Books API."""
+
+from typing import cast
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Request
+
+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 .responses import BookListReponse, BookResponseModel
+
+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),
+) -> BookListReponse:
+    """Get all books.
+
+    Args:
+        books_service (BookService): Book service.
+
+    Returns:
+        BookListReponse: List of books
+    """
+    books: list[BookEntity] = books_service.get_all_books()
+
+    return BookListReponse(
+        books=cast(
+            list[BookResponseModel],
+            map(lambda book: BookResponseModel(**book.model_dump()), books),
+        ),
+        size=len(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),
+) -> BookResponseModel:
+    """Get a book.
+
+    Args:
+        book_id (str): Book id
+        books_service (BookService): Book service
+
+    Returns:
+        BookResponseModel: Book
+    """
+    book: BookEntity = books_service.get_book(book_id)
+
+    return BookResponseModel(**book.model_dump())

fastapi_factory_utilities/example/app/__init__.py

@@ -0,0 +1,6 @@
+"""Provides the App and AppConfig classes."""
+
+from .app import App
+from .config import AppConfig
+
+__all__: list[str] = ["App", "AppConfig"]

fastapi_factory_utilities/example/app/app.py

@@ -0,0 +1,37 @@
+"""Provides the concrete application class."""
+
+from typing import ClassVar
+
+from beanie import Document
+
+from fastapi_factory_utilities.core.app import BaseApplication
+from fastapi_factory_utilities.core.app.base.plugins_manager_abstract import (
+    PluginsActivationList,
+)
+from fastapi_factory_utilities.example.models.books.document import BookDocument
+
+from .config import AppConfig
+
+
+class App(BaseApplication):
+    """Concrete application class."""
+
+    PACKAGE_NAME: str = "fastapi_factory_utilities.example"
+
+    CONFIG_CLASS = AppConfig
+
+    ODM_DOCUMENT_MODELS: ClassVar[list[type[Document]]] = [BookDocument]
+
+    def __init__(self, config: AppConfig, plugin_activation_list: PluginsActivationList | None = None) -> None:
+        """Instantiate the application with the configuration and the API router.
+
+        Args:
+            config (AppConfig): The application configuration.
+            plugin_activation_list (PluginsActivationList | None, optional): The plugins activation list.
+        """
+        super().__init__(config=config, plugin_activation_list=plugin_activation_list)
+
+        # Prevent circular imports
+        from ..api import api_router  # pylint: disable=import-outside-toplevel
+
+        self.get_asgi_app().include_router(router=api_router)