codex-core 0.3.0__tar.gz → 0.4.0__tar.gz

{codex_core-0.3.0 → codex_core-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-core
-Version: 0.3.0
+Version: 0.4.0
 Summary: Core utilities, schemas and settings for Codex WaaS toolkit
 Project-URL: Homepage, https://github.com/codexdlc/codex-core
 Project-URL: Documentation, https://codexdlc.github.io/codex-core/

{codex_core-0.3.0 → codex_core-0.4.0}/src/codex_core/common/__init__.py

@@ -1,6 +1,6 @@
 """Common utilities: logging, caching, phone normalization, text processing."""
 
-from .log_context import TaskLogContext
+from .log_context import TaskLogContext, clear_log_context, get_log_context, set_log_context
 from .loguru_setup import (
     InterceptHandler,
     LoggingSettingsProtocol,
@@ -12,6 +12,9 @@ from .text import clean_string, normalize_name, sanitize_for_sms, transliterate
 
 __all__ = [
     "TaskLogContext",
+    "clear_log_context",
+    "get_log_context",
+    "set_log_context",
     "InterceptHandler",
     "LoggingSettingsProtocol",
     "setup_logging",

{codex_core-0.3.0 → codex_core-0.4.0}/src/codex_core/common/log_context.py

@@ -1,29 +1,63 @@
-"""Structured logging context bound to a named task or worker.
+"""Structured logging context: per-request contextvars and per-task wrappers.
 
-Provides :class:`TaskLogContext` — a thin, stateful wrapper around
-``logging.Logger`` that automatically enriches every log record with
-a fixed set of structured fields (task name, worker name, arbitrary
-extras).
+Two complementary mechanisms:
 
-This module intentionally avoids any dependency on Loguru so that it
-works with any log sink: standard-library ``logging``, Loguru (via
-:class:`~codex_core.common.loguru_setup.InterceptHandler`), JSON
-formatters, ELK, or Loki.
+1. **contextvars-based context** — ``set_log_context`` / ``clear_log_context`` /
+   ``get_log_context``.  Designed for async request/task scoping: set fields once
+   at the start of a request or worker task, and every ``logger.*()`` call in that
+   async context automatically includes them via the Loguru patcher configured in
+   :func:`~codex_core.common.loguru_setup.setup_logging`.
 
-Example:
+2. **TaskLogContext** — a stateful wrapper around ``logging.Logger`` for code that
+   uses the standard library directly (see class docstring for details).
+
+Example (contextvars):
+    ```python
+    from codex_core.common.log_context import set_log_context, clear_log_context
+
+    set_log_context(request_id="abc-123", char_id=42)
+    logger.info("CombatMoveSubmitted")  # extra contains request_id, char_id
+    clear_log_context()
+    ```
+
+Example (TaskLogContext):
     ```python
     from codex_core.common.log_context import TaskLogContext
 
     log = TaskLogContext("send_booking_notification", worker="notification_worker")
     log.info("Processing appointment", extra={"appointment_id": 123})
-    # LogRecord contains: task="send_booking_notification",
-    #   worker="notification_worker", appointment_id=123
     ```
 """
 
+import contextvars
 import logging
 from typing import Any
 
+# ---------------------------------------------------------------------------
+# Async-safe contextvars log context
+# ---------------------------------------------------------------------------
+
+_log_context: contextvars.ContextVar[dict[str, Any]] = contextvars.ContextVar(
+    "log_context", default={}
+)
+
+
+def set_log_context(**kwargs: Any) -> None:
+    """Merge *kwargs* into the current async-local log context."""
+    current = _log_context.get().copy()
+    current.update(kwargs)
+    _log_context.set(current)
+
+
+def clear_log_context() -> None:
+    """Reset the async-local log context to empty."""
+    _log_context.set({})
+
+
+def get_log_context() -> dict[str, Any]:
+    """Return a shallow copy of the current async-local log context."""
+    return _log_context.get().copy()
+
 
 class TaskLogContext:
     """Structured logging adapter that binds context fields to every record.

codex_core-0.4.0/src/codex_core/common/loguru_setup.py

@@ -0,0 +1,307 @@
+"""Application-level Loguru configuration helpers (optional dependency).
+
+Provides opinionated, zero-boilerplate Loguru setup for codex_tools
+applications.  The codex_core *library* itself never calls these
+helpers; it uses the standard ``logging`` module exclusively so that
+consumers retain full control over their log infrastructure.
+
+**Dev mode** (``debug=True``): three sinks — colourised stdout, rotating
+plain-text ``debug.log``, and JSON ``errors.json``.
+
+**Prod mode** (``debug=False``): a single JSON-serialised stdout sink
+designed for ingestion by Grafana Alloy / Loki / ELK.  File sinks are
+omitted because container runtimes capture stdout natively.
+
+Both modes inject a **patcher** that enriches every log record with:
+
+- ``service`` — the service name passed to the setup function.
+- Any fields set via :func:`~codex_core.common.log_context.set_log_context`
+  (request_id, char_id, correlation_id, etc.).
+
+A built-in **healthcheck filter** suppresses records whose ``extra``
+contains ``healthcheck=True``, preventing ``/health`` endpoint noise
+from reaching log aggregators.
+
+Standard-library ``logging`` records are bridged via
+:class:`InterceptHandler` so that third-party libraries (SQLAlchemy,
+httpx, aiogram, etc.) are automatically captured by Loguru.
+
+Availability:
+    ``loguru`` is an **optional** dependency.  Both :func:`setup_logging`
+    and :func:`setup_universal_logging` raise :exc:`ImportError` with an
+    actionable message when ``loguru`` is not installed.
+"""
+
+import logging
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from .log_context import get_log_context
+
+if TYPE_CHECKING:
+    from types import FrameType
+
+    from loguru import Logger
+
+logger: "Logger | None"
+try:
+    from loguru import logger as _loguru_logger
+except ImportError:
+    logger = None
+else:
+    logger = _loguru_logger
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_context_patcher(service_name: str) -> Any:
+    """Return a Loguru patcher that injects service name and contextvars."""
+
+    def _patcher(record: dict[str, Any]) -> None:
+        record["extra"]["service"] = service_name
+        record["extra"].update(get_log_context())
+
+    return _patcher
+
+
+def _healthcheck_filter(record: dict[str, Any]) -> bool:
+    """Suppress log records tagged with ``healthcheck=True``."""
+    return not record["extra"].get("healthcheck", False)
+
+
+# ---------------------------------------------------------------------------
+# InterceptHandler
+# ---------------------------------------------------------------------------
+
+
+class InterceptHandler(logging.Handler):
+    """Bridge standard-library ``logging`` records to the Loguru sink.
+
+    Install this handler on the root logger (or any named logger) to
+    forward all ``logging``-based records into Loguru transparently.
+    The handler resolves the correct call-stack depth so that Loguru
+    reports the *original* call site rather than the handler frame.
+
+    This class is stateless and thread-safe; a single instance may be
+    shared across all intercepted loggers.
+
+    Example:
+        ```python
+        import logging
+        from codex_core.common.loguru_setup import InterceptHandler
+
+        logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+        ```
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if logger is None:
+            return
+
+        level: str | int
+        try:
+            level = logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        frame: FrameType | None = logging.currentframe()
+        depth = 6
+        while frame and frame.f_code.co_filename == logging.__file__:
+            frame = frame.f_back
+            depth += 1
+
+        logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())
+
+
+# ---------------------------------------------------------------------------
+# setup_universal_logging (raw-args variant)
+# ---------------------------------------------------------------------------
+
+_CONSOLE_FORMAT = (
+    "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
+    "<level>{level: <8}</level> | "
+    "<magenta>{extra[service]}</magenta> | "
+    "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
+    "<level>{message}</level>"
+)
+
+_FILE_FORMAT = "{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}"
+
+
+def setup_universal_logging(
+    log_dir: Path,
+    service_name: str = "App",
+    console_level: str = "INFO",
+    file_level: str = "DEBUG",
+    rotation: str = "10 MB",
+    is_debug: bool = False,
+) -> None:
+    """Configure Loguru with three sinks and standard-library interception.
+
+    Intended for applications that do not use
+    :class:`~codex_core.settings.BaseCommonSettings` but still want the
+    full codex_core logging stack.  Callers supply raw configuration
+    values directly rather than a settings object.
+
+    Args:
+        log_dir: Directory where log files are created.
+        service_name: Label embedded in the console format string.
+        console_level: Minimum level for stdout output.
+        file_level: Minimum level for the debug log file.
+        rotation: Loguru rotation threshold string.
+        is_debug: When ``True``, enables ``backtrace`` and ``diagnose``.
+
+    Raises:
+        ImportError: If ``loguru`` is not installed.
+    """
+    if logger is None:
+        raise ImportError("loguru is not installed. Please install it manually: pip install loguru")
+
+    logger.remove()
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    logger.configure(patcher=_make_context_patcher(service_name))
+
+    logger.add(
+        sink=sys.stdout,
+        level=console_level,
+        colorize=True,
+        filter=_healthcheck_filter,
+        format=_CONSOLE_FORMAT,
+    )
+
+    logger.add(
+        sink=str(log_dir / "debug.log"),
+        level=file_level,
+        rotation=rotation,
+        compression="zip",
+        format=_FILE_FORMAT,
+        enqueue=True,
+        backtrace=is_debug,
+        diagnose=is_debug,
+    )
+
+    logger.add(
+        sink=str(log_dir / "errors.json"),
+        level="ERROR",
+        serialize=True,
+        rotation=rotation,
+        compression="zip",
+        enqueue=True,
+    )
+
+    logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+
+    logger.info("LoguruSetupComplete log_dir={}", log_dir)
+
+
+# ---------------------------------------------------------------------------
+# LoggingSettingsProtocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class LoggingSettingsProtocol(Protocol):
+    """Structural protocol for the logging-related subset of settings."""
+
+    log_level_console: str
+    log_level_file: str
+    log_rotation: str
+    log_dir: str
+    debug: bool
+
+
+# ---------------------------------------------------------------------------
+# setup_logging (settings-based variant)
+# ---------------------------------------------------------------------------
+
+
+def setup_logging(
+    settings: LoggingSettingsProtocol,
+    service_name: str,
+    intercept_loggers: list[str] | None = None,
+    log_levels: dict[str, int] | None = None,
+) -> None:
+    """Configure Loguru from a settings object.
+
+    **Dev** (``settings.debug is True``): colourised console + file sinks.
+    **Prod** (``settings.debug is False``): JSON-serialised stdout only.
+
+    Both modes apply a patcher (service name + contextvars) and a
+    healthcheck filter.
+
+    Args:
+        settings: Object satisfying :class:`LoggingSettingsProtocol`.
+        service_name: Identifies the service in log output.
+        intercept_loggers: Logger names whose handlers are replaced
+            with :class:`InterceptHandler`.
+        log_levels: ``{logger_name: level_int}`` for silencing noisy
+            libraries.
+
+    Raises:
+        ImportError: If ``loguru`` is not installed.
+    """
+    if logger is None:
+        raise ImportError("loguru is not installed. Please install it manually: pip install loguru")
+
+    logger.remove()
+
+    logger.configure(patcher=_make_context_patcher(service_name))
+
+    if settings.debug:
+        # ── Dev: colourised console + file sinks ──
+        log_dir = Path(settings.log_dir) / service_name
+        log_dir.mkdir(parents=True, exist_ok=True)
+
+        logger.add(
+            sink=sys.stdout,
+            level=settings.log_level_console,
+            colorize=True,
+            filter=_healthcheck_filter,
+            format=_CONSOLE_FORMAT,
+        )
+
+        logger.add(
+            sink=str(log_dir / "debug.log"),
+            level=settings.log_level_file,
+            rotation=settings.log_rotation,
+            compression="zip",
+            format=_FILE_FORMAT,
+            enqueue=True,
+            backtrace=True,
+            diagnose=True,
+        )
+
+        logger.add(
+            sink=str(log_dir / "errors.json"),
+            level="ERROR",
+            serialize=True,
+            rotation=settings.log_rotation,
+            compression="zip",
+            enqueue=True,
+        )
+    else:
+        # ── Prod: JSON stdout only (Alloy / Loki / ELK ingestion) ──
+        logger.add(
+            sink=sys.stdout,
+            level=settings.log_level_console,
+            serialize=True,
+            colorize=False,
+            filter=_healthcheck_filter,
+            enqueue=True,
+        )
+
+    # Intercept standard logging
+    logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+
+    if intercept_loggers:
+        for name in intercept_loggers:
+            logging.getLogger(name).handlers = [InterceptHandler()]
+
+    if log_levels:
+        for name, level in log_levels.items():
+            logging.getLogger(name).setLevel(level)

codex_core-0.4.0/tests/unit/common/test_log_context.py

@@ -0,0 +1,98 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from codex_core.common.log_context import (
+    TaskLogContext,
+    clear_log_context,
+    get_log_context,
+    set_log_context,
+)
+
+pytestmark = pytest.mark.unit
+
+
+# ---------------------------------------------------------------------------
+# contextvars functions
+# ---------------------------------------------------------------------------
+
+
+class TestContextVars:
+    def setup_method(self):
+        clear_log_context()
+
+    def teardown_method(self):
+        clear_log_context()
+
+    def test_empty_by_default(self):
+        assert get_log_context() == {}
+
+    def test_set_and_get(self):
+        set_log_context(request_id="abc-123", char_id=42)
+        ctx = get_log_context()
+        assert ctx == {"request_id": "abc-123", "char_id": 42}
+
+    def test_set_merges_incrementally(self):
+        set_log_context(request_id="abc")
+        set_log_context(char_id=42)
+        assert get_log_context() == {"request_id": "abc", "char_id": 42}
+
+    def test_set_overwrites_existing_key(self):
+        set_log_context(request_id="old")
+        set_log_context(request_id="new")
+        assert get_log_context() == {"request_id": "new"}
+
+    def test_clear_resets_to_empty(self):
+        set_log_context(request_id="abc", char_id=42)
+        clear_log_context()
+        assert get_log_context() == {}
+
+    def test_get_returns_copy(self):
+        set_log_context(request_id="abc")
+        ctx = get_log_context()
+        ctx["injected"] = True
+        assert "injected" not in get_log_context()
+
+
+# ---------------------------------------------------------------------------
+# TaskLogContext (existing tests preserved)
+# ---------------------------------------------------------------------------
+
+
+def test_task_log_context_initialization():
+    ctx = TaskLogContext("my_task", worker="worker_1")
+    assert ctx._base_extra == {"task": "my_task", "worker": "worker_1"}
+    assert ctx._logger.name == "my_task"
+
+    ctx_with_custom_logger = TaskLogContext("my_task", logger_name="custom.logger", worker="worker_2")
+    assert ctx_with_custom_logger._base_extra == {"task": "my_task", "worker": "worker_2"}
+    assert ctx_with_custom_logger._logger.name == "custom.logger"
+
+
+@patch("logging.getLogger")
+def test_task_log_context_methods(mock_get_logger):
+    mock_logger = MagicMock()
+    mock_get_logger.return_value = mock_logger
+
+    ctx = TaskLogContext("test_task", worker="test_worker")
+
+    ctx.debug("debug message", extra={"key": "val"})
+    mock_logger.debug.assert_called_once_with(
+        "debug message", extra={"task": "test_task", "worker": "test_worker", "key": "val"}
+    )
+
+    ctx.info("info message")
+    mock_logger.info.assert_called_once_with("info message", extra={"task": "test_task", "worker": "test_worker"})
+
+    ctx.warning("warning message")
+    mock_logger.warning.assert_called_once_with("warning message", extra={"task": "test_task", "worker": "test_worker"})
+
+    ctx.error("error message", exc_info=True)
+    mock_logger.error.assert_called_once_with(
+        "error message", extra={"task": "test_task", "worker": "test_worker"}, exc_info=True
+    )
+
+    ctx.exception("exception message")
+    mock_logger.exception.assert_called_once_with(
+        "exception message", extra={"task": "test_task", "worker": "test_worker"}
+    )