matrx-api 0.1.0__py3-none-any.whl

matrx_api/errors.py

@@ -0,0 +1,88 @@
+"""The one error model. Mirrors MatrxApiError / OrganizationContextError of @ai-matrx/api."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _non_blank(value: Any) -> str | None:
+    return value if isinstance(value, str) and value.strip() else None
+
+
+def extract_error_message(detail: Any) -> str | None:
+    """Richest human-readable message from a Matrx/FastAPI error body (same order as the TS client)."""
+    if not isinstance(detail, dict):
+        return None
+    candidates: list[str] = []
+
+    def push(v: str | None) -> None:
+        if v:
+            candidates.append(v)
+
+    push(_non_blank(detail.get("user_message")))
+    push(_non_blank(detail.get("message")))
+    details = detail.get("details")
+    if isinstance(details, list):
+        msgs = []
+        for entry in details:
+            if not isinstance(entry, dict):
+                continue
+            m = _non_blank(entry.get("message"))
+            if not m:
+                continue
+            f = _non_blank(entry.get("field"))
+            msgs.append(f"{f}: {m}" if f else m)
+        if msgs:
+            push("; ".join(msgs))
+    inner = detail.get("detail")
+    if isinstance(inner, dict):
+        push(_non_blank(inner.get("message")) or _non_blank(inner.get("user_message")))
+    if isinstance(inner, str) and inner.strip():
+        push(inner)
+    if isinstance(inner, list):
+        msgs = [m for e in inner if isinstance(e, dict) and (m := _non_blank(e.get("msg")))]
+        if msgs:
+            push("; ".join(msgs))
+    return candidates[0] if candidates else None
+
+
+def extract_error_code(detail: Any) -> str | None:
+    """Machine code: top-level ``code``, else ``detail.code``."""
+    if not isinstance(detail, dict):
+        return None
+    top = _non_blank(detail.get("code"))
+    if top:
+        return top
+    inner = detail.get("detail")
+    if isinstance(inner, dict):
+        return _non_blank(inner.get("code"))
+    return None
+
+
+class MatrxApiError(Exception):
+    """Every failed call: HTTP status, server code and message. ``status`` is 0 for a transport failure."""
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        path: str,
+        server_detail: Any = None,
+        message: str | None = None,
+        code: str | None = None,
+    ) -> None:
+        self.status = status
+        self.path = path
+        self.server_detail = server_detail
+        self.code = code or extract_error_code(server_detail)
+        self.message = message or extract_error_message(server_detail) or f"HTTP {status}"
+        super().__init__(f"{self.message} [{status}{' ' + self.code if self.code else ''}] {path}")
+
+
+class OrganizationContextError(Exception):
+    """Raised BEFORE the wire when an org-required operation has no (valid) organization."""
+
+    def __init__(self, code: str, message: str) -> None:
+        self.code = code
+        self.message = message
+        super().__init__(f"{message} [{code}]")

matrx_api/generated/__init__.py

@@ -0,0 +1 @@
+"""One module per x-matrx-domain: ``from matrx_api.generated import files``. Generated - do not edit."""