iii-sdk 0.11.3.dev1__tar.gz → 0.11.4.dev1__tar.gz

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.4.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iii-sdk
-Version: 0.11.3.dev1
+Version: 0.11.4.dev1
 Summary: III SDK for Python
 Project-URL: Homepage, https://github.com/iii-hq/sdk
 Project-URL: Repository, https://github.com/iii-hq/sdk

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.4.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iii-sdk"
-version = "0.11.3.dev1"
+version = "0.11.4.dev1"
 description = "III SDK for Python"
 authors = [{ name = "III" }]
 license = { text = "Apache-2.0" }

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.4.dev1}/src/iii/__init__.py

@@ -1,6 +1,7 @@
 """III SDK for Python."""
 
 from .channels import ChannelReader, ChannelWriter
+from .errors import IIIForbiddenError, IIIInvocationError, IIITimeoutError
 from .format_utils import extract_request_format, extract_response_format, python_type_to_format
 from .iii import TriggerAction, register_worker
 from .iii_constants import FunctionRef, InitOptions, ReconnectionConfig, TelemetryOptions
@@ -62,6 +63,10 @@ __all__ = [
     # Channels
     "ChannelReader",
     "ChannelWriter",
+    # Errors
+    "IIIForbiddenError",
+    "IIIInvocationError",
+    "IIITimeoutError",
     # Core
     "FunctionRef",
     "InitOptions",

iii_sdk-0.11.4.dev1/src/iii/errors.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class IIIInvocationError(Exception):
+    """Raised when an invocation dispatched by the SDK fails.
+
+    Subclass by code:
+      - ``IIIForbiddenError``  (``code == 'FORBIDDEN'``)
+      - ``IIITimeoutError``    (``code == 'TIMEOUT'``)
+
+    Catch the base to handle every rejection; catch a subclass to react to
+    a specific category. ``except Exception`` continues to work because
+    ``IIIInvocationError`` inherits from ``Exception``.
+
+    Attributes are read-only after construction. ``stacktrace`` is the
+    engine-side trace when the remote handler raised; it may include
+    internal file paths and should not be surfaced to end users. ``str(err)``
+    intentionally never includes the stacktrace.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        function_id: str | None = None,
+        stacktrace: str | None = None,
+        invocation_id: str | None = None,
+    ) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+        self.function_id = function_id
+        self.stacktrace = stacktrace
+        self.invocation_id = invocation_id
+
+
+class IIIForbiddenError(IIIInvocationError):
+    """Raised when RBAC denies an invocation. ``code == 'FORBIDDEN'``."""
+
+
+class IIITimeoutError(IIIInvocationError):
+    """Raised when an invocation exceeds its timeout. ``code == 'TIMEOUT'``."""
+
+
+def _wrap_wire_error(
+    error: Any,
+    *,
+    function_id: str | None,
+    invocation_id: str | None,
+) -> IIIInvocationError:
+    """Convert a wire ``ErrorBody``-shaped dict into a typed exception.
+
+    Dispatches to ``IIIForbiddenError`` / ``IIITimeoutError`` based on
+    ``error['code']``. Malformed shapes (non-dict, missing fields, non-string
+    values) fall back to ``IIIInvocationError(code='UNKNOWN', ...)`` so no
+    rejection path prints as a raw dict repr.
+    """
+    if isinstance(error, dict):
+        raw_code = error.get("code")
+        code = raw_code if isinstance(raw_code, str) else "UNKNOWN"
+
+        raw_message = error.get("message")
+        message = raw_message if isinstance(raw_message, str) else "<no message>"
+
+        raw_stacktrace = error.get("stacktrace")
+        stacktrace = raw_stacktrace if isinstance(raw_stacktrace, str) else None
+
+        cls: type[IIIInvocationError] = {
+            "FORBIDDEN": IIIForbiddenError,
+            "TIMEOUT": IIITimeoutError,
+        }.get(code, IIIInvocationError)
+
+        return cls(
+            code=code,
+            message=message,
+            function_id=function_id,
+            stacktrace=stacktrace,
+            invocation_id=invocation_id,
+        )
+
+    return IIIInvocationError(
+        code="UNKNOWN",
+        message=str(error),
+        function_id=function_id,
+        invocation_id=invocation_id,
+    )

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.4.dev1}/src/iii/iii.py

@@ -9,6 +9,7 @@ import random
 import threading
 import traceback
 import uuid
+from dataclasses import dataclass
 from importlib.metadata import version
 from typing import Any, Awaitable, Callable, Coroutine, TypeVar, cast
 
@@ -16,6 +17,7 @@ import websockets
 from websockets.asyncio.client import ClientConnection
 
 from .channels import ChannelReader, ChannelWriter
+from .errors import IIIInvocationError, IIITimeoutError, _wrap_wire_error
 from .format_utils import extract_request_format, extract_response_format
 from .iii_constants import (
     DEFAULT_RECONNECTION_CONFIG,
@@ -25,7 +27,6 @@ from .iii_constants import (
     InitOptions,
 )
 from .iii_types import (
-    FunctionInfo,
     HttpInvocationConfig,
     InvocationResultMessage,
     InvokeFunctionMessage,
@@ -42,13 +43,10 @@ from .iii_types import (
     StreamChannelRef,
     TriggerActionEnqueue,
     TriggerActionVoid,
-    TriggerInfo,
     TriggerRequest,
-    TriggerTypeInfo,
     UnregisterFunctionMessage,
     UnregisterTriggerMessage,
     UnregisterTriggerTypeMessage,
-    WorkerInfo,
 )
 from .stream import (
     IStream,
@@ -86,6 +84,18 @@ class _TraceContextError(Exception):
         self.traceparent = traceparent
 
 
+@dataclass(frozen=True)
+class _PendingInvocation:
+    """Pending invocation record kept on the SDK until the engine responds.
+
+    ``function_id`` is preserved so the timeout and error-wrapping paths
+    can name the target without plumbing it through every call site.
+    """
+
+    future: asyncio.Future[Any]
+    function_id: str
+
+
 class III:
     """WebSocket client for communication with the III Engine.
 
@@ -107,18 +117,13 @@ class III:
         self._ws: ClientConnection | None = None
         self._functions: dict[str, RemoteFunctionData] = {}
         self._services: dict[str, RegisterServiceMessage] = {}
-        self._pending: dict[str, asyncio.Future[Any]] = {}
+        self._pending: dict[str, _PendingInvocation] = {}
         self._triggers: dict[str, RegisterTriggerMessage] = {}
         self._trigger_types: dict[str, RemoteTriggerTypeData] = {}
         self._queue: list[dict[str, Any]] = []
         self._reconnect_task: asyncio.Task[None] | None = None
         self._running = False
         self._receiver_task: asyncio.Task[None] | None = None
-        self._functions_available_callbacks: set[
-            Callable[[list[FunctionInfo]], None]
-        ] = set()
-        self._functions_available_trigger: Trigger | None = None
-        self._functions_available_function_id: str | None = None
         self._reconnection_config = (
             self._options.reconnection_config or DEFAULT_RECONNECTION_CONFIG
         )
@@ -224,9 +229,16 @@ class III:
                     pass
 
         # Reject all pending invocations
-        for invocation_id, future in list(self._pending.items()):
-            if not future.done():
-                future.set_exception(Exception("iii is shutting down"))
+        for invocation_id, pending in list(self._pending.items()):
+            if not pending.future.done():
+                pending.future.set_exception(
+                    IIIInvocationError(
+                        code="SHUTDOWN",
+                        message="iii is shutting down",
+                        function_id=pending.function_id,
+                        invocation_id=invocation_id,
+                    )
+                )
         self._pending.clear()
 
         if self._ws:
@@ -401,15 +413,21 @@ class III:
             log.debug(f"Worker registered with ID: {worker_id}")
 
     def _handle_result(self, invocation_id: str, result: Any, error: Any) -> None:
-        future = self._pending.pop(invocation_id, None)
-        if not future:
+        pending = self._pending.pop(invocation_id, None)
+        if not pending:
             log.debug(f"No pending invocation: {invocation_id}")
             return
 
         if error:
-            future.set_exception(Exception(str(error)))
+            pending.future.set_exception(
+                _wrap_wire_error(
+                    error,
+                    function_id=pending.function_id,
+                    invocation_id=invocation_id,
+                )
+            )
         else:
-            future.set_result(result)
+            pending.future.set_result(result)
 
     def _inject_traceparent(self) -> str | None:
         from opentelemetry import context as otel_context
@@ -972,7 +990,9 @@ class III:
             actions.
 
         Raises:
-            TimeoutError: If the invocation times out.
+            IIITimeoutError: If the invocation times out. ``code == 'TIMEOUT'``.
+            IIIForbiddenError: If RBAC denies the invocation. ``code == 'FORBIDDEN'``.
+            IIIInvocationError: For any other engine rejection.
 
         Examples:
             >>> result = iii.trigger({'function_id': 'greet', 'payload': {'name': 'World'}})
@@ -997,7 +1017,9 @@ class III:
             The result of the function invocation, or ``None`` for void calls.
 
         Raises:
-            TimeoutError: If the invocation times out.
+            IIITimeoutError: If the invocation times out. ``code == 'TIMEOUT'``.
+            IIIForbiddenError: If RBAC denies the invocation. ``code == 'FORBIDDEN'``.
+            IIIInvocationError: For any other engine rejection.
 
         Examples:
             >>> result = await iii.trigger_async({'function_id': 'greet', 'payload': {'name': 'World'}})
@@ -1035,7 +1057,9 @@ class III:
         invocation_id = str(uuid.uuid4())
         future: asyncio.Future[Any] = self._loop.create_future()
 
-        self._pending[invocation_id] = future
+        self._pending[invocation_id] = _PendingInvocation(
+            future=future, function_id=function_id
+        )
 
         enqueue_action: TriggerActionEnqueue | None = (
             action if isinstance(action, TriggerActionEnqueue) else None
@@ -1056,152 +1080,13 @@ class III:
             return await asyncio.wait_for(future, timeout=timeout_secs)
         except asyncio.TimeoutError:
             self._pending.pop(invocation_id, None)
-            raise TimeoutError(
-                f"Invocation of '{function_id}' timed out after {timeout_ms}ms"
+            raise IIITimeoutError(
+                code="TIMEOUT",
+                message=f"invocation timed out after {timeout_ms}ms",
+                function_id=function_id,
+                invocation_id=invocation_id,
             )
 
-    def list_functions(self) -> list[FunctionInfo]:
-        """List all functions registered with the engine across all workers.
-
-        Returns:
-            A list of ``FunctionInfo`` objects describing each function.
-
-        Examples:
-            >>> for fn in iii.list_functions():
-            ...     print(fn.function_id, fn.description)
-        """
-        return self._run_on_loop(self.list_functions_async())
-
-    async def list_functions_async(self) -> list[FunctionInfo]:
-        """List all functions registered with the engine across all workers.
-
-        Returns:
-            A list of ``FunctionInfo`` objects describing each function.
-
-        Examples:
-            >>> for fn in await iii.list_functions_async():
-            ...     print(fn.function_id, fn.description)
-        """
-        result = await self.trigger_async(
-            {"function_id": "engine::functions::list", "payload": {}}
-        )
-        functions_data = result.get("functions", [])
-        return [FunctionInfo(**f) for f in functions_data]
-
-    def list_workers(self) -> list[WorkerInfo]:
-        """List all workers currently connected to the engine.
-
-        Returns:
-            A list of ``WorkerInfo`` objects with worker metadata.
-
-        Examples:
-            >>> for w in iii.list_workers():
-            ...     print(w.name, w.worker_id)
-        """
-        return self._run_on_loop(self.list_workers_async())
-
-    async def list_workers_async(self) -> list[WorkerInfo]:
-        """List all workers currently connected to the engine.
-
-        Returns:
-            A list of ``WorkerInfo`` objects with worker metadata.
-
-        Examples:
-            >>> for w in await iii.list_workers_async():
-            ...     print(w.name, w.worker_id)
-        """
-        result = await self.trigger_async(
-            {"function_id": "engine::workers::list", "payload": {}}
-        )
-        workers_data = result.get("workers", [])
-        return [WorkerInfo(**w) for w in workers_data]
-
-    def list_triggers(self, include_internal: bool = False) -> list[TriggerInfo]:
-        """List all triggers registered with the engine.
-
-        Args:
-            include_internal: If ``True``, include engine-internal triggers
-                (e.g. ``functions-available``). Defaults to ``False``.
-
-        Returns:
-            A list of ``TriggerInfo`` objects.
-
-        Examples:
-            >>> triggers = iii.list_triggers()
-            >>> internal = iii.list_triggers(include_internal=True)
-        """
-        return self._run_on_loop(self.list_triggers_async(include_internal))
-
-    async def list_triggers_async(
-        self, include_internal: bool = False
-    ) -> list[TriggerInfo]:
-        """List all triggers registered with the engine.
-
-        Args:
-            include_internal: If ``True``, include engine-internal triggers
-                (e.g. ``functions-available``). Defaults to ``False``.
-
-        Returns:
-            A list of ``TriggerInfo`` objects.
-
-        Examples:
-            >>> triggers = await iii.list_triggers_async()
-            >>> internal = await iii.list_triggers_async(include_internal=True)
-        """
-        result = await self.trigger_async(
-            {
-                "function_id": "engine::triggers::list",
-                "payload": {"include_internal": include_internal},
-            }
-        )
-        triggers_data = result.get("triggers", [])
-        return [TriggerInfo(**t) for t in triggers_data]
-
-    def list_trigger_types(
-        self, include_internal: bool = False
-    ) -> list[TriggerTypeInfo]:
-        """List all trigger types registered with the engine.
-
-        Args:
-            include_internal: If ``True``, include engine-internal trigger
-                types (e.g. ``engine::functions-available``). Defaults to ``False``.
-
-        Returns:
-            A list of ``TriggerTypeInfo`` objects with ``trigger_request_format``
-            and ``call_request_format`` schemas.
-
-        Examples:
-            >>> trigger_types = iii.list_trigger_types()
-            >>> for tt in trigger_types:
-            ...     print(tt.id, tt.trigger_request_format)
-        """
-        return self._run_on_loop(self.list_trigger_types_async(include_internal))
-
-    async def list_trigger_types_async(
-        self, include_internal: bool = False
-    ) -> list[TriggerTypeInfo]:
-        """List all trigger types registered with the engine.
-
-        Args:
-            include_internal: If ``True``, include engine-internal trigger
-                types (e.g. ``engine::functions-available``). Defaults to ``False``.
-
-        Returns:
-            A list of ``TriggerTypeInfo`` objects with ``trigger_request_format``
-            and ``call_request_format`` schemas.
-
-        Examples:
-            >>> trigger_types = await iii.list_trigger_types_async()
-        """
-        result = await self.trigger_async(
-            {
-                "function_id": "engine::trigger-types::list",
-                "payload": {"include_internal": include_internal},
-            }
-        )
-        types_data = result.get("trigger_types", [])
-        return [TriggerTypeInfo(**t) for t in types_data]
-
     def create_channel(self, buffer_size: int | None = None) -> Channel:
         """Create a streaming channel pair for worker-to-worker data transfer.
 
@@ -1305,69 +1190,6 @@ class III:
         )
         asyncio.run_coroutine_threadsafe(self._send(msg), self._loop)
 
-    def on_functions_available(
-        self, callback: Callable[[list[FunctionInfo]], None]
-    ) -> Callable[[], None]:
-        """Subscribe to function-availability events from the engine.
-
-        The callback fires whenever the set of available functions changes
-        (e.g. a new worker connects or a function is unregistered).
-
-        Args:
-            callback (Callable[[list[FunctionInfo]], None]): Receives the
-                current list of ``FunctionInfo`` objects each time
-                availability changes.
-
-        Returns:
-            A callable that unsubscribes when called.  Calling the
-            returned function removes the callback and, if no callbacks
-            remain, tears down the internal trigger.
-
-        Examples:
-            >>> def on_change(functions):
-            ...     print("Available:", [f.function_id for f in functions])
-            >>> unsub = iii.on_functions_available(on_change)
-            >>> # later ...
-            >>> unsub()
-        """
-        self._functions_available_callbacks.add(callback)
-
-        if not self._functions_available_trigger:
-            if not self._functions_available_function_id:
-                self._functions_available_function_id = (
-                    f"iii.on_functions_available.{uuid.uuid4()}"
-                )
-
-            function_id = self._functions_available_function_id
-            if function_id not in self._functions:
-
-                async def handler(data: dict[str, Any]) -> None:
-                    functions_data = data.get("functions", [])
-                    functions = [FunctionInfo(**f) for f in functions_data]
-                    for cb in list(self._functions_available_callbacks):
-                        cb(functions)
-
-                self.register_function({"id": function_id}, handler)
-
-            self._functions_available_trigger = self.register_trigger(
-                {
-                    "type": "engine::functions-available",
-                    "function_id": function_id,
-                    "config": {},
-                }
-            )
-
-        def unsubscribe() -> None:
-            self._functions_available_callbacks.discard(callback)
-            if (
-                len(self._functions_available_callbacks) == 0
-                and self._functions_available_trigger
-            ):
-                self._functions_available_trigger.unregister()
-                self._functions_available_trigger = None
-
-        return unsubscribe
-
     def create_stream(self, stream_name: str, stream: IStream[Any]) -> None:
         """Register a custom stream implementation, overriding the engine default.
 

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.4.dev1}/src/iii/types.py

@@ -10,7 +10,6 @@ from typing import TYPE_CHECKING, Any, Awaitable, Callable, Generic, Protocol, T
 from pydantic import BaseModel, ConfigDict, Field
 
 from .iii_types import (
-    FunctionInfo,
     HttpInvocationConfig,
     RegisterFunctionInput,
     RegisterFunctionMessage,
@@ -19,7 +18,6 @@ from .iii_types import (
     RegisterTriggerTypeInput,
     RegisterTriggerTypeMessage,
     StreamChannelRef,
-    TriggerInfo,
     TriggerRequest,
 )
 from .stream import IStream
@@ -80,11 +78,6 @@ class RemoteServiceFunctionData(BaseModel):
     handler: RemoteFunctionHandler
 
 
-# Type aliases for registration inputs
-# Callback type for functions available event
-FunctionsAvailableCallback = Callable[[list[FunctionInfo]], None]
-
-
 class IIIClient(Protocol):
     """Protocol for III client implementations."""
 
@@ -108,18 +101,10 @@ class IIIClient(Protocol):
 
     def unregister_trigger_type(self, trigger_type: RegisterTriggerTypeInput | dict[str, Any]) -> None: ...
 
-    def list_trigger_types(self, include_internal: bool = False) -> list[Any]: ...
-
     def create_channel(self, buffer_size: int | None = None) -> Channel: ...
 
     def create_stream(self, stream_name: str, stream: IStream[Any]) -> None: ...
 
-    def list_functions(self) -> list[FunctionInfo]: ...
-
-    def list_triggers(self, include_internal: bool = False) -> list[TriggerInfo]: ...
-
-    def on_functions_available(self, callback: FunctionsAvailableCallback) -> Callable[[], None]: ...
-
     def shutdown(self) -> None: ...
 
 

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.4.dev1}/tests/test_api_triggers.py

@@ -194,6 +194,42 @@ async def test_custom_status_code(engine_http_url, iii_client: III):
     trigger.unregister()
 
 
+@pytest.mark.asyncio
+async def test_content_type_on_api_response_return(engine_http_url, iii_client: III):
+    """Returning an ApiResponse dict with headers should set the response Content-Type."""
+    xml_body = '<?xml version="1.0" encoding="UTF-8"?><note><to>user</to><body>hello</body></note>'
+
+    def handler(_input_data):
+        return {
+            "status_code": 200,
+            "headers": {"Content-Type": "text/xml"},
+            "body": xml_body,
+        }
+
+    fn_ref = iii_client.register_function({"id": "test.api.xml.return.py"}, handler)
+    trigger = iii_client.register_trigger(
+        {
+            "type": "http",
+            "function_id": "test.api.xml.return.py",
+            "config": {
+                "api_path": "test/py/xml-return",
+                "http_method": "POST",
+            },
+        }
+    )
+
+    time.sleep(0.3)
+
+    async with aiohttp.ClientSession() as session:
+        async with session.post(f"{engine_http_url}/test/py/xml-return") as resp:
+            assert resp.status == 200
+            assert resp.headers.get("content-type") == "text/xml"
+            assert await resp.text() == xml_body
+
+    fn_ref.unregister()
+    trigger.unregister()
+
+
 @pytest.mark.asyncio
 async def test_download_pdf_streaming(engine_http_url, iii_client: III):
     """Stream a PDF file as a download response."""

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.4.dev1}/tests/test_async_api.py

@@ -10,21 +10,6 @@ def test_trigger_async_is_coroutine_function():
     assert inspect.iscoroutinefunction(III.trigger_async)
 
 
-def test_list_functions_async_is_coroutine_function():
-    assert hasattr(III, "list_functions_async")
-    assert inspect.iscoroutinefunction(III.list_functions_async)
-
-
-def test_list_workers_async_is_coroutine_function():
-    assert hasattr(III, "list_workers_async")
-    assert inspect.iscoroutinefunction(III.list_workers_async)
-
-
-def test_list_triggers_async_is_coroutine_function():
-    assert hasattr(III, "list_triggers_async")
-    assert inspect.iscoroutinefunction(III.list_triggers_async)
-
-
 def test_create_channel_async_is_coroutine_function():
     assert hasattr(III, "create_channel_async")
     assert inspect.iscoroutinefunction(III.create_channel_async)
@@ -44,9 +29,6 @@ def test_async_methods_have_docstrings():
     """All public async methods must have docstrings."""
     async_methods = [
         "trigger_async",
-        "list_functions_async",
-        "list_workers_async",
-        "list_triggers_async",
         "create_channel_async",
         "connect_async",
         "shutdown_async",

{iii_sdk-0.11.3.dev1 → iii_sdk-0.11.4.dev1}/tests/test_bridge.py

@@ -4,7 +4,7 @@ import asyncio
 
 import pytest
 
-from iii import TriggerAction
+from iii import FunctionInfo, TriggerAction
 from iii.iii import III
 
 
@@ -21,7 +21,10 @@ async def wait_for(condition, timeout=5.0, interval=0.1):
 @pytest.mark.asyncio
 async def test_connect_successfully(iii_client: III):
     """SDK connects to the engine and can list functions."""
-    functions = iii_client.list_functions()
+    result = iii_client.trigger(
+        {"function_id": "engine::functions::list", "payload": {}}
+    )
+    functions = [FunctionInfo(**f) for f in result.get("functions", [])]
     assert isinstance(functions, list)
 
 
@@ -83,13 +86,16 @@ async def test_invoke_function_fire_and_forget(iii_client: III):
 
 @pytest.mark.asyncio
 async def test_list_registered_functions(iii_client: III):
-    """Registered function IDs appear in list_functions()."""
+    """Registered function IDs appear in the engine functions list."""
     fn1 = iii_client.register_function({"id": "test.bridge.py.list.func1"}, lambda _: {})
     fn2 = iii_client.register_function({"id": "test.bridge.py.list.func2"}, lambda _: {})
     await asyncio.sleep(0.3)
 
     try:
-        functions = iii_client.list_functions()
+        result = iii_client.trigger(
+            {"function_id": "engine::functions::list", "payload": {}}
+        )
+        functions = [FunctionInfo(**f) for f in result.get("functions", [])]
         function_ids = [f.function_id for f in functions]
 
         assert "test.bridge.py.list.func1" in function_ids