Source code for core_apis.api

# -*- coding: utf-8 -*-

"""
FastAPI application factory and configuration.

This module provides the main application factory function for creating
configured FastAPI instances with routing, middleware, and health checks.
"""

from typing import Optional

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

from .config import AppConfig
from .cors import CorsConfig
from .routers import routers
from .routers.health import health_router

__all__ = [
    "AppConfig",
    "create_application",
    "CorsConfig",
]




def create_application(
    app_config: Optional[AppConfig] = None,
    **kwargs,
) -> FastAPI:
    """
    It creates the FastAPI application. Remember to inject the routers before
    creating the application like:

    .. code-block:: python

        from fastapi import APIRouter

        from core_apis.api import server
        from core_apis.api.routers import add_router

        router = APIRouter()
        add_router(router)

        @router.get(path="/server_status")
        def new_router():
            return {"status": "OK"}

        server.run()
    ..

    :param app_config:
        Application configuration. Pass an :class:`AppConfig` instance
        to customize name, version, CORS, debug mode, and more.
        Defaults to :class:`AppConfig` with all default values.

    :param kwargs: Additional keyword arguments passed directly to :class:`FastAPI`.
    :return: Returns the FastAPI application.
    """

    _config = app_config or AppConfig()

    application = FastAPI(
        title=_config.name,
        description=_config.description,
        version=_config.version,
        debug=_config.debug,
        **kwargs,
    )

    if _config.cors_config and _config.cors_config.enabled:
        application.add_middleware(
            CORSMiddleware,  # type: ignore[arg-type]
            allow_origins=_config.cors_config.origins,
            allow_methods=_config.cors_config.methods,
            allow_headers=_config.cors_config.headers,
        )

    for router in [*routers, health_router]:
        application.include_router(
            router=router,
            prefix=_config.base_path,
        )

    return application