alt-python-logger 1.0.0__tar.gz

alt_python_logger-1.0.0/.gitignore

@@ -0,0 +1,30 @@
+
+# ── GSD baseline (auto-generated) ──
+.gsd
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+*~
+.idea/
+.vscode/
+*.code-workspace
+.env
+.env.*
+!.env.example
+node_modules/
+.next/
+dist/
+build/
+__pycache__/
+*.pyc
+.venv/
+venv/
+target/
+vendor/
+*.log
+coverage/
+.cache/
+tmp/
+.bg_shell
+/.bg-shell/

alt_python_logger-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,427 @@
+# logger
+
+[![Language](https://img.shields.io/badge/language-Python-3776ab.svg)](https://www.python.org/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Config-driven, category-based structured logging for Python. Log levels are set
+in config under `logging.level` using a dot-hierarchy that mirrors Python's
+`logging` namespace. The library wraps Python's stdlib `logging` as the emit
+backend, so all existing stdlib handlers (file, rotating, socket, syslog) work
+without any extra configuration.
+
+Port of [`@alt-javascript/logger`](https://github.com/alt-javascript/boot/tree/main/packages/logger)
+to Python.
+
+## Install
+
+```bash
+uv add logger        # or: pip install logger
+```
+
+Requires Python 3.12+ and the `config` package (workspace dependency).
+
+## Quick Start
+
+```python
+from logger import logger_factory
+
+log = logger_factory.get_logger("com.example.MyService")
+
+log.fatal("Service crashed")
+log.error("Request failed", {"status": 500, "path": "/api/users"})
+log.warn("Retry attempt 3")
+log.info("Application started")
+log.verbose("Processing record 42 of 1000")
+log.debug("SQL: SELECT * FROM users WHERE id = ?")
+```
+
+Zero setup — `logger_factory` reads from the default `config` singleton, which
+discovers `application.yaml` (or `.json`, `.properties`, `.env`) from the
+current working directory.
+
+## Log Levels
+
+From least to most verbose, with the internal severity integer used for
+`is_*_enabled()` comparisons:
+
+| Level | Severity | Python stdlib int | Method |
+|---|---|---|---|
+| `fatal` | 0 (most severe) | 50 (CRITICAL) | `log.fatal(msg, meta=None)` |
+| `error` | 1 | 40 (ERROR) | `log.error(msg, meta=None)` |
+| `warn` | 2 | 30 (WARNING) | `log.warn(msg, meta=None)` |
+| `info` | 3 | 20 (INFO) | `log.info(msg, meta=None)` |
+| `verbose` | 4 | 15 (custom) | `log.verbose(msg, meta=None)` |
+| `debug` | 5 (least severe) | 10 (DEBUG) | `log.debug(msg, meta=None)` |
+
+A logger set to level `info` enables `fatal`, `error`, `warn`, and `info`. It
+suppresses `verbose` and `debug`. See
+[ADR-007](../../docs/decisions/ADR-007-logger-level-ordering.md) for why the
+ordering is preserved from the JS source.
+
+## Config-Driven Levels
+
+Set levels in config under `logging.level`. The hierarchy uses nested dicts —
+each node corresponds to a dot segment of the category name.
+
+```yaml
+# application.yaml
+logging:
+  level:
+    /:           warn       # root level — applies to all loggers
+    com:
+      example:   debug      # com.example.* → debug
+      noisy:
+        handler: warn       # com.example.noisy.handler → warn
+  format: text              # text or json (default: json)
+```
+
+The lookup walks the category's dot segments from left to right, applying the
+most-specific match found:
+
+```python
+logger_factory.get_logger("com.example.MyService")   # → debug (from com.example)
+logger_factory.get_logger("com.example.noisy.handler") # → warn (from com.example.noisy.handler)
+logger_factory.get_logger("other.pkg.Handler")        # → warn (from root /)
+```
+
+**Config key format:** Level keys must be **nested dicts** — flat dotted keys
+like `"com.example": debug` are not recognised by the segment walker. See
+[ADR-008](../../docs/decisions/ADR-008-config-level-keys.md).
+
+## Level Guards
+
+Use guards before constructing expensive log arguments:
+
+```python
+if log.is_debug_enabled():
+    log.debug(f"Query plan: {explain_query(sql)}")
+```
+
+| Method | Returns `True` when... |
+|---|---|
+| `is_fatal_enabled()` | level is `fatal` |
+| `is_error_enabled()` | level is `fatal` or `error` |
+| `is_warn_enabled()` | level is `fatal`, `error`, or `warn` |
+| `is_info_enabled()` | level is `fatal` through `info` |
+| `is_verbose_enabled()` | level is `fatal` through `verbose` |
+| `is_debug_enabled()` | any level (level is `debug`) |
+
+## Log Formats
+
+### JSON (default)
+
+```python
+{"level": "info", "message": "Started", "timestamp": "2026-01-15T12:00:00+00:00", "category": "com.example.MyService"}
+```
+
+Pass a plain dict as `meta` to merge fields into the JSON object:
+
+```python
+log.info("Request complete", {"status": 200, "duration_ms": 42})
+# => {"level":"info","message":"Request complete","timestamp":"...","category":"...","status":200,"duration_ms":42}
+```
+
+Pass any other value as `meta` to include it under a `"meta"` key:
+
+```python
+log.error("Unexpected value", "some_string")
+# => {"level":"error","message":"Unexpected value","timestamp":"...","category":"...","meta":"some_string"}
+```
+
+### Plain text
+
+```
+2026-01-15T12:00:00+00:00:com.example.MyService:info:Application started
+```
+
+Set `logging.format: text` in config to enable plain text output.
+
+## API Reference
+
+### `LoggerFactory`
+
+Main factory class. Creates `ConfigurableLogger` instances wired to a config
+source.
+
+#### Constructor
+
+```python
+LoggerFactory(config=None, cache=None, config_path=None)
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `config` | config-like | Config source. Default: module-level `config` singleton. |
+| `cache` | `LoggerCategoryCache \| None` | Level cache. Default: fresh per-instance cache (see [ADR-009](../../docs/decisions/ADR-009-per-instance-logger-cache.md)). |
+| `config_path` | `str` | Root path for level lookup. Default: `"logging.level"`. |
+
+#### `factory.get_logger(category)`
+
+Returns a `ConfigurableLogger` for the given category.
+
+`category` may be:
+- A string: `"com.example.MyService"`
+- A class instance with a `qualifier` attribute
+- A class instance (uses `type(instance).__name__`)
+- `None` (uses `"ROOT"`)
+
+```python
+log = factory.get_logger("com.example.MyService")
+log = factory.get_logger(my_service_instance)
+```
+
+#### `LoggerFactory.get_logger_static(category, config, config_path, cache)`
+
+Static convenience method equivalent to constructing a factory and calling
+`get_logger()`.
+
+---
+
+### `ConfigurableLogger`
+
+A `DelegatingLogger` whose level is set from config at construction time.
+
+#### `ConfigurableLogger.get_logger_level(category, config_path, config, cache)`
+
+Static method. Walks the category's dot segments and returns the most-specific
+level found in config. Falls back to `"info"` if nothing is found.
+
+The root level is read from `{config_path}./` (e.g. `logging.level./`).
+Category segment levels are read from `{config_path}.{segment}` (e.g.
+`logging.level.com`, `logging.level.com.example`).
+
+---
+
+### `Logger`
+
+Base class. Stores the severity level and provides `is_*_enabled()` guards.
+
+#### `Logger(category=None, level=None)`
+
+| Parameter | Default | Description |
+|---|---|---|
+| `category` | `"ROOT"` | Logger category name |
+| `level` | `"info"` | Initial log level |
+
+#### `logger.set_level(level)`
+
+Change the level at runtime. Accepts any key from `LoggerLevel.ENUMS`.
+
+---
+
+### `ConsoleLogger`
+
+Logger that emits via a stdlib `logging.Logger`. Extends `Logger`.
+
+```python
+ConsoleLogger(category=None, level=None, formatter=None, stdlib_logger=None)
+```
+
+| Parameter | Description |
+|---|---|
+| `category` | Logger category name |
+| `level` | Initial level |
+| `formatter` | `JSONFormatter` (default) or `PlainTextFormatter` |
+| `stdlib_logger` | stdlib `logging.Logger` instance, or `CachingConsole` for tests |
+
+---
+
+### `DelegatingLogger`
+
+Wraps a `provider` logger and forwards all calls to it.
+
+```python
+DelegatingLogger(provider)
+```
+
+Raises `ValueError` if `provider` is `None`.
+
+---
+
+### `MultiLogger`
+
+Fans out log calls to multiple child loggers.
+
+```python
+MultiLogger(loggers=None, category=None, level=None)
+```
+
+`set_level()` propagates to all child loggers.
+
+```python
+from logger import MultiLogger, ConsoleLogger
+
+ml = MultiLogger([console_logger, file_logger], level="info")
+ml.info("Written to both")
+```
+
+---
+
+### `JSONFormatter`
+
+```python
+formatter.format(timestamp, category, level, message, meta=None)
+```
+
+Returns a JSON string. Dict `meta` is merged into the top-level object; other
+types are stored under `"meta"`.
+
+---
+
+### `PlainTextFormatter`
+
+```python
+formatter.format(timestamp, category, level, message, meta=None)
+```
+
+Returns `"{timestamp}:{category}:{level}:{message}{meta}"`.
+
+---
+
+### `LoggerCategoryCache`
+
+Simple dict cache for resolved level strings.
+
+| Method | Description |
+|---|---|
+| `get(key)` | Returns the cached level string or `None`. |
+| `put(key, level)` | Stores a level string. |
+
+---
+
+### `LoggerLevel`
+
+Level constants and mappings.
+
+```python
+from logger import LoggerLevel
+
+LoggerLevel.FATAL    # "fatal"
+LoggerLevel.ERROR    # "error"
+LoggerLevel.WARN     # "warn"
+LoggerLevel.INFO     # "info"
+LoggerLevel.VERBOSE  # "verbose"
+LoggerLevel.DEBUG    # "debug"
+
+LoggerLevel.ENUMS    # {"fatal": 0, ..., "debug": 5}
+LoggerLevel.STDLIB   # {"fatal": 50, ..., "debug": 10}
+```
+
+---
+
+### `CachingConsole`
+
+In-memory log sink for test fixtures. Pass as `stdlib_logger` to
+`ConsoleLogger`.
+
+```python
+from logger import ConsoleLogger, CachingConsole, PlainTextFormatter
+
+sink = CachingConsole()
+log  = ConsoleLogger(
+    category="test",
+    level="debug",
+    formatter=PlainTextFormatter(),
+    stdlib_logger=sink,
+)
+
+log.info("captured")
+assert "captured" in sink.messages[0][1]
+
+sink.clear()
+```
+
+`sink.messages` is a list of `(level_int, formatted_string)` tuples.
+
+---
+
+## All Exports
+
+```python
+from logger import (
+    LoggerLevel,
+    Logger,
+    ConsoleLogger,
+    DelegatingLogger,
+    ConfigurableLogger,
+    LoggerCategoryCache,
+    LoggerFactory,
+    JSONFormatter,
+    PlainTextFormatter,
+    CachingConsole,
+    MultiLogger,
+    logger_factory,   # module-level singleton
+)
+```
+
+## Testing
+
+Use `CachingConsole` to capture log output in tests without writing to stdout:
+
+```python
+from config import EphemeralConfig
+from logger import (
+    LoggerFactory, ConsoleLogger, CachingConsole, PlainTextFormatter
+)
+
+def test_logs_at_correct_level():
+    cfg  = EphemeralConfig({"logging": {"level": {"/": "debug"}}})
+    sink = CachingConsole()
+    provider = ConsoleLogger(
+        category="test",
+        formatter=PlainTextFormatter(),
+        stdlib_logger=sink,
+    )
+    from logger import ConfigurableLogger, LoggerCategoryCache
+    log = ConfigurableLogger(
+        config=cfg,
+        provider=provider,
+        category="test",
+        cache=LoggerCategoryCache(),
+    )
+
+    log.info("hello")
+    assert any("hello" in msg for _, msg in sink.messages)
+```
+
+Alternatively, create a `LoggerFactory` with an `EphemeralConfig` and call
+`get_logger()` — the factory wires `CachingConsole` is not needed for level
+assertions:
+
+```python
+def test_level_from_config():
+    cfg     = EphemeralConfig({"logging": {"level": {"/": "warn"}}})
+    factory = LoggerFactory(config=cfg)
+    log     = factory.get_logger("my.service")
+
+    assert log.is_warn_enabled() is True
+    assert log.is_info_enabled() is False
+```
+
+## Troubleshooting
+
+**All log messages appear regardless of configured level**
+Check that `logging.level` in your config file uses nested dicts, not flat
+dotted keys. `{"com.example": "debug"}` is not recognised — use
+`{"com": {"example": "debug"}}`. See
+[ADR-008](../../docs/decisions/ADR-008-config-level-keys.md).
+
+**`is_debug_enabled()` returns `True` at `info` level**
+This should not happen with the current implementation. If you observe this,
+check whether a stale `LoggerCategoryCache` from a previous factory is being
+passed explicitly. The default per-instance cache is always fresh.
+
+**Logger emits to the wrong stdlib handler**
+`ConsoleLogger` creates a stdlib logger named after the category
+(`logging.getLogger(category)`). If your application calls
+`logging.basicConfig()` or attaches handlers to the root logger, those handlers
+will also receive these messages via propagation. Use
+`logging.getLogger("com.example").propagate = False` to suppress if needed.
+
+**`logger_factory.get_logger()` always returns `info` level**
+The module-level `logger_factory` uses the module-level `config` singleton, which
+reads from the current working directory. If no `application.yaml` is present and
+`PY_ACTIVE_PROFILES` is not set, the level defaults to `info` (the fallback when
+no `logging.level./` key is found). Create a config file or pass an explicit
+`config` to `LoggerFactory`.

alt_python_logger-1.0.0/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",
+]

alt_python_logger-1.0.0/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()

alt_python_logger-1.0.0/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