graphddb-runtime 0.1.0__tar.gz → 0.2.0__tar.gz

{graphddb_runtime-0.1.0 → graphddb_runtime-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphddb-runtime
-Version: 0.1.0
+Version: 0.2.0
 Summary: Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44).
 License: MIT
 Requires-Python: >=3.9

{graphddb_runtime-0.1.0 → graphddb_runtime-0.2.0}/graphddb_runtime/batch.py

@@ -152,7 +152,8 @@ class BatchWriteExecutor:
 
     ``BatchWriteItem`` carries **no conditions** (DynamoDB has no per-request
     ``ConditionExpression`` for it) and is **not atomic** — both are properties of
-    the command-contract ``'batchWrite'`` mode (issue #64). The sleep is injected
+    the command-contract ``mode: 'parallel'`` coalesced fan-out (issue #64/#101).
+    The sleep is injected
     so unit tests can observe the backoff schedule without real delays.
     """
 

{graphddb_runtime-0.1.0 → graphddb_runtime-0.2.0}/graphddb_runtime/runtime.py

@@ -789,11 +789,11 @@ class GraphDDBRuntime:
         the method's declared mode:
 
         - ``single`` key  → the one referenced write op in ``commands``;
-        - ``keys[]`` + ``transact``   → one ``TransactWriteItems`` (the synthesized
+        - ``keys[]`` + ``transaction`` → one ``TransactWriteItems`` (the synthesized
           per-key ``forEach`` transaction; **atomic**, ≤25, condition-capable). An
           array of **>25 keys is rejected** — an atomic transaction cannot be split.
-        - ``keys[]`` + ``batchWrite`` → a ``BatchWriteItem`` (**non-atomic**, **no
-          conditions**), chunked ≤25 per request with ``UnprocessedItems`` retry.
+        - ``keys[]`` + ``parallel``    → a non-atomic per-key fan-out with partial
+          success (unconditioned put/delete coalesce into a ``BatchWriteItem``).
 
         ``params`` are the mutation values shared across every key (the body's
         ``params`` argument). For each key the runtime merges ``{**key, **params}``
@@ -810,9 +810,15 @@ class GraphDDBRuntime:
         shared = dict(params or {})
 
         if isinstance(key_or_keys, list):
-            self._execute_command_batch(
+            outcome = self._execute_command_batch(
                 contract_name, method_name, method, key_or_keys, shared
             )
+            # #101 `mode: 'parallel'` returns a partial-success result list; the
+            # atomic / batchWrite forms return None (fire-and-forget). Surface the
+            # parallel outcome to the caller wrapped as `{"results": [...]}`, matching
+            # the TS runtime's `CommandParallelReturn`.
+            if outcome is not None:
+                return {"results": outcome}
             return None
 
         # Single key → the referenced write surface, driven by key + params.
@@ -894,15 +900,19 @@ class GraphDDBRuntime:
         method: Mapping[str, Any],
         keys: List[Mapping[str, Any]],
         shared: Mapping[str, Any],
-    ) -> None:
-        """Apply a command method's array form per its declared batch target."""
+    ) -> Optional[List[Dict[str, Any]]]:
+        """Apply a command method's array form per its declared `mode` target.
+
+        Returns ``None`` for the atomic ``transaction`` form (fire-and-forget), or
+        the per-op partial-success result list for the #101 ``parallel`` form."""
         batch = method.get("batch")
         label = f"{contract_name}.{method_name}"
         if batch is None:
             raise ContractArityError(
                 f"command method '{label}' was called with an array of keys, but it "
-                f"declares no batched-write form. Declare a 'transact' or 'batchWrite' "
-                f"batch on the method, or call it with a single key."
+                f"declares no key-array bulk form. Author the method with "
+                f"`mode: 'transaction'` / `mode: 'parallel'`, or call it with a "
+                f"single key."
             )
         mode = batch.get("mode")
         if mode == "transaction":
@@ -912,13 +922,57 @@ class GraphDDBRuntime:
                 batch["transaction"], {**dict(shared), "keys": [dict(k) for k in keys]}
             )
             return
-        if mode == "batchWrite":
-            self._execute_batch_write(label, batch["operation"], keys, shared)
-            return
+        if mode == "parallel":
+            # #101 — non-atomic per-key fan-out with partial success. This branch
+            # returns a per-op result list; the caller (execute_command_method)
+            # surfaces it.
+            return self._execute_command_parallel(
+                label, batch["operation"], keys, shared
+            )
         raise GraphDDBError(  # pragma: no cover - serializer only emits the two above
             f"{label}: unknown batch resolution mode '{mode}'"
         )
 
+    def _execute_command_parallel(
+        self,
+        label: str,
+        command_id: str,
+        keys: List[Mapping[str, Any]],
+        shared: Mapping[str, Any],
+    ) -> List[Dict[str, Any]]:
+        """#101 ``mode: 'parallel'`` — non-atomic per-key fan-out, partial success.
+
+        Mirrors the TS ``executeParallelWrites``: when the per-key op carries no
+        condition and is put/delete, coalesce into a ``BatchWriteItem`` (chunk ≤25,
+        ``UnprocessedItems`` retry) and report every key ``{"ok": True}``; otherwise
+        issue each conditional write individually, collecting ``{"ok": bool,
+        "error"?}`` per key. A per-op failure NEVER aborts the others. The result
+        list is aligned to the input key order.
+        """
+        if not keys:
+            return []
+        spec = self._commands.get(command_id)
+        if spec is None:
+            raise ContractNotFoundError(
+                f"{label}: referenced write op '{command_id}' is not present in "
+                f"`commands`."
+            )
+        op_type = spec["type"]
+        has_condition = spec.get("condition") is not None
+        coalescible = not has_condition and op_type in ("PutItem", "DeleteItem")
+        if coalescible:
+            self._execute_batch_write(label, command_id, keys, shared)
+            return [{"ok": True} for _ in keys]
+        results: List[Dict[str, Any]] = []
+        for key in keys:
+            params = {**dict(key), **dict(shared)}
+            try:
+                self.execute_command(command_id, params)
+                results.append({"ok": True})
+            except Exception as exc:  # noqa: BLE001 - per-op partial success
+                results.append({"ok": False, "error": str(exc)})
+        return results
+
     def _execute_batch_write(
         self,
         label: str,
@@ -930,8 +984,9 @@ class GraphDDBRuntime:
 
         Reuses :class:`BatchWriteExecutor` (chunk ≤25, ``UnprocessedItems`` retry).
         DynamoDB's ``BatchWriteItem`` supports only ``PutRequest`` / ``DeleteRequest``
-        — a command whose single-key op is an ``UpdateItem`` cannot resolve its
-        array form to a ``BatchWriteItem`` (it must declare ``transact``).
+        — a command whose single-key op is an ``UpdateItem`` cannot coalesce its
+        ``mode: 'parallel'`` array form into a ``BatchWriteItem`` (it falls back to
+        per-key ``UpdateItem`` calls, or must declare ``mode: 'transaction'``).
         """
         spec = self._commands.get(command_id)
         if spec is None:
@@ -942,8 +997,8 @@ class GraphDDBRuntime:
         op_type = spec["type"]
         if op_type == "UpdateItem":
             raise GraphDDBError(
-                f"{label}: 'batchWrite' only supports put / delete (DynamoDB's "
-                f"BatchWriteItem has no Update request). Declare a 'transact' batch "
+                f"{label}: BatchWriteItem only supports put / delete (DynamoDB's "
+                f"BatchWriteItem has no Update request). Declare `mode: 'transaction'` "
                 f"for a batched update."
             )
         requests: List[Dict[str, Any]] = []

{graphddb_runtime-0.1.0 → graphddb_runtime-0.2.0}/graphddb_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphddb-runtime
-Version: 0.1.0
+Version: 0.2.0
 Summary: Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44).
 License: MIT
 Requires-Python: >=3.9

{graphddb_runtime-0.1.0 → graphddb_runtime-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphddb-runtime"
-version = "0.1.0"
+version = "0.2.0"
 description = "Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44)."
 readme = "README.md"
 requires-python = ">=3.9"

{graphddb_runtime-0.1.0 → graphddb_runtime-0.2.0}/tests/test_integration_command.py

@@ -6,11 +6,11 @@ fixtures (``UserCommands`` / ``MembershipCommands`` in operations.json) and
 asserts the **actual persisted state** after each write:
 
   - single key  → one write op (update / put / delete);
-  - key array + 'transact'   → one atomic TransactWriteItems (with a per-item
-    condition: applies on success, rolls the WHOLE batch back on failure);
-  - key array + 'batchWrite' → a non-atomic BatchWriteItem (put / delete),
-    chunked > 25 with retry;
-  - a >25-key 'transact' array is rejected (an atomic batch cannot be split).
+  - key array + `mode: 'transaction'` → one atomic TransactWriteItems (with a
+    per-item condition: applies on success, rolls the WHOLE batch back on failure);
+  - key array + `mode: 'parallel'`    → a non-atomic per-key fan-out (put / delete
+    coalesce into BatchWriteItem), chunked > 25 with retry;
+  - a >25-key `mode: 'transaction'` array is rejected (an atomic batch cannot be split).
 
 This mirrors the TS suite (__tests__/integration/command-runtime.test.ts) over
 the **same SSoT**, proving the two runtimes produce identical effects.
@@ -147,7 +147,10 @@ def test_single_update_applies(rt, client):
 
 def test_single_put_then_delete(rt, client):
     rt.execute_command_method(
-        "MembershipCommands", "add", {"groupId": "eng", "userId": "solo"}, {"role": "lead"}
+        "MembershipCommands",
+        "add",
+        {"groupId": "eng", "userId": "solo"},
+        {"role": "lead", "joinedAt": "2021-06-01T00:00:00.000Z"},
     )
     row = _membership(client, "eng", "solo")
     assert row is not None and row["role"]["S"] == "lead"
@@ -172,9 +175,21 @@ def test_transact_array_applies_atomically(rt, client):
 
 
 def test_transact_condition_rolls_back_whole_batch_on_failure(rt, client):
-    # Make e 'pending' so its `status = active` condition fails; the atomic batch
-    # must then roll d back too.
-    rt.execute_command_method("UserCommands", "disable", {"userId": "e"}, {"status": "pending"})
+    # Make e 'pending' so its literal `status = active` condition fails; the atomic
+    # batch must then roll d back too. (`disable`'s input is `literal('disabled')`,
+    # so the 'pending' precondition is written with a raw put rather than the command.)
+    client.put_item(
+        TableName=TABLE,
+        Item={
+            "PK": {"S": "USER#e"},
+            "SK": {"S": "PROFILE"},
+            "userId": {"S": "e"},
+            "name": {"S": "User e"},
+            "email": {"S": "e@x.com"},
+            "status": {"S": "pending"},
+            "createdAt": {"S": "2021-01-01T00:00:00.000Z"},
+        },
+    )
     assert _user_status(client, "e") == "pending"
 
     with pytest.raises(OperationExecutionError):
@@ -182,7 +197,7 @@ def test_transact_condition_rolls_back_whole_batch_on_failure(rt, client):
             "UserCommands",
             "disableIfActive",
             [{"userId": "d"}, {"userId": "e"}],
-            {"status": "disabled", "expected": "active"},
+            {"status": "disabled"},
         )
     # d unchanged (rolled back); e unchanged.
     assert _user_status(client, "d") == "active"
@@ -194,7 +209,7 @@ def test_transact_condition_applies_when_all_hold(rt, client):
         "UserCommands",
         "disableIfActive",
         [{"userId": "f"}],
-        {"status": "disabled", "expected": "active"},
+        {"status": "disabled"},
     )
     assert _user_status(client, "f") == "disabled"
 
@@ -205,12 +220,14 @@ def test_transact_rejects_over_25_keys(rt, client):
         rt.execute_command_method("UserCommands", "disable", keys, {"status": "disabled"})
 
 
-# ── array + batchWrite → non-atomic BatchWriteItem (chunked > 25) ────────────
+# ── array + mode:'parallel' → non-atomic BatchWriteItem (chunked > 25) ───────
 
 
 def test_batch_write_puts_and_chunks_over_25(rt, client):
     keys = [{"groupId": "big", "userId": f"m{i}"} for i in range(30)]
-    rt.execute_command_method("MembershipCommands", "add", keys, {"role": "member"})
+    rt.execute_command_method(
+        "MembershipCommands", "add", keys, {"role": "member", "joinedAt": "2021-06-01T00:00:00.000Z"}
+    )
     assert _membership(client, "big", "m0")["role"]["S"] == "member"
     assert _membership(client, "big", "m24")["role"]["S"] == "member"
     assert _membership(client, "big", "m29")["role"]["S"] == "member"
@@ -218,7 +235,9 @@ def test_batch_write_puts_and_chunks_over_25(rt, client):
 
 def test_batch_write_deletes(rt, client):
     keys = [{"groupId": "big", "userId": f"m{i}"} for i in range(30)]
-    rt.execute_command_method("MembershipCommands", "add", keys, {"role": "member"})
+    rt.execute_command_method(
+        "MembershipCommands", "add", keys, {"role": "member", "joinedAt": "2021-06-01T00:00:00.000Z"}
+    )
     rt.execute_command_method("MembershipCommands", "remove", keys)
     assert _membership(client, "big", "m0") is None
     assert _membership(client, "big", "m29") is None

{graphddb_runtime-0.1.0 → graphddb_runtime-0.2.0}/tests/test_unit.py

@@ -901,7 +901,7 @@ def test_command_method_single_update_runs_one_update_item():
 
 
 def test_command_method_transact_array_runs_one_transaction():
-    """A key array + 'transact' → ONE TransactWriteItems (one item per key)."""
+    """A key array + `mode: 'transaction'` → ONE TransactWriteItems (one item per key)."""
     client = FakeClient()
     rt = make_runtime(client)
     rt.execute_command_method(
@@ -920,26 +920,28 @@ def test_command_method_transact_array_runs_one_transaction():
 
 
 def test_command_method_transact_carries_per_item_condition():
-    """A conditional 'transact' batch attaches the equality condition per item."""
+    """A conditional `mode: 'transaction'` batch attaches the equality condition per item."""
     client = FakeClient()
     rt = make_runtime(client)
     rt.execute_command_method(
         "UserCommands",
         "disableIfActive",
         [{"userId": "a"}, {"userId": "b"}],
-        {"status": "disabled", "expected": "active"},
+        {"status": "disabled"},
     )
     method, req = client.calls[0]
     assert method == "transact_write_items"
     update = req["TransactItems"][0]["Update"]
     assert "ConditionExpression" in update
-    assert "active" in [
-        _DESER.deserialize(v) for v in update["ExpressionAttributeValues"].values()
-    ]
+    # #101 descriptor form: the gate is a concrete-literal equality (status == 'active');
+    # the written value is the 'disabled' status param. Both appear per item.
+    values = [_DESER.deserialize(v) for v in update["ExpressionAttributeValues"].values()]
+    assert "active" in values
+    assert "disabled" in values
 
 
 def test_command_method_transact_rejects_over_25_keys():
-    """A >25-key 'transact' array is rejected — an atomic tx cannot be split."""
+    """A >25-key `mode: 'transaction'` array is rejected — an atomic tx cannot be split."""
     client = FakeClient()
     rt = make_runtime(client)
     keys = [{"userId": f"u{i}"} for i in range(26)]
@@ -949,32 +951,38 @@ def test_command_method_transact_rejects_over_25_keys():
     assert all(m != "transact_write_items" for m, _ in client.calls)
 
 
-def test_command_method_batch_write_array_runs_batch_write_item():
-    """A key array + 'batchWrite' → a BatchWriteItem of PutRequests (no conditions)."""
+def test_command_method_parallel_guarded_create_runs_individual_conditional_puts():
+    """#101 `mode: 'parallel'` + a guarded create (attribute_not_exists) → INDIVIDUAL
+    conditional PutItem writes (not a condition-less BatchWriteItem), with per-key
+    partial-success results aligned to key order."""
     client = FakeClient()
     rt = make_runtime(client)
-    rt.execute_command_method(
+    out = rt.execute_command_method(
         "MembershipCommands",
         "add",
         [{"groupId": "eng", "userId": "a"}, {"groupId": "eng", "userId": "b"}],
-        {"role": "member"},
+        {"role": "member", "joinedAt": "1970-01-01T00:00:00Z"},
     )
-    assert len(client.calls) == 1
-    method, req = client.calls[0]
-    assert method == "batch_write_item"
-    (table, requests), = req["RequestItems"].items()
-    assert len(requests) == 2
-    item0 = plain(requests[0]["PutRequest"]["Item"])
+    # A guarded create carries a condition, so the parallel path issues one PutItem
+    # per key (concurrently) — never a coalesced BatchWriteItem.
+    methods = [m for m, _ in client.calls]
+    assert methods == ["put_item", "put_item"]
+    first = client.calls[0][1]
+    assert "ConditionExpression" in first
+    item0 = plain(first["Item"])
     assert item0["PK"] == "GROUP#eng"
     assert item0["SK"] == "USER#a"
     assert item0["role"] == "member"
+    # Partial-success result: both keys ok, aligned to input order.
+    assert out == {"results": [{"ok": True}, {"ok": True}]}
 
 
-def test_command_method_batch_write_delete_runs_delete_requests():
-    """A 'batchWrite' delete resolves to DeleteRequests keyed per input key."""
+def test_command_method_parallel_unconditioned_delete_coalesces_batch_write():
+    """#101 `mode: 'parallel'` + an UNconditioned delete coalesces into a
+    BatchWriteItem (DeleteRequests), reporting every key ok."""
     client = FakeClient()
     rt = make_runtime(client)
-    rt.execute_command_method(
+    out = rt.execute_command_method(
         "MembershipCommands",
         "remove",
         [{"groupId": "eng", "userId": "a"}, {"groupId": "eng", "userId": "b"}],
@@ -986,6 +994,7 @@ def test_command_method_batch_write_delete_runs_delete_requests():
         "PK": "GROUP#eng",
         "SK": "USER#a",
     }
+    assert out == {"results": [{"ok": True}, {"ok": True}]}
 
 
 def test_command_method_unknown_contract_raises():