kstlib 1.0.2__py3-none-any.whl → 1.1.0__py3-none-any.whl

kstlib/rapi/exceptions.py

@@ -203,11 +203,175 @@ class ResponseTooLargeError(RapiError):
         self.max_size = max_size
 
 
+class ConfirmationRequiredError(RapiError):
+    """Raised when a dangerous endpoint requires confirmation.
+
+    This exception is raised at runtime when calling an endpoint
+    that has a safeguard configured but the confirm parameter is
+    missing or incorrect.
+
+    Attributes:
+        endpoint_ref: Full endpoint reference (api.endpoint).
+        expected: Expected confirmation string.
+        actual: Actual confirmation string provided (None if missing).
+
+    Examples:
+        >>> raise ConfirmationRequiredError("api.delete", expected="DELETE X")
+        Traceback (most recent call last):
+        ...
+        kstlib.rapi.exceptions.ConfirmationRequiredError: ... requires confirmation...
+    """
+
+    def __init__(
+        self,
+        endpoint_ref: str,
+        *,
+        expected: str,
+        actual: str | None = None,
+    ) -> None:
+        """Initialize ConfirmationRequiredError.
+
+        Args:
+            endpoint_ref: Full endpoint reference (api.endpoint).
+            expected: Expected confirmation string.
+            actual: Actual confirmation string provided (None if missing).
+        """
+        if actual is None:
+            message = f"Endpoint '{endpoint_ref}' requires confirmation. Pass confirm=\"{expected}\" to proceed."
+        else:
+            message = f'Confirmation mismatch for \'{endpoint_ref}\'. Expected: "{expected}", got: "{actual}"'
+        super().__init__(
+            message,
+            details={
+                "endpoint_ref": endpoint_ref,
+                "expected": expected,
+                "actual": actual,
+            },
+        )
+        self.endpoint_ref = endpoint_ref
+        self.expected = expected
+        self.actual = actual
+
+
+class SafeguardMissingError(RapiError):
+    """Raised when endpoint requires safeguard but none is configured.
+
+    This exception is raised at config load time when an endpoint uses
+    a method that requires a safeguard (e.g., DELETE, PUT) but no
+    safeguard string is provided in the endpoint configuration.
+
+    Attributes:
+        endpoint_ref: Full endpoint reference (api.endpoint).
+        method: HTTP method that requires the safeguard.
+
+    Examples:
+        >>> raise SafeguardMissingError("api.delete", "DELETE")
+        Traceback (most recent call last):
+        ...
+        kstlib.rapi.exceptions.SafeguardMissingError: ... requires a safeguard...
+    """
+
+    def __init__(self, endpoint_ref: str, method: str) -> None:
+        """Initialize SafeguardMissingError.
+
+        Args:
+            endpoint_ref: Full endpoint reference (api.endpoint).
+            method: HTTP method that requires the safeguard.
+        """
+        message = (
+            f"Endpoint '{endpoint_ref}' uses method {method} which requires a safeguard. "
+            f"Add 'safeguard: \"...\"' to the endpoint or remove {method} from "
+            f"rapi.safeguard.required_methods in kstlib.conf.yml."
+        )
+        super().__init__(
+            message,
+            details={"endpoint_ref": endpoint_ref, "method": method},
+        )
+        self.endpoint_ref = endpoint_ref
+        self.method = method
+
+
+class EndpointCollisionError(RapiError):
+    """Raised when endpoints collide in strict mode.
+
+    This exception is raised at config load time when the same endpoint
+    reference is defined in multiple files and strict mode is enabled.
+
+    Attributes:
+        endpoint_ref: Full endpoint reference (api.endpoint).
+        source_files: List of files defining this endpoint.
+
+    Examples:
+        >>> raise EndpointCollisionError("api.create", ["a.rapi.yml", "b.rapi.yml"])
+        Traceback (most recent call last):
+        ...
+        kstlib.rapi.exceptions.EndpointCollisionError: Endpoint 'api.create' defined in multiple files...
+    """
+
+    def __init__(self, endpoint_ref: str, source_files: list[str]) -> None:
+        """Initialize EndpointCollisionError.
+
+        Args:
+            endpoint_ref: Full endpoint reference (api.endpoint).
+            source_files: List of files defining this endpoint.
+        """
+        message = (
+            f"Endpoint '{endpoint_ref}' defined in multiple files: {', '.join(source_files)}. "
+            f"Set rapi.strict: false to allow overwriting (last file wins)."
+        )
+        super().__init__(
+            message,
+            details={"endpoint_ref": endpoint_ref, "source_files": source_files},
+        )
+        self.endpoint_ref = endpoint_ref
+        self.source_files = source_files
+
+
+class EnvVarError(RapiError):
+    """Raised when environment variable substitution fails.
+
+    This exception is raised at config load time when a required
+    environment variable is not set and no default value is provided.
+
+    Attributes:
+        var_name: Name of the missing environment variable.
+        source: Source file or context where the variable was referenced.
+
+    Examples:
+        >>> raise EnvVarError("VIYA_HOST")
+        Traceback (most recent call last):
+        ...
+        kstlib.rapi.exceptions.EnvVarError: Environment variable 'VIYA_HOST' is not set...
+    """
+
+    def __init__(self, var_name: str, source: str | None = None) -> None:
+        """Initialize EnvVarError.
+
+        Args:
+            var_name: Name of the missing environment variable.
+            source: Source file or context where the variable was referenced.
+        """
+        if source:
+            message = f"Environment variable '{var_name}' is not set (required by {source}). Use ${{VAR:-default}} for optional variables."
+        else:
+            message = f"Environment variable '{var_name}' is not set. Use ${{VAR:-default}} for optional variables."
+        super().__init__(
+            message,
+            details={"var_name": var_name, "source": source},
+        )
+        self.var_name = var_name
+        self.source = source
+
+
 __all__ = [
+    "ConfirmationRequiredError",
     "CredentialError",
     "EndpointAmbiguousError",
+    "EndpointCollisionError",
     "EndpointNotFoundError",
+    "EnvVarError",
     "RapiError",
     "RequestError",
     "ResponseTooLargeError",
+    "SafeguardMissingError",
 ]

{kstlib-1.0.2.dist-info → kstlib-1.1.0.dist-info}/METADATA

@@ -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.dist-info → kstlib-1.1.0.dist-info}/RECORD

@@ -1,8 +1,8 @@
 kstlib/__init__.py,sha256=MO6fLXlSp_EKA-itBMmPMPoQDLja9MTMxGSgMFicaZE,10518
 kstlib/__main__.py,sha256=l9-cxF6BGDYCb-giF4hDEewFv5ytrhKZTxfsVenUB3A,323
-kstlib/kstlib.conf.yml,sha256=6NJznp7xBilNexSpRWHpxPVWH_fIs25vVjcKYVIXiNA,29616
+kstlib/kstlib.conf.yml,sha256=qqfg4rfEtJAXkE5ujML864yq46lGQaSN2p0PTPgJegA,30040
 kstlib/limits.py,sha256=i3E1O_qvniUlJoyzh6Gv14h7faqxEwydX6Gk6uOHCFo,31578
-kstlib/meta.py,sha256=UN-1r-en-rXM3Af5DFGGbx5Q37BoBUuHD-Niy6vGOKk,6149
+kstlib/meta.py,sha256=4kFOEbhEMRtTfOqD81NHVehojpsRf_6VK3LNOC1N600,6149
 kstlib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kstlib/ssl.py,sha256=LudzVfYFAoSxKFyEzACQlYnjPmuusoRl4tAPPsdBBmU,10355
 kstlib/alerts/__init__.py,sha256=mixRr15D5jIhoyLWn6PWrZI6K-urwuw0aMBzMGhqTXQ,3153
@@ -51,7 +51,7 @@ kstlib/cli/commands/ops/status.py,sha256=83yXo-3EamyXyYkGW22tMc0CjT577SYfE8jQp2o
 kstlib/cli/commands/ops/stop.py,sha256=dXo0HPKqEA1quWY4tIXWB8aZzFas06tWkFL4Fy86MVA,1421
 kstlib/cli/commands/rapi/__init__.py,sha256=OUbYf-C1Blt7ItIV2-G5LMo61zw_xLQaPrNB-xWwLXk,1712
 kstlib/cli/commands/rapi/call.py,sha256=hMLpZ8SFinLjwFpAHnl2bGzMbLZxUiZzm5e-pR6om9s,9976
-kstlib/cli/commands/rapi/list.py,sha256=w7rU9CtudAuY_7dAwDBh5pPCrk5yhjbfYfVw0kDQM7o,3014
+kstlib/cli/commands/rapi/list.py,sha256=Sm8MbcYklevhmvZMnqvez3Hsl1dx_Pclc_M-hSUcEMw,7873
 kstlib/cli/commands/rapi/show.py,sha256=dLRq5WeG3wvoysEt8ivNp06wHep14PvQNaiAlRVJQrQ,7599
 kstlib/cli/commands/secrets/__init__.py,sha256=qxmuaeAgyVexnnOx72oqNOFJNBsn-CtEuMrXSAu3_vk,760
 kstlib/cli/commands/secrets/common.py,sha256=9nurm3R1BVb_-Oa3t-LcpywBYK6SGeLGR6fzqm4bl_k,12043
@@ -110,11 +110,11 @@ kstlib/ops/manager.py,sha256=mcGCUOP8BZ_kZobn4YJcu1ZgEOMG2AKn12NJLgFanFE,12933
 kstlib/ops/models.py,sha256=PTBhPSxBdzK-gRGQznwj5i-mg2gNBhXbV6Ojgc31t-w,5317
 kstlib/ops/tmux.py,sha256=9WxCcKYmkmYMehEazTz4oWmlU7TDzfT3VVPTKQ9L1_0,11175
 kstlib/ops/validators.py,sha256=CfkEdv5pxg5vYESz2XG5ghU9wcuUW0yWD8V8xb5gYw0,8072
-kstlib/rapi/__init__.py,sha256=To_PLcyuTeATI8J_7z56CXjZGfxPZ80l5ux1tQu3h68,3236
-kstlib/rapi/client.py,sha256=b1Kvyf2RbQerp43N-WRgTVMiRQ6qFQzPQ86yuPXAM8o,29427
-kstlib/rapi/config.py,sha256=TsjcydfTNMwsyBn0vRuitMKGLamvy99hVUhQTsFB7OA,28870
+kstlib/rapi/__init__.py,sha256=7RsJCkcL95iB7i9YZQom-AXZJDi1WLnSMOzO-Yre5fk,3436
+kstlib/rapi/client.py,sha256=OFmNcUy28S-VF7JhVmwdPQdkhQ_xkJBXA0LxJsplmL4,31421
+kstlib/rapi/config.py,sha256=RwHt6oASsr8A1DNiEu2p9YMShqT6LB54RUrf-9xNymw,48083
 kstlib/rapi/credentials.py,sha256=Q8zGwhx1JLdJFSU8XoKKwch8i_rB6n4Xb87VUruv9c0,31502
-kstlib/rapi/exceptions.py,sha256=eK7t93uyjDkmoM2mpCz8F3SQ4NyC9KtU99dNQI23PDg,6528
+kstlib/rapi/exceptions.py,sha256=aF3kddBzLGR-3VhHzQKVco_ctArxWamWqVyPipIEV9E,12439
 kstlib/resilience/__init__.py,sha256=5u8anwYCOD2bvyCPT3RQkZBuSZKzzu3p-ljpx8__4NI,3167
 kstlib/resilience/circuit_breaker.py,sha256=MiliIvNUiqH7DcXjWLs6lIDTh-jOfnBnNt5EWxmV5EI,13781
 kstlib/resilience/exceptions.py,sha256=5UNyEHR-TEP66jB2RyqsYjPyisyL_FKjiGCBQziNShw,2556
@@ -155,9 +155,9 @@ kstlib/websocket/__init__.py,sha256=yNpCeg3S0NA61WEOIaVW2-DeFFdPyNhFpV4Xi7ZEUT4,
 kstlib/websocket/exceptions.py,sha256=Mku-3SoaadbRwQZLR7Rx5J4VVrp8wwJjKnCWOOxse3s,5957
 kstlib/websocket/manager.py,sha256=rxiQ1N-H9PVWl9WEr_24QxeIHu9j8REL4GH31QrmTSg,42587
 kstlib/websocket/models.py,sha256=-Ooe2oZJLH9wAW9_yZyUE1mreaguQZK3c4Y_Zt8MOgM,10986
-kstlib-1.0.2.dist-info/licenses/LICENSE.md,sha256=y9Wv0ooml-DVaNOLi2BKvWJyklSACRKnLGOYXhnrdiQ,1077
-kstlib-1.0.2.dist-info/METADATA,sha256=qUGJK6Cj171pAR2ap-1wVEcNqB1E18mbgl30f9AbpWQ,7384
-kstlib-1.0.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-kstlib-1.0.2.dist-info/entry_points.txt,sha256=mqwbGFeHB_sJYnZMTpx-_64FPW6apGcfeK8VvObs5jM,48
-kstlib-1.0.2.dist-info/top_level.txt,sha256=tgPJhgVk1CqZM_mx4fmT0_GUKmnLpJuntTo5GMs7EOs,7
-kstlib-1.0.2.dist-info/RECORD,,
+kstlib-1.1.0.dist-info/licenses/LICENSE.md,sha256=y9Wv0ooml-DVaNOLi2BKvWJyklSACRKnLGOYXhnrdiQ,1077
+kstlib-1.1.0.dist-info/METADATA,sha256=myhJd84yRVoRs0Dt0Oh-f2gu7t7mOUC8NtEOXUdL-wY,7766
+kstlib-1.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+kstlib-1.1.0.dist-info/entry_points.txt,sha256=mqwbGFeHB_sJYnZMTpx-_64FPW6apGcfeK8VvObs5jM,48
+kstlib-1.1.0.dist-info/top_level.txt,sha256=tgPJhgVk1CqZM_mx4fmT0_GUKmnLpJuntTo5GMs7EOs,7
+kstlib-1.1.0.dist-info/RECORD,,