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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iii-sdk
-Version: 0.11.4.dev3
+Version: 0.11.4.dev4
 Summary: III SDK for Python
 Project-URL: Homepage, https://github.com/iii-hq/sdk
 Project-URL: Repository, https://github.com/iii-hq/sdk

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

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

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

@@ -5,7 +5,7 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from typing import Any, Generic, List, Literal, TypeVar
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 TData = TypeVar("TData")
 
@@ -91,6 +91,20 @@ class StreamUpdateInput(BaseModel):
     ops: list["UpdateOp"]
 
 
+class UpdateOpError(BaseModel):
+    """Per-op error returned by ``state::update`` / ``stream::update``.
+
+    Currently emitted only by the ``merge`` op when input violates the
+    new validation bounds. Successfully applied ops are still
+    reflected in the response's ``new_value``.
+    """
+
+    op_index: int
+    code: str
+    message: str
+    doc_url: str | None = None
+
+
 class StreamSetResult(BaseModel, Generic[TData]):
     """Result of stream set operation."""
 
@@ -103,6 +117,12 @@ class StreamUpdateResult(BaseModel, Generic[TData]):
 
     old_value: TData | None = None
     new_value: TData
+    # Per-op errors. Currently emitted only by the ``merge`` op for
+    # validation rejections. Field is omitted from the JSON wire when
+    # empty. ``default_factory`` is used (not ``= []``) to keep
+    # Pydantic's parameterized-Generic + default handling well-behaved
+    # across Python versions.
+    errors: list[UpdateOpError] = Field(default_factory=list)
 
 
 class StreamDeleteResult(BaseModel):
@@ -151,13 +171,38 @@ class UpdateRemove(BaseModel):
 
 
 class UpdateMerge(BaseModel):
-    """Shallow root-level merge operation for stream update.
-
-    Only an empty path is supported. Non-empty paths are ignored by the engine.
+    """Shallow merge an object into the target.
+
+    The target is the root (when ``path`` is omitted, an empty string,
+    or an empty list) or an arbitrary nested location specified by an
+    array of literal segments.
+
+    Path forms accepted:
+      - ``None`` / ``""`` / ``[]``: merge at the root.
+      - ``"foo"``: equivalent to ``["foo"]`` -- single first-level key.
+      - ``["a", "b", "c"]``: nested path. Each element is a *literal*
+        key. ``["a.b"]`` writes a single key named ``"a.b"``, not
+        ``a -> b``.
+
+    Engine semantics:
+      - Missing or non-object intermediates along the path are
+        auto-replaced with ``{}``.
+      - The merge is shallow at the target node (top-level keys of
+        ``value`` overwrite same-named keys; siblings preserved).
+
+    Validation: invalid paths/values (depth > 32 segments, segment >
+    256 bytes, value depth > 16, > 1024 top-level keys, or any
+    ``__proto__`` / ``constructor`` / ``prototype`` segment or
+    top-level key) are rejected with a structured error in the
+    ``errors`` array of the ``state::update`` / ``stream::update``
+    response. The merge does not apply when an error is returned.
     """
 
     type: str = "merge"
-    path: str
+    # Optional. Accepts a single string or a list of literal segments.
+    # Pydantic resolves ``str | list[str]`` via smart-union: string
+    # input -> str, array input -> list[str].
+    path: str | list[str] | None = None
     value: Any
 
 

iii_sdk-0.11.4.dev4/tests/test_stream_models.py

@@ -0,0 +1,73 @@
+"""Unit tests for stream model serialization."""
+
+import json
+
+from iii.stream import StreamUpdateResult, UpdateAppend, UpdateMerge, UpdateOpError
+
+
+def test_update_append_model_serializes() -> None:
+    op = UpdateAppend(path="chunks", value={"text": "hello"})
+
+    assert op.model_dump() == {"type": "append", "path": "chunks", "value": {"text": "hello"}}
+
+
+def test_update_merge_with_string_path_round_trips() -> None:
+    op = UpdateMerge(path="session-abc", value={"author": "alice"})
+    dumped = op.model_dump()
+    assert dumped == {
+        "type": "merge",
+        "path": "session-abc",
+        "value": {"author": "alice"},
+    }
+    # JSON round-trip preserves the string form.
+    parsed = UpdateMerge.model_validate(json.loads(json.dumps(dumped)))
+    assert parsed.path == "session-abc"
+
+
+def test_update_merge_with_array_path_round_trips() -> None:
+    op = UpdateMerge(path=["sessions", "abc"], value={"ts": "chunk"})
+    dumped = op.model_dump()
+    assert dumped == {
+        "type": "merge",
+        "path": ["sessions", "abc"],
+        "value": {"ts": "chunk"},
+    }
+    parsed = UpdateMerge.model_validate(json.loads(json.dumps(dumped)))
+    assert parsed.path == ["sessions", "abc"]
+
+
+def test_update_merge_without_path_round_trips() -> None:
+    op = UpdateMerge(value={"x": 1})
+    dumped = op.model_dump()
+    assert dumped == {"type": "merge", "path": None, "value": {"x": 1}}
+    parsed = UpdateMerge.model_validate(json.loads(json.dumps(dumped)))
+    assert parsed.path is None
+
+
+def test_update_op_error_round_trip() -> None:
+    err = UpdateOpError(
+        op_index=0,
+        code="merge.path.too_deep",
+        message="Path depth 33 exceeds maximum of 32",
+        doc_url="https://docs.iii.dev/workers/iii-state#merge-bounds",
+    )
+    dumped = err.model_dump()
+    assert dumped["code"] == "merge.path.too_deep"
+    assert dumped["op_index"] == 0
+
+
+def test_stream_update_result_with_errors_round_trips() -> None:
+    result = StreamUpdateResult[dict](
+        old_value=None,
+        new_value={"a": 1},
+        errors=[
+            UpdateOpError(
+                op_index=0,
+                code="merge.path.proto_polluted",
+                message='Path segment "__proto__" is a prototype-pollution sink',
+            )
+        ],
+    )
+    dumped = result.model_dump()
+    assert len(dumped["errors"]) == 1
+    assert dumped["errors"][0]["code"] == "merge.path.proto_polluted"

iii_sdk-0.11.4.dev3/tests/test_stream_models.py

@@ -1,9 +0,0 @@
-"""Unit tests for stream model serialization."""
-
-from iii.stream import UpdateAppend
-
-
-def test_update_append_model_serializes() -> None:
-    op = UpdateAppend(path="chunks", value={"text": "hello"})
-
-    assert op.model_dump() == {"type": "append", "path": "chunks", "value": {"text": "hello"}}