hexastack-logging 0.0.0__py3-none-any.whl

hexastack_logging/__init__.py

@@ -0,0 +1,6 @@
+from hexastack_logging import adapters, infra
+
+__all__ = [
+    "adapters",
+    "infra",
+]

hexastack_logging/adapters/__init__.py

@@ -0,0 +1,13 @@
+from hexastack_logging.adapters.logger import (
+    LoguruAdapter,
+    RichLogger,
+    StructlogAdapter,
+    StructuredLogger,
+)
+
+__all__ = [
+    "LoguruAdapter",
+    "RichLogger",
+    "StructlogAdapter",
+    "StructuredLogger",
+]

hexastack_logging/adapters/logger/__init__.py

@@ -0,0 +1,11 @@
+from hexastack_logging.adapters.logger.loguru import LoguruAdapter
+from hexastack_logging.adapters.logger.rich import RichLogger
+from hexastack_logging.adapters.logger.structlog import StructlogAdapter
+from hexastack_logging.adapters.logger.structured import StructuredLogger
+
+__all__ = [
+    "LoguruAdapter",
+    "RichLogger",
+    "StructlogAdapter",
+    "StructuredLogger",
+]

hexastack_logging/adapters/logger/loguru.py

@@ -0,0 +1,133 @@
+import importlib
+from typing import Any
+
+from hexastack_core.domain.exceptions import MissingDependencyError
+from hexastack_core.ports.logging import Extras, LoggingPort
+from hexastack_core.utils.context import get_correlation_id, get_user_context
+
+
+class LoguruAdapter(LoggingPort):
+    """Optional Loguru adapter implementing LoggingPort.
+
+    Notes/Architectural Intent:
+        Delegates logging to loguru while binding Hexastack correlation
+        and user context.
+    """
+
+    def __init__(self, logger: Any = None) -> None:
+        """Initialize LoguruAdapter.
+
+        Args:
+            logger: Optional loguru logger instance.
+
+        Raises:
+            MissingDependencyError: If loguru package is not installed.
+        """
+        if logger is None:
+            try:
+                loguru_mod = importlib.import_module("loguru")
+                self._logger: Any = loguru_mod.logger
+            except ImportError as err:
+                raise MissingDependencyError(
+                    "loguru is required for LoguruAdapter. Install via 'pip install hexastack-logging[loguru]'."
+                ) from err
+        else:
+            self._logger = logger
+
+    def _get_bound_logger(self, extra: Extras | None = None) -> Any:
+        bind_dict: dict[str, Any] = dict(extra) if extra else {}
+        cid = get_correlation_id()
+        if cid:
+            bind_dict["correlation_id"] = cid
+        user = get_user_context()
+        if user:
+            bind_dict["user_id"] = user.user_id
+            if user.tenant_id:
+                bind_dict["tenant_id"] = user.tenant_id
+        return self._logger.bind(**bind_dict)
+
+    def critical(
+        self, message: str, extra: Extras | None = None, exc: Exception | None = None
+    ) -> None:
+        """Log a critical message through loguru.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+            exc: Optional exception instance to attach traceback.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        log = self._get_bound_logger(extra)
+        log.opt(exception=exc).critical(message)
+
+    def debug(self, message: str, extra: Extras | None = None) -> None:
+        """Log a debug message through loguru.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        log = self._get_bound_logger(extra)
+        log.debug(message)
+
+    def error(
+        self, message: str, extra: Extras | None = None, exc: Exception | None = None
+    ) -> None:
+        """Log an error message through loguru.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+            exc: Optional exception instance to attach traceback.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        log = self._get_bound_logger(extra)
+        log.opt(exception=exc).error(message)
+
+    def info(self, message: str, extra: Extras | None = None) -> None:
+        """Log an informational message through loguru.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        log = self._get_bound_logger(extra)
+        log.info(message)
+
+    def warning(self, message: str, extra: Extras | None = None) -> None:
+        """Log a warning message through loguru.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        log = self._get_bound_logger(extra)
+        log.warning(message)

hexastack_logging/adapters/logger/rich.py

@@ -0,0 +1,131 @@
+import importlib
+from typing import Any
+
+from hexastack_core.domain.exceptions import MissingDependencyError
+from hexastack_core.ports.logging import Extras, LoggingPort
+from hexastack_core.utils.context import get_correlation_id
+
+
+class RichLogger(LoggingPort):
+    """Optional Rich terminal logger implementing LoggingPort.
+
+    Notes/Architectural Intent:
+        Renders rich stylized terminal logs with correlation ID tags when rich is installed.
+    """
+
+    def __init__(self, console: Any = None) -> None:
+        """Initialize RichLogger.
+
+        Args:
+            console: Optional rich.console.Console instance.
+
+        Raises:
+            MissingDependencyError: If rich package is not installed.
+        """
+        if console is None:
+            try:
+                rich_console_mod = importlib.import_module("rich.console")
+                self._console: Any = rich_console_mod.Console()
+            except ImportError as err:
+                raise MissingDependencyError(
+                    "rich is required for RichLogger. Install via 'pip install hexastack-logging[rich]'."
+                ) from err
+        else:
+            self._console = console
+
+    def _render(
+        self,
+        level: str,
+        color: str,
+        message: str,
+        extra: Extras | None = None,
+        exc: Exception | None = None,
+    ) -> None:
+        cid = get_correlation_id()
+        cid_tag = f"[dim][corr:{cid[:8]}][/dim] " if cid else ""
+        extra_str = f" [dim]{extra}[/dim]" if extra else ""
+        exc_str = f"\n[red]{exc}[/red]" if exc else ""
+        self._console.print(
+            f"[{color}][{level:<8}][/{color}] {cid_tag}{message}{extra_str}{exc_str}"
+        )
+
+    def critical(
+        self, message: str, extra: Extras | None = None, exc: Exception | None = None
+    ) -> None:
+        """Log a critical message with Rich formatting.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+            exc: Optional exception instance to attach traceback.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._render("CRITICAL", "bold red", message, extra=extra, exc=exc)
+
+    def debug(self, message: str, extra: Extras | None = None) -> None:
+        """Log a debug message with Rich formatting.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._render("DEBUG", "cyan", message, extra=extra)
+
+    def error(
+        self, message: str, extra: Extras | None = None, exc: Exception | None = None
+    ) -> None:
+        """Log an error message with Rich formatting.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+            exc: Optional exception instance to attach traceback.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._render("ERROR", "red", message, extra=extra, exc=exc)
+
+    def info(self, message: str, extra: Extras | None = None) -> None:
+        """Log an informational message with Rich formatting.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._render("INFO", "green", message, extra=extra)
+
+    def warning(self, message: str, extra: Extras | None = None) -> None:
+        """Log a warning message with Rich formatting.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._render("WARNING", "yellow", message, extra=extra)

hexastack_logging/adapters/logger/structlog.py

@@ -0,0 +1,128 @@
+import importlib
+from typing import Any
+
+from hexastack_core.domain.exceptions import MissingDependencyError
+from hexastack_core.ports.logging import Extras, LoggingPort
+from hexastack_core.utils.context import get_correlation_id, get_user_context
+
+
+class StructlogAdapter(LoggingPort):
+    """Optional Structlog adapter implementing LoggingPort.
+
+    Notes/Architectural Intent:
+        Delegates logging to structlog BoundLogger while binding Hexastack correlation
+        and user context.
+    """
+
+    def __init__(self, logger: Any = None) -> None:
+        """Initialize StructlogAdapter.
+
+        Args:
+            logger: Optional structlog logger instance.
+
+        Raises:
+            MissingDependencyError: If structlog package is not installed.
+        """
+        if logger is None:
+            try:
+                structlog_mod = importlib.import_module("structlog")
+                self._logger: Any = structlog_mod.get_logger()
+            except ImportError as err:
+                raise MissingDependencyError(
+                    "structlog is required for StructlogAdapter. Install via 'pip install hexastack-logging[structlog]'."
+                ) from err
+        else:
+            self._logger = logger
+
+    def _bind_context(self, extra: Extras | None = None) -> dict[str, Any]:
+        context: dict[str, Any] = dict(extra) if extra else {}
+        cid = get_correlation_id()
+        if cid:
+            context["correlation_id"] = cid
+        user = get_user_context()
+        if user:
+            context["user_id"] = user.user_id
+            if user.tenant_id:
+                context["tenant_id"] = user.tenant_id
+        return context
+
+    def critical(
+        self, message: str, extra: Extras | None = None, exc: Exception | None = None
+    ) -> None:
+        """Log a critical message through structlog.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+            exc: Optional exception instance to attach traceback.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._logger.critical(message, exc_info=exc, **self._bind_context(extra))
+
+    def debug(self, message: str, extra: Extras | None = None) -> None:
+        """Log a debug message through structlog.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._logger.debug(message, **self._bind_context(extra))
+
+    def error(
+        self, message: str, extra: Extras | None = None, exc: Exception | None = None
+    ) -> None:
+        """Log an error message through structlog.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+            exc: Optional exception instance to attach traceback.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._logger.error(message, exc_info=exc, **self._bind_context(extra))
+
+    def info(self, message: str, extra: Extras | None = None) -> None:
+        """Log an informational message through structlog.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._logger.info(message, **self._bind_context(extra))
+
+    def warning(self, message: str, extra: Extras | None = None) -> None:
+        """Log a warning message through structlog.
+
+        Args:
+            message: Text message to log.
+            extra: Optional key-value dictionary of contextual metadata.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._logger.warning(message, **self._bind_context(extra))

hexastack_logging/adapters/logger/structured.py

@@ -0,0 +1,139 @@
+import logging
+from logging.handlers import QueueListener
+
+from hexastack_core.ports.logging import Extras, LoggingPort
+from hexastack_logging.infra.config import (
+    HexastackLoggingConfig,
+    configure_logging,
+)
+
+
+class StructuredLogger(LoggingPort):
+    """Production-grade structured logger implementing LoggingPort.
+
+    Notes/Architectural Intent:
+        Delegates to standard library logging.Logger configured with CorrelationIdFilter,
+        SanitizerFilter, rotating file handlers, and optional background QueueListener.
+    """
+
+    def __init__(
+        self,
+        name: str = "hexastack",
+        config: HexastackLoggingConfig | None = None,
+        logger: logging.Logger | None = None,
+        listener: QueueListener | None = None,
+    ) -> None:
+        """Initialize StructuredLogger with logger name, configuration, and optional listener.
+
+        Args:
+            name: Logger hierarchy name identifier.
+            config: Optional configuration model.
+            logger: Optional pre-configured Logger instance.
+            listener: Optional active QueueListener instance.
+        """
+        self._logger = logger or logging.getLogger(name)
+        if logger is None:
+            self._listener = configure_logging(
+                config=config, target_logger=self._logger
+            )
+        else:
+            self._listener = listener
+
+    def close(self) -> None:
+        """Stop and flush the background QueueListener if active.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        if self._listener is not None:
+            self._listener.stop()
+            self._listener = None
+
+    def critical(
+        self, message: str, extra: Extras | None = None, exc: Exception | None = None
+    ) -> None:
+        """Log a critical message with extra context.
+
+        Args:
+            message: The message string to log.
+            extra: Optional key-value dictionary of contextual metadata.
+            exc: Optional exception instance to attach traceback.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._logger.critical(message, exc_info=exc, extra=extra)
+
+    def debug(self, message: str, extra: Extras | None = None) -> None:
+        """Log a debug message with extra context.
+
+        Args:
+            message: The message string to log.
+            extra: Optional key-value dictionary of contextual metadata.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._logger.debug(message, extra=extra)
+
+    def error(
+        self, message: str, extra: Extras | None = None, exc: Exception | None = None
+    ) -> None:
+        """Log an error message with extra context.
+
+        Args:
+            message: The message string to log.
+            extra: Optional key-value dictionary of contextual metadata.
+            exc: Optional exception instance to attach traceback.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._logger.error(message, exc_info=exc, extra=extra)
+
+    def info(self, message: str, extra: Extras | None = None) -> None:
+        """Log an informational message with extra context.
+
+        Args:
+            message: The message string to log.
+            extra: Optional key-value dictionary of contextual metadata.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._logger.info(message, extra=extra)
+
+    @property
+    def listener(self) -> QueueListener | None:
+        """The active QueueListener instance if async queueing is enabled."""
+        return self._listener
+
+    def warning(self, message: str, extra: Extras | None = None) -> None:
+        """Log a warning message with extra context.
+
+        Args:
+            message: The message string to log.
+            extra: Optional key-value dictionary of contextual metadata.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        self._logger.warning(message, extra=extra)

hexastack_logging/infra/__init__.py

@@ -0,0 +1,31 @@
+from hexastack_logging.infra.config import (
+    AsyncQueueConfig,
+    FileLoggingConfig,
+    HexastackLoggingConfig,
+    SanitizerConfig,
+    configure_logging,
+    register_logging_config,
+)
+from hexastack_logging.infra.filters import (
+    CorrelationIdFilter,
+    SanitizerFilter,
+)
+from hexastack_logging.infra.formatters import (
+    ConsoleFormatter,
+    JsonFormatter,
+)
+from hexastack_logging.infra.sanitizer import Sanitizer
+
+__all__ = [
+    "AsyncQueueConfig",
+    "configure_logging",
+    "ConsoleFormatter",
+    "CorrelationIdFilter",
+    "FileLoggingConfig",
+    "HexastackLoggingConfig",
+    "JsonFormatter",
+    "register_logging_config",
+    "Sanitizer",
+    "SanitizerConfig",
+    "SanitizerFilter",
+]

hexastack_logging/infra/bootstrap.py

@@ -0,0 +1,55 @@
+from hexastack_core.infra.bootstrap import BootstrapContext
+from hexastack_core.infra.registries.config import ConfigRegistry
+from hexastack_core.ports.bootstrap import BootstrapperPort
+from hexastack_core.ports.logging import LoggingPort
+from hexastack_logging.adapters.logger.structured import StructuredLogger
+from hexastack_logging.infra.config import (
+    HexastackLoggingConfig,
+    register_logging_config,
+)
+
+
+class LoggingBootstrapper(BootstrapperPort):
+    """Bootstrap extension initializing logging configuration and LoggingPort adapter.
+
+    Notes/Architectural Intent:
+        Implements BootstrapperPort for hexastack-logging, registering 'logging'
+        config section in Phase 1 and binding StructuredLogger into rodi DI in Phase 2.
+    """
+
+    name: str = "logging"
+    order: int = 10
+
+    def configure(self, context: BootstrapContext) -> None:
+        """Phase 2: Configure root logging and register StructuredLogger in container.
+
+        Args:
+            context: BootstrapContext containing DI container and loaded config.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        if LoggingPort not in context.container:
+            cfg = context.get_config("logging", HexastackLoggingConfig)
+            logger = StructuredLogger(config=cfg)
+            context.container.add_instance(logger, declared_class=LoggingPort)
+            context.properties["logger"] = logger
+        else:
+            context.properties["logger"] = context.container.resolve(LoggingPort)
+
+    def register_config(self, registry: ConfigRegistry) -> None:
+        """Phase 1: Register logging configuration schema under 'logging'.
+
+        Args:
+            registry: Target ConfigRegistry instance.
+
+        Returns:
+            None.
+
+        Raises:
+            None.
+        """
+        register_logging_config(registry)