kstlib 1.0.2__tar.gz → 1.1.0__tar.gz

{kstlib-1.0.2/src/kstlib.egg-info → kstlib-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kstlib
-Version: 1.0.2
+Version: 1.1.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>
@@ -9,15 +9,20 @@ Project-URL: Homepage, https://github.com/KaminoU/kstlib
 Project-URL: Repository, https://github.com/KaminoU/kstlib
 Project-URL: Bug Tracker, https://github.com/KaminoU/kstlib/issues
 Project-URL: Changelog, https://github.com/KaminoU/kstlib/blob/main/CHANGELOG.md
-Keywords: kstlib
+Keywords: kstlib,config,configuration,yaml,secrets,sops,logging,oauth2,oidc,rest-api,http-client,resilience,circuit-breaker,rate-limiter,websocket,alerts,toolkit
 Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.md

{kstlib-1.0.2 → kstlib-1.1.0}/pyproject.toml

@@ -10,7 +10,25 @@ description = "Config-driven helpers for Python projects (dynamic config, secure
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "MIT"
 license-files = ["LICENSE.md"]
-keywords = ["kstlib"]
+keywords = [
+    "kstlib",
+    "config",
+    "configuration",
+    "yaml",
+    "secrets",
+    "sops",
+    "logging",
+    "oauth2",
+    "oidc",
+    "rest-api",
+    "http-client",
+    "resilience",
+    "circuit-breaker",
+    "rate-limiter",
+    "websocket",
+    "alerts",
+    "toolkit",
+]
 dynamic = ["version"]
 dependencies = [
     # --- Configuration & Serialization ---
@@ -43,13 +61,18 @@ dependencies = [
 ]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
     "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Systems Administration",
+    "Typing :: Typed",
 ]
 
 requires-python = ">=3.10"

kstlib-1.1.0/src/kstlib/cli/commands/rapi/list.py

@@ -0,0 +1,261 @@
+"""List available API endpoints."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from rich.table import Table
+
+from kstlib.cli.common import console
+from kstlib.rapi import load_rapi_config
+
+if TYPE_CHECKING:
+    from kstlib.rapi.config import ApiConfig, EndpointConfig
+
+
+def _matches_filter(
+    filter_terms: list[str],
+    ref: str,
+    method: str,
+    path: str,
+    description: str | None,
+) -> bool:
+    """Check if endpoint matches all filter terms (AND logic).
+
+    Args:
+        filter_terms: List of lowercase search terms.
+        ref: Endpoint reference (e.g., "github.repos").
+        method: HTTP method (e.g., "GET").
+        path: Endpoint path.
+        description: Optional endpoint description.
+
+    Returns:
+        True if all terms match any field.
+    """
+    searchable = f"{ref} {method} {path} {description or ''}".lower()
+    return all(term in searchable for term in filter_terms)
+
+
+def _build_query_body_display(
+    ep_config: EndpointConfig,
+    method: str,
+) -> tuple[str, str]:
+    """Build query and body column displays.
+
+    Args:
+        ep_config: Endpoint configuration.
+        method: HTTP method.
+
+    Returns:
+        Tuple of (query_display, body_display).
+    """
+    query_display = f"[yellow]{len(ep_config.query)}[/]" if ep_config.query else "-"
+    body_display = "-"
+    if ep_config.body_template and method in ("POST", "PUT", "PATCH"):
+        body_display = f"[green]{len(ep_config.body_template)}[/]"
+    return query_display, body_display
+
+
+def _build_compact_indicator(ep_config: EndpointConfig, method: str) -> str:
+    """Build compact param indicator for non-verbose mode.
+
+    Args:
+        ep_config: Endpoint configuration.
+        method: HTTP method.
+
+    Returns:
+        Formatted indicator string (e.g., " (4) (2)").
+    """
+    indicator = ""
+    if ep_config.query:
+        indicator += f" [yellow]({len(ep_config.query)})[/]"
+    if ep_config.body_template and method in ("POST", "PUT", "PATCH"):
+        indicator += f" [green]({len(ep_config.body_template)})[/]"
+    return indicator
+
+
+def _add_endpoint_row(
+    table: Table,
+    ep_config: EndpointConfig,
+    api_name: str,
+    verbose: bool,
+    *,
+    short_desc: bool = False,
+) -> None:
+    """Add a single endpoint row to the table.
+
+    Args:
+        table: Rich table to add row to.
+        ep_config: Endpoint configuration.
+        api_name: Parent API name.
+        verbose: Whether to show verbose columns.
+        short_desc: Whether to truncate description (verbose mode only).
+    """
+    ref = f"{api_name}.{ep_config.name}"
+    method = ep_config.method.upper()
+    path_display = f"[dim]{ep_config.path}[/]"
+
+    if verbose:
+        query_display, body_display = _build_query_body_display(ep_config, method)
+        description = ep_config.description or ""
+        desc_display = (description[:40] + "...") if short_desc and len(description) > 43 else description
+        table.add_row(ref, method, path_display, query_display, body_display, desc_display)
+    else:
+        indicator = _build_compact_indicator(ep_config, method)
+        table.add_row(ref, method, path_display + indicator)
+
+
+def _create_table(verbose: bool) -> Table:
+    """Create the endpoints table with appropriate columns.
+
+    Args:
+        verbose: Whether to include verbose columns.
+
+    Returns:
+        Configured Rich table.
+    """
+    table = Table(title="Available Endpoints", show_lines=False)
+    table.add_column("Reference", style="cyan")
+    table.add_column("Method", style="green", justify="center")
+    table.add_column("Path")
+
+    if verbose:
+        table.add_column("Query", justify="center")
+        table.add_column("Body", justify="center")
+        table.add_column("Description", style="dim")
+
+    return table
+
+
+def _collect_matching_endpoints(
+    apis: dict[str, ApiConfig],
+    filter_terms: list[str],
+) -> list[tuple[str, EndpointConfig]]:
+    """Collect endpoints matching the filter.
+
+    Args:
+        apis: Dictionary of API configurations.
+        filter_terms: List of lowercase filter terms.
+
+    Returns:
+        List of (api_name, endpoint_config) tuples.
+    """
+    results = []
+    for api_name, api_config in sorted(apis.items()):
+        for ep_name, ep_config in sorted(api_config.endpoints.items()):
+            ref = f"{api_name}.{ep_name}"
+            method = ep_config.method.upper()
+            description = ep_config.description or ""
+
+            if filter_terms and not _matches_filter(filter_terms, ref, method, ep_config.path, description):
+                continue
+
+            results.append((api_name, ep_config))
+    return results
+
+
+def list_endpoints(
+    api: Annotated[
+        str | None,
+        typer.Argument(help="Filter by API name (optional)."),
+    ] = None,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Show additional details (method, description, query params).",
+        ),
+    ] = False,
+    filter_str: Annotated[
+        str | None,
+        typer.Option(
+            "--filter",
+            "-f",
+            help="Filter endpoints by keyword(s). Searches in ref, method, path, description.",
+        ),
+    ] = None,
+    short_desc: Annotated[
+        bool,
+        typer.Option(
+            "--short-desc",
+            help="Truncate descriptions to 40 chars (verbose mode only).",
+        ),
+    ] = False,
+) -> None:
+    """List all configured API endpoints.
+
+    Examples:
+        # List all endpoints
+        kstlib rapi list
+
+        # List endpoints for specific API
+        kstlib rapi list github
+
+        # Filter by keyword (searches everywhere)
+        kstlib rapi list --filter "delete"
+
+        # Multiple keywords (AND logic)
+        kstlib rapi list --filter "annotation GET"
+
+        # Combine API filter with keyword filter
+        kstlib rapi list annotations --filter "member"
+
+        # Verbose output with method, description, query params
+        kstlib rapi list -v
+
+        # Show details for specific endpoint (use 'rapi show')
+        kstlib rapi show annotations.create
+    """
+    try:
+        config_manager = load_rapi_config()
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        console.print(f"[red]Failed to load rapi config: {e}[/]")
+        raise typer.Exit(code=1) from e
+
+    apis = config_manager.apis
+
+    if not apis:
+        console.print("[yellow]No APIs configured in kstlib.conf.yml[/]")
+        console.print("[dim]Add APIs under 'rapi.api' section.[/]")
+        raise typer.Exit(code=0)
+
+    # 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())}[/]")
+            raise typer.Exit(code=1)
+        apis = {api: apis[api]}
+
+    # Parse filter terms
+    filter_terms = filter_str.lower().split() if filter_str else []
+
+    # Collect matching endpoints
+    matches = _collect_matching_endpoints(apis, filter_terms)
+
+    if not matches:
+        if filter_terms:
+            console.print(f"[yellow]No endpoints matching '{filter_str}'[/]")
+        else:
+            console.print("[yellow]No endpoints found.[/]")
+        raise typer.Exit(code=0)
+
+    # Build and populate table
+    table = _create_table(verbose)
+    for api_name, ep_config in matches:
+        _add_endpoint_row(table, ep_config, api_name, verbose, short_desc=short_desc)
+
+    console.print(table)
+
+    # Summary
+    total_apis = len(apis)
+    total_endpoints = sum(len(a.endpoints) for a in apis.values())
+    if filter_terms:
+        console.print(f"\n[dim]{len(matches)} matching / {total_endpoints} total endpoints[/]")
+    else:
+        console.print(f"\n[dim]{total_endpoints} endpoints across {total_apis} API(s)[/]")
+
+
+__all__ = ["list_endpoints"]

{kstlib-1.0.2 → kstlib-1.1.0}/src/kstlib/kstlib.conf.yml

@@ -623,6 +623,17 @@ rapi:
     retry_delay: 1.0           # Initial delay between retries (seconds)
     retry_backoff: 2.0         # Exponential backoff multiplier
 
+  # Safeguard configuration for dangerous HTTP methods
+  # Endpoints using these methods MUST define a safeguard string
+  # to prevent accidental destructive operations
+  safeguard:
+    # HTTP methods that require a safeguard to be defined on endpoints
+    # Default: DELETE and PUT (most destructive operations)
+    # Set to empty list [] to disable safeguard requirements
+    required_methods:
+      - DELETE
+      - PUT
+
   # Pretty-print settings for CLI output
   # Controls formatting of JSON and XML responses in terminal
   pretty_render:

{kstlib-1.0.2 → kstlib-1.1.0}/src/kstlib/meta.py

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

{kstlib-1.0.2 → kstlib-1.1.0}/src/kstlib/rapi/__init__.py

@@ -85,26 +85,32 @@ from kstlib.rapi.config import (
     EndpointConfig,
     HmacConfig,
     RapiConfigManager,
+    SafeguardConfig,
     load_rapi_config,
 )
 from kstlib.rapi.credentials import CredentialRecord, CredentialResolver
 from kstlib.rapi.exceptions import (
+    ConfirmationRequiredError,
     CredentialError,
     EndpointAmbiguousError,
     EndpointNotFoundError,
+    EnvVarError,
     RapiError,
     RequestError,
     ResponseTooLargeError,
+    SafeguardMissingError,
 )
 
 __all__ = [
     "ApiConfig",
+    "ConfirmationRequiredError",
     "CredentialError",
     "CredentialRecord",
     "CredentialResolver",
     "EndpointAmbiguousError",
     "EndpointConfig",
     "EndpointNotFoundError",
+    "EnvVarError",
     "HmacConfig",
     "RapiClient",
     "RapiConfigManager",
@@ -112,6 +118,8 @@ __all__ = [
     "RapiResponse",
     "RequestError",
     "ResponseTooLargeError",
+    "SafeguardConfig",
+    "SafeguardMissingError",
     "call",
     "call_async",
     "load_rapi_config",

{kstlib-1.0.2 → kstlib-1.1.0}/src/kstlib/rapi/client.py

@@ -27,6 +27,7 @@ from kstlib.rapi.config import (
 )
 from kstlib.rapi.credentials import CredentialRecord, CredentialResolver
 from kstlib.rapi.exceptions import (
+    ConfirmationRequiredError,
     RequestError,
     ResponseTooLargeError,
 )
@@ -45,6 +46,37 @@ def _log_trace(msg: str, *args: Any) -> None:
     log.log(TRACE_LEVEL, msg, *args)
 
 
+def _validate_safeguard(
+    endpoint_config: EndpointConfig,
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    confirm: str | None,
+) -> None:
+    """Validate safeguard confirmation for dangerous endpoints.
+
+    Args:
+        endpoint_config: Endpoint configuration.
+        args: Positional arguments for path/safeguard substitution.
+        kwargs: Keyword arguments for path/safeguard substitution.
+        confirm: Confirmation string provided by caller.
+
+    Raises:
+        ConfirmationRequiredError: If safeguard is required but confirm is missing or wrong.
+    """
+    if endpoint_config.safeguard is None:
+        return
+
+    expected = endpoint_config.build_safeguard(*args, **kwargs)
+    if expected is None:
+        return
+
+    if confirm is None:
+        raise ConfirmationRequiredError(endpoint_config.full_ref, expected=expected)
+
+    if confirm != expected:
+        raise ConfirmationRequiredError(endpoint_config.full_ref, expected=expected, actual=confirm)
+
+
 @dataclass
 class RapiResponse:
     """Response from an API call.
@@ -238,6 +270,7 @@ class RapiClient:
         body: Any = None,
         headers: Mapping[str, str] | None = None,
         timeout: float | None = None,
+        confirm: str | None = None,
         **kwargs: Any,
     ) -> RapiResponse:
         """Make a synchronous API call.
@@ -248,12 +281,14 @@ class RapiClient:
             body: Request body (dict for JSON, str for raw).
             headers: Runtime headers (override service/endpoint headers).
             timeout: Request timeout (uses config default if None).
+            confirm: Confirmation string for dangerous endpoints with safeguard.
             **kwargs: Keyword arguments for path parameters and query params.
 
         Returns:
             RapiResponse with parsed data.
 
         Raises:
+            ConfirmationRequiredError: If safeguard requires confirmation.
             RequestError: If request fails after retries.
             ResponseTooLargeError: If response exceeds max size.
 
@@ -262,6 +297,7 @@ class RapiClient:
             >>> client.call("httpbin.get_ip")  # doctest: +SKIP
             >>> client.call("httpbin.delayed", 5)  # doctest: +SKIP
             >>> client.call("httpbin.post_data", body={"key": "value"})  # doctest: +SKIP
+            >>> client.call("admin.delete_user", userId="123", confirm="DELETE USER 123")  # doctest: +SKIP
         """
         log.debug("Calling endpoint: %s", endpoint_ref)
 
@@ -269,6 +305,9 @@ class RapiClient:
         api_config, endpoint_config = self._config_manager.resolve(endpoint_ref)
         _log_trace("Resolved to: %s", endpoint_config.full_ref)
 
+        # Validate safeguard before proceeding
+        _validate_safeguard(endpoint_config, args, kwargs, confirm)
+
         # Build request
         request = self._build_request(
             api_config,
@@ -290,6 +329,7 @@ class RapiClient:
         body: Any = None,
         headers: Mapping[str, str] | None = None,
         timeout: float | None = None,
+        confirm: str | None = None,
         **kwargs: Any,
     ) -> RapiResponse:
         """Make an asynchronous API call.
@@ -300,12 +340,14 @@ class RapiClient:
             body: Request body (dict for JSON, str for raw).
             headers: Runtime headers (override service/endpoint headers).
             timeout: Request timeout (uses config default if None).
+            confirm: Confirmation string for dangerous endpoints with safeguard.
             **kwargs: Keyword arguments for path parameters and query params.
 
         Returns:
             RapiResponse with parsed data.
 
         Raises:
+            ConfirmationRequiredError: If safeguard requires confirmation.
             RequestError: If request fails after retries.
             ResponseTooLargeError: If response exceeds max size.
         """
@@ -315,6 +357,9 @@ class RapiClient:
         api_config, endpoint_config = self._config_manager.resolve(endpoint_ref)
         _log_trace("Resolved to: %s", endpoint_config.full_ref)
 
+        # Validate safeguard before proceeding
+        _validate_safeguard(endpoint_config, args, kwargs, confirm)
+
         # Build request
         request = self._build_request(
             api_config,
@@ -814,6 +859,7 @@ def call(
     *args: Any,
     body: Any = None,
     headers: Mapping[str, str] | None = None,
+    confirm: str | None = None,
     **kwargs: Any,
 ) -> RapiResponse:
     """Convenience function for quick API calls.
@@ -825,6 +871,7 @@ def call(
         *args: Positional path parameters.
         body: Request body.
         headers: Runtime headers.
+        confirm: Confirmation string for dangerous endpoints with safeguard.
         **kwargs: Keyword parameters.
 
     Returns:
@@ -835,7 +882,7 @@ def call(
         >>> response = call("httpbin.get_ip")  # doctest: +SKIP
     """
     client = RapiClient()
-    return client.call(endpoint_ref, *args, body=body, headers=headers, **kwargs)
+    return client.call(endpoint_ref, *args, body=body, headers=headers, confirm=confirm, **kwargs)
 
 
 async def call_async(
@@ -843,6 +890,7 @@ async def call_async(
     *args: Any,
     body: Any = None,
     headers: Mapping[str, str] | None = None,
+    confirm: str | None = None,
     **kwargs: Any,
 ) -> RapiResponse:
     """Convenience function for async API calls.
@@ -854,6 +902,7 @@ async def call_async(
         *args: Positional path parameters.
         body: Request body.
         headers: Runtime headers.
+        confirm: Confirmation string for dangerous endpoints with safeguard.
         **kwargs: Keyword parameters.
 
     Returns:
@@ -864,7 +913,7 @@ async def call_async(
         >>> response = await call_async("httpbin.get_ip")  # doctest: +SKIP
     """
     client = RapiClient()
-    return await client.call_async(endpoint_ref, *args, body=body, headers=headers, **kwargs)
+    return await client.call_async(endpoint_ref, *args, body=body, headers=headers, confirm=confirm, **kwargs)
 
 
 __all__ = [