iii-sdk 0.21.6.dev1__tar.gz → 0.21.7.dev1__tar.gz

{iii_sdk-0.21.6.dev1 → iii_sdk-0.21.7.dev1}/PKG-INFO

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

{iii_sdk-0.21.6.dev1 → iii_sdk-0.21.7.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iii-sdk"
-version = "0.21.6.dev1"
+version = "0.21.7.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-helpers==0.21.6.dev1",
+    "iii-helpers==0.21.7.dev1",
 ]
 
 [project.urls]

{iii_sdk-0.21.6.dev1 → iii_sdk-0.21.7.dev1}/src/iii/iii.py

@@ -70,15 +70,15 @@ def _metadata_passing_mode(handler: Callable[..., Any]) -> str:
 
     Only handlers that explicitly declare a parameter named ``metadata``
     receive the sidecar; every other signature keeps its exact pre-metadata
-    call shape (``handler(data)``), so existing handlers -- including ones
-    with unrelated optional parameters, ``*args``, or ``**kwargs`` -- keep
+    call shape (``handler(data)``), so existing handlers, including ones
+    with unrelated optional parameters, ``*args``, or ``**kwargs``, keep
     working unchanged. Returns one of:
 
     - ``"positional"``: ``metadata`` is the second positional parameter
       (e.g. ``def handler(data, metadata=None)``).
     - ``"keyword"``: ``metadata`` is keyword-only
       (e.g. ``def handler(data, *, metadata=None)``).
-    - ``"none"``: no ``metadata`` parameter -- omit metadata.
+    - ``"none"``: no ``metadata`` parameter; omit metadata.
 
     If the signature cannot be introspected (some builtins/C callables),
     falls back to ``"none"`` to preserve back-compat.
@@ -260,7 +260,7 @@ class III:
 
         Initializes OpenTelemetry (if configured), attaches the event loop,
         and establishes the WebSocket connection. This is called automatically
-        during construction -- use it only if you need to reconnect manually
+        during construction; use it only if you need to reconnect manually
         from an async context.
         """
         self._running = True
@@ -814,6 +814,11 @@ class III:
         Returns:
             One of ``"disconnected"``, ``"connecting"``, ``"connected"``,
             ``"reconnecting"``, or ``"failed"``.
+
+        Examples:
+            >>> worker = register_worker("ws://localhost:49134")
+            >>> if worker.get_connection_state() != "connected":
+            ...     print("engine not reachable yet")
         """
         return self._connection_state
 
@@ -912,6 +917,8 @@ class III:
     ) -> Trigger:
         """Bind a trigger configuration to a registered function.
 
+        <!-- docs:expand-params -->
+
         Args:
             trigger: A ``RegisterTriggerInput`` or dict with ``type``,
                 ``function_id``, and optional ``config``.
@@ -977,15 +984,15 @@ class III:
         ``def handler(data, metadata=None)`` or ``def handler(data, *,
         metadata=None)``).  Metadata is only forwarded to handlers that
         declare a parameter literally named ``metadata``, so existing
-        handlers -- including ones with unrelated extra parameters,
-        ``*args``, or ``**kwargs`` -- keep working unchanged.
+        handlers, including ones with unrelated extra parameters,
+        ``*args``, or ``**kwargs``, keep working unchanged.
 
         ``request_format`` and ``response_format`` are auto-extracted
         from the handler's type hints when omitted or passed as ``None``
         (the default).  To opt out of auto-extraction, pass an explicit
         schema (``RegisterFunctionFormat`` or ``dict``).  This behavior
-        is Python-specific -- the Node SDK does not auto-extract from TS
-        types, because TypeScript types are erased at runtime.
+        is Python-specific; the Node SDK relies on explicit schemas because
+        TypeScript types are erased at runtime.
 
         Args:
             function_id: Unique string identifier for the function.
@@ -994,8 +1001,8 @@ class III:
                 ``data`` (the trigger payload) as the first argument and
                 may optionally accept ``metadata`` (per-invocation
                 metadata) as a second argument; they may return a value.
-            description: Human-readable description.
-            metadata: Arbitrary metadata.
+            description: Human-readable description of what the function does.
+            metadata: Arbitrary metadata attached to the function.
             request_format: Schema describing expected input.  When
                 ``None`` (default), auto-extracted from the handler's
                 first-parameter type hint.  Pass an explicit schema to
@@ -1127,12 +1134,14 @@ class III:
     def trigger(self, request: "dict[str, Any] | TriggerRequest") -> Any:
         """Invoke a remote function.
 
+        <!-- docs:expand-params -->
+
         The routing behavior and return type depend on the ``action`` field:
 
-        - No action: synchronous -- waits for the function to return.
-        - ``TriggerAction.Enqueue(...)``: async via named queue -- returns a dict
+        - No action: synchronous, waits for the function to return.
+        - ``TriggerAction.Enqueue(...)``: async via named queue, returns a dict
           with ``messageReceiptId``.
-        - ``TriggerAction.Void()``: fire-and-forget -- returns ``None``.
+        - ``TriggerAction.Void()``: fire-and-forget, returns ``None``.
 
         Args:
             request: A ``TriggerRequest`` or dict with ``function_id``,
@@ -1159,10 +1168,10 @@ class III:
 
         The routing behavior and return type depend on the ``action`` field:
 
-        - No action: synchronous -- waits for the function to return.
-        - ``TriggerAction.Enqueue(...)``: async via named queue -- returns a dict
+        - No action: synchronous, waits for the function to return.
+        - ``TriggerAction.Enqueue(...)``: async via named queue, returns a dict
           with ``messageReceiptId``.
-        - ``TriggerAction.Void()``: fire-and-forget -- returns ``None``.
+        - ``TriggerAction.Void()``: fire-and-forget, returns ``None``.
 
         Args:
             request: A ``TriggerRequest`` or dict with ``function_id``, ``payload``,
@@ -1179,8 +1188,8 @@ class III:
                 RBAC denied it.
 
         Examples:
-            >>> result = await iii.trigger_async({'function_id': 'greet', 'payload': {'name': 'World'}})
-            >>> await iii.trigger_async({'function_id': 'notify', 'payload': {}, 'action': TriggerAction.Void()})
+            >>> result = await worker.trigger_async({'function_id': 'greet', 'payload': {'name': 'World'}})
+            >>> await worker.trigger_async({'function_id': 'notify', 'payload': {}, 'action': TriggerAction.Void()})
         """
         req = request if isinstance(request, dict) else request.model_dump()
         function_id = req["function_id"]
@@ -1342,8 +1351,8 @@ class III:
 
         Public callers must use the free function from ``iii.helpers``.
         Registers 5 of the 6 ``IStream`` methods (``get``, ``set``, ``delete``,
-        ``list``, ``list_groups``). The ``update`` method is **not** registered
-        -- atomic updates are handled by the engine's built-in stream update
+        ``list``, ``list_groups``). The ``update`` method is **not** registered;
+        atomic updates are handled by the engine's built-in stream update
         logic.
         """
 
@@ -1385,6 +1394,7 @@ class TriggerAction:
 
     Examples:
         >>> from iii import TriggerAction
+        >>> # The queue must be declared in the iii-queue worker's queue_configs.
         >>> worker.trigger({'function_id': 'process', 'payload': {}, 'action': TriggerAction.Enqueue(queue='jobs')})
         >>> worker.trigger({'function_id': 'notify', 'payload': {}, 'action': TriggerAction.Void()})
     """
@@ -1405,7 +1415,7 @@ class TriggerAction:
 
 
 def register_worker(address: str, options: InitOptions | None = None) -> III:
-    """Create an III client and connect to the engine.
+    """Register the worker with a iii instance, returns a connected worker client.
 
     Blocks until the WebSocket connection is established and ready.
 

{iii_sdk-0.21.6.dev1 → iii_sdk-0.21.7.dev1}/src/iii/iii_constants.py

@@ -18,7 +18,12 @@ DEFAULT_RECONNECTION_CONFIG = ReconnectionConfig()
 
 @dataclass
 class FunctionRef:
-    """Reference to a registered function, allowing programmatic unregistration."""
+    """Reference to a registered function, allowing programmatic unregistration.
+
+    Attributes:
+        id: The unique function identifier.
+        unregister: Removes this function from the engine.
+    """
 
     id: str
     unregister: Callable[[], None]
@@ -26,12 +31,12 @@ class FunctionRef:
 
 @dataclass
 class TelemetryOptions:
-    """Worker metadata reported to the engine.
+    """Worker metadata reported to the engine (language, framework, project).
 
     Attributes:
-        language: Programming language of the worker (e.g. ``python``).
+        language: Programming language of the worker.
         project_name: Name of the project this worker belongs to.
-        framework: Framework name (e.g. ``motia``) if applicable.
+        framework: Framework name, if applicable.
         amplitude_api_key: Amplitude API key for product analytics.
     """
 
@@ -43,14 +48,14 @@ class TelemetryOptions:
 
 @dataclass
 class InitOptions:
-    """Options for configuring the III SDK.
+    """Configuration options passed to ``register_worker``.
 
     Attributes:
         worker_name: Display name for this worker. Defaults to ``hostname:pid``.
         worker_description: One-line, human/LLM-readable summary of what this
             worker does. Surfaces in ``engine::workers::list`` / ``engine::workers::info``.
         enable_metrics_reporting: Enable worker metrics via OpenTelemetry. Default ``True``.
-        invocation_timeout_ms: Default timeout for ``trigger()`` in milliseconds. Default ``30000``.
+        invocation_timeout_ms: Default timeout for ``worker.trigger()`` invocations in milliseconds. Default ``30000``.
         reconnection_config: WebSocket reconnection behavior.
         otel: OpenTelemetry configuration. Enabled by default.
             Set ``{'enabled': False}`` or env ``OTEL_ENABLED=false`` to disable.

{iii_sdk-0.21.6.dev1 → iii_sdk-0.21.7.dev1}/src/iii/iii_types.py

@@ -63,14 +63,14 @@ class RegisterTriggerTypeInput(BaseModel):
     """Input for registering a trigger type.
 
     Attributes:
-        id: Unique identifier for the trigger type.
-        description: Human-readable description of the trigger type.
+        id: Unique identifier for the trigger type (e.g. ``state``, ``durable:subscriber``).
+        description: Human-readable description of what this trigger type does.
         trigger_request_format: JSON Schema describing the expected trigger config.
         call_request_format: JSON Schema describing the payload sent to functions.
     """
 
-    id: str = Field(description="Unique identifier for the trigger type.")
-    description: str = Field(description="Human-readable description of the trigger type.")
+    id: str = Field(description="Unique identifier for the trigger type (e.g. ``state``, ``durable:subscriber``).")
+    description: str = Field(description="Human-readable description of what this trigger type does.")
     trigger_request_format: Any | None = Field(
         default=None, description="JSON Schema for trigger configuration."
     )
@@ -83,17 +83,27 @@ class RegisterTriggerInput(BaseModel):
     """Input for registering a trigger (matches Node SDK's RegisterTriggerInput).
 
     Attributes:
-        type: Trigger type identifier (e.g. ``http``, ``queue``, ``cron``).
-        function_id: ID of the function this trigger invokes.
-        config: Trigger-type-specific configuration.
-        metadata: Arbitrary metadata attached to the trigger.
+        type: Identifier of the registered trigger type this trigger uses (e.g. ``storage::object-created``, ``http``).
+        function_id: ID of the function this trigger invokes when it fires.
+        config: Trigger-type-specific configuration, matching the shape the trigger type expects.
+        metadata: Arbitrary user-specifiable metadata supplied to the triggered handler function on every invocation.
     """
 
-    type: str = Field(description="Trigger type identifier.")
-    function_id: str = Field(description="ID of the function this trigger invokes.")
-    config: Any = Field(default=None, description="Trigger-type-specific configuration.")
+    type: str = Field(
+        description=(
+            "Identifier of the registered trigger type this trigger uses "
+            "(e.g. ``storage::object-created``, ``http``)."
+        )
+    )
+    function_id: str = Field(description="ID of the function this trigger invokes when it fires.")
+    config: Any = Field(
+        default=None, description="Trigger-type-specific configuration, matching the shape the trigger type expects."
+    )
     metadata: Any | None = Field(
-        default=None, description="Arbitrary metadata attached to the trigger."
+        default=None,
+        description=(
+            "Arbitrary user-specifiable metadata supplied to the triggered handler function on every invocation."
+        ),
     )
 
 
@@ -170,7 +180,7 @@ class RegisterFunctionMessage(BaseModel):
 class TriggerActionEnqueue(BaseModel):
     """Routes the invocation through a named queue for async processing.
 
-    Requires a queue worker in the project — run ``iii worker add queue``.
+    Requires a queue worker in the project. Run ``iii worker add queue``.
     Without it the trigger rejects with ``enqueue_error`` (no queue provider).
 
     Attributes:
@@ -222,28 +232,33 @@ class TriggerRequest(BaseModel):
 
     Attributes:
         function_id: ID of the function to invoke.
-        payload: Data to pass to the function.
-        action: Routing action, ``None`` for sync, ``TriggerAction.Enqueue(...)``
-            for queue, ``TriggerAction.Void()`` for fire-and-forget.
-        timeout_ms: Override the default invocation timeout.
-        metadata: Arbitrary per-invocation metadata delivered to the handler
-            as a separate channel (not folded into ``payload``).
+        payload: Input data passed to the function.
+        action: Sets how the trigger is routed. Omit for a synchronous
+            request/response. Specify for a specific routing scheme (e.g.
+            ``TriggerAction.Enqueue(...)``, ``TriggerAction.Void()``).
+        timeout_ms: Override the default invocation timeout, in milliseconds.
+        metadata: Arbitrary user-specifiable metadata supplied to the triggered
+            handler function on every invocation.
     """
 
     function_id: str = Field(description="ID of the function to invoke.")
-    payload: Any = Field(default=None, description="Data to pass to the function.")
+    payload: Any = Field(default=None, description="Input data passed to the function.")
     action: TriggerActionEnqueue | TriggerActionVoid | None = Field(
         default=None,
         description=(
-            "Routing action: ``None`` for sync, "
-            "``TriggerAction.Enqueue(...)`` for queue, "
-            "``TriggerAction.Void()`` for fire-and-forget."
+            "Sets how the trigger is routed. Omit for a synchronous request/response. "
+            "Specify for a specific routing scheme (e.g. ``TriggerAction.Enqueue(...)``, "
+            "``TriggerAction.Void()``)."
         ),
     )
-    timeout_ms: int | None = Field(default=None, description="Override the default invocation timeout.")
+    timeout_ms: int | None = Field(
+        default=None, description="Override the default invocation timeout, in milliseconds."
+    )
     metadata: Any | None = Field(
         default=None,
-        description="Arbitrary per-invocation metadata delivered to the handler.",
+        description=(
+            "Arbitrary user-specifiable metadata supplied to the triggered handler function on every invocation."
+        ),
     )
 
 

{iii_sdk-0.21.6.dev1 → iii_sdk-0.21.7.dev1}/src/iii/state.py

@@ -16,14 +16,25 @@ TData = TypeVar("TData")
 
 
 class StateGetInput(BaseModel):
-    """Input for retrieving a state value."""
+    """Input for retrieving a state value.
+
+    Attributes:
+        scope: State scope (namespace).
+        key: Key within the scope.
+    """
 
     scope: str
     key: str
 
 
 class StateSetInput(BaseModel):
-    """Input for setting a state value."""
+    """Input for setting a state value.
+
+    Attributes:
+        scope: State scope (namespace).
+        key: Key within the scope.
+        value: Value to store.
+    """
 
     scope: str
     key: str
@@ -31,20 +42,35 @@ class StateSetInput(BaseModel):
 
 
 class StateDeleteInput(BaseModel):
-    """Input for deleting a state value."""
+    """Input for deleting a state value.
+
+    Attributes:
+        scope: State scope (namespace).
+        key: Key within the scope.
+    """
 
     scope: str
     key: str
 
 
 class StateListInput(BaseModel):
-    """Input for listing all values in a state scope."""
+    """Input for listing all values in a state scope.
+
+    Attributes:
+        scope: State scope (namespace).
+    """
 
     scope: str
 
 
 class StateUpdateInput(BaseModel):
-    """Input for atomically updating a state value."""
+    """Input for atomically updating a state value.
+
+    Attributes:
+        scope: State scope (namespace).
+        key: Key within the scope.
+        ops: Ordered list of update operations to apply atomically.
+    """
 
     scope: str
     key: str
@@ -52,21 +78,35 @@ class StateUpdateInput(BaseModel):
 
 
 class StateSetResult(BaseModel, Generic[TData]):
-    """Result of a state set operation."""
+    """Result of a state set operation.
+
+    Attributes:
+        old_value: Previous value (if it existed).
+        new_value: New value that was stored.
+    """
 
     old_value: TData | None = None
     new_value: TData
 
 
 class StateUpdateResult(BaseModel, Generic[TData]):
-    """Result of a state update operation."""
+    """Result of a state update operation.
+
+    Attributes:
+        old_value: Previous value (if it existed).
+        new_value: New value after the update.
+    """
 
     old_value: TData | None = None
     new_value: TData
 
 
 class StateDeleteResult(BaseModel):
-    """Result of a state delete operation."""
+    """Result of a state delete operation.
+
+    Attributes:
+        old_value: Previous value (if it existed).
+    """
 
     old_value: Any | None = None
 
@@ -80,7 +120,16 @@ class StateEventType(str, Enum):
 
 
 class StateEventData(BaseModel, Generic[TData]):
-    """Payload for state change events."""
+    """Payload for state change events.
+
+    Attributes:
+        type: Event category (always ``state``).
+        event_type: Type of state change.
+        scope: State scope (namespace).
+        key: Key within the scope.
+        old_value: Previous value (for update/delete events).
+        new_value: New value (for create/update events).
+    """
 
     type: str = "state"
     event_type: StateEventType

{iii_sdk-0.21.6.dev1 → iii_sdk-0.21.7.dev1}/src/iii/triggers.py

@@ -16,7 +16,16 @@ R = TypeVar("R")
 
 
 class TriggerConfig(BaseModel, Generic[TConfig]):
-    """Configuration for a trigger."""
+    """Configuration passed to a trigger handler when a trigger instance is
+    registered or unregistered.
+
+    Attributes:
+        id: Trigger instance ID.
+        function_id: Function to invoke when the trigger fires.
+        config: Trigger-specific configuration.
+        metadata: Arbitrary user-specifiable metadata supplied to the triggered
+            handler function on every invocation.
+    """
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 

{iii_sdk-0.21.6.dev1 → iii_sdk-0.21.7.dev1}/src/iii/types.py

@@ -126,7 +126,10 @@ class Channel:
 
 @dataclass
 class InternalHttpRequest:
-    """HTTP request with embedded channel references for streaming."""
+    """HTTP request with embedded channel references for streaming.
+
+    <!-- docs:internal -->
+    """
 
     path_params: dict[str, str]
     query_params: dict[str, str | list[str]]
@@ -163,7 +166,7 @@ class StreamResponse:
 
 @dataclass
 class StreamRequest:
-    """Streaming request without the response writer."""
+    """Incoming streaming request received by a function registered with a stream trigger."""
 
     path_params: dict[str, str]
     query_params: dict[str, str | list[str]]