voltwire-fastapi-logging 0.0.1__py3-none-any.whl

voltwire/fastapi/logging/__init__.py

@@ -0,0 +1,35 @@
+__version__ = "0.0.0"
+
+from typing import Any, Protocol
+
+from pydantic import BaseModel
+
+from voltwire.fastapi.logging._constants import log_context
+from voltwire.fastapi.logging.middleware import ContextEnricher
+
+__all__ = ["ContextEnricher", "log_context", "integration_logger", "log_banner", "IntegrationLogContext", "AppRuntimeSettings"]
+
+
+class IntegrationLogContext(BaseModel):
+    integration: str
+    message: str
+
+
+class AppRuntimeSettings(Protocol):
+    app_name: str
+    version: str
+    environment: str
+
+
+def log_banner(settings: AppRuntimeSettings):
+    print(
+        f"Application: '{settings.app_name}' Version: '{settings.version}' Environment: '{settings.environment}'",
+        flush=True,
+    )
+
+
+def integration_logger(context: IntegrationLogContext, **extra: Any):
+    from loguru import logger
+
+    context_dict = {**context.model_dump(), **extra}
+    return logger.contextualize(**context_dict)

voltwire/fastapi/logging/_constants.py

@@ -0,0 +1,11 @@
+from typing import Any
+
+from loguru import logger
+
+APP_LOG_FORMAT = (
+    "<level>{level}</level>: <green>{time:YYYY-MM-DDTHH:mm:s:SSS!UTC}</green> "
+    "| {process}:{thread} | {name}:{line} - {message} | {extra}"
+)
+
+def log_context(**extra: Any):
+    return logger.contextualize(**extra)

voltwire/fastapi/logging/base.py

@@ -0,0 +1,81 @@
+import logging
+import sys
+from dataclasses import dataclass
+from typing import Protocol
+
+from loguru import logger
+
+from voltwire.fastapi.logging._constants import APP_LOG_FORMAT
+
+
+class LogSettings(Protocol):
+    level: str
+
+
+@dataclass
+class DefaultLogSettings:
+    level: str = "INFO"
+
+
+# Loggers known to attach their own handlers directly (bypassing propagation
+# to root) rather than relying on the standard logging tree.
+_DIRECTLY_HANDLED_LOGGERS = (
+    "uvicorn",
+    "uvicorn.access",
+    "uvicorn.error",
+    "gunicorn",
+    "gunicorn.access",
+    "gunicorn.error",
+    "sqlalchemy",
+    "sqlalchemy.engine",
+)
+
+
+class InterceptHandler(logging.Handler):
+    """Forwards stdlib `logging` records into loguru.
+
+    Installed on the root logger so any code using plain
+    `logging.getLogger(__name__)` (this codebase, other voltwire
+    packages, or third-party dependencies) is routed through loguru
+    without those callers needing to know loguru exists.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            level = logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        frame, depth = logging.currentframe(), 0
+        while frame and (depth == 0 or frame.f_code.co_filename == logging.__file__):
+            frame = frame.f_back
+            depth += 1
+
+        logger.opt(depth=depth, exception=record.exc_info).log(
+            level, record.getMessage()
+        )
+
+
+def setup_logging(settings: LogSettings):
+
+    # ensure all python and loguru loggers are clean
+    logger.remove()
+    root = logging.getLogger()
+    for handler in root.handlers[:]:
+        root.removeHandler(handler)
+
+    logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+
+    # some libraries attach handlers directly to their own named logger
+    # instead of propagating to root - strip those so they route through
+    # the intercept handler too.
+    for name in _DIRECTLY_HANDLED_LOGGERS:
+        named_logger = logging.getLogger(name)
+        named_logger.handlers = []
+        named_logger.propagate = True
+
+    logger.add(
+        sys.stdout,
+        format=APP_LOG_FORMAT,
+        level=settings.level,
+    )

voltwire/fastapi/logging/middleware.py

@@ -0,0 +1,55 @@
+from dataclasses import dataclass, field
+from typing import Protocol, Callable, Awaitable, Any
+
+from loguru import logger
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+
+from voltwire.fastapi.logging._constants import log_context
+
+ContextEnricher = Callable[[Request, dict[str, Any]], Awaitable[None]]
+
+
+class LoggingMiddlewareSettings(Protocol):
+    context_enrichers: list[ContextEnricher]
+
+@dataclass
+class DefaultLoggingMiddlewareSettings:
+    context_enrichers: list[ContextEnricher] = field(default_factory=list)
+
+class LoggingContextMiddleware(BaseHTTPMiddleware):
+    """
+    This middleware enriches every log entry with request context.
+    - Adds method and path to all logs within the request scope
+    - Executes custom context enrichers to add additional context
+    
+    Custom context enrichers can be registered via settings:
+        async def custom_enricher(request: Request, context: dict[str, Any]) -> None:
+            context["custom_field"] = "custom_value"
+        
+        settings = DefaultLoggingMiddlewareSettings(
+            context_enrichers=[custom_enricher]
+        )
+        app.add_middleware(LoggingContextMiddleware, settings=settings)
+    """
+
+    def __init__(self, app, settings: LoggingMiddlewareSettings):
+        super().__init__(app)
+        self.settings = settings
+
+    async def dispatch(self, request: Request, call_next):
+        request_context = {"method": request.method, "path": request.url.path}
+
+        # Execute custom context enrichers
+        for enricher in self.settings.context_enrichers:
+            try:
+                await enricher(request, request_context)
+            except Exception as e:
+                logger.warning(f"Context enricher {enricher.__name__} failed: {str(e)}")
+
+        # Process the request within loguru context
+        with log_context(**request_context):
+            logger.trace(f"Request started: {request.method} {request.url.path}")
+            response = await call_next(request)
+            logger.trace(f"Request completed: {request.method} {request.url.path} - {response.status_code}")
+            return response

voltwire_fastapi_logging-0.0.1.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.5
+Name: voltwire-fastapi-logging
+Version: 0.0.1
+Summary: Logging utilities for FastAPI apps
+Author-email: Hermann Steidel <hsteidel.software@gmail.com>
+License-Expression: MIT
+Requires-Python: <4.0,>=3.13
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: starlette>=0.27.0
+Description-Content-Type: text/markdown
+
+<img src="https://raw.githubusercontent.com/hsteidel/voltwire/main/assets/icons/fastapi-logging.svg" alt="" width="56" height="56" align="left">
+
+# voltwire-fastapi-logging
+
+Logging utilities for FastAPI apps: request-context-enriching middleware.
+
+## Installation
+
+```bash
+pip install voltwire-fastapi-logging
+```
+
+## Quickstart
+
+```python
+from voltwire.fastapi.logging import setup_logging, DefaultLogSettings
+
+setup_logging(DefaultLogSettings(enable_json=False, level="INFO"))
+```
+
+Add `LoggingContextMiddleware` to enrich every log entry within a request with a correlation
+ID, method, and path:
+
+```python
+from voltwire.fastapi.logging import LoggingContextMiddleware, DefaultLoggingMiddlewareSettings
+
+app.add_middleware(LoggingContextMiddleware, settings=DefaultLoggingMiddlewareSettings())
+```

voltwire_fastapi_logging-0.0.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+voltwire/fastapi/logging/__init__.py,sha256=gHFrqH3OIg4-YueYIWOfv4yGJcsUwEYUc5WPfn2AjZA,920
+voltwire/fastapi/logging/_constants.py,sha256=Ntzvv3fLW9ZsYv_yB4uHJXGSOg0ivGbTcXBN5_Dg5SU,290
+voltwire/fastapi/logging/base.py,sha256=cKqyGid75Wek7zRaPyKMvw_8KIc49gY62LcMFgSdB9I,2212
+voltwire/fastapi/logging/middleware.py,sha256=7k1aT52aTtRuVkpyG-DJPtjh-0rOZZKvwgwLBlfNG0E,2163
+voltwire_fastapi_logging-0.0.1.dist-info/METADATA,sha256=lrjFI89ITQcxZHMZfPAcfePOvZo_3AUYsWx3zmw6Dtw,1161
+voltwire_fastapi_logging-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+voltwire_fastapi_logging-0.0.1.dist-info/RECORD,,

voltwire_fastapi_logging-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any