hexastack-logging 0.0.0__tar.gz

hexastack_logging-0.0.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.3
+Name: hexastack-logging
+Version: 0.0.0
+Summary: Add your description here
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Requires-Dist: hexastack-core
+Requires-Dist: loguru>=0.7.0 ; extra == 'all'
+Requires-Dist: rich>=13.0.0 ; extra == 'all'
+Requires-Dist: structlog>=24.0.0 ; extra == 'all'
+Requires-Dist: loguru>=0.7.0 ; extra == 'loguru'
+Requires-Dist: rich>=13.0.0 ; extra == 'rich'
+Requires-Dist: structlog>=24.0.0 ; extra == 'structlog'
+Requires-Python: >=3.13
+Provides-Extra: all
+Provides-Extra: loguru
+Provides-Extra: rich
+Provides-Extra: structlog
+Description-Content-Type: text/markdown
+
+# hexastack-logging
+
+> Structured logging, security sanitization, and adapter integrations (Loguru, Rich, Structlog) for Hexastack.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-logging` provides high-performance, structured telemetry across the entire Hexastack lifecycle:
+
+- **Multiple Backend Adapters**: Native implementations for `Loguru`, `Rich`, `Structlog`, and standard library structured logging.
+- **Security & PII Sanitization**: Automatic masking of sensitive fields (passwords, tokens, authorization headers, credit cards).
+- **Formatters**: JSON formatting for cloud aggregators (Datadog, CloudWatch) and colored console formatting for local development.
+- **Context & Correlation Integration**: Injects active `correlation_id` from async context into all log outputs.
+- **Log Filtering & Levels**: Fine-grained level filtering and module-based log routing.
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_logging/
+├── domain/          # LogRecord, LogLevel, Logging exceptions
+├── ports/           # LoggerPort, FormatterPort, FilterPort, SanitizerPort
+├── adapters/        # LoguruAdapter, RichAdapter, StructlogAdapter, StructuredLogger
+└── infra/           # LoggingBootstrapper (order=10), Formatters, Sanitizers, Config
+```
+
+### Key Exports
+
+| Category | Exports |
+|---|---|
+| **Adapters** | `StructuredLogger`, `LoguruAdapter`, `RichAdapter`, `StructlogAdapter` |
+| **Bootstrap** | `LoggingBootstrapper` (order=10), `HexastackLoggingConfig` |
+| **Formatters** | `JsonFormatter`, `ConsoleFormatter` |
+| **Sanitization** | `SanitizerFilter`, `mask_sensitive_data` |
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph SiblingConsumers ["Consumers of LoggerPort"]
+        CQRS["hexastack-cqrs (LoggingMiddleware)"]
+        FASTAPI["hexastack-fastapi (HttpLoggingMiddleware)"]
+        GRPC["hexastack-grpc (LoggingServerInterceptor)"]
+        GRAPHQL["hexastack-graphql (CorrelationExtension)"]
+        CORE_CTX["hexastack-core (get_correlation_id)"]
+    end
+
+    subgraph LoggingSubsystem ["hexastack-logging"]
+        BOOT["LoggingBootstrapper (order=10)"]
+        ADAPTERS["Adapters (Loguru / Rich / Structlog / StdLib)"]
+        SAN["PII Sanitizer & JSON Formatter"]
+    end
+
+    BOOT --> ADAPTERS
+    ADAPTERS --> SAN
+    ADAPTERS -. reads context .-> CORE_CTX
+
+    CQRS -. resolves from DI .-> ADAPTERS
+    FASTAPI -. resolves from DI .-> ADAPTERS
+    GRPC -. resolves from DI .-> ADAPTERS
+    GRAPHQL -. resolves from DI .-> ADAPTERS
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: Abstract `LoggerPort`, DI container, and async context tracking.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **Dependency Provider**: Binds `LoggerPort` into the DI container at `order=10` (before CQRS `order=20`), ensuring telemetry is available to all subsequent bootstrappers and middlewares.
+- **Correlation ID Synchronization**: Automatically reads and outputs `get_correlation_id()` stored in `hexastack_core.utils.context`.
+
+### Optional Integrations (Extras)
+- `[loguru]`: Enables `loguru>=0.7.0`.
+- `[rich]`: Enables `rich>=13.0.0` console formatting.
+- `[structlog]`: Enables `structlog>=24.0.0`.
+- `[all]`: Installs all optional logging backends.
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone standard library logging
+pip install hexastack-logging
+
+# With Loguru and Rich support
+pip install "hexastack-logging[loguru,rich]"
+
+# All logging backends
+pip install "hexastack-logging[all]"
+
+# Via umbrella package
+pip install hexastack
+```
+
+---
+
+## 5. Configuration Reference
+
+```toml
+[hexastack.logging]
+level = "INFO" # "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
+format = "json" # "json", "console"
+backend = "structlog" # "standard", "loguru", "rich", "structlog"
+sanitize_keys = ["password", "token", "secret", "authorization", "api_key"]
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_core.ports.logging import LoggerPort
+
+runtime = bootstrap(
+    config_overrides={
+        "logging": {
+            "level": "DEBUG",
+            "format": "console",
+        }
+    }
+)
+
+logger = runtime.container.get(LoggerPort)
+logger.info("Application initialized successfully", extra={"user_count": 42})
+```

hexastack_logging-0.0.0/README.md

@@ -0,0 +1,132 @@
+# hexastack-logging
+
+> Structured logging, security sanitization, and adapter integrations (Loguru, Rich, Structlog) for Hexastack.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-logging` provides high-performance, structured telemetry across the entire Hexastack lifecycle:
+
+- **Multiple Backend Adapters**: Native implementations for `Loguru`, `Rich`, `Structlog`, and standard library structured logging.
+- **Security & PII Sanitization**: Automatic masking of sensitive fields (passwords, tokens, authorization headers, credit cards).
+- **Formatters**: JSON formatting for cloud aggregators (Datadog, CloudWatch) and colored console formatting for local development.
+- **Context & Correlation Integration**: Injects active `correlation_id` from async context into all log outputs.
+- **Log Filtering & Levels**: Fine-grained level filtering and module-based log routing.
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_logging/
+├── domain/          # LogRecord, LogLevel, Logging exceptions
+├── ports/           # LoggerPort, FormatterPort, FilterPort, SanitizerPort
+├── adapters/        # LoguruAdapter, RichAdapter, StructlogAdapter, StructuredLogger
+└── infra/           # LoggingBootstrapper (order=10), Formatters, Sanitizers, Config
+```
+
+### Key Exports
+
+| Category | Exports |
+|---|---|
+| **Adapters** | `StructuredLogger`, `LoguruAdapter`, `RichAdapter`, `StructlogAdapter` |
+| **Bootstrap** | `LoggingBootstrapper` (order=10), `HexastackLoggingConfig` |
+| **Formatters** | `JsonFormatter`, `ConsoleFormatter` |
+| **Sanitization** | `SanitizerFilter`, `mask_sensitive_data` |
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph SiblingConsumers ["Consumers of LoggerPort"]
+        CQRS["hexastack-cqrs (LoggingMiddleware)"]
+        FASTAPI["hexastack-fastapi (HttpLoggingMiddleware)"]
+        GRPC["hexastack-grpc (LoggingServerInterceptor)"]
+        GRAPHQL["hexastack-graphql (CorrelationExtension)"]
+        CORE_CTX["hexastack-core (get_correlation_id)"]
+    end
+
+    subgraph LoggingSubsystem ["hexastack-logging"]
+        BOOT["LoggingBootstrapper (order=10)"]
+        ADAPTERS["Adapters (Loguru / Rich / Structlog / StdLib)"]
+        SAN["PII Sanitizer & JSON Formatter"]
+    end
+
+    BOOT --> ADAPTERS
+    ADAPTERS --> SAN
+    ADAPTERS -. reads context .-> CORE_CTX
+
+    CQRS -. resolves from DI .-> ADAPTERS
+    FASTAPI -. resolves from DI .-> ADAPTERS
+    GRPC -. resolves from DI .-> ADAPTERS
+    GRAPHQL -. resolves from DI .-> ADAPTERS
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: Abstract `LoggerPort`, DI container, and async context tracking.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **Dependency Provider**: Binds `LoggerPort` into the DI container at `order=10` (before CQRS `order=20`), ensuring telemetry is available to all subsequent bootstrappers and middlewares.
+- **Correlation ID Synchronization**: Automatically reads and outputs `get_correlation_id()` stored in `hexastack_core.utils.context`.
+
+### Optional Integrations (Extras)
+- `[loguru]`: Enables `loguru>=0.7.0`.
+- `[rich]`: Enables `rich>=13.0.0` console formatting.
+- `[structlog]`: Enables `structlog>=24.0.0`.
+- `[all]`: Installs all optional logging backends.
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone standard library logging
+pip install hexastack-logging
+
+# With Loguru and Rich support
+pip install "hexastack-logging[loguru,rich]"
+
+# All logging backends
+pip install "hexastack-logging[all]"
+
+# Via umbrella package
+pip install hexastack
+```
+
+---
+
+## 5. Configuration Reference
+
+```toml
+[hexastack.logging]
+level = "INFO" # "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
+format = "json" # "json", "console"
+backend = "structlog" # "standard", "loguru", "rich", "structlog"
+sanitize_keys = ["password", "token", "secret", "authorization", "api_key"]
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_core.ports.logging import LoggerPort
+
+runtime = bootstrap(
+    config_overrides={
+        "logging": {
+            "level": "DEBUG",
+            "format": "console",
+        }
+    }
+)
+
+logger = runtime.container.get(LoggerPort)
+logger.info("Application initialized successfully", extra={"user_count": 42})
+```

hexastack_logging-0.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "hexastack-logging"
+version = "0.0.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = ["hexastack-core"]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.optional-dependencies]
+loguru = ["loguru>=0.7.0"]
+rich = ["rich>=13.0.0"]
+structlog = ["structlog>=24.0.0"]
+all = [
+    "loguru>=0.7.0",
+    "rich>=13.0.0",
+    "structlog>=24.0.0",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+logging = "hexastack_logging.infra.bootstrap:LoggingBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_logging"]

hexastack_logging-0.0.0/pyproject.toml.orig

@@ -0,0 +1,35 @@
+[project]
+name = "hexastack-logging"
+version = "0.0.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+]
+
+[project.optional-dependencies]
+loguru = ["loguru>=0.7.0"]
+rich = ["rich>=13.0.0"]
+structlog = ["structlog>=24.0.0"]
+all = [
+    "loguru>=0.7.0",
+    "rich>=13.0.0",
+    "structlog>=24.0.0",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+logging = "hexastack_logging.infra.bootstrap:LoggingBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-core = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_logging"]

hexastack_logging-0.0.0/src/hexastack_logging/__init__.py

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

hexastack_logging-0.0.0/src/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-0.0.0/src/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-0.0.0/src/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-0.0.0/src/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)