alt-python-logger 1.0.0__py3-none-any.whl

alt_python_logger-1.0.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: alt-python-logger
+Version: 1.0.0
+Summary: Spring-inspired config-driven logger for Python
+Requires-Python: >=3.12
+Requires-Dist: alt-python-common
+Requires-Dist: alt-python-config

alt_python_logger-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+logger/__init__.py,sha256=decdLYHfkgQ2Se_VcKEIWJgnZ0G2bvZea0eic7I445g,1917
+logger/caching_console.py,sha256=AcZwrwuugO3ievCYNdZVfatmmjJZUxkSe1gEdqG7EvA,948
+logger/configurable_logger.py,sha256=a3Xvga7szv1R_hkMAhHew5bmgPtiUz1M1Y2BoV3PHXw,4190
+logger/console_logger.py,sha256=PEUGpL3OuXm7Z6tRtZlEsaYRYpnFRCDT11SWEjVohQM,3129
+logger/delegating_logger.py,sha256=IH62HpazfBb9Q2wOoushhARNFERCKb0ouA6zdnYkxa4,2218
+logger/json_formatter.py,sha256=BD6yIbVcasoZbaavDn6BwxK9FZUFcagat1lrU6LkgWg,1018
+logger/logger.py,sha256=oZ_k-t1PWxA5e8mTApD0lr6INEkRSHY_fXujkNvbCs0,1664
+logger/logger_category_cache.py,sha256=Zy5EhiaF6KuHDf88Nv2vSrqZeJMk55n0n9Y5ydr32Tg,618
+logger/logger_factory.py,sha256=R8USeMqXAOmChBiSh51xbKIoDgMXFoLeM1Igqkk3q0c,3808
+logger/logger_level.py,sha256=tpT9uiPP41gJukMUGT2IzqwXV9Exqh6yr6xg-STDBIc,2098
+logger/multi_logger.py,sha256=MagghSGdn9IuXQrqhS5dZALUNOeiGQtMWKpya5fTiAk,1892
+logger/plain_text_formatter.py,sha256=1jYqOdnRYgobNYN0yQ3YEc8UPTp1wpHvVCaYT2vNiFo,722
+alt_python_logger-1.0.0.dist-info/METADATA,sha256=BC9fe02M5AkzAJvMzaZbFmr8QITSd1nCV22O0wbn0wo,208
+alt_python_logger-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+alt_python_logger-1.0.0.dist-info/RECORD,,

alt_python_logger-1.0.0.dist-info/WHEEL

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

logger/__init__.py

@@ -0,0 +1,60 @@
+"""
+logger — Spring-inspired config-driven logger for Python.
+
+Quick start::
+
+    from logger import logger_factory
+
+    log = logger_factory.get_logger("com.example.MyService")
+    log.info("Application started")
+    log.debug("Debug detail")  # suppressed unless logging.level.com.example = debug
+
+    # Or with ConfigFactory-backed config for full Spring-style setup:
+    from config import ConfigFactory
+    from logger import LoggerFactory
+
+    factory = LoggerFactory(config=ConfigFactory.get_config())
+    log = factory.get_logger("com.example.MyService")
+
+Level hierarchy (config keys):
+  logging.level./             → root level (default: info)
+  logging.level.com           → level for all 'com.*' loggers
+  logging.level.com.example   → level for 'com.example.*' loggers
+
+Log format (config key):
+  logging.format=text         → PlainTextFormatter
+  logging.format=json         → JSONFormatter (default)
+"""
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+from logger.logger_level import LoggerLevel
+from logger.logger import Logger
+from logger.console_logger import ConsoleLogger
+from logger.delegating_logger import DelegatingLogger
+from logger.configurable_logger import ConfigurableLogger
+from logger.logger_category_cache import LoggerCategoryCache
+from logger.logger_factory import LoggerFactory
+from logger.json_formatter import JSONFormatter
+from logger.plain_text_formatter import PlainTextFormatter
+from logger.caching_console import CachingConsole
+from logger.multi_logger import MultiLogger
+
+# Module-level singleton — zero setup required.
+logger_factory = LoggerFactory()
+
+__all__ = [
+    "LoggerLevel",
+    "Logger",
+    "ConsoleLogger",
+    "DelegatingLogger",
+    "ConfigurableLogger",
+    "LoggerCategoryCache",
+    "LoggerFactory",
+    "JSONFormatter",
+    "PlainTextFormatter",
+    "CachingConsole",
+    "MultiLogger",
+    "logger_factory",
+]

logger/caching_console.py

@@ -0,0 +1,35 @@
+"""
+logger.caching_console — In-memory log capture for tests.
+
+Replaces the stdlib logger with a list accumulator so test code can
+assert on what was logged without depending on stdout.
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+from typing import Any
+
+
+class CachingConsole:
+    """
+    In-memory log store.  Passed to ConsoleLogger in place of a stdlib logger.
+
+    Exposes .messages for inspection in tests.
+
+    Mirrors the JS CachingConsole class.
+    """
+
+    def __init__(self) -> None:
+        self.messages: list[tuple[int, str]] = []
+
+    def isEnabledFor(self, level: int) -> bool:  # noqa: N802 — matches stdlib Logger API
+        return True
+
+    def log(self, level: int, message: str, *args: Any, **kwargs: Any) -> None:  # type: ignore[override]
+        self.messages.append((level, message))
+
+    def clear(self) -> None:
+        self.messages.clear()

logger/configurable_logger.py

@@ -0,0 +1,118 @@
+"""
+logger.configurable_logger — Logger that reads its level from config.
+
+Config path convention (dot-separated, Spring-aligned):
+  logging.level./     → root logger level  (equivalent to JS 'logging.level./')
+  logging.level.com.example     → level for 'com.example' category prefix
+  logging.level.com.example.MyService → level for exact category
+
+The lookup walks the category's dot-separated segments, taking the most-specific
+level found.  Results are cached in LoggerCategoryCache.
+
+Key design difference from JS:
+  JS uses slash-separated category names (com/example/MyService) and a path-style
+  config key (logging.level./com/example).
+  Python uses dot-separated names (com.example.MyService) and config key
+  logging.level.com.example.MyService.
+
+  Root level is stored at config key: logging.level./  (slash = root marker,
+  same as JS convention, kept for config-file compatibility).
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+from typing import Any
+
+from logger.delegating_logger import DelegatingLogger
+from logger.logger import Logger
+from logger.logger_category_cache import LoggerCategoryCache
+from logger.logger_level import LoggerLevel
+
+
+class ConfigurableLogger(DelegatingLogger):
+    """
+    Logger whose level is driven by config.
+
+    Mirrors the JS ConfigurableLogger class.
+    """
+
+    DEFAULT_CONFIG_PATH = "logging.level"
+
+    def __init__(
+        self,
+        config: Any,
+        provider: Logger,
+        category: str | None = None,
+        config_path: str | None = None,
+        cache: LoggerCategoryCache | None = None,
+    ) -> None:
+        super().__init__(provider)
+        if config is None:
+            raise ValueError("config is required")
+        if cache is None:
+            raise ValueError("cache is required")
+        self.config = config
+        self.category = category or Logger.DEFAULT_CATEGORY
+        self.provider.category = self.category
+        self.config_path = config_path or self.DEFAULT_CONFIG_PATH
+        self.cache = cache
+
+        # Apply level from config immediately
+        level = self.get_logger_level(
+            self.category, self.config_path, self.config, self.cache
+        )
+        self.provider.set_level(level)
+
+    @staticmethod
+    def get_logger_level(
+        category: str,
+        config_path: str,
+        config: Any,
+        cache: LoggerCategoryCache,
+    ) -> str:
+        """
+        Walk the category's dot-segments looking for the most-specific level in config.
+
+        Config key structure:
+          {config_path}./            → root level  (e.g. logging.level./)
+          {config_path}.com          → level for top-level 'com' prefix
+          {config_path}.com.example  → level for 'com.example' prefix
+
+        The root slash marker keeps parity with the JS config file convention.
+        """
+        path = config_path or ConfigurableLogger.DEFAULT_CONFIG_PATH
+        level = LoggerLevel.INFO
+
+        # Check root level: e.g. logging.level./
+        root_key = f"{path}./"
+        cached = cache.get(root_key)
+        if cached:
+            level = cached
+        elif config.has(root_key):
+            val = config.get(root_key)
+            if isinstance(val, str) and val in LoggerLevel.ENUMS:
+                level = val
+                cache.put(root_key, level)
+
+        # Walk category segments
+        segments = (category or "").split(".")
+        path_step = path
+        for i, seg in enumerate(segments):
+            if not seg:
+                continue
+            path_step = f"{path_step}.{seg}" if i > 0 or path_step == path else f"{path}.{seg}"
+            cached = cache.get(path_step)
+            if cached:
+                level = cached
+            elif config.has(path_step):
+                val = config.get(path_step)
+                # Only apply string values — nested dicts mean there are more-specific
+                # level entries under this prefix; the loop will eventually reach them.
+                if isinstance(val, str) and val in LoggerLevel.ENUMS:
+                    level = val
+                    cache.put(path_step, level)
+
+        return level

logger/console_logger.py

@@ -0,0 +1,87 @@
+"""
+logger.console_logger — Logger that writes formatted records to stdout.
+
+The formatter (JSONFormatter or PlainTextFormatter) produces the final string.
+Output goes to sys.stdout so all levels appear on stdout — error and fatal
+included. Callers that want stderr routing can pass a custom sink.
+
+The optional stdlib_logger parameter accepts a CachingConsole (or any object
+with isEnabledFor(int) and log(int, str)) for use in tests.
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+from logger.logger import Logger
+from logger.logger_level import LoggerLevel
+from logger.json_formatter import JSONFormatter
+
+
+class ConsoleLogger(Logger):
+    """
+    Logger implementation that emits formatted records to stdout.
+
+    Mirrors the JS ConsoleLogger class.
+    """
+
+    def __init__(
+        self,
+        category: str | None = None,
+        level: str | None = None,
+        formatter: Any = None,
+        stdlib_logger: Any = None,
+    ) -> None:
+        super().__init__(category, level)
+        self.formatter = formatter or JSONFormatter()
+        # stdlib_logger is kept for test injection (CachingConsole).
+        # When None we write directly to sys.stdout — no stdlib handler chain.
+        self._sink = stdlib_logger  # None means use sys.stdout
+
+    # ------------------------------------------------------------------
+    # Emit
+    # ------------------------------------------------------------------
+
+    def _emit(self, level_name: str, message: str, meta: Any = None) -> None:
+        formatted = self.formatter.format(
+            datetime.now(timezone.utc), self.category, level_name, message, meta
+        )
+        if self._sink is not None:
+            stdlib_level = LoggerLevel.STDLIB[level_name]
+            if self._sink.isEnabledFor(stdlib_level):
+                self._sink.log(stdlib_level, formatted)
+        else:
+            print(formatted, file=sys.stdout)
+
+    def log(self, level: str, message: str, meta: Any = None) -> None:
+        if self.is_level_enabled(level):
+            self._emit(level, message, meta)
+
+    def debug(self, message: str, meta: Any = None) -> None:
+        if self.is_debug_enabled():
+            self._emit(LoggerLevel.DEBUG, message, meta)
+
+    def verbose(self, message: str, meta: Any = None) -> None:
+        if self.is_verbose_enabled():
+            self._emit(LoggerLevel.VERBOSE, message, meta)
+
+    def info(self, message: str, meta: Any = None) -> None:
+        if self.is_info_enabled():
+            self._emit(LoggerLevel.INFO, message, meta)
+
+    def warn(self, message: str, meta: Any = None) -> None:
+        if self.is_warn_enabled():
+            self._emit(LoggerLevel.WARN, message, meta)
+
+    def error(self, message: str, meta: Any = None) -> None:
+        if self.is_error_enabled():
+            self._emit(LoggerLevel.ERROR, message, meta)
+
+    def fatal(self, message: str, meta: Any = None) -> None:
+        if self.is_fatal_enabled():
+            self._emit(LoggerLevel.FATAL, message, meta)

logger/delegating_logger.py

@@ -0,0 +1,73 @@
+"""
+logger.delegating_logger — Logger that delegates all calls to a provider.
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+from typing import Any
+
+from logger.logger import Logger
+from logger.logger_level import LoggerLevel
+
+
+class DelegatingLogger(Logger):
+    """
+    Wraps a provider logger, forwarding all calls to it.
+
+    Mirrors the JS DelegatingLogger class.
+    """
+
+    def __init__(self, provider: Logger) -> None:
+        if provider is None:
+            raise ValueError("provider is required")
+        # Don't call super().__init__() with a level — level lives on the provider
+        self.provider = provider
+        self.category = provider.category
+
+    def set_level(self, level: str) -> None:
+        self.provider.set_level(level)
+
+    def is_level_enabled(self, level: str) -> bool:
+        return self.provider.is_level_enabled(level)
+
+    def is_fatal_enabled(self) -> bool:
+        return self.provider.is_fatal_enabled()
+
+    def is_error_enabled(self) -> bool:
+        return self.provider.is_error_enabled()
+
+    def is_warn_enabled(self) -> bool:
+        return self.provider.is_warn_enabled()
+
+    def is_info_enabled(self) -> bool:
+        return self.provider.is_info_enabled()
+
+    def is_verbose_enabled(self) -> bool:
+        return self.provider.is_verbose_enabled()
+
+    def is_debug_enabled(self) -> bool:
+        return self.provider.is_debug_enabled()
+
+    def log(self, level: str, message: str, meta: Any = None) -> None:
+        self.provider.log(level, message, meta)
+
+    def debug(self, message: str, meta: Any = None) -> None:
+        self.provider.debug(message, meta)
+
+    def verbose(self, message: str, meta: Any = None) -> None:
+        self.provider.verbose(message, meta)
+
+    def info(self, message: str, meta: Any = None) -> None:
+        self.provider.info(message, meta)
+
+    def warn(self, message: str, meta: Any = None) -> None:
+        self.provider.warn(message, meta)
+
+    def error(self, message: str, meta: Any = None) -> None:
+        self.provider.error(message, meta)
+
+    def fatal(self, message: str, meta: Any = None) -> None:
+        self.provider.fatal(message, meta)

logger/json_formatter.py

@@ -0,0 +1,44 @@
+"""
+logger.json_formatter — Formats log entries as JSON strings.
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+import json
+from datetime import datetime
+from typing import Any
+
+from common import is_plain_object
+
+
+class JSONFormatter:
+    """
+    Formats log entries as JSON strings.
+
+    Output: {"level": ..., "message": ..., "timestamp": ..., "category": ..., [meta fields]}
+
+    Mirrors the JS JSONFormatter class.
+    """
+
+    def format(
+        self,
+        timestamp: datetime,
+        category: str,
+        level: str,
+        message: str,
+        meta: Any = None,
+    ) -> str:
+        record: dict[str, Any] = {
+            "level": level,
+            "message": message,
+            "timestamp": timestamp.isoformat(),
+            "category": category,
+        }
+        if is_plain_object(meta):
+            record.update(meta)
+        elif meta is not None:
+            record["meta"] = meta
+        return json.dumps(record)

logger/logger.py

@@ -0,0 +1,55 @@
+"""
+logger.logger — Base logger with level-gated methods.
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+from logger.logger_level import LoggerLevel
+
+
+class Logger:
+    """
+    Base logger.  Stores severity level and provides is_*_enabled() guards.
+
+    severity_level: int from LoggerLevel.ENUMS (fatal=0, debug=5).
+    A logger with level X enables all methods whose ENUMS value is <= X.
+    """
+
+    DEFAULT_CATEGORY = "ROOT"
+
+    def __init__(
+        self,
+        category: str | None = None,
+        level: str | None = None,
+    ) -> None:
+        self.category: str = category or Logger.DEFAULT_CATEGORY
+        self._levels = LoggerLevel.ENUMS
+        self.set_level(level or LoggerLevel.INFO)
+
+    def set_level(self, level: str) -> None:
+        self._level_name = level or LoggerLevel.INFO
+        self._severity = self._levels.get(self._level_name, self._levels[LoggerLevel.INFO])
+
+    def is_level_enabled(self, level: str) -> bool:
+        return self._levels.get(level, -1) <= self._severity
+
+    def is_fatal_enabled(self) -> bool:
+        return self.is_level_enabled(LoggerLevel.FATAL)
+
+    def is_error_enabled(self) -> bool:
+        return self.is_level_enabled(LoggerLevel.ERROR)
+
+    def is_warn_enabled(self) -> bool:
+        return self.is_level_enabled(LoggerLevel.WARN)
+
+    def is_info_enabled(self) -> bool:
+        return self.is_level_enabled(LoggerLevel.INFO)
+
+    def is_verbose_enabled(self) -> bool:
+        return self.is_level_enabled(LoggerLevel.VERBOSE)
+
+    def is_debug_enabled(self) -> bool:
+        return self.is_level_enabled(LoggerLevel.DEBUG)

logger/logger_category_cache.py

@@ -0,0 +1,27 @@
+"""
+logger.logger_category_cache — Simple dict cache for resolved logger levels.
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+from typing import Any
+
+
+class LoggerCategoryCache:
+    """
+    Caches the resolved log level string for each category path.
+
+    Mirrors the JS LoggerCategoryCache class.
+    """
+
+    def __init__(self) -> None:
+        self._cache: dict[str, str] = {}
+
+    def get(self, key: str) -> str | None:
+        return self._cache.get(key)
+
+    def put(self, key: str, level: str) -> None:
+        self._cache[key] = level

logger/logger_factory.py

@@ -0,0 +1,111 @@
+"""
+logger.logger_factory — Factory for creating ConfigurableLoggers.
+
+LoggerFactory.get_logger(category) creates a logger whose level is read from
+the active config at logging.level.<category> (dot hierarchy).
+
+The module-level loggerFactory singleton is usable with no setup — it reads
+from the config module's default config.
+
+Format selection:
+  logging.format=json  → JSONFormatter (default in non-browser contexts)
+  logging.format=text  → PlainTextFormatter
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+from typing import Any
+
+from logger.configurable_logger import ConfigurableLogger
+from logger.console_logger import ConsoleLogger
+from logger.logger_category_cache import LoggerCategoryCache
+from logger.json_formatter import JSONFormatter
+from logger.plain_text_formatter import PlainTextFormatter
+
+
+_shared_cache = LoggerCategoryCache()
+
+
+class LoggerFactory:
+    """
+    Creates ConfigurableLogger instances wired to a config source.
+
+    Mirrors the JS LoggerFactory class.
+    """
+
+    def __init__(
+        self,
+        config: Any = None,
+        cache: LoggerCategoryCache | None = None,
+        config_path: str | None = None,
+    ) -> None:
+        if config is None:
+            from config import config as _default_config
+            config = _default_config
+        self.config = config
+        # Each factory gets its own cache by default to avoid cross-instance pollution.
+        # Pass a shared cache explicitly when you want level caching across factories.
+        self.cache = cache if cache is not None else LoggerCategoryCache()
+        self.config_path = config_path or ConfigurableLogger.DEFAULT_CONFIG_PATH
+
+    # ------------------------------------------------------------------
+    # Instance method
+    # ------------------------------------------------------------------
+
+    def get_logger(self, category: Any = None) -> ConfigurableLogger:
+        """
+        Create a ConfigurableLogger for the given category.
+
+        category may be:
+          - a string (used directly)
+          - an object with a .qualifier, .name, or .__class__.__name__ attribute
+          - None (uses ROOT category)
+        """
+        cat = self._resolve_category(category)
+        formatter = self._get_formatter()
+        provider = ConsoleLogger(category=cat, formatter=formatter)
+        return ConfigurableLogger(
+            config=self.config,
+            provider=provider,
+            category=cat,
+            config_path=self.config_path,
+            cache=self.cache,
+        )
+
+    def _get_formatter(self) -> Any:
+        fmt = "json"
+        if self.config.has("logging.format"):
+            fmt = self.config.get("logging.format")
+        return PlainTextFormatter() if fmt.lower() == "text" else JSONFormatter()
+
+    @staticmethod
+    def _resolve_category(category: Any) -> str:
+        if isinstance(category, str):
+            return category
+        if category is None:
+            return ""
+        return (
+            getattr(category, "qualifier", None)
+            or getattr(category, "name", None)
+            or type(category).__name__
+        )
+
+    # ------------------------------------------------------------------
+    # Static convenience
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def get_logger_static(
+        category: Any = None,
+        config: Any = None,
+        config_path: str | None = None,
+        cache: LoggerCategoryCache | None = None,
+    ) -> ConfigurableLogger:
+        """
+        Static factory method — matches JS LoggerFactory.getLogger() signature.
+        """
+        factory = LoggerFactory(config=config, cache=cache, config_path=config_path)
+        return factory.get_logger(category)

logger/logger_level.py

@@ -0,0 +1,73 @@
+"""
+logger.logger_level — Log level constants.
+
+Level ordering mirrors the JS LoggerLevel (fatal=0, debug=5, higher = more verbose).
+Python's stdlib uses the inverse (DEBUG=10, CRITICAL=50, higher = more severe).
+
+We define our own ENUMS dict for the is_*_enabled() comparisons (lower = more
+severe, same as JS), AND map each level to the corresponding stdlib int so
+ConsoleLogger can pass the right level to the underlying stdlib logger.
+
+JS → Python stdlib mapping:
+  fatal   → CRITICAL  (50)
+  error   → ERROR     (40)
+  warn    → WARNING   (30)
+  info    → INFO      (20)
+  verbose → 15  (custom, between DEBUG and INFO)
+  debug   → DEBUG     (10)
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+import logging
+
+# Register the custom VERBOSE level so stdlib logging knows about it
+VERBOSE_INT = 15
+logging.addLevelName(VERBOSE_INT, "VERBOSE")
+
+
+class LoggerLevel:
+    """
+    Level constants for the alt-python logger.
+
+    ENUMS: name → severity int (fatal=0, debug=5) — used for is_*_enabled() comparisons.
+    STDLIB: name → Python stdlib logging int — used when emitting via stdlib.
+    """
+
+    FATAL = "fatal"
+    ERROR = "error"
+    WARN = "warn"
+    INFO = "info"
+    VERBOSE = "verbose"
+    DEBUG = "debug"
+
+    # Severity order: lower number = more severe (same as JS)
+    ENUMS: dict[str, int] = {
+        "fatal": 0,
+        "error": 1,
+        "warn": 2,
+        "info": 3,
+        "verbose": 4,
+        "debug": 5,
+    }
+
+    # Maps to Python stdlib logging level ints
+    STDLIB: dict[str, int] = {
+        "fatal": logging.CRITICAL,
+        "error": logging.ERROR,
+        "warn": logging.WARNING,
+        "info": logging.INFO,
+        "verbose": VERBOSE_INT,
+        "debug": logging.DEBUG,
+    }
+
+    @staticmethod
+    def from_stdlib(stdlib_level: int) -> str:
+        """Convert a stdlib logging int back to a LoggerLevel name."""
+        for name, val in LoggerLevel.STDLIB.items():
+            if val == stdlib_level:
+                return name
+        return LoggerLevel.INFO

logger/multi_logger.py

@@ -0,0 +1,60 @@
+"""
+logger.multi_logger — Fan-out logger that writes to multiple loggers simultaneously.
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+from typing import Any
+
+from logger.logger import Logger
+from logger.logger_level import LoggerLevel
+
+
+class MultiLogger(Logger):
+    """
+    Fans out log calls to multiple child loggers.
+
+    Mirrors the JS MultiLogger class.
+    """
+
+    def __init__(
+        self,
+        loggers: list[Logger] | None = None,
+        category: str | None = None,
+        level: str | None = None,
+    ) -> None:
+        # Assign loggers BEFORE calling super().__init__() because set_level()
+        # iterates self.loggers and is called during base class construction.
+        self.loggers: list[Logger] = list(loggers) if loggers else []
+        super().__init__(category, level)
+
+    def set_level(self, level: str) -> None:
+        super().set_level(level)
+        for lg in self.loggers:
+            lg.set_level(level)
+
+    def log(self, level: str, message: str, meta: Any = None) -> None:
+        if self.is_level_enabled(level):
+            for lg in self.loggers:
+                lg.log(level, message, meta)
+
+    def debug(self, message: str, meta: Any = None) -> None:
+        self.log(LoggerLevel.DEBUG, message, meta)
+
+    def verbose(self, message: str, meta: Any = None) -> None:
+        self.log(LoggerLevel.VERBOSE, message, meta)
+
+    def info(self, message: str, meta: Any = None) -> None:
+        self.log(LoggerLevel.INFO, message, meta)
+
+    def warn(self, message: str, meta: Any = None) -> None:
+        self.log(LoggerLevel.WARN, message, meta)
+
+    def error(self, message: str, meta: Any = None) -> None:
+        self.log(LoggerLevel.ERROR, message, meta)
+
+    def fatal(self, message: str, meta: Any = None) -> None:
+        self.log(LoggerLevel.FATAL, message, meta)

logger/plain_text_formatter.py

@@ -0,0 +1,32 @@
+"""
+logger.plain_text_formatter — Formats log entries as plain text.
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+from datetime import datetime
+from typing import Any
+
+
+class PlainTextFormatter:
+    """
+    Formats log entries as plain text.
+
+    Output: timestamp:category:level:message[meta]
+
+    Mirrors the JS PlainTextFormatter class.
+    """
+
+    def format(
+        self,
+        timestamp: datetime,
+        category: str,
+        level: str,
+        message: str,
+        meta: Any = None,
+    ) -> str:
+        suffix = str(meta) if meta is not None else ""
+        return f"{timestamp.isoformat()}:{category}:{level}:{message}{suffix}"