fastapi-mongo-base 1.3.7__tar.gz → 1.4.0__tar.gz

{fastapi_mongo_base-1.3.7/src/fastapi_mongo_base.egg-info → fastapi_mongo_base-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-mongo-base
-Version: 1.3.7
+Version: 1.4.0
 Summary: A simple boilerplate application, including models and schemas and abstract router, for FastAPI with MongoDB
 Author-email: Mahdi Kiani <mahdikiany@gmail.com>
 Maintainer-email: Mahdi Kiani <mahdikiany@gmail.com>
@@ -33,6 +33,7 @@ Requires-Dist: fastapi>=0.129.0
 Requires-Dist: uvicorn[standard]>=0.41.0
 Requires-Dist: uuid6>=2025.0.1
 Requires-Dist: typing_extensions>=4.5.0; python_version < "3.11"
+Requires-Dist: pydantic-settings>=2.14.2
 Provides-Extra: usso
 Requires-Dist: usso>=0.30.1; extra == "usso"
 Provides-Extra: sql
@@ -43,6 +44,10 @@ Requires-Dist: pytest-cov; extra == "test"
 Requires-Dist: pytest-asyncio; extra == "test"
 Requires-Dist: mongomock_motor; extra == "test"
 Requires-Dist: coverage; extra == "test"
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.25.0; extra == "prometheus"
+Provides-Extra: sentry
+Requires-Dist: sentry-sdk[fastapi]>=2.0.0; extra == "sentry"
 Dynamic: license-file
 
 # FastAPI MongoDB Base

{fastapi_mongo_base-1.3.7 → fastapi_mongo_base-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-mongo-base"
-version = "1.3.7"
+version = "1.4.0"
 description = "A simple boilerplate application, including models and schemas and abstract router, for FastAPI with MongoDB"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -35,12 +35,15 @@ dependencies = [
   "uvicorn[standard]>=0.41.0",
   "uuid6>=2025.0.1",
   "typing_extensions>=4.5.0; python_version<'3.11'",
+  "pydantic-settings>=2.14.2",
 ]
 
 [project.optional-dependencies]
 usso = ["usso>=0.30.1"]
 sql = ["sqlalchemy>=2.0.43"]
 test = ["pytest", "pytest-cov", "pytest-asyncio", "mongomock_motor", "coverage"]
+prometheus = ["prometheus-client>=0.25.0"]
+sentry = ["sentry-sdk[fastapi]>=2.0.0"]
 
 [project.urls]
 "Homepage" = "https://github.com/mahdikiani/fastapi-mongo-base-app"

{fastapi_mongo_base-1.3.7 → fastapi_mongo_base-1.4.0}/src/fastapi_mongo_base/core/app_factory.py

@@ -13,6 +13,7 @@ from fastapi.staticfiles import StaticFiles
 
 from . import config, db, exceptions
 from .error_responses import COMMON_ERROR_RESPONSES, setup_openapi_errors
+from .sentry import setup_sentry
 
 
 def health(request: fastapi.Request) -> dict[str, str]:
@@ -160,6 +161,7 @@ def get_app_kwargs(
         init_functions = []
 
     settings.config_logger()
+    setup_sentry(settings)
 
     if settings is None:
         settings = config.Settings()

fastapi_mongo_base-1.4.0/src/fastapi_mongo_base/core/config.py

@@ -0,0 +1,284 @@
+"""FastAPI server configuration."""
+
+import dataclasses
+import json
+import logging
+import logging.config
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from singleton import Singleton
+
+
+class JsonFormatter(logging.Formatter):
+    """
+    Logging formatter that outputs a single-line structured JSON object.
+
+    Using json_advanced.dumps ensures special types (datetime, UUID,
+    ObjectId, Pydantic models, etc.) are serialised without raising errors.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Serialise *record* to a JSON string."""
+        data: dict[str, object] = {
+            "timestamp": self.formatTime(record, self.datefmt),
+            "level": record.levelname,
+            "logger": record.name,
+            "filename": record.filename,
+            "lineno": record.lineno,
+            "funcName": record.funcName,
+            "message": record.getMessage(),
+        }
+        if record.exc_info:
+            data["exc_info"] = self.formatException(record.exc_info)
+        if record.stack_info:
+            data["stack_info"] = self.formatStack(record.stack_info)
+        return json.dumps(data, ensure_ascii=False)
+
+
+class ProjectSettings(BaseSettings):
+    """Environment-backed settings loaded by pydantic-settings."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        case_sensitive=False,
+    )
+
+    root_url: str = Field(
+        default="http://localhost:8000",
+        validation_alias="DOMAIN",
+    )
+    project_name: str = Field(
+        default="PROJECT", validation_alias="PROJECT_NAME"
+    )
+    base_path: str = "/api/v1"
+    worker_update_time: int = 180
+    debug: bool = False
+
+    @field_validator("worker_update_time")
+    @classmethod
+    def normalize_worker_update_time(cls, value: int) -> int:
+        """
+        Preserve the previous fallback for falsy worker update values.
+
+        Args:
+            value: Configured worker update interval.
+
+        Returns:
+            Worker update interval with the legacy fallback applied.
+
+        """
+        return value or 180
+
+    cors_origins: str | None = Field(
+        default=None,
+        validation_alias="CORS_ORIGINS",
+    )
+    page_max_limit: int = 100
+    mongo_uri: str = Field(
+        default="mongodb://localhost:27017/", validation_alias="MONGO_URI"
+    )
+    mongo_server_selection_timeout_ms: int = 5000
+    mongo_connect_timeout_ms: int = 5000
+    sentry_dsn: str | None = Field(default=None, validation_alias="SENTRY_DSN")
+    sentry_environment: str | None = Field(
+        default=None,
+        validation_alias="SENTRY_ENVIRONMENT",
+    )
+    sentry_release: str | None = Field(
+        default=None,
+        validation_alias="SENTRY_RELEASE",
+    )
+    sentry_traces_sample_rate: float | None = Field(
+        default=None,
+        validation_alias="SENTRY_TRACES_SAMPLE_RATE",
+    )
+    sentry_profiles_sample_rate: float | None = Field(
+        default=None,
+        validation_alias="SENTRY_PROFILES_SAMPLE_RATE",
+    )
+    sentry_send_default_pii: bool = Field(
+        default=False,
+        validation_alias="SENTRY_SEND_DEFAULT_PII",
+    )
+    log_format: Literal["json", "text"] = Field(
+        default="json",
+        validation_alias="LOG_FORMAT",
+    )
+
+    @classmethod
+    def get_coverage_dir(cls) -> str:
+        """
+        Get the directory path for coverage reports.
+
+        Returns:
+            Path string to coverage directory.
+
+        """
+        return getattr(cls, "base_dir", Path(".")) / "htmlcov"
+
+    @classmethod
+    def get_log_config(
+        cls,
+        console_level: str = "INFO",
+        log_format: str | None = None,
+        **kwargs: object,
+    ) -> dict[str, object]:
+        """
+        Get logging configuration dictionary.
+
+        Args:
+            console_level: Logging level for console handler.
+            log_format: ``"json"`` for structured JSON output (default, suited
+                for Kubernetes / log-aggregation pipelines) or ``"text"`` for
+                the human-readable bracketed format.  When *None* the value is
+                read from the ``log_format`` attribute on the class (which is
+                itself populated from the ``LOG_FORMAT`` environment variable).
+            **kwargs: Additional keyword arguments (reserved for subclasses).
+
+        Returns:
+            Dictionary with logging configuration.
+        """
+        resolved_format = log_format or getattr(cls, "log_format", "json")
+
+        if resolved_format == "json":
+            formatter_config: dict[str, object] = {"()": JsonFormatter}
+        else:
+            formatter_config = {
+                "format": "[{levelname} : {filename}:{lineno} : {asctime} -> {funcName:10}] {message}",  # noqa: E501
+                "style": "{",
+            }
+
+        return {
+            "version": 1,
+            "formatters": {"standard": formatter_config},
+            "handlers": {
+                "console": {
+                    "class": "logging.StreamHandler",
+                    "level": console_level,
+                    "formatter": "standard",
+                }
+            },
+            "loggers": {
+                "": {
+                    "handlers": ["console"],
+                    "level": "INFO",
+                    "propagate": True,
+                },
+            },
+        }
+
+    @classmethod
+    def config_logger(cls) -> None:
+        """Configure Python logging with settings from get_log_config."""
+        log_format = project_settings.log_format
+        log_config = cls.get_log_config(log_format=log_format)
+        if log_config["handlers"].get("file"):
+            (cls.get_coverage_dir() / "logs").mkdir(
+                parents=True, exist_ok=True
+            )
+        logging.config.dictConfig(log_config)
+
+
+project_settings = ProjectSettings()
+
+
+@dataclasses.dataclass
+class Settings(metaclass=Singleton):
+    """Server config settings."""
+
+    # base_dir: Path = Path(__file__).resolve().parent.parent  # noqa: ERA001
+    root_url: str = project_settings.root_url
+    project_name: str = project_settings.project_name
+    base_path: str = project_settings.base_path
+    worker_update_time: int = project_settings.worker_update_time
+    debug: bool = project_settings.debug
+
+    _cors_origins_str: str | None = project_settings.cors_origins
+
+    @property
+    def cors_origins(self) -> list[str]:
+        """
+        CORS allowed origins as a list.
+
+        Returns:
+            List of allowed origin URLs.
+
+        """
+        if self._cors_origins_str and "[" in self._cors_origins_str:
+            return json.loads(self._cors_origins_str)
+        if self._cors_origins_str:
+            return [s.strip() for s in self._cors_origins_str.split(",")]
+        return ["http://localhost:8000"]
+
+    page_max_limit: int = project_settings.page_max_limit
+    mongo_uri: str = project_settings.mongo_uri
+    mongo_server_selection_timeout_ms: int = (
+        project_settings.mongo_server_selection_timeout_ms
+    )
+    mongo_connect_timeout_ms: int = project_settings.mongo_connect_timeout_ms
+    sentry_dsn: str | None = project_settings.sentry_dsn
+    sentry_environment: str | None = project_settings.sentry_environment
+    sentry_release: str | None = project_settings.sentry_release
+    sentry_traces_sample_rate: float | None = (
+        project_settings.sentry_traces_sample_rate
+    )
+    sentry_profiles_sample_rate: float | None = (
+        project_settings.sentry_profiles_sample_rate
+    )
+    sentry_send_default_pii: bool = project_settings.sentry_send_default_pii
+    log_format: str = project_settings.log_format
+
+    @classmethod
+    def get_coverage_dir(cls) -> str:
+        """
+        Get the directory path for coverage reports.
+
+        Returns:
+            Path string to coverage directory.
+
+        """
+        return project_settings.get_coverage_dir()
+
+    @classmethod
+    def get_log_config(
+        cls,
+        console_level: str = "INFO",
+        log_format: str | None = None,
+        **kwargs: object,
+    ) -> dict[str, object]:
+        """
+        Get logging configuration dictionary.
+
+        Args:
+            console_level: Logging level for console handler.
+            log_format: ``"json"`` for structured JSON output (default, suited
+                for Kubernetes / log-aggregation pipelines) or ``"text"`` for
+                the human-readable bracketed format.  When *None* the value is
+                read from the ``log_format`` attribute on the class (which is
+                itself populated from the ``LOG_FORMAT`` environment variable).
+            **kwargs: Additional keyword arguments (reserved for subclasses).
+
+        Returns:
+            Dictionary with logging configuration.
+        """
+        return project_settings.get_log_config(
+            console_level=console_level,
+            log_format=log_format,
+            **kwargs,
+        )
+
+    @classmethod
+    def config_logger(cls) -> None:
+        """Configure Python logging with settings from get_log_config."""
+        log_format = getattr(cls, "log_format", "json")
+        log_config = cls.get_log_config(log_format=log_format)
+        if log_config["handlers"].get("file"):
+            (getattr(cls, "base_dir", Path(".")) / "logs").mkdir(
+                parents=True, exist_ok=True
+            )
+        logging.config.dictConfig(log_config)

{fastapi_mongo_base-1.3.7 → fastapi_mongo_base-1.4.0}/src/fastapi_mongo_base/core/db.py

@@ -4,10 +4,10 @@ import logging
 
 from beanie import init_beanie
 
-from fastapi_mongo_base.models import BaseEntity
-from fastapi_mongo_base.utils import basic
-
+from ..models import BaseEntity
+from ..utils import basic
 from .config import Settings
+from .errors.mongodb_errors import MongoDBConnectionError
 
 
 async def init_mongo_db(settings: Settings | None = None) -> object:
@@ -42,6 +42,18 @@ async def init_mongo_db(settings: Settings | None = None) -> object:
     if settings is None:
         settings = Settings()
 
+    try:
+        from pymongo import monitoring
+
+        from ..core.prometheus.mongo import DatabasePoolMonitor
+
+        pool_monitor = DatabasePoolMonitor(
+            database_name=settings.project_name,
+        )
+        monitoring.register(pool_monitor)
+    except ImportError:
+        pass
+
     client = AsyncMongoClient(
         settings.mongo_uri,
         serverSelectionTimeoutMS=settings.mongo_server_selection_timeout_ms,
@@ -65,15 +77,15 @@ async def init_mongo_db(settings: Settings | None = None) -> object:
         logging.exception(
             "MongoDB connection timeout at %s", settings.mongo_uri
         )
-        raise SystemExit(1) from e
+        raise MongoDBConnectionError("Failed to connect to MongoDB") from e
 
     except PyMongoError as e:
         logging.exception("MongoDB error at %s", settings.mongo_uri)
-        raise SystemExit(1) from e
+        raise MongoDBConnectionError("Failed to connect to MongoDB") from e
 
     except Exception as e:
         logging.exception("Unexpected failure initializing MongoDB")
-        raise SystemExit(1) from e
+        raise MongoDBConnectionError("Failed to connect to MongoDB") from e
 
     return db
 

{fastapi_mongo_base-1.3.7 → fastapi_mongo_base-1.4.0}/src/fastapi_mongo_base/core/error_responses.py

@@ -1,7 +1,5 @@
 """OpenAPI error response schemas aligned with exception handlers."""
 
-from typing import Any
-
 import fastapi
 from fastapi.openapi.utils import get_openapi
 from pydantic import BaseModel, ConfigDict, Field
@@ -25,8 +23,8 @@ class ValidationReason(BaseModel):
     field: str
     type: str | None = None
     msg: str | None = None
-    input: Any = None
-    ctx: dict[str, Any] | None = None
+    input: object = None
+    ctx: dict[str, object] | None = None
 
 
 class ValidationErrorResponseModel(BaseModel):
@@ -45,7 +43,7 @@ class InternalErrorResponseModel(BaseModel):
     error: str = "Exception"
 
 
-COMMON_ERROR_RESPONSES: dict[int, dict[str, Any]] = {
+COMMON_ERROR_RESPONSES: dict[int, dict[str, object]] = {
     400: {
         "model": APIErrorResponseModel,
         "description": "Bad request",
@@ -89,7 +87,7 @@ COMMON_ERROR_RESPONSES: dict[int, dict[str, Any]] = {
 }
 
 
-def _patch_validation_responses(schema: dict[str, Any]) -> None:
+def _patch_validation_responses(schema: dict[str, object]) -> None:
     validation_ref = {
         "$ref": "#/components/schemas/ValidationErrorResponseModel"
     }
@@ -119,7 +117,7 @@ def setup_openapi_errors(app: fastapi.FastAPI) -> None:
 
     """
 
-    def custom_openapi() -> dict[str, Any]:
+    def custom_openapi() -> dict[str, object]:
         if app.openapi_schema:
             return app.openapi_schema
 

{fastapi_mongo_base-1.3.7 → fastapi_mongo_base-1.4.0}/src/fastapi_mongo_base/core/errors/resource_errors.py

@@ -13,6 +13,7 @@ class ResourceError(BaseHTTPException):
 
     def __init__(
         self,
+        error_code: str | None = None,
         detail: str | None = None,
         message: dict | None = None,
         **kwargs: object,
@@ -20,7 +21,7 @@ class ResourceError(BaseHTTPException):
         """Initialize ResourceError with optional detail, message, and data."""
         super().__init__(
             status_code=self.status_code,
-            error_code=self.error_code,
+            error_code=error_code or self.error_code,
             detail=detail or self.message_en,
             message=message,
             **kwargs,

fastapi_mongo_base-1.4.0/src/fastapi_mongo_base/core/middlewares/prometheus.py

@@ -0,0 +1,165 @@
+"""Prometheus metrics middleware for FastAPI applications."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Awaitable, Callable, Iterable
+from http import HTTPStatus
+from typing import ClassVar
+
+from prometheus_client import Counter, Gauge, Histogram
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.types import ASGIApp
+
+RequestEndpoint = Callable[[Request], Awaitable[Response]]
+
+
+class PrometheusMiddleware(BaseHTTPMiddleware):
+    """
+    Collect Prometheus HTTP metrics for a FastAPI/Starlette app.
+
+    The middleware records request count, in-progress requests, and request
+    latency. Metrics are labelled by HTTP method, route template, and status
+    code so endpoint-level latency can be queried without exploding label
+    cardinality from path parameters.
+
+    Example:
+        app.add_middleware(PrometheusMiddleware)
+
+    """
+
+    DEFAULT_EXCLUDED_PATHS: ClassVar[set[str]] = {
+        "/metrics",
+        "/docs",
+        "/redoc",
+        "/openapi.json",
+        "/favicon.ico",
+    }
+
+    DEFAULT_BUCKETS: ClassVar[tuple[float, ...]] = (
+        0.005,
+        0.01,
+        0.025,
+        0.05,
+        0.075,
+        0.1,
+        0.25,
+        0.5,
+        0.75,
+        1.0,
+        2.5,
+        5.0,
+        7.5,
+        10.0,
+    )
+
+    REQUESTS_TOTAL: ClassVar[Counter] = Counter(
+        "http_requests_total",
+        "Total number of HTTP requests.",
+        ("method", "endpoint", "status_code"),
+    )
+    REQUESTS_IN_PROGRESS: ClassVar[Gauge] = Gauge(
+        "http_requests_in_progress",
+        "Number of HTTP requests currently being processed.",
+        ("method", "endpoint"),
+    )
+    REQUEST_LATENCY_SECONDS: ClassVar[Histogram] = Histogram(
+        "http_request_duration_seconds",
+        "HTTP request latency in seconds.",
+        ("method", "endpoint", "status_code"),
+        buckets=DEFAULT_BUCKETS,
+    )
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        excluded_paths: Iterable[str] | None = None,
+    ) -> None:
+        """
+        Initialize the Prometheus metrics middleware.
+
+        Args:
+            app: ASGI application instance.
+            excluded_paths: Exact URL paths that should not be measured.
+
+        """
+        super().__init__(app)
+        self.excluded_paths = set(
+            excluded_paths or self.DEFAULT_EXCLUDED_PATHS
+        )
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: RequestEndpoint,
+    ) -> Response:
+        """
+        Measure request metrics and forward the request downstream.
+
+        Args:
+            request: Incoming HTTP request.
+            call_next: Next middleware or route handler.
+
+        Returns:
+            HTTP response returned by downstream application.
+
+        Raises:
+            Exception: Re-raises downstream exceptions after recording metrics.
+
+        """
+        if request.url.path in self.excluded_paths:
+            return await call_next(request)
+
+        method = request.method
+        endpoint = self._get_endpoint(request)
+        status_code = str(HTTPStatus.INTERNAL_SERVER_ERROR.value)
+        start_time = time.perf_counter()
+
+        in_progress = self.REQUESTS_IN_PROGRESS.labels(
+            method=method,
+            endpoint=endpoint,
+        )
+        in_progress.inc()
+
+        try:
+            response = await call_next(request)
+            status_code = str(response.status_code)
+        except Exception:
+            status_code = str(HTTPStatus.INTERNAL_SERVER_ERROR.value)
+            raise
+        else:
+            return response
+        finally:
+            elapsed = time.perf_counter() - start_time
+            in_progress.dec()
+            self.REQUESTS_TOTAL.labels(
+                method=method,
+                endpoint=endpoint,
+                status_code=status_code,
+            ).inc()
+            self.REQUEST_LATENCY_SECONDS.labels(
+                method=method,
+                endpoint=endpoint,
+                status_code=status_code,
+            ).observe(elapsed)
+
+    @staticmethod
+    def _get_endpoint(request: Request) -> str:
+        """
+        Return the matched route path template for a request.
+
+        Args:
+            request: Incoming HTTP request.
+
+        Returns:
+            Route template when available, otherwise the raw URL path.
+
+        """
+        route = request.scope.get("route")
+        path = getattr(route, "path", None)
+        if isinstance(path, str):
+            return path
+        return request.url.path