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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iii-sdk
-Version: 0.11.4.dev1
+Version: 0.11.4.dev3
 Summary: III SDK for Python
 Project-URL: Homepage, https://github.com/iii-hq/sdk
 Project-URL: Repository, https://github.com/iii-hq/sdk
@@ -53,7 +53,7 @@ iii = register_worker("ws://localhost:49134")
 def greet(data):
     return {"message": f"Hello, {data['name']}!"}
 
-iii.register_function({"id": "greet"}, greet)
+iii.register_function("greet", greet)
 
 iii.register_trigger({
     "type": "http",
@@ -72,7 +72,7 @@ print(result)  # {"message": "Hello, world!"}
 | 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 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 |
@@ -86,7 +86,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
@@ -94,7 +94,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"},
 })
 ```
@@ -102,7 +102,7 @@ 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

{iii_sdk-0.11.4.dev1 → iii_sdk-0.11.4.dev3}/README.md

@@ -22,7 +22,7 @@ iii = register_worker("ws://localhost:49134")
 def greet(data):
     return {"message": f"Hello, {data['name']}!"}
 
-iii.register_function({"id": "greet"}, greet)
+iii.register_function("greet", greet)
 
 iii.register_trigger({
     "type": "http",
@@ -41,7 +41,7 @@ print(result)  # {"message": "Hello, world!"}
 | 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 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 |
@@ -55,7 +55,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 +63,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,7 +71,7 @@ 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

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

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

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

@@ -21,7 +21,6 @@ from .iii_types import (
     OnTriggerTypeRegistrationInput,
     OnTriggerTypeRegistrationResult,
     RegisterFunctionFormat,
-    RegisterFunctionInput,
     RegisterFunctionMessage,
     RegisterServiceInput,
     RegisterTriggerInput,
@@ -92,7 +91,6 @@ __all__ = [
     "HttpInvocationConfig",
     "MessageType",
     "RegisterFunctionFormat",
-    "RegisterFunctionInput",
     "RegisterFunctionMessage",
     "RegisterServiceInput",
     "RegisterTriggerInput",

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

@@ -787,7 +787,7 @@ class III:
 
     def register_function(
         self,
-        func_or_id: RegisterFunctionInput | dict[str, Any] | str,
+        function_id: str,
         handler_or_invocation: RemoteFunctionHandler | HttpInvocationConfig,
         *,
         description: str | None = None,
@@ -805,27 +805,28 @@ class III:
         block the event loop.  Each handler receives a single ``data``
         argument containing the trigger payload.
 
-        When ``func_or_id`` is a ``str``, the simplified API is used:
         ``request_format`` and ``response_format`` are auto-extracted
-        from the handler's type hints when not explicitly provided.
+        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.
 
         Args:
-            func_or_id: A ``RegisterFunctionInput``, dict with ``id``, or
-                a plain string function ID.  When a string is passed, use
-                keyword arguments for ``description``, ``metadata``,
-                ``request_format``, and ``response_format``.
+            function_id: Unique string identifier for the function.
             handler_or_invocation: A callable handler or
                 ``HttpInvocationConfig``.  Callable handlers receive one
                 positional argument (``data`` -- the trigger payload) and
                 may return a value.
-            description: Human-readable description (only with string ID).
-            metadata: Arbitrary metadata (only with string ID).
-            request_format: Schema describing expected input (only with
-                string ID).  Auto-extracted from handler type hints when
-                omitted.
-            response_format: Schema describing expected output (only with
-                string ID).  Auto-extracted from handler type hints when
-                omitted.
+            description: Human-readable description.
+            metadata: Arbitrary metadata.
+            request_format: Schema describing expected input.  When
+                ``None`` (default), auto-extracted from the handler's
+                first-parameter type hint.  Pass an explicit schema to
+                override; there is no way to register with no schema
+                when the handler is typed.
+            response_format: Schema describing expected output.  Same
+                auto-extraction semantics as ``request_format``.
 
         Returns:
             A ``FunctionRef`` with an ``id`` attribute and an
@@ -833,14 +834,15 @@ class III:
             the function from the engine.
 
         Raises:
-            ValueError: If ``id`` is empty or already registered.
-            TypeError: If ``handler_or_invocation`` is not callable or
+            TypeError: If ``function_id`` is not a string, or if
+                ``handler_or_invocation`` is not callable or
                 ``HttpInvocationConfig``.
+            ValueError: If ``function_id`` is empty or already registered.
 
         Examples:
             >>> def greet(data):
             ...     return {'message': f"Hello, {data['name']}!"}
-            >>> fn = iii.register_function({"id": "greet", "description": "Greets a user"}, greet)
+            >>> fn = iii.register_function("greet", greet, description="Greets a user")
             >>> fn.unregister()
 
             >>> from pydantic import BaseModel
@@ -852,31 +854,29 @@ class III:
             ...     return GreetOutput(message=f"Hello, {data.name}!")
             >>> fn = iii.register_function("greet", greet, description="Greets a user")
         """
-        if isinstance(func_or_id, str):
-            # Simplified API: auto-extract formats from handler type hints
-            handler_for_extraction = (
-                handler_or_invocation if callable(handler_or_invocation) else None
-            )
-            if request_format is None and handler_for_extraction is not None:
-                request_format = extract_request_format(handler_for_extraction)
-            if response_format is None and handler_for_extraction is not None:
-                response_format = extract_response_format(handler_for_extraction)
-            func = RegisterFunctionInput(
-                id=func_or_id,
-                description=description,
-                metadata=metadata,
-                request_format=request_format,
-                response_format=response_format,
+        if not isinstance(function_id, str):
+            raise TypeError(
+                f"function_id must be str, got {type(function_id).__name__}"
             )
-        elif isinstance(func_or_id, dict):
-            func = RegisterFunctionInput(**func_or_id)
-        else:
-            func = func_or_id
-
-        if not func.id or not func.id.strip():
+        if not function_id or not function_id.strip():
             raise ValueError("id is required")
-        if func.id in self._functions:
-            raise ValueError(f"function id '{func.id}' already registered")
+        if function_id in self._functions:
+            raise ValueError(f"function id '{function_id}' already registered")
+
+        handler_for_extraction = (
+            handler_or_invocation if callable(handler_or_invocation) else None
+        )
+        if request_format is None and handler_for_extraction is not None:
+            request_format = extract_request_format(handler_for_extraction)
+        if response_format is None and handler_for_extraction is not None:
+            response_format = extract_response_format(handler_for_extraction)
+        func = RegisterFunctionInput(
+            id=function_id,
+            description=description,
+            metadata=metadata,
+            request_format=request_format,
+            response_format=response_format,
+        )
 
         if isinstance(handler_or_invocation, HttpInvocationConfig):
             msg = RegisterFunctionMessage(
@@ -1107,7 +1107,7 @@ class III:
 
         Examples:
             >>> ch = iii.create_channel()
-            >>> fn = iii.register_function({"id": "producer"}, producer_handler)
+            >>> fn = iii.register_function("producer", producer_handler)
             >>> iii.trigger({"function_id": "producer", "payload": {"output": ch.writer_ref}})
         """
         return self._run_on_loop(self.create_channel_async(buffer_size))
@@ -1128,7 +1128,7 @@ class III:
 
         Examples:
             >>> ch = await iii.create_channel_async()
-            >>> fn = iii.register_function({"id": "producer"}, producer_handler)
+            >>> fn = iii.register_function("producer", producer_handler)
             >>> await iii.trigger_async({"function_id": "producer", "payload": {"output": ch.writer_ref}})
         """
         result = await self.trigger_async(
@@ -1237,12 +1237,12 @@ class III:
             )
             return await stream.list_groups(input_data)
 
-        self.register_function({"id": f"stream::get({stream_name})"}, get_handler)
-        self.register_function({"id": f"stream::set({stream_name})"}, set_handler)
-        self.register_function({"id": f"stream::delete({stream_name})"}, delete_handler)
-        self.register_function({"id": f"stream::list({stream_name})"}, list_handler)
+        self.register_function(f"stream::get({stream_name})", get_handler)
+        self.register_function(f"stream::set({stream_name})", set_handler)
+        self.register_function(f"stream::delete({stream_name})", delete_handler)
+        self.register_function(f"stream::list({stream_name})", list_handler)
         self.register_function(
-            {"id": f"stream::list_groups({stream_name})"}, list_groups_handler
+            f"stream::list_groups({stream_name})", list_groups_handler
         )
 
 

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

@@ -135,6 +135,14 @@ class UpdateDecrement(BaseModel):
     by: int | float
 
 
+class UpdateAppend(BaseModel):
+    """Append operation for stream update."""
+
+    type: str = "append"
+    path: str
+    value: Any
+
+
 class UpdateRemove(BaseModel):
     """Remove operation for stream update."""
 
@@ -143,14 +151,17 @@ class UpdateRemove(BaseModel):
 
 
 class UpdateMerge(BaseModel):
-    """Merge operation for stream update."""
+    """Shallow root-level merge operation for stream update.
+
+    Only an empty path is supported. Non-empty paths are ignored by the engine.
+    """
 
     type: str = "merge"
     path: str
     value: Any
 
 
-UpdateOp = UpdateSet | UpdateIncrement | UpdateDecrement | UpdateRemove | UpdateMerge
+UpdateOp = UpdateSet | UpdateIncrement | UpdateDecrement | UpdateAppend | UpdateRemove | UpdateMerge
 
 
 class StreamTriggerConfig(BaseModel):

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

@@ -11,7 +11,6 @@ from pydantic import BaseModel, ConfigDict, Field
 
 from .iii_types import (
     HttpInvocationConfig,
-    RegisterFunctionInput,
     RegisterFunctionMessage,
     RegisterServiceInput,
     RegisterTriggerInput,
@@ -87,7 +86,7 @@ class IIIClient(Protocol):
 
     def register_function(
         self,
-        func: RegisterFunctionInput | dict[str, Any],
+        function_id: str,
         handler_or_invocation: RemoteFunctionHandler | HttpInvocationConfig,
     ) -> Any: ...
 

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

@@ -24,7 +24,7 @@ async def test_get_endpoint(engine_http_url, iii_client: III):
     def handler(input_data):
         return {"status_code": 200, "body": {"message": "Hello from GET"}}
 
-    fn_ref = iii_client.register_function({"id": "test.api.get.py"}, handler)
+    fn_ref = iii_client.register_function("test.api.get.py", handler)
     trigger = iii_client.register_trigger(
         {
             "type": "http",
@@ -59,7 +59,7 @@ async def test_post_endpoint_with_body(engine_http_url, iii_client: III):
             "body": {"received": body, "created": True},
         }
 
-    fn_ref = iii_client.register_function({"id": "test.api.post.py"}, handler)
+    fn_ref = iii_client.register_function("test.api.post.py", handler)
     trigger = iii_client.register_trigger(
         {
             "type": "http",
@@ -97,7 +97,7 @@ async def test_path_parameters(engine_http_url, iii_client: III):
             "body": {"id": input_data.get("path_params", {}).get("id")},
         }
 
-    fn_ref = iii_client.register_function({"id": "test.api.getbyid.py"}, handler)
+    fn_ref = iii_client.register_function("test.api.getbyid.py", handler)
     trigger = iii_client.register_trigger(
         {
             "type": "http",
@@ -138,7 +138,7 @@ async def test_query_parameters(engine_http_url, iii_client: III):
             "body": {"query": q, "limit": limit},
         }
 
-    fn_ref = iii_client.register_function({"id": "test.api.search.py"}, handler)
+    fn_ref = iii_client.register_function("test.api.search.py", handler)
     trigger = iii_client.register_trigger(
         {
             "type": "http",
@@ -170,7 +170,7 @@ async def test_custom_status_code(engine_http_url, iii_client: III):
     def handler(input_data):
         return {"status_code": 404, "body": {"error": "Not found"}}
 
-    fn_ref = iii_client.register_function({"id": "test.api.notfound.py"}, handler)
+    fn_ref = iii_client.register_function("test.api.notfound.py", handler)
     trigger = iii_client.register_trigger(
         {
             "type": "http",
@@ -206,7 +206,7 @@ async def test_content_type_on_api_response_return(engine_http_url, iii_client:
             "body": xml_body,
         }
 
-    fn_ref = iii_client.register_function({"id": "test.api.xml.return.py"}, handler)
+    fn_ref = iii_client.register_function("test.api.xml.return.py", handler)
     trigger = iii_client.register_trigger(
         {
             "type": "http",
@@ -245,7 +245,7 @@ async def test_download_pdf_streaming(engine_http_url, iii_client: III):
         await response.writer.write(original_pdf)
         await response.writer.close_async()
 
-    fn_ref = iii_client.register_function({"id": "test.api.download.pdf.py"}, handler)
+    fn_ref = iii_client.register_function("test.api.download.pdf.py", handler)
     trigger = iii_client.register_trigger(
         {
             "type": "http",
@@ -296,7 +296,7 @@ async def test_upload_pdf_streaming(engine_http_url, iii_client: III):
         await response.writer.write(body)
         await response.writer.close_async()
 
-    fn_ref = iii_client.register_function({"id": "test.api.upload.pdf.py"}, handler)
+    fn_ref = iii_client.register_function("test.api.upload.pdf.py", handler)
     trigger = iii_client.register_trigger(
         {
             "type": "http",
@@ -359,7 +359,7 @@ async def test_sse_streaming(engine_http_url, iii_client: III):
 
         await response.writer.close_async()
 
-    fn_ref = iii_client.register_function({"id": "test.api.sse.py"}, handler)
+    fn_ref = iii_client.register_function("test.api.sse.py", handler)
     trigger = iii_client.register_trigger(
         {
             "type": "http",
@@ -434,7 +434,7 @@ async def test_urlencoded_form_data(engine_http_url, iii_client: III):
         await response.writer.write(result)
         await response.writer.close_async()
 
-    fn_ref = iii_client.register_function({"id": "test.api.form.urlencoded.py"}, handler)
+    fn_ref = iii_client.register_function("test.api.form.urlencoded.py", handler)
     trigger = iii_client.register_trigger(
         {
             "type": "http",
@@ -504,7 +504,7 @@ async def test_multipart_form_data(engine_http_url, iii_client: III):
         await response.writer.write(result)
         await response.writer.close_async()
 
-    fn_ref = iii_client.register_function({"id": "test.api.form.multipart.py"}, handler)
+    fn_ref = iii_client.register_function("test.api.form.multipart.py", handler)
     trigger = iii_client.register_trigger(
         {
             "type": "http",

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

@@ -21,9 +21,7 @@ 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."""
-    result = iii_client.trigger(
-        {"function_id": "engine::functions::list", "payload": {}}
-    )
+    result = iii_client.trigger({"function_id": "engine::functions::list", "payload": {}})
     functions = [FunctionInfo(**f) for f in result.get("functions", [])]
     assert isinstance(functions, list)
 
@@ -37,7 +35,7 @@ async def test_register_and_invoke_function(iii_client: III):
         received.append(data)
         return {"echoed": data}
 
-    fn = iii_client.register_function({"id": "test.bridge.py.echo"}, echo_handler)
+    fn = iii_client.register_function("test.bridge.py.echo", echo_handler)
     await asyncio.sleep(0.3)
 
     try:
@@ -66,15 +64,17 @@ async def test_invoke_function_fire_and_forget(iii_client: III):
         received_event.set()
         return {}
 
-    fn = iii_client.register_function({"id": "test.bridge.py.receiver"}, receiver_handler)
+    fn = iii_client.register_function("test.bridge.py.receiver", receiver_handler)
     await asyncio.sleep(0.3)
 
     try:
-        result = iii_client.trigger({
-            "function_id": "test.bridge.py.receiver",
-            "payload": {"value": 42},
-            "action": TriggerAction.Void(),
-        })
+        result = iii_client.trigger(
+            {
+                "function_id": "test.bridge.py.receiver",
+                "payload": {"value": 42},
+                "action": TriggerAction.Void(),
+            }
+        )
 
         assert result is None
 
@@ -87,14 +87,12 @@ 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 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 _: {})
+    fn1 = iii_client.register_function("test.bridge.py.list.func1", lambda _: {})
+    fn2 = iii_client.register_function("test.bridge.py.list.func2", lambda _: {})
     await asyncio.sleep(0.3)
 
     try:
-        result = iii_client.trigger(
-            {"function_id": "engine::functions::list", "payload": {}}
-        )
+        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]
 
@@ -109,8 +107,10 @@ async def test_list_registered_functions(iii_client: III):
 async def test_reject_non_existent_function(iii_client: III):
     """Triggering a non-existent function raises an error."""
     with pytest.raises(Exception):
-        iii_client.trigger({
-            "function_id": "nonexistent.function.py",
-            "payload": {},
-            "timeout_ms": 2000,
-        })
+        iii_client.trigger(
+            {
+                "function_id": "nonexistent.function.py",
+                "payload": {},
+                "timeout_ms": 2000,
+            }
+        )

{iii_sdk-0.11.4.dev1 → iii_sdk-0.11.4.dev3}/tests/test_context_propagation.py

@@ -60,19 +60,21 @@ def test_handle_invoke_restores_trace_context_from_traceparent():
         return {"ok": True}
 
     client = III(address="ws://localhost:9999", options=InitOptions(worker_name="test"))
-    client.register_function({"id": "test::fn"}, handler)
+    client.register_function("test::fn", handler)
 
     # Real W3C traceparent: trace_id = 4bf92f3577b34da6a3ce929d0e0e4736
     fake_traceparent = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
 
     # Use a non-None invocation_id with mocked _send so _invoke_with_otel_context is awaited
     with patch.object(client, "_send", new_callable=AsyncMock):
-        client._run_on_loop(client._handle_invoke(
-            invocation_id="test-invocation-id",
-            path="test::fn",
-            data={},
-            traceparent=fake_traceparent,
-        ))
+        client._run_on_loop(
+            client._handle_invoke(
+                invocation_id="test-invocation-id",
+                path="test::fn",
+                data={},
+                traceparent=fake_traceparent,
+            )
+        )
 
     expected_trace_id = 0x4BF92F3577B34DA6A3CE929D0E0E4736
     assert captured_trace_id, "handler did not capture an active span"
@@ -90,15 +92,17 @@ def test_handle_invoke_without_traceparent_runs_normally():
         return {"ok": True}
 
     client = III(address="ws://localhost:9999", options=InitOptions(worker_name="test"))
-    client.register_function({"id": "test::fn"}, handler)
+    client.register_function("test::fn", handler)
 
     with patch.object(client, "_send", new_callable=AsyncMock):
-        client._run_on_loop(client._handle_invoke(
-            invocation_id="test-invocation-id",
-            path="test::fn",
-            data={},
-            traceparent=None,
-        ))
+        client._run_on_loop(
+            client._handle_invoke(
+                invocation_id="test-invocation-id",
+                path="test::fn",
+                data={},
+                traceparent=None,
+            )
+        )
 
     assert called