iii-sdk 0.19.0.dev2__tar.gz → 0.19.0.dev3__tar.gz

{iii_sdk-0.19.0.dev2 → iii_sdk-0.19.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iii-sdk
-Version: 0.19.0.dev2
+Version: 0.19.0.dev3
 Summary: III SDK for Python
 Project-URL: Homepage, https://github.com/iii-hq/iii
 Project-URL: Repository, https://github.com/iii-hq/iii
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
-Requires-Dist: iii-observability==0.19.0.dev2
+Requires-Dist: iii-observability==0.19.0.dev3
 Requires-Dist: opentelemetry-api>=1.25
 Requires-Dist: pydantic>=2.0
 Requires-Dist: websockets>=12.0

{iii_sdk-0.19.0.dev2 → iii_sdk-0.19.0.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iii-sdk"
-version = "0.19.0.dev2"
+version = "0.19.0.dev3"
 description = "III SDK for Python"
 authors = [{ name = "III" }]
 license = { text = "Apache-2.0" }
@@ -23,7 +23,7 @@ dependencies = [
     "websockets>=12.0",
     "pydantic>=2.0",
     "opentelemetry-api>=1.25",
-    "iii-observability==0.19.0.dev2",
+    "iii-observability==0.19.0.dev3",
 ]
 
 [project.urls]

{iii_sdk-0.19.0.dev2 → iii_sdk-0.19.0.dev3}/src/iii/__init__.py

@@ -1,34 +1,7 @@
 """III SDK for Python."""
 
-from iii_observability import (
-    DEFAULT_ALLOWLIST,
-    REDACTED_PLACEHOLDER,
-    BaggageSpanProcessor,
-    Logger,
-    OtelConfig,
-    ReconnectionConfig,
-    current_span_id,
-    current_span_is_recording,
-    current_trace_id,
-    execute_traced_request,
-    extract_baggage,
-    extract_traceparent,
-    flush_otel,
-    init_otel,
-    inject_baggage,
-    inject_traceparent,
-    record_span_event,
-    redact,
-    redact_and_truncate,
-    resolve_max_bytes_from_env,
-    set_current_span_attribute,
-    set_current_span_error,
-    shutdown_otel,
-    with_span,
-)
-
 from .channels import ChannelReader, ChannelWriter
-from .errors import IIIForbiddenError, IIIInvocationError, IIITimeoutError
+from .errors import IIIInvocationError
 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, TelemetryOptions
@@ -80,40 +53,14 @@ from .types import (
 from .utils import http
 
 __all__ = [
-    # Telemetry helpers
-    "BaggageSpanProcessor",
-    "DEFAULT_ALLOWLIST",
-    "REDACTED_PLACEHOLDER",
-    "current_span_id",
-    "current_span_is_recording",
-    "current_trace_id",
-    "execute_traced_request",
-    "extract_baggage",
-    "extract_traceparent",
-    "flush_otel",
-    "init_otel",
-    "inject_baggage",
-    "inject_traceparent",
-    "record_span_event",
-    "redact",
-    "redact_and_truncate",
-    "resolve_max_bytes_from_env",
-    "set_current_span_attribute",
-    "set_current_span_error",
-    "shutdown_otel",
-    "with_span",
     # Channels
     "ChannelReader",
     "ChannelWriter",
     # Errors
-    "IIIForbiddenError",
     "IIIInvocationError",
-    "IIITimeoutError",
     # Core
     "FunctionRef",
     "InitOptions",
-    "OtelConfig",
-    "ReconnectionConfig",
     "register_worker",
     "TelemetryOptions",
     "TriggerAction",
@@ -142,8 +89,6 @@ __all__ = [
     "TriggerActionEnqueue",
     "TriggerActionVoid",
     "TriggerRequest",
-    # Logger
-    "Logger",
     # Triggers
     "Trigger",
     "TriggerConfig",

{iii_sdk-0.19.0.dev2 → iii_sdk-0.19.0.dev3}/src/iii/errors.py

@@ -6,13 +6,10 @@ 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``.
+    Inspect ``err.code`` to react to a specific category (e.g.
+    ``'FORBIDDEN'`` for RBAC denials, ``'TIMEOUT'`` for timeouts). Catch
+    this class to handle every rejection. ``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
@@ -36,26 +33,18 @@ class IIIInvocationError(Exception):
         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.
+    """Convert a wire ``ErrorBody``-shaped dict into an ``IIIInvocationError``.
 
-    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.
+    The ``code`` field distinguishes categories (e.g. ``'FORBIDDEN'``,
+    ``'TIMEOUT'``). Malformed shapes (non-dict, missing fields, non-string
+    values) fall back to ``code='UNKNOWN'`` so no rejection path prints as a
+    raw dict repr.
     """
     if isinstance(error, dict):
         raw_code = error.get("code")
@@ -67,12 +56,7 @@ def _wrap_wire_error(
         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(
+        return IIIInvocationError(
             code=code,
             message=message,
             function_id=function_id,

{iii_sdk-0.19.0.dev2 → iii_sdk-0.19.0.dev3}/src/iii/iii.py

@@ -18,7 +18,7 @@ from iii_observability import OtelConfig
 from websockets.asyncio.client import ClientConnection
 
 from .channels import ChannelReader, ChannelWriter
-from .errors import IIIInvocationError, IIITimeoutError, _wrap_wire_error
+from .errors import IIIInvocationError, _wrap_wire_error
 from .format_utils import extract_request_format, extract_response_format
 from .iii_constants import (
     DEFAULT_RECONNECTION_CONFIG,
@@ -482,6 +482,7 @@ class III:
 
     async def _invoke_with_otel_context(
         self,
+        function_id: str,
         handler: Callable[[Any], Awaitable[Any]],
         data: Any,
         traceparent: str | None,
@@ -509,10 +510,16 @@ class III:
         )
         payload_max_bytes = resolve_max_bytes_from_env()
 
+        # INTERNAL and named `execute` (not `call`/`trigger`): the engine
+        # already emits the SERVER `call <fn>` span for this hop AND a
+        # `trigger <fn>` span from fire_triggers. Reusing either name would
+        # duplicate an engine span under the worker's service. `execute` is
+        # unique, so the worker handler span reads as a clean internal child
+        # of the engine's call span (and is collapsible by a single rule).
         with tracer.start_as_current_span(
-            f"call {handler.__name__}",
+            f"execute {function_id}",
             context=parent_ctx,
-            kind=trace.SpanKind.SERVER,
+            kind=trace.SpanKind.INTERNAL,
         ) as span:
             if trace_payloads and span.is_recording():
                 input_json, input_truncated = redact_and_truncate(data, payload_max_bytes)
@@ -620,7 +627,7 @@ class III:
         if not invocation_id:
             task = asyncio.create_task(
                 self._invoke_with_otel_context(
-                    func.handler, resolved_data, traceparent, baggage
+                    path, func.handler, resolved_data, traceparent, baggage
                 )
             )
             task.add_done_callback(self._log_task_exception)
@@ -628,6 +635,7 @@ class III:
 
         try:
             result, response_traceparent = await self._invoke_with_otel_context(
+                path,
                 func.handler,
                 resolved_data,
                 traceparent,
@@ -1073,9 +1081,9 @@ class III:
             actions.
 
         Raises:
-            IIITimeoutError: If the invocation times out. ``code == 'TIMEOUT'``.
-            IIIForbiddenError: If RBAC denies the invocation. ``code == 'FORBIDDEN'``.
-            IIIInvocationError: For any other engine rejection.
+            IIIInvocationError: For any engine rejection. Inspect ``code``:
+                ``'TIMEOUT'`` if the invocation timed out, ``'FORBIDDEN'`` if
+                RBAC denied it.
 
         Examples:
             >>> result = iii.trigger({'function_id': 'greet', 'payload': {'name': 'World'}})
@@ -1100,9 +1108,9 @@ class III:
             The result of the function invocation, or ``None`` for void calls.
 
         Raises:
-            IIITimeoutError: If the invocation times out. ``code == 'TIMEOUT'``.
-            IIIForbiddenError: If RBAC denies the invocation. ``code == 'FORBIDDEN'``.
-            IIIInvocationError: For any other engine rejection.
+            IIIInvocationError: For any engine rejection. Inspect ``code``:
+                ``'TIMEOUT'`` if the invocation timed out, ``'FORBIDDEN'`` if
+                RBAC denied it.
 
         Examples:
             >>> result = await iii.trigger_async({'function_id': 'greet', 'payload': {'name': 'World'}})
@@ -1163,7 +1171,7 @@ class III:
             return await asyncio.wait_for(future, timeout=timeout_secs)
         except asyncio.TimeoutError:
             self._pending.pop(invocation_id, None)
-            raise IIITimeoutError(
+            raise IIIInvocationError(
                 code="TIMEOUT",
                 message=f"invocation timed out after {timeout_ms}ms",
                 function_id=function_id,

{iii_sdk-0.19.0.dev2 → iii_sdk-0.19.0.dev3}/tests/test_errors.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import pytest
 
-from iii import IIIForbiddenError, IIIInvocationError, IIITimeoutError
+from iii import IIIInvocationError
 from iii.errors import _wrap_wire_error
 
 
@@ -57,34 +57,19 @@ class TestIIIInvocationError:
         assert str(err) == "TIMEOUT: gone"
 
 
-class TestSubclassHierarchy:
-    def test_forbidden_is_invocation_error(self) -> None:
-        err = IIIForbiddenError(code="FORBIDDEN", message="x")
-        assert isinstance(err, IIIInvocationError)
-        assert isinstance(err, IIIForbiddenError)
-        assert isinstance(err, Exception)
-
-    def test_timeout_is_invocation_error(self) -> None:
-        err = IIITimeoutError(code="TIMEOUT", message="x")
-        assert isinstance(err, IIIInvocationError)
-        assert isinstance(err, IIITimeoutError)
-        assert isinstance(err, Exception)
+class TestCodeDiscrimination:
+    def test_categories_discriminated_by_code(self) -> None:
+        """Categories are distinguished by ``code``, not by subclass."""
+        for code in ("FORBIDDEN", "TIMEOUT", "UNKNOWN"):
+            err = IIIInvocationError(code=code, message="x")
+            assert isinstance(err, IIIInvocationError)
+            assert isinstance(err, Exception)
+            assert err.code == code
 
-    def test_except_ordering_catches_subclass_first(self) -> None:
-        """`except IIIForbiddenError` fires before `except IIIInvocationError`."""
-        caught: str | None = None
-        try:
-            raise IIIForbiddenError(code="FORBIDDEN", message="x")
-        except IIIForbiddenError:
-            caught = "forbidden"
-        except IIIInvocationError:
-            caught = "base"
-        assert caught == "forbidden"
-
-    def test_base_catches_every_subclass(self) -> None:
+    def test_base_catches_every_category(self) -> None:
         for err in (
-            IIIForbiddenError(code="FORBIDDEN", message="x"),
-            IIITimeoutError(code="TIMEOUT", message="x"),
+            IIIInvocationError(code="FORBIDDEN", message="x"),
+            IIIInvocationError(code="TIMEOUT", message="x"),
             IIIInvocationError(code="UNKNOWN", message="x"),
         ):
             try:
@@ -95,30 +80,30 @@ class TestSubclassHierarchy:
     def test_except_exception_still_works(self) -> None:
         """Migration guarantee: existing `except Exception:` handlers still catch."""
         try:
-            raise IIIForbiddenError(code="FORBIDDEN", message="x")
+            raise IIIInvocationError(code="FORBIDDEN", message="x")
         except Exception as got:
             assert isinstance(got, IIIInvocationError)
 
 
 class TestWrapWireError:
-    def test_forbidden_dict_dispatches_to_forbidden_error(self) -> None:
+    def test_forbidden_dict_sets_forbidden_code(self) -> None:
         err = _wrap_wire_error(
             {"code": "FORBIDDEN", "message": "not allowed"},
             function_id="engine::functions::list",
             invocation_id="inv-1",
         )
-        assert isinstance(err, IIIForbiddenError)
+        assert type(err) is IIIInvocationError
         assert err.code == "FORBIDDEN"
         assert err.function_id == "engine::functions::list"
         assert err.invocation_id == "inv-1"
 
-    def test_timeout_dict_dispatches_to_timeout_error(self) -> None:
+    def test_timeout_dict_sets_timeout_code(self) -> None:
         err = _wrap_wire_error(
             {"code": "TIMEOUT", "message": "gone"},
             function_id="api::slow",
             invocation_id=None,
         )
-        assert isinstance(err, IIITimeoutError)
+        assert type(err) is IIIInvocationError
         assert err.code == "TIMEOUT"
 
     def test_unknown_code_falls_back_to_base(self) -> None:

{iii_sdk-0.19.0.dev2 → iii_sdk-0.19.0.dev3}/tests/test_invocation_exception.py

@@ -34,7 +34,7 @@ async def test_invoke_with_otel_context_records_exception_with_stacktrace():
             raise ValueError("test invocation error")
 
         with pytest.raises(_TraceContextError) as exc_info:
-            await client._invoke_with_otel_context(failing_handler, {"key": "value"}, None, None)
+            await client._invoke_with_otel_context("test.fn", failing_handler, {"key": "value"}, None, None)
         assert isinstance(exc_info.value.__cause__, ValueError)
         assert "test invocation error" in str(exc_info.value.__cause__)
 
@@ -81,7 +81,7 @@ async def test_invoke_with_otel_context_success_no_exception():
         async def success_handler(data):
             return {"result": "ok"}
 
-        result, traceparent = await client._invoke_with_otel_context(success_handler, {"key": "value"}, None, None)
+        result, traceparent = await client._invoke_with_otel_context("test.fn", success_handler, {"key": "value"}, None, None)
 
         assert result == {"result": "ok"}
 

{iii_sdk-0.19.0.dev2 → iii_sdk-0.19.0.dev3}/tests/test_rbac_workers.py

@@ -8,7 +8,6 @@ import pytest
 from iii import (
     AuthInput,
     AuthResult,
-    IIIForbiddenError,
     IIIInvocationError,
     InitOptions,
     MiddlewareFunctionInput,
@@ -350,22 +349,21 @@ class TestRbacWorkers:
             iii_client.shutdown()
 
     def test_forbidden_wrapped_as_typed_error(self, iii_server):
-        """FORBIDDEN rejections surface as IIIForbiddenError with function_id set
-        and the engine's remediation phrase in the message."""
+        """FORBIDDEN rejections surface as IIIInvocationError (code='FORBIDDEN')
+        with function_id set and the engine's remediation phrase in the message."""
         iii_client = register_worker(
             EW_URL,
             InitOptions(otel={"enabled": False}, headers={"x-test-token": "valid-token"}),
         )
 
         try:
-            with pytest.raises(IIIForbiddenError) as excinfo:
+            with pytest.raises(IIIInvocationError) as excinfo:
                 iii_client.trigger({
                     "function_id": "test::ew::private",
                     "payload": {},
                 })
 
             err = excinfo.value
-            assert isinstance(err, IIIInvocationError)  # base class
             assert err.code == "FORBIDDEN"
             assert err.function_id == "test::ew::private"
             assert "FORBIDDEN" in str(err)
@@ -432,7 +430,7 @@ class TestRbacWorkers:
         try:
             def handler(data: dict) -> dict:
                 # If the carve-out regresses, this nested trigger surfaces
-                # IIIForbiddenError and the handler propagates it as a failure.
+                # IIIInvocationError (code='FORBIDDEN') and the handler propagates it as a failure.
                 iii_client.trigger({
                     "function_id": "engine::log::info",
                     "payload": {
@@ -473,7 +471,7 @@ class TestRbacWorkers:
 
         try:
             # No exception == carve-out is working. If this raises
-            # IIIForbiddenError, the carve-out regressed.
+            # IIIInvocationError (code='FORBIDDEN'), the carve-out regressed.
             iii_client.trigger({
                 "function_id": "engine::log::info",
                 "payload": {"message": "carve-out direct invocation"},

{iii_sdk-0.19.0.dev2 → iii_sdk-0.19.0.dev3}/uv.lock

@@ -546,7 +546,7 @@ wheels = [
 
 [[package]]
 name = "iii-observability"
-version = "0.16.0.dev3"
+version = "0.18.0"
 source = { editable = "../observability" }
 dependencies = [
     { name = "httpx" },
@@ -572,7 +572,7 @@ provides-extras = ["dev"]
 
 [[package]]
 name = "iii-sdk"
-version = "0.16.0.dev3"
+version = "0.18.0"
 source = { editable = "." }
 dependencies = [
     { name = "iii-observability" },