kstlib 3.2.0__tar.gz → 3.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kstlib
-Version: 3.2.0
+Version: 3.3.1
 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.1/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.1}/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.1}/src/kstlib/cli/app.py

@@ -24,7 +24,7 @@ from kstlib.cli.commands.ops import register_cli as register_ops_cli
 from kstlib.cli.commands.rapi import register_cli as register_rapi_cli
 from kstlib.cli.commands.secrets import register_cli as register_secrets_cli
 from kstlib.cli.commands.secrets import shred as secrets_shred
-from kstlib.cli.common import console
+from kstlib.cli.common import console, err_console
 from kstlib.logging import LogManager, get_logger, init_logging
 
 app = typer.Typer(add_completion=False, name=meta.__app_name__)
@@ -223,8 +223,8 @@ def main(  # pylint: disable=unused-argument
         # Explicit --log-level takes precedence
         level = log_level.upper()
         if level not in LOG_LEVELS:
-            console.print(f"[red]Invalid log level: {log_level}[/]")
-            console.print(f"[dim]Valid levels: {', '.join(LOG_LEVELS)}[/]")
+            err_console.print(f"[red]Invalid log level: {log_level}[/]")
+            err_console.print(f"[dim]Valid levels: {', '.join(LOG_LEVELS)}[/]")
             raise typer.Exit(1)
     elif verbose > 0:
         # -v/-vv/-vvv flags

{kstlib-3.2.0 → kstlib-3.3.1}/src/kstlib/cli/commands/config.py

@@ -8,7 +8,7 @@ from typing import Annotated
 import typer
 from rich.panel import Panel
 
-from kstlib.cli.common import console
+from kstlib.cli.common import console, err_console
 from kstlib.config.export import (
     ConfigExportError,
     ConfigExportOptions,
@@ -59,18 +59,18 @@ def export_command(
     try:
         result = export_configuration(options)
     except ConfigExportError as exc:
-        console.print(f"[bold red]{exc}[/bold red]")
+        err_console.print(f"[bold red]{exc}[/bold red]")
         raise typer.Exit(code=1) from exc
 
     if stdout:
         if result.content is None:
-            console.print("[bold red]Export failed: empty content.[/bold red]")
+            err_console.print("[bold red]Export failed: empty content.[/bold red]")
             raise typer.Exit(code=1)
         console.print(result.content)
         return
 
     if result.destination is None:
-        console.print("[bold red]Export failed: missing destination file.[/bold red]")
+        err_console.print("[bold red]Export failed: missing destination file.[/bold red]")
         raise typer.Exit(code=1)
     console.print(
         Panel.fit(

{kstlib-3.2.0 → kstlib-3.3.1}/src/kstlib/cli/commands/rapi/__init__.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING
 import typer
 from typer.core import TyperGroup
 
-from kstlib.cli.common import console
+from kstlib.cli.common import err_console
 from kstlib.rapi import load_rapi_config
 
 if TYPE_CHECKING:
@@ -35,7 +35,7 @@ def _load_config_or_exit() -> RapiConfigManager:
     try:
         return load_rapi_config()
     except Exception as exc:  # pylint: disable=broad-exception-caught
-        console.print(f"[red]Failed to load rapi config: {exc}[/]")
+        err_console.print(f"[red]Failed to load rapi config: {exc}[/]")
         raise typer.Exit(code=1) from exc
 
 

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

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import json
+import re
 from typing import TYPE_CHECKING, Annotated, Any, cast
 
+import httpx
 import typer
 from typer.core import TyperCommand
 
@@ -15,7 +17,9 @@ from kstlib.rapi import (
     CredentialError,
     EndpointAmbiguousError,
     EndpointNotFoundError,
+    PathParameterError,
     RapiClient,
+    RapiError,
     RapiResponse,
     RequestError,
     ResponseTooLargeError,
@@ -530,19 +534,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 +581,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(
@@ -703,6 +742,44 @@ def _render_response(
         _format_output(response, fmt, quiet, out, raw=raw, minify=minify)
 
 
+def _payload(key: str, value: object) -> dict[str, Any] | None:
+    """Build a single-key error payload, or None when the value is empty."""
+    return {key: value} if value else None
+
+
+def _build_call_error_result(e: RapiError | httpx.InvalidURL) -> CommandResult:
+    """Map a failed rapi call error to its ERROR CommandResult.
+
+    Handles every exception caught by the ``call`` command except
+    ``AuthExpiredError`` (which keeps its dedicated exit-code-4 handling).
+    Each branch preserves the exact message and payload of the original
+    per-type handler.
+    """
+    payload: dict[str, Any] | None = None
+    if isinstance(e, EndpointNotFoundError):
+        message = f"Endpoint not found: {e.endpoint_ref}"
+        payload = _payload("searched_apis", e.searched_apis)
+    elif isinstance(e, EndpointAmbiguousError):
+        message = f"Ambiguous endpoint: '{e.endpoint_name}' exists in multiple APIs"
+        payload = {"matching_apis": e.matching_apis}
+    elif isinstance(e, ServerNotFoundError):
+        message = f"Server profile not found: '{e.server_name}'. Available: {e.available or '(none configured)'}"
+        payload = _payload("available_servers", e.available)
+    elif isinstance(e, CredentialError):
+        message = f"Credential error: {e}"
+        payload = _payload("credential_name", e.credential_name)
+    elif isinstance(e, RequestError):
+        message = f"Request failed: {e}"
+        payload = {"status_code": e.status_code, "retryable": e.retryable}
+    elif isinstance(e, ResponseTooLargeError):
+        message = f"Response too large: {e.response_size} bytes (max: {e.max_size})"
+    elif isinstance(e, PathParameterError):
+        message = f"Path parameter error: {e}"
+    else:
+        message = f"Invalid URL: {e}"
+    return CommandResult(status=CommandStatus.ERROR, message=message, payload=payload)
+
+
 def call(
     endpoint: Annotated[
         str,
@@ -811,10 +888,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,
@@ -927,78 +1006,19 @@ def call(
         if not response.ok:
             raise typer.Exit(code=1)
 
-    except EndpointNotFoundError as e:
-        exit_with_result(
-            CommandResult(
-                status=CommandStatus.ERROR,
-                message=f"Endpoint not found: {e.endpoint_ref}",
-                payload={"searched_apis": e.searched_apis} if e.searched_apis else None,
-            ),
-            quiet=quiet,
-            exit_code=1,
-            cause=e,
-        )
-    except EndpointAmbiguousError as e:
-        exit_with_result(
-            CommandResult(
-                status=CommandStatus.ERROR,
-                message=f"Ambiguous endpoint: '{e.endpoint_name}' exists in multiple APIs",
-                payload={"matching_apis": e.matching_apis},
-            ),
-            quiet=quiet,
-            exit_code=1,
-            cause=e,
-        )
-    except ServerNotFoundError as e:
-        exit_with_result(
-            CommandResult(
-                status=CommandStatus.ERROR,
-                message=(
-                    f"Server profile not found: '{e.server_name}'. Available: {e.available or '(none configured)'}"
-                ),
-                payload={"available_servers": e.available} if e.available else None,
-            ),
-            quiet=quiet,
-            exit_code=1,
-            cause=e,
-        )
-    except CredentialError as e:
-        exit_with_result(
-            CommandResult(
-                status=CommandStatus.ERROR,
-                message=f"Credential error: {e}",
-                payload={"credential_name": e.credential_name} if e.credential_name else None,
-            ),
-            quiet=quiet,
-            exit_code=1,
-            cause=e,
-        )
     except AuthExpiredError as e:
         _handle_auth_expired_error(e, quiet=quiet)
-    except RequestError as e:
-        exit_with_result(
-            CommandResult(
-                status=CommandStatus.ERROR,
-                message=f"Request failed: {e}",
-                payload={
-                    "status_code": e.status_code,
-                    "retryable": e.retryable,
-                },
-            ),
-            quiet=quiet,
-            exit_code=1,
-            cause=e,
-        )
-    except ResponseTooLargeError as e:
-        exit_with_result(
-            CommandResult(
-                status=CommandStatus.ERROR,
-                message=f"Response too large: {e.response_size} bytes (max: {e.max_size})",
-            ),
-            quiet=quiet,
-            exit_code=1,
-            cause=e,
-        )
+    except (
+        EndpointNotFoundError,
+        EndpointAmbiguousError,
+        ServerNotFoundError,
+        CredentialError,
+        RequestError,
+        ResponseTooLargeError,
+        PathParameterError,
+        httpx.InvalidURL,
+    ) as e:
+        exit_with_result(_build_call_error_result(e), quiet=quiet, exit_code=1, cause=e)
 
 
 __all__ = ["call"]

{kstlib-3.2.0 → kstlib-3.3.1}/src/kstlib/cli/commands/rapi/list.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING, Annotated
 import typer
 from rich.table import Table
 
-from kstlib.cli.common import console
+from kstlib.cli.common import console, err_console
 
 if TYPE_CHECKING:
     from kstlib.rapi.config import ApiConfig, EndpointConfig
@@ -228,8 +228,8 @@ def list_endpoints(
     # Filter by API name if specified
     if api:
         if api not in apis:
-            console.print(f"[red]API '{api}' not found.[/]")
-            console.print(f"[dim]Available APIs: {', '.join(apis.keys())}[/]")
+            err_console.print(f"[red]API '{api}' not found.[/]")
+            err_console.print(f"[dim]Available APIs: {', '.join(apis.keys())}[/]")
             raise typer.Exit(code=1)
         apis = {api: apis[api]}
 

{kstlib-3.2.0 → kstlib-3.3.1}/src/kstlib/cli/commands/rapi/show.py

@@ -11,7 +11,7 @@ from rich.markup import escape
 from rich.panel import Panel
 from rich.table import Table
 
-from kstlib.cli.common import console
+from kstlib.cli.common import console, err_console
 from kstlib.limits import HARD_MAX_DISPLAY_VALUE_LENGTH, HARD_MAX_ENDPOINT_REF_LENGTH
 from kstlib.rapi import EndpointNotFoundError
 from kstlib.rapi.config import _PATH_PARAM_PATTERN
@@ -33,12 +33,12 @@ def _truncate(value: str, max_length: int = HARD_MAX_DISPLAY_VALUE_LENGTH) -> st
 def _validate_endpoint_ref(endpoint_ref: str) -> None:
     """Validate endpoint reference for security (deep defense)."""
     if len(endpoint_ref) > HARD_MAX_ENDPOINT_REF_LENGTH:
-        console.print(f"[red]Endpoint reference too long: {len(endpoint_ref)} > {HARD_MAX_ENDPOINT_REF_LENGTH}[/]")
+        err_console.print(f"[red]Endpoint reference too long: {len(endpoint_ref)} > {HARD_MAX_ENDPOINT_REF_LENGTH}[/]")
         raise typer.Exit(code=1)
 
     if not _ENDPOINT_REF_PATTERN.match(endpoint_ref):
-        console.print("[red]Endpoint reference contains invalid characters.[/]")
-        console.print("[dim]Allowed: alphanumeric, underscore, dot, hyphen[/]")
+        err_console.print("[red]Endpoint reference contains invalid characters.[/]")
+        err_console.print("[dim]Allowed: alphanumeric, underscore, dot, hyphen[/]")
         raise typer.Exit(code=1)
 
 
@@ -183,8 +183,8 @@ def show_endpoint(
     try:
         api_config, ep_config = config_manager.resolve(endpoint_ref)
     except EndpointNotFoundError as e:
-        console.print(f"[red]Endpoint not found: {endpoint_ref}[/]")
-        console.print(f"[dim]Available APIs: {', '.join(e.searched_apis)}[/]")
+        err_console.print(f"[red]Endpoint not found: {endpoint_ref}[/]")
+        err_console.print(f"[dim]Available APIs: {', '.join(e.searched_apis)}[/]")
         raise typer.Exit(code=1) from e
 
     path_params = _PATH_PARAM_PATTERN.findall(ep_config.path)

{kstlib-3.2.0 → kstlib-3.3.1}/src/kstlib/cli/common.py

@@ -12,6 +12,7 @@ from rich.panel import Panel
 from rich.pretty import Pretty
 
 console = Console()
+err_console = Console(stderr=True)
 
 
 class CommandStatus(str, Enum):
@@ -39,17 +40,23 @@ STYLE_MAP = {
 
 
 def render_result(result: CommandResult) -> None:
-    """Render a command result using Rich components."""
+    """Render a command result using Rich components.
+
+    ERROR results render to stderr (keeping stdout clean for shell capture);
+    OK and WARNING results render to stdout.
+    """
     style = STYLE_MAP[result.status]
-    console.print(Panel(result.message, title=result.status.value.upper(), style=style, border_style=style))
+    target = err_console if result.status is CommandStatus.ERROR else console
+    target.print(Panel(result.message, title=result.status.value.upper(), style=style, border_style=style))
     if result.payload is not None:
-        console.print(Pretty(result.payload))
+        target.print(Pretty(result.payload))
 
 
 def emit_result(result: CommandResult, quiet: bool) -> None:
     """Output a command result honoring the quiet flag."""
     if quiet:
-        console.print(result.message, style=STYLE_MAP[result.status])
+        target = err_console if result.status is CommandStatus.ERROR else console
+        target.print(result.message, style=STYLE_MAP[result.status])
     else:
         render_result(result)
 
@@ -80,6 +87,7 @@ __all__ = [
     "CommandStatus",
     "console",
     "emit_result",
+    "err_console",
     "exit_error",
     "exit_with_result",
     "render_result",

{kstlib-3.2.0 → kstlib-3.3.1}/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.1}/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.1}/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.1}/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.1}/src/kstlib/meta.py

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

{kstlib-3.2.0 → kstlib-3.3.1}/src/kstlib/rapi/__init__.py

@@ -98,6 +98,7 @@ from kstlib.rapi.exceptions import (
     EndpointNotFoundError,
     EnvVarError,
     MinifyRequiresRawError,
+    PathParameterError,
     RapiError,
     RequestError,
     ResponseTooLargeError,
@@ -119,6 +120,7 @@ __all__ = [
     "HmacConfig",
     "MinifyRequiresRawError",
     "MultipartConfig",
+    "PathParameterError",
     "RapiClient",
     "RapiConfigManager",
     "RapiError",