provide-foundation 0.0.0.dev0__py3-none-any.whl

provide/foundation/logger/core.py

@@ -0,0 +1,239 @@
+#
+# core.py
+#
+"""
+Core FoundationLogger implementation.
+Contains the main logging class with all logging methods.
+"""
+
+import contextlib
+import threading
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+from provide.foundation.types import TRACE_LEVEL_NAME
+
+if TYPE_CHECKING:
+    from provide.foundation.logger.config import TelemetryConfig
+    from provide.foundation.logger.setup.emoji_resolver import ResolvedEmojiConfig
+
+_LAZY_SETUP_LOCK = threading.Lock()
+_LAZY_SETUP_STATE: dict[str, Any] = {"done": False, "error": None, "in_progress": False}
+
+
+class FoundationLogger:
+    """A `structlog`-based logger providing a standardized logging interface."""
+
+    def __init__(self) -> None:
+        self._internal_logger = structlog.get_logger().bind(
+            logger_name=f"{self.__class__.__module__}.{self.__class__.__name__}"
+        )
+        self._is_configured_by_setup: bool = False
+        self._active_config: TelemetryConfig | None = None
+        self._active_resolved_emoji_config: ResolvedEmojiConfig | None = None
+
+    def _check_structlog_already_disabled(self) -> bool:
+        try:
+            current_config = structlog.get_config()
+            if current_config and isinstance(
+                current_config.get("logger_factory"), structlog.ReturnLoggerFactory
+            ):
+                with _LAZY_SETUP_LOCK:
+                    _LAZY_SETUP_STATE["done"] = True
+                return True
+        except Exception:
+            pass
+        return False
+
+    def _ensure_configured(self) -> None:
+        """
+        Ensures the logger is configured, performing lazy setup if necessary.
+        This method is thread-safe and handles setup failures gracefully.
+        """
+        # Fast path for already configured loggers.
+        if self._is_configured_by_setup or (
+            _LAZY_SETUP_STATE["done"] and not _LAZY_SETUP_STATE["error"]
+        ):
+            return
+
+        # If setup is in progress by another thread, or failed previously, use fallback.
+        if _LAZY_SETUP_STATE["in_progress"] or _LAZY_SETUP_STATE["error"]:
+            self._setup_emergency_fallback()
+            return
+
+        # If structlog is already configured to be a no-op, we're done.
+        if self._check_structlog_already_disabled():
+            return
+
+        # Acquire lock to perform setup.
+        with _LAZY_SETUP_LOCK:
+            # Double-check state after acquiring lock, as another thread might have finished.
+            if self._is_configured_by_setup or (
+                _LAZY_SETUP_STATE["done"] and not _LAZY_SETUP_STATE["error"]
+            ):
+                return
+
+            # If error was set while waiting for lock, use fallback.
+            if _LAZY_SETUP_STATE["error"]:
+                self._setup_emergency_fallback()
+                return
+
+            # If still needs setup, perform lazy setup.
+            if not _LAZY_SETUP_STATE["done"]:
+                self._perform_lazy_setup()
+
+    def _perform_lazy_setup(self) -> None:
+        """Perform the actual lazy setup of the logging system."""
+        from provide.foundation.logger.setup.coordinator import internal_setup
+
+        try:
+            _LAZY_SETUP_STATE["in_progress"] = True
+            internal_setup(is_explicit_call=False)
+        except Exception as e:
+            _LAZY_SETUP_STATE["error"] = e
+            self._setup_emergency_fallback()
+        finally:
+            _LAZY_SETUP_STATE["in_progress"] = False
+
+    def _setup_emergency_fallback(self) -> None:
+        """Set up emergency fallback logging when normal setup fails."""
+        from provide.foundation.utils.streams import get_safe_stderr
+
+        with contextlib.suppress(Exception):
+            structlog.configure(
+                processors=[structlog.dev.ConsoleRenderer()],
+                logger_factory=structlog.PrintLoggerFactory(file=get_safe_stderr()),
+                wrapper_class=structlog.BoundLogger,
+                cache_logger_on_first_use=True,
+            )
+
+    def get_logger(self, name: str | None = None) -> Any:
+        self._ensure_configured()
+        effective_name = name if name is not None else "pyvider.default"
+        return structlog.get_logger().bind(logger_name=effective_name)
+
+    def _log_with_level(
+        self, level_method_name: str, event: str, **kwargs: Any
+    ) -> None:
+        self._ensure_configured()
+
+        # Use the logger name from kwargs if provided, otherwise default
+        logger_name = kwargs.pop("_foundation_logger_name", "pyvider.dynamic_call")
+        log = self.get_logger(logger_name)
+
+        # Handle trace level specially since PrintLogger doesn't have trace method
+        if level_method_name == "trace":
+            kwargs["_foundation_level_hint"] = TRACE_LEVEL_NAME.lower()
+            log.msg(event, **kwargs)
+        else:
+            getattr(log, level_method_name)(event, **kwargs)
+
+    def _format_message_with_args(self, event: str | Any, args: tuple[Any, ...]) -> str:
+        """Format a log message with positional arguments using % formatting."""
+        if args:
+            try:
+                return str(event) % args
+            except (TypeError, ValueError):
+                return f"{event} {args}"
+        return str(event)
+
+    def trace(
+        self,
+        event: str,
+        *args: Any,
+        _foundation_logger_name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Log trace-level event for detailed debugging."""
+        formatted_event = self._format_message_with_args(event, args)
+        if _foundation_logger_name is not None:
+            kwargs["_foundation_logger_name"] = _foundation_logger_name
+        self._log_with_level(TRACE_LEVEL_NAME.lower(), formatted_event, **kwargs)
+
+    def debug(self, event: str, *args: Any, **kwargs: Any) -> None:
+        """Log debug-level event."""
+        formatted_event = self._format_message_with_args(event, args)
+        self._log_with_level("debug", formatted_event, **kwargs)
+
+    def info(self, event: str, *args: Any, **kwargs: Any) -> None:
+        """Log info-level event."""
+        formatted_event = self._format_message_with_args(event, args)
+        self._log_with_level("info", formatted_event, **kwargs)
+
+    def warning(self, event: str, *args: Any, **kwargs: Any) -> None:
+        """Log warning-level event."""
+        formatted_event = self._format_message_with_args(event, args)
+        self._log_with_level("warning", formatted_event, **kwargs)
+
+    warn = warning  # Alias for compatibility
+
+    def error(self, event: str, *args: Any, **kwargs: Any) -> None:
+        """Log error-level event."""
+        formatted_event = self._format_message_with_args(event, args)
+        self._log_with_level("error", formatted_event, **kwargs)
+
+    def exception(self, event: str, *args: Any, **kwargs: Any) -> None:
+        """Log error-level event with exception traceback."""
+        formatted_event = self._format_message_with_args(event, args)
+        kwargs["exc_info"] = True
+        self._log_with_level("error", formatted_event, **kwargs)
+
+    def critical(self, event: str, *args: Any, **kwargs: Any) -> None:
+        """Log critical-level event."""
+        formatted_event = self._format_message_with_args(event, args)
+        self._log_with_level("critical", formatted_event, **kwargs)
+
+    def bind(self, **kwargs: Any) -> Any:
+        """
+        Create a new logger with additional context bound to it.
+
+        Args:
+            **kwargs: Key-value pairs to bind to the logger
+
+        Returns:
+            A new logger instance with the bound context
+        """
+        self._ensure_configured()
+        log = self.get_logger("pyvider.context_bind")
+        return log.bind(**kwargs)
+
+    def unbind(self, *keys: str) -> Any:
+        """
+        Create a new logger with specified keys removed from context.
+
+        Args:
+            *keys: Context keys to remove
+
+        Returns:
+            A new logger instance without the specified keys
+        """
+        self._ensure_configured()
+        log = self.get_logger("pyvider.context_unbind")
+        return log.unbind(*keys)
+
+    def try_unbind(self, *keys: str) -> Any:
+        """
+        Create a new logger with specified keys removed from context.
+        Does not raise an error if keys don't exist.
+
+        Args:
+            *keys: Context keys to remove
+
+        Returns:
+            A new logger instance without the specified keys
+        """
+        self._ensure_configured()
+        log = self.get_logger("pyvider.context_try_unbind")
+        return log.try_unbind(*keys)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Override setattr to prevent accidental modification of logger state."""
+        if hasattr(self, name) and name.startswith("_"):
+            super().__setattr__(name, value)
+        else:
+            super().__setattr__(name, value)
+
+
+# Global logger instance
+logger: FoundationLogger = FoundationLogger()

provide/foundation/logger/custom_processors.py

@@ -0,0 +1,172 @@
+#
+# custom_processors.py
+#
+"""
+Foundation Telemetry Custom Structlog Processors.
+Includes processors for log level normalization, level-based filtering,
+and logger name emoji prefixes. The semantic field emoji prefix processor
+is now created as a closure in config.py.
+"""
+
+import logging as stdlib_logging
+from typing import TYPE_CHECKING, Any, Protocol, cast
+
+import structlog
+
+from provide.foundation.types import TRACE_LEVEL_NAME, TRACE_LEVEL_NUM, LogLevelStr
+
+if TYPE_CHECKING:
+    pass
+
+_NUMERIC_TO_LEVEL_NAME_CUSTOM: dict[int, str] = {
+    stdlib_logging.CRITICAL: "critical",
+    stdlib_logging.ERROR: "error",
+    stdlib_logging.WARNING: "warning",
+    stdlib_logging.INFO: "info",
+    stdlib_logging.DEBUG: "debug",
+    TRACE_LEVEL_NUM: TRACE_LEVEL_NAME.lower(),
+}
+
+
+class StructlogProcessor(Protocol):
+    def __call__(
+        self, logger: Any, method_name: str, event_dict: structlog.types.EventDict
+    ) -> structlog.types.EventDict: ...  # pragma: no cover
+
+
+def add_log_level_custom(
+    _logger: Any, method_name: str, event_dict: structlog.types.EventDict
+) -> structlog.types.EventDict:
+    level_hint: str | None = event_dict.pop("_foundation_level_hint", None)
+    if level_hint is not None:
+        event_dict["level"] = level_hint.lower()
+    elif "level" not in event_dict:
+        match method_name:
+            case "exception":
+                event_dict["level"] = "error"
+            case "warn":
+                event_dict["level"] = "warning"
+            case "msg":
+                event_dict["level"] = "info"
+            case _:
+                event_dict["level"] = method_name.lower()
+    return event_dict
+
+
+class _LevelFilter:
+    def __init__(
+        self,
+        default_level_str: LogLevelStr,
+        module_levels: dict[str, LogLevelStr],
+        level_to_numeric_map: dict[LogLevelStr, int],
+    ) -> None:
+        self.default_numeric_level: int = level_to_numeric_map[default_level_str]
+        self.module_numeric_levels: dict[str, int] = {
+            module: level_to_numeric_map[level_str]
+            for module, level_str in module_levels.items()
+        }
+        self.level_to_numeric_map = level_to_numeric_map
+        self.sorted_module_paths: list[str] = sorted(
+            self.module_numeric_levels.keys(), key=len, reverse=True
+        )
+
+    def __call__(
+        self, _logger: Any, _method_name: str, event_dict: structlog.types.EventDict
+    ) -> structlog.types.EventDict:
+        logger_name: str = event_dict.get("logger_name", "unnamed_filter_target")
+        event_level_str_from_dict = str(event_dict.get("level", "info")).upper()
+        event_level_text: LogLevelStr = cast(LogLevelStr, event_level_str_from_dict)
+        event_num_level: int = self.level_to_numeric_map.get(
+            event_level_text, self.level_to_numeric_map["INFO"]
+        )
+        threshold_num_level: int = self.default_numeric_level
+        for path_prefix in self.sorted_module_paths:
+            if logger_name.startswith(path_prefix):
+                threshold_num_level = self.module_numeric_levels[path_prefix]
+                break
+        if event_num_level < threshold_num_level:
+            raise structlog.DropEvent
+        return event_dict
+
+
+def filter_by_level_custom(
+    default_level_str: LogLevelStr,
+    module_levels: dict[str, LogLevelStr],
+    level_to_numeric_map: dict[LogLevelStr, int],
+) -> _LevelFilter:
+    return _LevelFilter(default_level_str, module_levels, level_to_numeric_map)
+
+
+_LOGGER_NAME_EMOJI_PREFIXES: dict[str, str] = {
+    "provide.foundation.core.test": "⚙️",
+    "provide.foundation.core_setup": "🛠️",
+    "provide.foundation.emoji_matrix_display": "💡",
+    "provide.foundation": "⚙️",
+    "provide.foundation.logger": "📝",
+    "provide.foundation.logger.config": "🔩",
+    "pyvider.dynamic_call_trace": "👣",
+    "pyvider.dynamic_call": "🗣️",
+    "pyvider.default": "📦",
+    "formatter.test": "🎨",
+    "service.alpha": "🇦",
+    "service.beta": "🇧",
+    "service.beta.child": "👶",
+    "service.gamma.trace_enabled": "🇬",
+    "service.delta": "🇩",
+    "das.test": "🃏",
+    "json.exc.test": "💥",
+    "service.name.test": "📛",
+    "simple": "📄",
+    "test.basic": "🧪",
+    "unknown": "❓",
+    "test": "🧪",
+    "default": "🔹",
+    "emoji.test": "🎭",
+}
+_SORTED_LOGGER_NAME_EMOJI_KEYWORDS: list[str] = sorted(
+    _LOGGER_NAME_EMOJI_PREFIXES.keys(), key=len, reverse=True
+)
+_EMOJI_LOOKUP_CACHE: dict[str, str] = {}
+_EMOJI_CACHE_SIZE_LIMIT: int = 1000
+
+
+def _compute_emoji_for_logger_name(logger_name: str) -> str:
+    for keyword in _SORTED_LOGGER_NAME_EMOJI_KEYWORDS:
+        if keyword == "default":
+            continue
+        if logger_name.startswith(keyword):
+            return _LOGGER_NAME_EMOJI_PREFIXES[keyword]
+    return _LOGGER_NAME_EMOJI_PREFIXES.get("default", "🔹")
+
+
+def add_logger_name_emoji_prefix(
+    _logger: Any, _method_name: str, event_dict: structlog.types.EventDict
+) -> structlog.types.EventDict:
+    logger_name = event_dict.get("logger_name", "default")
+    if logger_name in _EMOJI_LOOKUP_CACHE:
+        chosen_emoji = _EMOJI_LOOKUP_CACHE[logger_name]
+    else:
+        chosen_emoji = _compute_emoji_for_logger_name(logger_name)
+        if len(_EMOJI_LOOKUP_CACHE) < _EMOJI_CACHE_SIZE_LIMIT:
+            _EMOJI_LOOKUP_CACHE[logger_name] = chosen_emoji
+    event_msg = event_dict.get("event")
+    if event_msg is not None:
+        event_dict["event"] = f"{chosen_emoji} {event_msg}"
+    elif chosen_emoji:
+        event_dict["event"] = chosen_emoji
+    return event_dict
+
+
+def get_emoji_cache_stats() -> dict[str, Any]:  # pragma: no cover
+    return {
+        "cache_size": len(_EMOJI_LOOKUP_CACHE),
+        "cache_limit": _EMOJI_CACHE_SIZE_LIMIT,
+        "cache_utilization": len(_EMOJI_LOOKUP_CACHE) / _EMOJI_CACHE_SIZE_LIMIT * 100
+        if _EMOJI_CACHE_SIZE_LIMIT > 0
+        else 0,
+    }
+
+
+def clear_emoji_cache() -> None:  # pragma: no cover
+    global _EMOJI_LOOKUP_CACHE
+    _EMOJI_LOOKUP_CACHE.clear()

provide/foundation/logger/emoji/__init__.py

@@ -0,0 +1,44 @@
+"""
+Emoji configuration and mapping for Foundation logger.
+
+This module provides emoji sets and mappings for visual enhancement
+of structured logs in various domains (HTTP, LLM, Database, etc.).
+"""
+
+from provide.foundation.logger.emoji.matrix import (
+    PRIMARY_EMOJI,
+    SECONDARY_EMOJI,
+    TERTIARY_EMOJI,
+    show_emoji_matrix,
+)
+from provide.foundation.logger.emoji.sets import (
+    DATABASE_EMOJI_SET,
+    HTTP_EMOJI_SET,
+    LEGACY_DAS_EMOJI_SETS,
+    LEGACY_DAS_FIELD_DEFINITIONS,
+    LLM_EMOJI_SET,
+)
+from provide.foundation.logger.emoji.types import (
+    EmojiSet,
+    EmojiSetConfig,
+    FieldToEmojiMapping,
+)
+
+__all__ = [
+    # Core emoji dictionaries
+    "PRIMARY_EMOJI",
+    "SECONDARY_EMOJI",
+    "TERTIARY_EMOJI",
+    # Emoji sets
+    "DATABASE_EMOJI_SET",
+    "HTTP_EMOJI_SET",
+    "LLM_EMOJI_SET",
+    "LEGACY_DAS_EMOJI_SETS",
+    "LEGACY_DAS_FIELD_DEFINITIONS",
+    # Types
+    "EmojiSet",
+    "EmojiSetConfig",
+    "FieldToEmojiMapping",
+    # Utilities
+    "show_emoji_matrix",
+]

provide/foundation/logger/emoji/matrix.py

@@ -0,0 +1,209 @@
+#
+# emoji_matrix.py
+#
+"""
+Foundation Telemetry Emoji Matrix and Display Utilities.
+Defines the core DAS emoji mappings and provides utilities to display
+active emoji configurations (DAS or emoji set-based).
+"""
+
+from provide.foundation.logger import (
+    base as foundation_logger_base,  # For accessing the global logger instance
+)
+
+# Import types for resolved config structure
+from provide.foundation.logger.emoji.types import EmojiSet, FieldToEmojiMapping
+
+PRIMARY_EMOJI: dict[str, str] = {
+    "system": "⚙️",
+    "server": "🛎️",
+    "client": "🙋",
+    "network": "🌐",
+    "security": "🔐",
+    "config": "🔩",
+    "database": "🗄️",
+    "cache": "💾",
+    "task": "🔄",
+    "plugin": "🔌",
+    "telemetry": "🛰️",
+    "di": "💉",
+    "protocol": "📡",
+    "file": "📄",
+    "user": "👤",
+    "test": "🧪",
+    "utils": "🧰",
+    "core": "🌟",
+    "auth": "🔑",
+    "entity": "🦎",
+    "report": "📈",
+    "payment": "💳",
+    "default": "❓",
+}
+
+SECONDARY_EMOJI: dict[str, str] = {
+    "init": "🌱",
+    "start": "🚀",
+    "stop": "🛑",
+    "connect": "🔗",
+    "disconnect": "💔",
+    "listen": "👂",
+    "send": "📤",
+    "receive": "📥",
+    "read": "📖",
+    "write": "📝",
+    "process": "⚙️",
+    "validate": "🛡️",
+    "execute": "▶️",
+    "query": "🔍",
+    "update": "🔄",
+    "delete": "🗑️",
+    "login": "➡️",
+    "logout": "⬅️",
+    "auth": "🔑",
+    "error": "🔥",
+    "encrypt": "🛡️",
+    "decrypt": "🔓",
+    "parse": "🧩",
+    "transmit": "📡",
+    "build": "🏗️",
+    "schedule": "📅",
+    "emit": "📢",
+    "load": "💡",
+    "observe": "🧐",
+    "request": "🗣️",
+    "interrupt": "🚦",
+    "register": "⚙️",
+    "default": "❓",
+}
+
+TERTIARY_EMOJI: dict[str, str] = {
+    "success": "✅",
+    "failure": "❌",
+    "error": "🔥",
+    "warning": "⚠️",
+    "info": "ℹ️",
+    "debug": "🐞",
+    "trace": "👣",
+    "attempt": "⏳",
+    "retry": "🔁",
+    "skip": "⏭️",
+    "complete": "🏁",
+    "timeout": "⏱️",
+    "notfound": "❓",
+    "unauthorized": "🚫",
+    "invalid": "💢",
+    "cached": "🎯",
+    "ongoing": "🏃",
+    "idle": "💤",
+    "ready": "👍",
+    "default": "➡️",
+}
+
+
+def _format_emoji_set_for_display(emoji_set: EmojiSet) -> list[str]:
+    lines = [
+        f"  Emoji Set: '{emoji_set.name}' (Default Key: '{emoji_set.default_emoji_key}')"
+    ]
+    for key, emoji in sorted(emoji_set.emojis.items()):
+        lines.append(f"    {emoji}  -> {key.capitalize()}")
+    return lines
+
+
+def _format_field_definition_for_display(field_def: FieldToEmojiMapping) -> str:
+    parts = [f"  Log Key: '{field_def.log_key}'"]
+    if field_def.description:
+        parts.append(f"    Desc: {field_def.description}")
+    if field_def.value_type:
+        parts.append(f"    Type: {field_def.value_type}")
+    if field_def.emoji_set_name:
+        parts.append(f"    Emoji Set: '{field_def.emoji_set_name}'")
+        if field_def.default_emoji_override_key:
+            parts.append(
+                f"    Default Emoji Key (Override): '{field_def.default_emoji_override_key}'"
+            )
+    return "\n".join(parts)
+
+
+def show_emoji_matrix() -> None:  # pragma: no cover
+    """
+    Prints the active Foundation emoji logging contract to the console.
+    If emoji sets are active, it displays their configuration.
+    Otherwise, it displays the core DAS emoji mappings.
+    Activated by `PROVIDE_SHOW_EMOJI_MATRIX` environment variable.
+    """
+    # Ensure the logger is configured to access the config
+    foundation_logger_base.logger._ensure_configured()
+
+    # Get the show_emoji_matrix flag from the logging config
+    telemetry_config = getattr(foundation_logger_base.logger, "_active_config", None)
+    if not telemetry_config or not telemetry_config.logging.show_emoji_matrix:
+        return
+
+    matrix_logger = foundation_logger_base.logger.get_logger(
+        "provide.foundation.emoji_matrix_display"
+    )
+
+    # Access the resolved emoji config from the global logger instance
+    # This assumes the logger has been configured (explicitly or lazily)
+    foundation_logger_base.logger._ensure_configured()  # Ensure config is loaded
+    resolved_config_tuple = getattr(
+        foundation_logger_base.logger, "_active_resolved_emoji_config", None
+    )
+
+    lines: list[str] = []
+
+    if resolved_config_tuple:
+        resolved_field_definitions, resolved_emoji_sets_lookup = resolved_config_tuple
+
+        if resolved_field_definitions:  # New emoji sets are active
+            lines.append("Foundation Telemetry: Active Emoji Set Contract")
+            lines.append("=" * 70)
+            lines.append(
+                "Active Field-to-Emoji Mappings (Order determines prefix sequence):"
+            )
+            if not resolved_field_definitions:
+                lines.append("  (No field-to-emoji mappings are active)")
+            for i, field_def in enumerate(resolved_field_definitions):
+                lines.append(f"\nField {i + 1}:")
+                lines.append(_format_field_definition_for_display(field_def))
+
+            lines.append("\n" + "=" * 70)
+            lines.append(
+                "Available Emoji Sets (Referenced by Field-to-Emoji Mappings):"
+            )
+            if not resolved_emoji_sets_lookup:
+                lines.append("  (No emoji sets are defined/active)")
+            for set_name in sorted(resolved_emoji_sets_lookup.keys()):
+                emoji_set = resolved_emoji_sets_lookup[set_name]
+                lines.extend(_format_emoji_set_for_display(emoji_set))
+                lines.append("")  # Spacer
+
+        else:  # No custom fields resolved, means core DAS is active
+            lines.append("Foundation Telemetry: Core DAS Emoji Contract")
+            lines.append("=" * 70)
+            lines.append("Primary Emojis ('domain' key):")
+            lines.extend(
+                f"  {e}  -> {k.capitalize()}" for k, e in PRIMARY_EMOJI.items()
+            )
+            lines.append("\nSecondary Emojis ('action' key):")
+            lines.extend(
+                f"  {e}  -> {k.capitalize()}" for k, e in SECONDARY_EMOJI.items()
+            )
+            lines.append("\nTertiary Emojis ('status' key):")
+            lines.extend(
+                f"  {e}  -> {k.capitalize()}" for k, e in TERTIARY_EMOJI.items()
+            )
+    else:
+        lines.append(
+            "Foundation Telemetry: Emoji configuration not yet resolved or available."
+        )
+
+    if lines:
+        matrix_logger.info("\n".join(lines))
+    else:  # Should not happen if _ensure_configured works
+        matrix_logger.warning(
+            "Could not determine active emoji configuration to display."
+        )
+
+
+# 💡🧱