iii-sdk 0.19.7.dev1__tar.gz → 0.20.0.dev1__tar.gz

{iii_sdk-0.19.7.dev1 → iii_sdk-0.20.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iii-sdk
-Version: 0.19.7.dev1
+Version: 0.20.0.dev1
 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.7.dev1
+Requires-Dist: iii-helpers==0.20.0.dev1
 Requires-Dist: opentelemetry-api>=1.25
 Requires-Dist: pydantic>=2.0
 Requires-Dist: websockets>=12.0

{iii_sdk-0.19.7.dev1 → iii_sdk-0.20.0.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iii-sdk"
-version = "0.19.7.dev1"
+version = "0.20.0.dev1"
 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.7.dev1",
+    "iii-helpers==0.20.0.dev1",
 ]
 
 [project.urls]
@@ -31,7 +31,7 @@ Homepage = "https://github.com/iii-hq/iii"
 Repository = "https://github.com/iii-hq/iii"
 
 [tool.uv.sources]
-iii-observability = { path = "../observability", editable = true }
+iii-helpers = { path = "../helpers", editable = true }
 
 [project.optional-dependencies]
 dev = [

iii_sdk-0.20.0.dev1/src/iii/__init__.py

@@ -0,0 +1,44 @@
+"""III SDK for Python."""
+
+from iii_helpers.queue import EnqueueResult
+
+from .errors import InvocationError
+from .iii import TriggerAction, register_worker
+from .iii_constants import (
+    InitOptions,
+    TelemetryOptions,
+)
+from .iii_types import (
+    MiddlewareFunctionInput,
+    TriggerActionEnqueue,
+    TriggerActionVoid,
+)
+from .stream import IStream
+from .types import (
+    IIIClient,
+    StreamRequest,
+    StreamResponse,
+)
+
+__all__ = [
+    # Errors
+    "InvocationError",
+    # Core
+    "InitOptions",
+    "register_worker",
+    "TelemetryOptions",
+    "TriggerAction",
+    # RBAC types
+    "MiddlewareFunctionInput",
+    # Message types
+    "TriggerActionEnqueue",
+    "TriggerActionVoid",
+    # Queue
+    "EnqueueResult",
+    # Types
+    "IIIClient",
+    "StreamRequest",
+    "StreamResponse",
+    # Stream
+    "IStream",
+]

iii_sdk-0.20.0.dev1/src/iii/channel.py

@@ -0,0 +1,7 @@
+"""Public channel types."""
+
+from .channels import ChannelReader, ChannelWriter
+from .iii_types import StreamChannelRef
+from .types import Channel
+
+__all__ = ["Channel", "ChannelReader", "ChannelWriter", "StreamChannelRef"]

iii_sdk-0.20.0.dev1/src/iii/engine.py

@@ -0,0 +1,6 @@
+"""Engine constants and handler types."""
+
+from .iii_constants import EngineFunctions, EngineTriggers
+from .types import RemoteFunctionHandler
+
+__all__ = ["EngineFunctions", "EngineTriggers", "RemoteFunctionHandler"]

{iii_sdk-0.19.7.dev1 → iii_sdk-0.20.0.dev1}/src/iii/errors.py

@@ -3,13 +3,13 @@ from __future__ import annotations
 from typing import Any
 
 
-class IIIInvocationError(Exception):
+class InvocationError(Exception):
     """Raised when an invocation dispatched by the SDK fails.
 
     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``.
+    work because ``InvocationError`` inherits from ``Exception``.
 
     Attributes are read-only after construction. ``stacktrace`` is the
     engine-side trace when the remote handler raised; it may include
@@ -38,8 +38,8 @@ def _wrap_wire_error(
     *,
     function_id: str | None,
     invocation_id: str | None,
-) -> IIIInvocationError:
-    """Convert a wire ``ErrorBody``-shaped dict into an ``IIIInvocationError``.
+) -> InvocationError:
+    """Convert a wire ``ErrorBody``-shaped dict into an ``InvocationError``.
 
     The ``code`` field distinguishes categories (e.g. ``'FORBIDDEN'``,
     ``'TIMEOUT'``). Malformed shapes (non-dict, missing fields, non-string
@@ -56,7 +56,7 @@ def _wrap_wire_error(
         raw_stacktrace = error.get("stacktrace")
         stacktrace = raw_stacktrace if isinstance(raw_stacktrace, str) else None
 
-        return IIIInvocationError(
+        return InvocationError(
             code=code,
             message=message,
             function_id=function_id,
@@ -64,7 +64,7 @@ def _wrap_wire_error(
             invocation_id=invocation_id,
         )
 
-    return IIIInvocationError(
+    return InvocationError(
         code="UNKNOWN",
         message=str(error),
         function_id=function_id,

{iii_sdk-0.19.7.dev1 → iii_sdk-0.20.0.dev1}/src/iii/format_utils.py

@@ -44,7 +44,7 @@ def _to_json_schema(annotation: Any) -> dict[str, Any] | None:
     if annotation is inspect.Parameter.empty or annotation is Any:
         return None
 
-    # Handle Optional[X] — produce {"type": ["<inner>", "null"]}
+    # Handle Optional[X], produce {"type": ["<inner>", "null"]}
     is_opt, inner = _is_optional(annotation)
     if is_opt:
         inner_schema = _to_json_schema(inner)
@@ -82,7 +82,7 @@ def _to_json_schema(annotation: Any) -> dict[str, Any] | None:
                 schema_dict["additionalProperties"] = value_schema
         return schema_dict
 
-    # Handle Pydantic BaseModel — use its built-in JSON Schema generation
+    # Handle Pydantic BaseModel, use its built-in JSON Schema generation
     if _is_pydantic_model(annotation):
         model_schema: dict[str, Any] = annotation.model_json_schema()
         return model_schema

{iii_sdk-0.19.7.dev1 → iii_sdk-0.20.0.dev1}/src/iii/helpers.py

@@ -34,7 +34,7 @@ class _IIIWithHelperShims(IIIClient, Protocol):
 
     The free functions below delegate to these private methods on the
     concrete :class:`III` instance. Defining the Protocol here mirrors the
-    Node SDK's ``IIIWithHelperShims`` intersection type — callers see the
+    Node SDK's ``IIIWithHelperShims`` intersection type, callers see the
     public :class:`IIIClient` Protocol; helpers see the shims internally.
     """
 
@@ -46,7 +46,7 @@ class _IIIWithHelperShims(IIIClient, Protocol):
 
     def _helpers_create_stream(
         self, stream_name: str, stream: IStream[Any]
-    ) -> None: ...  # noqa: D401 — internal shim, generic erased at the boundary
+    ) -> None: ...  # noqa: D401  (internal shim, generic erased at the boundary)
 
 
 def create_channel(iii: IIIClient, buffer_size: int | None = None) -> Channel:

{iii_sdk-0.19.7.dev1 → iii_sdk-0.20.0.dev1}/src/iii/iii.py

@@ -14,11 +14,19 @@ from importlib.metadata import version
 from typing import Any, Awaitable, Callable, Coroutine, TypeVar, cast
 
 import websockets
-from iii_observability import OtelConfig
+from iii_helpers.http import HttpInvocationConfig
+from iii_helpers.observability import OtelConfig
+from iii_helpers.stream import (
+    StreamDeleteInput,
+    StreamGetInput,
+    StreamListGroupsInput,
+    StreamListInput,
+    StreamSetInput,
+)
 from websockets.asyncio.client import ClientConnection
 
 from .channels import ChannelReader, ChannelWriter
-from .errors import IIIInvocationError, _wrap_wire_error
+from .errors import InvocationError, _wrap_wire_error
 from .format_utils import extract_request_format, extract_response_format
 from .iii_constants import (
     DEFAULT_RECONNECTION_CONFIG,
@@ -28,7 +36,6 @@ from .iii_constants import (
     InitOptions,
 )
 from .iii_types import (
-    HttpInvocationConfig,
     InvocationResultMessage,
     InvokeFunctionMessage,
     MessageType,
@@ -47,14 +54,7 @@ from .iii_types import (
     UnregisterTriggerMessage,
     UnregisterTriggerTypeMessage,
 )
-from .stream import (
-    IStream,
-    StreamDeleteInput,
-    StreamGetInput,
-    StreamListGroupsInput,
-    StreamListInput,
-    StreamSetInput,
-)
+from .stream import IStream
 from .triggers import Trigger, TriggerConfig, TriggerHandler, TriggerTypeRef
 from .types import Channel, RemoteFunctionData, RemoteTriggerTypeData, is_channel_ref
 
@@ -83,7 +83,7 @@ def _detect_project_name(cwd: str | None = None) -> str | None:
     when both signals are unavailable (e.g. cwd is the filesystem root, or
     the Python runtime has no TOML parser and no readable cwd basename).
 
-    No directory walking — only inspects ``cwd`` itself, so the SDK never
+    No directory walking, only inspects ``cwd`` itself, so the SDK never
     reads files outside the user's explicit working directory.
     """
     try:
@@ -142,7 +142,7 @@ class III:
 
     Examples:
         >>> from iii import register_worker, InitOptions
-        >>> iii = register_worker('ws://localhost:49134', InitOptions(worker_name='my-worker'))
+        >>> worker = register_worker('ws://localhost:49134', InitOptions(worker_name='my-worker'))
     """
 
     def __init__(self, address: str, options: InitOptions | None = None) -> None:
@@ -207,9 +207,9 @@ class III:
         instance must not be reused.
 
         Examples:
-            >>> iii = register_worker('ws://localhost:49134')
+            >>> worker = register_worker('ws://localhost:49134')
             >>> # ... do work ...
-            >>> iii.shutdown()
+            >>> worker.shutdown()
         """
         self._run_on_loop(self.shutdown_async())
         self._loop.call_soon_threadsafe(self._loop.stop)
@@ -224,7 +224,7 @@ class III:
         from an async context.
         """
         self._running = True
-        from iii_observability.telemetry import attach_event_loop, init_otel
+        from iii_helpers.observability.telemetry import attach_event_loop, init_otel
 
         loop = asyncio.get_running_loop()
         otel_cfg: OtelConfig | None = None
@@ -247,9 +247,9 @@ class III:
         instance must not be reused.
 
         Examples:
-            >>> iii = register_worker('ws://localhost:49134')
+            >>> worker = register_worker('ws://localhost:49134')
             >>> # ... do work ...
-            >>> await iii.shutdown_async()
+            >>> await worker.shutdown_async()
         """
         self._running = False
 
@@ -265,7 +265,7 @@ class III:
         for invocation_id, pending in list(self._pending.items()):
             if not pending.future.done():
                 pending.future.set_exception(
-                    IIIInvocationError(
+                    InvocationError(
                         code="SHUTDOWN",
                         message="iii is shutting down",
                         function_id=pending.function_id,
@@ -280,7 +280,7 @@ class III:
 
         self._set_connection_state("disconnected")
 
-        from iii_observability.telemetry import shutdown_otel_async
+        from iii_helpers.observability.telemetry import shutdown_otel_async
 
         await shutdown_otel_async()
 
@@ -502,7 +502,7 @@ class III:
         tracer = trace.get_tracer("iii-python-sdk")
         import os
 
-        from iii_observability import redact_and_truncate, resolve_max_bytes_from_env
+        from iii_helpers.observability import redact_and_truncate, resolve_max_bytes_from_env
 
         trace_payloads = os.environ.get("III_DISABLE_TRACE_PAYLOADS", "").lower() not in (
             "1",
@@ -800,7 +800,7 @@ class III:
             ``register_function`` methods.
 
         Examples:
-            >>> webhook = iii.register_trigger_type(
+            >>> webhook = worker.register_trigger_type(
             ...     RegisterTriggerTypeInput(
             ...         id="webhook",
             ...         description="Webhook trigger",
@@ -853,8 +853,8 @@ class III:
             trigger_type: A ``RegisterTriggerTypeInput`` or dict with ``id`` and optional ``description``.
 
         Examples:
-            >>> iii.unregister_trigger_type({"id": "webhook", "description": "Webhook trigger"})
-            >>> iii.unregister_trigger_type(RegisterTriggerTypeInput(id="webhook", description="Webhook trigger"))
+            >>> worker.unregister_trigger_type({"id": "webhook", "description": "Webhook trigger"})
+            >>> worker.unregister_trigger_type(RegisterTriggerTypeInput(id="webhook", description="Webhook trigger"))
         """
         if isinstance(trigger_type, dict):
             type_id = trigger_type["id"]
@@ -878,12 +878,12 @@ class III:
             the engine as part of the registration message.
 
         Examples:
-            >>> trigger = iii.register_trigger({
+            >>> trigger = worker.register_trigger({
             ...   'type': 'http',
             ...   'function_id': 'greet',
             ...   'config': {'api_path': '/greet', 'http_method': 'GET'}
             ... })
-            >>> trigger = iii.register_trigger(RegisterTriggerInput(
+            >>> trigger = worker.register_trigger(RegisterTriggerInput(
             ...     type="http", function_id="greet",
             ...     config={'api_path': '/greet', 'http_method': 'GET'}
             ... ))
@@ -967,7 +967,7 @@ class III:
         Examples:
             >>> def greet(data):
             ...     return {'message': f"Hello, {data['name']}!"}
-            >>> fn = iii.register_function("greet", greet, description="Greets a user")
+            >>> fn = worker.register_function("greet", greet, description="Greets a user")
             >>> fn.unregister()
 
             >>> from pydantic import BaseModel
@@ -977,7 +977,7 @@ class III:
             ...     message: str
             >>> async def greet(data: GreetInput) -> GreetOutput:
             ...     return GreetOutput(message=f"Hello, {data.name}!")
-            >>> fn = iii.register_function("greet", greet, description="Greets a user")
+            >>> fn = worker.register_function("greet", greet, description="Greets a user")
         """
         if not isinstance(function_id, str):
             raise TypeError(
@@ -1081,13 +1081,13 @@ class III:
             actions.
 
         Raises:
-            IIIInvocationError: For any engine rejection. Inspect ``code``:
+            InvocationError: 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'}})
-            >>> iii.trigger({'function_id': 'notify', 'payload': {}, 'action': TriggerAction.Void()})
+            >>> result = worker.trigger({'function_id': 'greet', 'payload': {'name': 'World'}})
+            >>> worker.trigger({'function_id': 'notify', 'payload': {}, 'action': TriggerAction.Void()})
         """
         return self._run_on_loop(self.trigger_async(request))
 
@@ -1108,7 +1108,7 @@ class III:
             The result of the function invocation, or ``None`` for void calls.
 
         Raises:
-            IIIInvocationError: For any engine rejection. Inspect ``code``:
+            InvocationError: For any engine rejection. Inspect ``code``:
                 ``'TIMEOUT'`` if the invocation timed out, ``'FORBIDDEN'`` if
                 RBAC denied it.
 
@@ -1171,7 +1171,7 @@ class III:
             return await asyncio.wait_for(future, timeout=timeout_secs)
         except asyncio.TimeoutError:
             self._pending.pop(invocation_id, None)
-            raise IIIInvocationError(
+            raise InvocationError(
                 code="TIMEOUT",
                 message=f"invocation timed out after {timeout_ms}ms",
                 function_id=function_id,
@@ -1308,8 +1308,8 @@ class TriggerAction:
 
     Examples:
         >>> from iii import TriggerAction
-        >>> iii.trigger({'function_id': 'process', 'payload': {}, 'action': TriggerAction.Enqueue(queue='jobs')})
-        >>> iii.trigger({'function_id': 'notify', 'payload': {}, 'action': TriggerAction.Void()})
+        >>> worker.trigger({'function_id': 'process', 'payload': {}, 'action': TriggerAction.Enqueue(queue='jobs')})
+        >>> worker.trigger({'function_id': 'notify', 'payload': {}, 'action': TriggerAction.Void()})
     """
 
     @staticmethod
@@ -1344,7 +1344,7 @@ def register_worker(address: str, options: InitOptions | None = None) -> III:
 
     Examples:
         >>> from iii import register_worker, InitOptions
-        >>> iii = register_worker('ws://localhost:49134', InitOptions(worker_name='my-worker'))
+        >>> worker = register_worker('ws://localhost:49134', InitOptions(worker_name='my-worker'))
     """
     client = III(address, options)
     client._wait_until_connected()

{iii_sdk-0.19.7.dev1 → iii_sdk-0.20.0.dev1}/src/iii/iii_constants.py

@@ -1,9 +1,9 @@
 """Constants and configuration types for the III SDK (mirrors iii-constants.ts)."""
 
 from dataclasses import dataclass
-from typing import Any, Callable, Literal
+from typing import Any, Callable, Final, Literal
 
-from iii_observability import OtelConfig, ReconnectionConfig
+from iii_helpers.observability import OtelConfig, ReconnectionConfig
 
 IIIConnectionState = Literal["disconnected", "connecting", "connected", "reconnecting", "failed"]
 
@@ -26,7 +26,7 @@ class FunctionRef:
 
 @dataclass
 class TelemetryOptions:
-    """Telemetry metadata to be reported to the engine.
+    """Worker metadata reported to the engine.
 
     Attributes:
         language: Programming language of the worker (e.g. ``python``).
@@ -54,7 +54,7 @@ class InitOptions:
         reconnection_config: WebSocket reconnection behavior.
         otel: OpenTelemetry configuration. Enabled by default.
             Set ``{'enabled': False}`` or env ``OTEL_ENABLED=false`` to disable.
-        telemetry: Internal telemetry metadata.
+        telemetry: Internal worker metadata reported to the engine.
     """
 
     worker_name: str | None = None
@@ -65,3 +65,24 @@ class InitOptions:
     otel: OtelConfig | dict[str, Any] | None = None
     headers: dict[str, str] | None = None
     telemetry: TelemetryOptions | None = None
+
+
+class EngineFunctions:
+    """Engine function ids for internal operations (parity with the Node SDK)."""
+
+    LIST_FUNCTIONS: Final[str] = "engine::functions::list"
+    INFO_FUNCTIONS: Final[str] = "engine::functions::info"
+    LIST_WORKERS: Final[str] = "engine::workers::list"
+    INFO_WORKERS: Final[str] = "engine::workers::info"
+    LIST_TRIGGERS: Final[str] = "engine::triggers::list"
+    INFO_TRIGGERS: Final[str] = "engine::triggers::info"
+    LIST_REGISTERED_TRIGGERS: Final[str] = "engine::registered-triggers::list"
+    INFO_REGISTERED_TRIGGERS: Final[str] = "engine::registered-triggers::info"
+    REGISTER_WORKER: Final[str] = "engine::workers::register"
+
+
+class EngineTriggers:
+    """Engine trigger ids (parity with the Node SDK)."""
+
+    FUNCTIONS_AVAILABLE: Final[str] = "engine::functions-available"
+    LOG: Final[str] = "log"