kstlib 3.2.0__tar.gz → 3.3.0__tar.gz

{kstlib-3.2.0/src/kstlib.egg-info → kstlib-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kstlib
-Version: 3.2.0
+Version: 3.3.0
 Summary: Config-driven helpers for Python projects (dynamic config, secure secrets, preset logging, and more…)
 Author-email: Michel TRUONG <michel.truong@gmail.com>
 Maintainer-email: Michel TRUONG <michel.truong@gmail.com>

kstlib-3.3.0/src/kstlib/_shared/logging_helpers.py

@@ -0,0 +1,40 @@
+"""Shared TRACE-level logging helper (private to kstlib internals).
+
+Consolidates the ``_log_trace`` helper that was previously duplicated across
+several sub-packages into a single shared emitter. Modules pass their own
+logger so emission stays attributed to the calling module's name.
+
+This module must never import ``kstlib.logging`` at top level: see
+:func:`log_trace` for the circular-import rationale.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import logging
+
+__all__ = ["log_trace"]
+
+
+def log_trace(logger: logging.Logger, msg: str, *args: object) -> None:
+    """Emit a TRACE-level (custom level 5) record on the given logger.
+
+    Args:
+        logger: Target standard-library logger to emit the record on.
+        msg: Log message, optionally containing ``%``-style placeholders.
+        *args: Positional arguments interpolated into ``msg`` lazily by the
+            logging framework (only when the record is actually emitted).
+
+    Note:
+        ``TRACE_LEVEL`` is imported lazily inside the function to avoid the
+        circular import chain
+        ``kstlib.logging.manager -> kstlib.config -> kstlib.config.sops``.
+        Importing ``kstlib.logging`` at module top level would resurrect that
+        cycle as soon as a cascade module (e.g. ``kstlib.config.sops``) imports
+        this helper.
+    """
+    from kstlib.logging import TRACE_LEVEL
+
+    logger.log(TRACE_LEVEL, msg, *args)

{kstlib-3.2.0 → kstlib-3.3.0}/src/kstlib/cache/strategies.py

@@ -29,19 +29,13 @@ from collections.abc import Callable
 from pathlib import Path
 from typing import Any, TypeVar, cast
 
+from kstlib._shared.logging_helpers import log_trace
 from kstlib.limits import CacheLimits, get_cache_limits
 from kstlib.utils.formatting import format_bytes
 
 logger = logging.getLogger(__name__)
 
 
-def _log_trace(msg: str, *args: object) -> None:
-    """Log at TRACE level (custom level 5, below DEBUG)."""
-    from kstlib.logging import TRACE_LEVEL
-
-    logger.log(TRACE_LEVEL, msg, *args)
-
-
 _CACHE_FORMAT_VERSION = "kstlib:file-cache:v1"
 _SUPPORTED_SERIALIZERS: set[str] = {"json", "pickle", "auto"}
 _PICKLE_SAFE_BUILTINS: set[str] = {
@@ -190,7 +184,7 @@ class TTLCacheStrategy(CacheStrategy):
         if key not in self._cache:
             # The key is the SHA256 hash from make_key; logging it is safe
             # by construction (never the function args themselves).
-            _log_trace("[CACHE] TTL miss: key=%s", key)
+            log_trace(logger, "[CACHE] TTL miss: key=%s", key)
             return None
 
         value, expiry = self._cache[key]
@@ -198,10 +192,10 @@ class TTLCacheStrategy(CacheStrategy):
         # Check expiration
         if time.time() > expiry:
             del self._cache[key]
-            _log_trace("[CACHE] TTL miss (expired): key=%s", key)
+            log_trace(logger, "[CACHE] TTL miss (expired): key=%s", key)
             return None
 
-        _log_trace("[CACHE] TTL hit: key=%s", key)
+        log_trace(logger, "[CACHE] TTL hit: key=%s", key)
         return value
 
     def set(self, key: str, value: Any) -> None:

{kstlib-3.2.0 → kstlib-3.3.0}/src/kstlib/cli/commands/rapi/call.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import re
 from typing import TYPE_CHECKING, Annotated, Any, cast
 
 import typer
@@ -530,19 +531,44 @@ def _emit_extracted_value(
         print(content)
 
 
-def _resolve_show_extracted(response: RapiResponse, key: str) -> tuple[Any, str | None]:
+def _split_extracted_keys(spec: str) -> list[str]:
+    """Split a ``--show-extracted`` spec on commas/whitespace, dropping empties.
+
+    Examples:
+        >>> _split_extracted_keys("v1,v2")
+        ['v1', 'v2']
+        >>> _split_extracted_keys("v1 v2")
+        ['v1', 'v2']
+        >>> _split_extracted_keys("v1, ,v2")
+        ['v1', 'v2']
+        >>> _split_extracted_keys("")
+        []
+
+    """
+    return [key for key in re.split(r"[,\s]+", spec) if key]
+
+
+def _resolve_show_extracted(response: RapiResponse, spec: str) -> tuple[Any, str | None]:
     """Resolve the ``--show-extracted`` value and its empty-policy hint.
 
-    The policy frontier is declared vs not declared: an endpoint without an
-    ``extract:`` directive or an unknown key is a usage failure (exit 1 via
-    the hint), while a declared key holding an empty collection is a
-    legitimate result. A declared key that evaluated to None (expression
-    matched nothing) also fails, mirroring ``--pick``. Hints name keys only,
-    never extracted values.
+    The failure semantics follow the output form:
+
+    - No ``spec`` (bare flag): the whole ``extracted`` mapping is returned as a
+      dict (exit 0; a missing ``extract:`` directive still fails).
+    - A single key: the raw value is returned and a None value fails (exit 1),
+      mirroring ``--pick``. This keeps backward compatibility with v3.2.0
+      scripts that read one key.
+    - Several keys (comma/space-separated): a JSON object subset is returned
+      (exit 0). A declared key whose expression matched nothing appears as
+      ``null``; only an unknown key fails.
+
+    An endpoint without an ``extract:`` directive, or an unknown key, is a
+    usage failure (exit 1 via the hint). Hints name keys only, never values.
 
     Args:
         response: The API response whose ``extracted`` mapping is read.
-        key: The requested key, or an empty string to select all keys.
+        spec: The requested keys (comma/space-separated), or an empty string
+            to select all keys.
 
     Returns:
         Tuple of (value to emit, empty hint). The hint is consumed by
@@ -552,12 +578,22 @@ def _resolve_show_extracted(response: RapiResponse, key: str) -> tuple[Any, str
     extracted: Mapping[str, Any] = response.extracted
     if not extracted:
         return None, "No extract: directive declared for this endpoint."
-    if not key:
+    keys = _split_extracted_keys(spec)
+    if not keys:
         return dict(extracted), None
-    if key not in extracted:
+    if len(keys) == 1:
+        key = keys[0]
+        if key not in extracted:
+            available = ", ".join(sorted(extracted))
+            return None, f"No extracted key '{key}'. Available: {available}."
+        return extracted.get(key), f"Extracted key '{key}' matched nothing."
+    missing = [key for key in keys if key not in extracted]
+    if missing:
         available = ", ".join(sorted(extracted))
-        return None, f"No extracted key '{key}'. Available: {available}."
-    return extracted.get(key), f"Extracted key '{key}' matched nothing."
+        noun = "key" if len(missing) == 1 else "keys"
+        names = ", ".join(f"'{key}'" for key in missing)
+        return None, f"No extracted {noun} {names}. Available: {available}."
+    return {key: extracted[key] for key in keys}, None
 
 
 def _handle_extraction_output(
@@ -811,10 +847,12 @@ def call(
         str | None,
         typer.Option(
             "--show-extracted",
-            metavar="[KEY]",
+            metavar="[KEY[,KEY...]]",
             help=(
                 "Print values declared by the endpoint extract: directive. "
-                "With KEY, print that key only; without, print all extracted keys as JSON."
+                "One KEY prints that value; several comma/space-separated keys "
+                "print a JSON object subset; without a value, print all keys as JSON. "
+                'Quote keys with spaces ("v1 v2") or join with commas (v1,v2) so the shell does not split them.'
             ),
         ),
     ] = None,

{kstlib-3.2.0 → kstlib-3.3.0}/src/kstlib/config/sops.py

@@ -28,6 +28,7 @@ import subprocess
 from collections import OrderedDict
 from typing import Any
 
+from kstlib._shared.logging_helpers import log_trace
 from kstlib.config.exceptions import ConfigSopsError, ConfigSopsNotAvailableError
 from kstlib.limits import (
     DEFAULT_MAX_SOPS_CACHE_ENTRIES,
@@ -37,17 +38,6 @@ from kstlib.limits import (
 logger = logging.getLogger(__name__)
 
 
-def _log_trace(msg: str, *args: object) -> None:
-    """Log at TRACE level (custom level 5, below DEBUG).
-
-    Uses a lazy import to avoid the circular import chain
-    ``kstlib.logging.manager -> kstlib.config -> kstlib.config.sops``.
-    """
-    from kstlib.logging import TRACE_LEVEL
-
-    logger.log(TRACE_LEVEL, msg, *args)
-
-
 SOPS_FILE_PATTERNS: tuple[str, ...] = (
     ".sops.yml",
     ".sops.yaml",
@@ -217,7 +207,7 @@ class SopsDecryptor:
         cached = self._cache.get(resolved)
         if cached and cached[0] == mtime:
             self._cache.move_to_end(resolved)
-            _log_trace("SOPS cache hit for: %s", path.name)
+            log_trace(logger, "SOPS cache hit for: %s", path.name)
             return cached[1]
 
         # Security: reject absolute/relative paths to prevent binary override via config
@@ -269,7 +259,7 @@ class SopsDecryptor:
         else:
             removed = self._cache.pop(path.resolve(), None)
             if removed:
-                _log_trace("SOPS cache entry removed: %s", path.name)
+                log_trace(logger, "SOPS cache entry removed: %s", path.name)
 
     @property
     def cache_size(self) -> int:

{kstlib-3.2.0 → kstlib-3.3.0}/src/kstlib/db/database.py

@@ -17,6 +17,7 @@ from typing import TYPE_CHECKING, Any, cast
 
 from typing_extensions import Self
 
+from kstlib._shared.logging_helpers import log_trace
 from kstlib.db.exceptions import TransactionError
 from kstlib.db.pool import ConnectionPool, PoolStats
 
@@ -35,13 +36,6 @@ log = logging.getLogger(__name__)
 _SQL_TRACE_TRUNCATE = 200
 
 
-def _log_trace(msg: str, *args: object) -> None:
-    """Log at TRACE level (custom level 5, below DEBUG)."""
-    from kstlib.logging import TRACE_LEVEL
-
-    log.log(TRACE_LEVEL, msg, *args)
-
-
 def _truncate_sql(sql: str, limit: int = _SQL_TRACE_TRUNCATE) -> str:
     """Return ``sql`` truncated to ``limit`` characters, single-line."""
     flat = " ".join(sql.split())
@@ -254,7 +248,7 @@ class AsyncDatabase:
         # Sanitization invariant : log the truncated SQL only, NEVER the
         # parameters tuple (would leak PII / credentials in WHERE/INSERT
         # values). Truncation prevents giant DDL from drowning the trace.
-        _log_trace("[DB] Execute: %s (params=%s)", _truncate_sql(sql), "yes" if parameters else "no")
+        log_trace(log, "[DB] Execute: %s (params=%s)", _truncate_sql(sql), "yes" if parameters else "no")
         pool = self._ensure_pool()
         async with pool.connection() as conn:
             if parameters:

{kstlib-3.2.0 → kstlib-3.3.0}/src/kstlib/kstlib.conf.yml

@@ -175,6 +175,10 @@ logger:
       format: "::: PID %(process)d / TID %(thread)d ::: %(message)s"
       show_path: true
       tracebacks_show_locals: true
+      # Console routing: stdout (default) | stderr. Route to stderr when the CLI
+      # emits data/JSON on stdout, so logs do not corrupt the piped output
+      # (Unix data vs diagnostics separation). Invalid values raise ConfigError.
+      stream: stdout
 
     # File handler settings
     # Two configuration styles are supported:

{kstlib-3.2.0 → kstlib-3.3.0}/src/kstlib/logging/manager.py

@@ -49,7 +49,7 @@ from rich.logging import RichHandler
 from rich.theme import Theme
 from rich.traceback import Traceback
 
-from kstlib.config import get_config
+from kstlib.config import ConfigError, get_config
 
 # =============================================================================
 # HARDCODED LIMITS (Deep Defense)
@@ -253,6 +253,7 @@ FALLBACK_DEFAULTS = {
         "format": "::: PID %(process)d / TID %(thread)d ::: %(message)s",
         "show_path": True,
         "tracebacks_show_locals": False,
+        "stream": "stdout",
     },
     "file": {
         "level": "DEBUG",
@@ -340,7 +341,15 @@ class LogManager(logging.Logger):
         # Setup console and theme
         self.width = shutil.get_terminal_size(fallback=(120, 30)).columns
         theme = self._create_theme()
-        self.console = Console(theme=theme, width=self.width)
+        # Route console output to stdout (default) or stderr. Routing to stderr
+        # keeps stdout clean for CLIs that emit data/JSON there (Unix data vs
+        # diagnostics separation). Fail fast on a typo so a misconfigured value
+        # never silently falls back to stdout and corrupts piped data.
+        stream = self._config.console.get("stream", "stdout")
+        if stream not in ("stdout", "stderr"):
+            raise ConfigError(f"Invalid console.stream {stream!r}: expected 'stdout' or 'stderr'")
+        _internal_log.debug("[INIT] console stream resolved to %r", stream)
+        self.console = Console(theme=theme, width=self.width, stderr=(stream == "stderr"))
 
         # Setup handlers
         self._setup_handlers()

{kstlib-3.2.0 → kstlib-3.3.0}/src/kstlib/meta.py

@@ -39,7 +39,7 @@ __logo__ = (
 )
 
 __app_name__ = "kstlib"
-__version__ = "3.2.0"
+__version__ = "3.3.0"
 __description__ = (
     "Config-driven helpers for Python projects (dynamic config, secure secrets, preset logging, and more…)"
 )