iii-sdk 0.12.0.dev1__tar.gz → 0.14.0.dev1__tar.gz

{iii_sdk-0.12.0.dev1 → iii_sdk-0.14.0.dev1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: iii-sdk
-Version: 0.12.0.dev1
+Version: 0.14.0.dev1
 Summary: III SDK for Python
-Project-URL: Homepage, https://github.com/iii-hq/sdk
-Project-URL: Repository, https://github.com/iii-hq/sdk
+Project-URL: Homepage, https://github.com/iii-hq/iii
+Project-URL: Repository, https://github.com/iii-hq/iii
 Author: III
 License: Apache-2.0
 Keywords: iii,sdk
@@ -14,6 +14,8 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
+Requires-Dist: opentelemetry-api>=1.25
+Requires-Dist: opentelemetry-sdk>=1.25
 Requires-Dist: pydantic>=2.0
 Requires-Dist: websockets>=12.0
 Provides-Extra: dev
@@ -21,15 +23,10 @@ Requires-Dist: aiohttp>=3.9; extra == 'dev'
 Requires-Dist: anyio>=4.0; extra == 'dev'
 Requires-Dist: griffe>=1.0; extra == 'dev'
 Requires-Dist: mypy>=1.8; extra == 'dev'
-Requires-Dist: opentelemetry-api>=1.25; extra == 'dev'
-Requires-Dist: opentelemetry-sdk>=1.25; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov>=6.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.2; extra == 'dev'
-Provides-Extra: otel
-Requires-Dist: opentelemetry-api>=1.25; extra == 'otel'
-Requires-Dist: opentelemetry-sdk>=1.25; extra == 'otel'
 Description-Content-Type: text/markdown
 
 # iii-sdk
@@ -56,30 +53,31 @@ iii = register_worker("ws://localhost:49134")
 def greet(data):
     return {"message": f"Hello, {data['name']}!"}
 
-iii.register_function({"id": "greet"}, greet)
+iii.register_function("hello::greet", greet)
 
 iii.register_trigger({
     "type": "http",
-    "function_id": "greet",
+    "function_id": "hello::greet",
     "config": {"api_path": "/greet", "http_method": "POST"},
 })
 
 iii.connect()
 
-result = iii.trigger({"function_id": "greet", "payload": {"name": "world"}})
+result = iii.trigger({"function_id": "hello::greet", "payload": {"name": "world"}})
 print(result)  # {"message": "Hello, world!"}
 ```
 
 ## API
 
-| Operation                | Signature                                         | Description                                            |
-| ------------------------ | ------------------------------------------------- | ------------------------------------------------------ |
-| Initialize               | `register_worker(url, options?)`                  | Create an SDK instance and auto-connect                |
-| Register function        | `iii.register_function({"id": id}, handler)`      | Register a function that can be invoked by name        |
-| Register trigger         | `iii.register_trigger({"type": ..., "function_id": ..., "config": ...})` | Bind a trigger (HTTP, cron, queue, etc.) to a function |
-| Invoke (await result)    | `iii.trigger({"function_id": id, "payload": data})` | Invoke a function and wait for the result           |
-| Invoke (fire-and-forget) | `iii.trigger({"function_id": id, ..., "action": TriggerAction.Void()})` | Fire-and-forget |
-| Shutdown                 | `iii.shutdown()`                                  | Disconnect and stop background thread                  |
+| Operation                | Signature                                                                              | Description                                            |
+| ------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Initialize               | `register_worker(url, options?)`                                                       | Create an SDK instance and auto-connect                |
+| Register function        | `iii.register_function(id, handler)`                                                   | Register a function that can be invoked by name        |
+| Register trigger         | `iii.register_trigger({"type": ..., "function_id": ..., "config": ...})`               | Bind a trigger (HTTP, cron, queue, etc.) to a function |
+| Invoke (await result)    | `iii.trigger({"function_id": id, "payload": data})`                                    | Invoke a function and wait for the result              |
+| Invoke (fire-and-forget) | `iii.trigger({"function_id": id, ..., "action": TriggerAction.Void()})`                | Fire-and-forget                                        |
+| Invoke (enqueue)         | `iii.trigger({"function_id": id, ..., "action": TriggerAction.Enqueue(queue="name")})` | Route invocation through a named queue                 |
+| Shutdown                 | `iii.shutdown()`                                                                       | Disconnect and stop background thread                  |
 
 `register_worker()` creates the SDK instance and auto-connects to the engine.
 
@@ -89,7 +87,7 @@ print(result)  # {"message": "Hello, world!"}
 def create_order(data):
     return {"status_code": 201, "body": {"id": "123", "item": data["body"]["item"]}}
 
-iii.register_function({"id": "orders.create"}, create_order)
+iii.register_function("orders::create", create_order)
 ```
 
 ### Registering Triggers
@@ -97,7 +95,7 @@ iii.register_function({"id": "orders.create"}, create_order)
 ```python
 iii.register_trigger({
     "type": "http",
-    "function_id": "orders.create",
+    "function_id": "orders::create",
     "config": {"api_path": "/orders", "http_method": "POST"},
 })
 ```
@@ -105,17 +103,9 @@ iii.register_trigger({
 ### Invoking Functions
 
 ```python
-result = iii.trigger({"function_id": "orders.create", "payload": {"body": {"item": "widget"}}})
+result = iii.trigger({"function_id": "orders::create", "payload": {"body": {"item": "widget"}}})
 ```
 
-## Modules
-
-| Import          | What it provides                  |
-| --------------- | --------------------------------- |
-| `iii`           | Core SDK (`III`, types)           |
-| `iii.stream`    | Stream client for real-time state |
-| `iii.telemetry` | OpenTelemetry integration         |
-
 ## Development
 
 ### Install in development mode

{iii_sdk-0.12.0.dev1 → iii_sdk-0.14.0.dev1}/README.md

@@ -22,30 +22,31 @@ iii = register_worker("ws://localhost:49134")
 def greet(data):
     return {"message": f"Hello, {data['name']}!"}
 
-iii.register_function({"id": "greet"}, greet)
+iii.register_function("hello::greet", greet)
 
 iii.register_trigger({
     "type": "http",
-    "function_id": "greet",
+    "function_id": "hello::greet",
     "config": {"api_path": "/greet", "http_method": "POST"},
 })
 
 iii.connect()
 
-result = iii.trigger({"function_id": "greet", "payload": {"name": "world"}})
+result = iii.trigger({"function_id": "hello::greet", "payload": {"name": "world"}})
 print(result)  # {"message": "Hello, world!"}
 ```
 
 ## API
 
-| Operation                | Signature                                         | Description                                            |
-| ------------------------ | ------------------------------------------------- | ------------------------------------------------------ |
-| Initialize               | `register_worker(url, options?)`                  | Create an SDK instance and auto-connect                |
-| Register function        | `iii.register_function({"id": id}, handler)`      | Register a function that can be invoked by name        |
-| Register trigger         | `iii.register_trigger({"type": ..., "function_id": ..., "config": ...})` | Bind a trigger (HTTP, cron, queue, etc.) to a function |
-| Invoke (await result)    | `iii.trigger({"function_id": id, "payload": data})` | Invoke a function and wait for the result           |
-| Invoke (fire-and-forget) | `iii.trigger({"function_id": id, ..., "action": TriggerAction.Void()})` | Fire-and-forget |
-| Shutdown                 | `iii.shutdown()`                                  | Disconnect and stop background thread                  |
+| Operation                | Signature                                                                              | Description                                            |
+| ------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Initialize               | `register_worker(url, options?)`                                                       | Create an SDK instance and auto-connect                |
+| Register function        | `iii.register_function(id, handler)`                                                   | Register a function that can be invoked by name        |
+| Register trigger         | `iii.register_trigger({"type": ..., "function_id": ..., "config": ...})`               | Bind a trigger (HTTP, cron, queue, etc.) to a function |
+| Invoke (await result)    | `iii.trigger({"function_id": id, "payload": data})`                                    | Invoke a function and wait for the result              |
+| Invoke (fire-and-forget) | `iii.trigger({"function_id": id, ..., "action": TriggerAction.Void()})`                | Fire-and-forget                                        |
+| Invoke (enqueue)         | `iii.trigger({"function_id": id, ..., "action": TriggerAction.Enqueue(queue="name")})` | Route invocation through a named queue                 |
+| Shutdown                 | `iii.shutdown()`                                                                       | Disconnect and stop background thread                  |
 
 `register_worker()` creates the SDK instance and auto-connects to the engine.
 
@@ -55,7 +56,7 @@ print(result)  # {"message": "Hello, world!"}
 def create_order(data):
     return {"status_code": 201, "body": {"id": "123", "item": data["body"]["item"]}}
 
-iii.register_function({"id": "orders.create"}, create_order)
+iii.register_function("orders::create", create_order)
 ```
 
 ### Registering Triggers
@@ -63,7 +64,7 @@ iii.register_function({"id": "orders.create"}, create_order)
 ```python
 iii.register_trigger({
     "type": "http",
-    "function_id": "orders.create",
+    "function_id": "orders::create",
     "config": {"api_path": "/orders", "http_method": "POST"},
 })
 ```
@@ -71,17 +72,9 @@ iii.register_trigger({
 ### Invoking Functions
 
 ```python
-result = iii.trigger({"function_id": "orders.create", "payload": {"body": {"item": "widget"}}})
+result = iii.trigger({"function_id": "orders::create", "payload": {"body": {"item": "widget"}}})
 ```
 
-## Modules
-
-| Import          | What it provides                  |
-| --------------- | --------------------------------- |
-| `iii`           | Core SDK (`III`, types)           |
-| `iii.stream`    | Stream client for real-time state |
-| `iii.telemetry` | OpenTelemetry integration         |
-
 ## Development
 
 ### Install in development mode

{iii_sdk-0.12.0.dev1 → iii_sdk-0.14.0.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iii-sdk"
-version = "0.12.0.dev1"
+version = "0.14.0.dev1"
 description = "III SDK for Python"
 authors = [{ name = "III" }]
 license = { text = "Apache-2.0" }
@@ -22,17 +22,15 @@ classifiers = [
 dependencies = [
     "websockets>=12.0",
     "pydantic>=2.0",
+    "opentelemetry-api>=1.25",
+    "opentelemetry-sdk>=1.25",
 ]
 
 [project.urls]
-Homepage = "https://github.com/iii-hq/sdk"
-Repository = "https://github.com/iii-hq/sdk"
+Homepage = "https://github.com/iii-hq/iii"
+Repository = "https://github.com/iii-hq/iii"
 
 [project.optional-dependencies]
-otel = [
-    "opentelemetry-api>=1.25",
-    "opentelemetry-sdk>=1.25",
-]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
@@ -41,8 +39,6 @@ dev = [
     "aiohttp>=3.9",
     "mypy>=1.8",
     "ruff>=0.2",
-    "opentelemetry-api>=1.25",
-    "opentelemetry-sdk>=1.25",
     "griffe>=1.0",
 ]
 

{iii_sdk-0.12.0.dev1 → iii_sdk-0.14.0.dev1}/src/iii/__init__.py

@@ -1,6 +1,8 @@
 """III SDK for Python."""
 
+from .baggage_span_processor import DEFAULT_ALLOWLIST, BaggageSpanProcessor
 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
@@ -20,7 +22,6 @@ from .iii_types import (
     OnTriggerTypeRegistrationInput,
     OnTriggerTypeRegistrationResult,
     RegisterFunctionFormat,
-    RegisterFunctionInput,
     RegisterFunctionMessage,
     RegisterServiceInput,
     RegisterTriggerInput,
@@ -35,6 +36,18 @@ from .iii_types import (
     TriggerTypeInfo,
 )
 from .logger import Logger
+from .payload import (
+    REDACTED_PLACEHOLDER,
+    redact,
+    redact_and_truncate,
+    resolve_max_bytes_from_env,
+)
+from .span_ops import (
+    current_span_is_recording,
+    record_span_event,
+    set_current_span_attribute,
+    set_current_span_error,
+)
 from .stream import (
     IStream,
     StreamChangeEvent,
@@ -59,9 +72,24 @@ from .types import (
 from .utils import http
 
 __all__ = [
+    # Telemetry helpers
+    "BaggageSpanProcessor",
+    "DEFAULT_ALLOWLIST",
+    "REDACTED_PLACEHOLDER",
+    "current_span_is_recording",
+    "record_span_event",
+    "set_current_span_attribute",
+    "set_current_span_error",
+    "redact",
+    "redact_and_truncate",
+    "resolve_max_bytes_from_env",
     # Channels
     "ChannelReader",
     "ChannelWriter",
+    # Errors
+    "IIIForbiddenError",
+    "IIIInvocationError",
+    "IIITimeoutError",
     # Core
     "FunctionRef",
     "InitOptions",
@@ -87,7 +115,6 @@ __all__ = [
     "HttpInvocationConfig",
     "MessageType",
     "RegisterFunctionFormat",
-    "RegisterFunctionInput",
     "RegisterFunctionMessage",
     "RegisterServiceInput",
     "RegisterTriggerInput",

iii_sdk-0.14.0.dev1/src/iii/baggage_span_processor.py

@@ -0,0 +1,42 @@
+"""Baggage -> span attribute processor."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from opentelemetry import baggage
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor
+
+#: DEFAULT_ALLOWLIST drift across languages would break worker chains;
+#: lockstep tests in each SDK pin this constant at CI time.
+DEFAULT_ALLOWLIST: tuple[str, ...] = (
+    "iii.session.id",
+    "iii.message.id",
+    "iii.function.id",
+)
+
+
+class BaggageSpanProcessor(SpanProcessor):
+
+    def __init__(self, allowlist: Sequence[str] = DEFAULT_ALLOWLIST) -> None:
+        self._allowlist: tuple[str, ...] = tuple(allowlist)
+
+    def on_start(self, span: Span, parent_context: Context | None = None) -> None:
+        # NoOp guard: skip allocation when sampler drops the span.
+        if not span.is_recording():
+            return
+
+        for key in self._allowlist:
+            value = baggage.get_baggage(key, parent_context)
+            if value is not None:
+                span.set_attribute(key, str(value))
+
+    def on_end(self, span: ReadableSpan) -> None:  # noqa: ARG002
+        pass
+
+    def shutdown(self) -> None:
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:  # noqa: ARG002
+        return True

iii_sdk-0.14.0.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,
+    )