iii-sdk 0.11.7.dev1__tar.gz → 0.11.7.dev2__tar.gz

{iii_sdk-0.11.7.dev1 → iii_sdk-0.11.7.dev2}/PKG-INFO

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

{iii_sdk-0.11.7.dev1 → iii_sdk-0.11.7.dev2}/pyproject.toml

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

{iii_sdk-0.11.7.dev1 → iii_sdk-0.11.7.dev2}/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, Field
+from pydantic import BaseModel, Field, model_serializer
 
 TData = TypeVar("TData")
 
@@ -117,11 +117,13 @@ 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.
+    # Per-op errors. Emitted by ``merge`` and ``append`` for validation
+    # rejections (path/value bounds, proto-pollution segments) and by
+    # ``append`` for the ``append.type_mismatch`` and
+    # ``append.target_not_object`` surfaces. 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)
 
 
@@ -156,12 +158,57 @@ class UpdateDecrement(BaseModel):
 
 
 class UpdateAppend(BaseModel):
-    """Append operation for stream update."""
+    """Append an element to an array, concatenate a string, or push at a nested path.
+
+    The target is the root (when ``path`` is omitted, an empty string,
+    or an empty list), a single first-level key (when ``path`` is a
+    non-empty string), or an arbitrary nested location (when ``path``
+    is a list of literal segments).
+
+    Path forms accepted (mirrors :class:`UpdateMerge` after #1547):
+      - ``None`` / ``""`` / ``[]``: append at the root.
+      - ``"foo"``: append at the first-level key ``foo``. A dotted
+        string like ``"a.b"`` is the literal key ``"a.b"``, *not*
+        traversed as ``a -> b``.
+      - ``["a", "b", "c"]``: nested path; each element is a literal
+        segment.
+
+    Engine semantics:
+      - Missing/non-object intermediates along a nested path are
+        auto-created/replaced with ``{}``.
+      - At the leaf:
+          - missing/null + nested path -> ``[value]`` (always an array)
+          - missing/null + single-string path -> string-as-string for
+            the string-concat tier, otherwise ``[value]``
+          - existing array -> push
+          - existing string + string value -> concatenate
+          - existing object/scalar at the leaf -> ``append.type_mismatch``
+
+    Validation: invalid paths (depth > 32 segments, segment > 256
+    bytes, or any ``__proto__`` / ``constructor`` / ``prototype``
+    segment) are rejected with a structured error in the ``errors``
+    field of the ``state::update`` / ``stream::update`` response. The
+    append does not apply when an error is returned for that op.
+    """
 
     type: str = "append"
-    path: str
+    # Optional. Accepts a single string (legacy / first-level key) or
+    # a list of literal segments (nested append). ``None`` / ``""`` /
+    # ``[]`` all route to root append.
+    path: str | list[str] | None = None
     value: Any
 
+    @model_serializer(mode="wrap")
+    def _omit_none_path(self, handler):  # type: ignore[no-untyped-def]
+        # Drop ``path: None`` from the wire so cross-SDK consumers see
+        # the field absent rather than ``null``. Mirrors the Rust
+        # ``#[serde(skip_serializing_if = "Option::is_none")]`` on
+        # ``UpdateOp::Append.path``.
+        data = handler(self)
+        if data.get("path") is None:
+            data.pop("path", None)
+        return data
+
 
 class UpdateRemove(BaseModel):
     """Remove operation for stream update."""
@@ -205,6 +252,16 @@ class UpdateMerge(BaseModel):
     path: str | list[str] | None = None
     value: Any
 
+    @model_serializer(mode="wrap")
+    def _omit_none_path(self, handler):  # type: ignore[no-untyped-def]
+        # Mirrors the same skip-when-none rule applied to
+        # ``UpdateOp::Merge.path`` in the Rust SDK so cross-SDK wire
+        # payloads are byte-identical for root merges.
+        data = handler(self)
+        if data.get("path") is None:
+            data.pop("path", None)
+        return data
+
 
 UpdateOp = UpdateSet | UpdateIncrement | UpdateDecrement | UpdateAppend | UpdateRemove | UpdateMerge
 

iii_sdk-0.11.7.dev2/tests/test_stream_models.py

@@ -0,0 +1,134 @@
+"""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_append_with_array_path_round_trips() -> None:
+    """Closes issue #1552 case 3: nested-path array form is the new happy path."""
+    op = UpdateAppend(path=["entityId", "buffer"], value="chunk")
+    dumped = op.model_dump()
+    assert dumped == {
+        "type": "append",
+        "path": ["entityId", "buffer"],
+        "value": "chunk",
+    }
+    parsed = UpdateAppend.model_validate(json.loads(json.dumps(dumped)))
+    assert parsed.path == ["entityId", "buffer"]
+
+
+def test_update_append_without_path_round_trips() -> None:
+    """Root append omits ``path`` from the wire (parity with the Rust
+    ``skip_serializing_if = "Option::is_none"`` on
+    ``UpdateOp::Append.path`` — surfaced in #1612 review)."""
+    op = UpdateAppend(value="first")
+    dumped = op.model_dump()
+    assert dumped == {"type": "append", "value": "first"}
+    assert "path" not in dumped
+    parsed = UpdateAppend.model_validate(json.loads(json.dumps(dumped)))
+    assert parsed.path is None
+
+
+def test_update_append_with_explicit_none_path() -> None:
+    """Explicit ``None`` and missing field both round-trip through a
+    wire payload that has no ``path`` key. ``path: null`` payloads
+    coming from older clients still deserialize for backward compat."""
+    op = UpdateAppend(path=None, value=42)
+    assert op.path is None
+    assert op.model_dump() == {"type": "append", "value": 42}
+    parsed = UpdateAppend.model_validate({"type": "append", "value": 42})
+    assert parsed.path is None
+    parsed_null = UpdateAppend.model_validate(
+        {"type": "append", "path": None, "value": 42}
+    )
+    assert parsed_null.path is None
+
+
+def test_update_append_with_empty_string_path() -> None:
+    """Empty string is preserved as `Single("")` — engine maps it to root append."""
+    op = UpdateAppend(path="", value="x")
+    dumped = op.model_dump()
+    assert dumped["path"] == ""
+
+
+def test_update_append_with_dotted_string_keeps_literal_segment() -> None:
+    """`"a.b"` is a single literal key, never traversed as `a -> b`."""
+    op = UpdateAppend(path="entityId.buffer", value="literal")
+    parsed = UpdateAppend.model_validate(json.loads(json.dumps(op.model_dump())))
+    assert parsed.path == "entityId.buffer"
+
+
+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:
+    """Same wire-format rule as ``UpdateAppend``: root merge omits the
+    ``path`` key entirely. ``path: null`` payloads still deserialize."""
+    op = UpdateMerge(value={"x": 1})
+    dumped = op.model_dump()
+    assert dumped == {"type": "merge", "value": {"x": 1}}
+    assert "path" not in dumped
+    parsed = UpdateMerge.model_validate(json.loads(json.dumps(dumped)))
+    assert parsed.path is None
+    parsed_null = UpdateMerge.model_validate(
+        {"type": "merge", "path": None, "value": {"x": 1}}
+    )
+    assert parsed_null.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://iii.dev/docs/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.7.dev1/tests/test_stream_models.py

@@ -1,73 +0,0 @@
-"""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://iii.dev/docs/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"