kstlib 3.3.0__tar.gz → 3.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kstlib
-Version: 3.3.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.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.3.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.3.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.3.0 → kstlib-3.3.1}/src/kstlib/cli/commands/rapi/call.py

@@ -6,6 +6,7 @@ import json
 import re
 from typing import TYPE_CHECKING, Annotated, Any, cast
 
+import httpx
 import typer
 from typer.core import TyperCommand
 
@@ -16,7 +17,9 @@ from kstlib.rapi import (
     CredentialError,
     EndpointAmbiguousError,
     EndpointNotFoundError,
+    PathParameterError,
     RapiClient,
+    RapiError,
     RapiResponse,
     RequestError,
     ResponseTooLargeError,
@@ -739,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,
@@ -965,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.3.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.3.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.3.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.3.0 → kstlib-3.3.1}/src/kstlib/meta.py

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

{kstlib-3.3.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",

{kstlib-3.3.0 → kstlib-3.3.1}/src/kstlib/rapi/config.py

@@ -28,6 +28,7 @@ from kstlib.rapi.exceptions import (
     EndpointCollisionError,
     EndpointNotFoundError,
     EnvVarError,
+    PathParameterError,
     SafeguardMissingError,
     ServerNotFoundError,
 )
@@ -53,13 +54,16 @@ def _validate_path_param(name: str, value: str) -> None:
         value: Substituted value to check.
 
     Raises:
-        ValueError: If the value contains path traversal or null bytes.
+        PathParameterError: If the value contains null bytes, control
+            characters, or path traversal segments.
 
     """
     if "\x00" in value:
-        raise ValueError(f"Null bytes not allowed in path parameter '{name}'")
+        raise PathParameterError(f"Null bytes not allowed in path parameter '{name}'")
+    if any(ord(c) < 0x20 or ord(c) == 0x7F for c in value):
+        raise PathParameterError(f"Control characters not allowed in path parameter '{name}'")
     if any(seg in value for seg in _DANGEROUS_PATH_SEGMENTS):
-        raise ValueError(f"Path traversal not allowed in parameter '{name}': {value!r}")
+        raise PathParameterError(f"Path traversal not allowed in parameter '{name}': {value!r}")
 
 
 # Deep defense: allowed values for HMAC config (hardcoded limits)
@@ -788,7 +792,7 @@ class EndpointConfig:
             Formatted path string.
 
         Raises:
-            ValueError: If required parameters are missing.
+            PathParameterError: If required parameters are missing or invalid.
 
         Examples:
             >>> config = EndpointConfig(
@@ -816,7 +820,7 @@ class EndpointConfig:
                     _validate_path_param(placeholder, value)
                     path = path.replace(f"{{{placeholder}}}", value)
                 else:
-                    raise ValueError(f"Missing positional argument {idx} for path {self.path}")
+                    raise PathParameterError(f"Missing positional argument {idx} for path {self.path}")
             elif placeholder in kwargs:
                 # Named: {name}
                 value = str(kwargs[placeholder])
@@ -829,7 +833,7 @@ class EndpointConfig:
                 path = path.replace(f"{{{placeholder}}}", value)
                 args = args[1:]
             else:
-                raise ValueError(f"Missing parameter '{placeholder}' for path {self.path}")
+                raise PathParameterError(f"Missing parameter '{placeholder}' for path {self.path}")
 
         return path
 

{kstlib-3.3.0 → kstlib-3.3.1}/src/kstlib/rapi/exceptions.py

@@ -462,6 +462,32 @@ class MinifyRequiresRawError(RapiError):
         super().__init__(message or self.DEFAULT_MESSAGE)
 
 
+class PathParameterError(RapiError, ValueError):
+    """Raised when a path parameter is missing or contains an invalid value.
+
+    Covers both failure modes of :meth:`EndpointConfig.build_path`: a required
+    ``{name}`` / ``{0}`` placeholder has no supplied value, or a supplied value
+    is rejected by validation (null bytes, control characters, path traversal).
+
+    Subclasses :class:`ValueError` as well as :class:`RapiError` so callers that
+    catch ``ValueError`` keep working while the CLI routes it through the typed
+    RAPI error chain for a clean message instead of a raw traceback.
+
+    Attributes:
+        message: Human-readable error message.
+        details: Additional context (e.g. the offending parameter name).
+
+    Examples:
+        >>> raise PathParameterError("invalid path parameter")
+        Traceback (most recent call last):
+        ...
+        kstlib.rapi.exceptions.PathParameterError: invalid path parameter
+        >>> isinstance(PathParameterError("x"), ValueError)
+        True
+
+    """
+
+
 __all__ = [
     "ConfirmationRequiredError",
     "CredentialError",
@@ -470,6 +496,7 @@ __all__ = [
     "EndpointNotFoundError",
     "EnvVarError",
     "MinifyRequiresRawError",
+    "PathParameterError",
     "RapiError",
     "RequestError",
     "ResponseTooLargeError",

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kstlib
-Version: 3.3.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>