graphddb-runtime 0.1.0__tar.gz

graphddb_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: graphddb-runtime
+Version: 0.1.0
+Summary: Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44).
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: boto3>=1.26
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+
+# graphddb-runtime
+
+Thin DynamoDB executor for [GraphDDB](https://www.npmjs.com/package/graphddb)-generated
+Python repositories.
+
+`graphddb-runtime` is the small, hand-written package that generated
+`repositories.py` modules import as `from graphddb_runtime import GraphDDBRuntime`.
+It interprets the `manifest.json` / `operations.json` specifications produced by
+`graphddb generate python` and executes the validated access patterns against
+DynamoDB through boto3 — no scans, no hand-written key logic.
+
+## Features
+
+- **Single-operation core** — `GetItem` / `Query` reads and
+  `PutItem` / `UpdateItem` / `DeleteItem` writes.
+- **Relations & assembly** — relation traversal, multi-operation assembly,
+  `BatchGetItem`, result limits, and `explain`.
+- **Conditional & transactional writes** — conditional writes, declarative
+  transactions (`execute_transaction`, with `forEach` / `when` expansion and
+  `TransactWriteItems` batching up to 25 items).
+- **Async adapter** — `AsyncGraphDDBRuntime` exposes an `await`-able surface
+  with behavior identical to the synchronous runtime.
+
+## Install
+
+```bash
+pip install graphddb-runtime
+```
+
+Requires Python 3.9+ and boto3.
+
+> **Versioning.** `graphddb-runtime` tracks the `graphddb` npm package version:
+> a given runtime release matches the `graphddb` CLI of the same version, so the
+> generated `manifest.json` / `operations.json` and the runtime that interprets
+> them always stay in sync. Install the `graphddb-runtime` whose version equals
+> the `graphddb` CLI you generated with.
+
+## Usage
+
+Point the runtime at the two JSON specs emitted by `graphddb generate python`
+and pass a boto3 DynamoDB client. The generated repositories wrap it with typed
+methods:
+
+```python
+import boto3
+from graphddb_runtime import GraphDDBRuntime
+from generated import UserRepository
+
+runtime = GraphDDBRuntime(
+    dynamodb_client=boto3.client("dynamodb"),
+    manifest_path="generated/manifest.json",
+    operations_path="generated/operations.json",
+    # Map logical table names to deployed physical names when they differ.
+    table_mapping={"UserPermissions": "UserPermissions-prod"},
+)
+
+users = UserRepository(runtime)
+user = users.get_user_by_email(email="alice@example.com")
+```
+
+### Async
+
+boto3 is a synchronous SDK, so the runtime core is synchronous.
+`AsyncGraphDDBRuntime` is a thin adapter that runs each blocking call in a worker
+thread via `asyncio.to_thread`, giving an `await`-able surface with identical
+behavior (same params, specs, results, and error types). It does not require
+`aioboto3`.
+
+```python
+import boto3
+from graphddb_runtime import GraphDDBRuntime, AsyncGraphDDBRuntime
+
+sync = GraphDDBRuntime(
+    dynamodb_client=boto3.client("dynamodb"),
+    manifest_path="generated/manifest.json",
+    operations_path="generated/operations.json",
+)
+runtime = AsyncGraphDDBRuntime(sync)
+
+user = await runtime.execute_query("getUser", {"userId": "alice"})
+await runtime.execute_transaction("addManyMembers", {"groupId": "eng", "members": [...]})
+```
+
+The wrapped synchronous runtime is available as `runtime.sync` for callers that
+need the blocking API directly.
+
+## AWS Lambda
+
+The runtime loads the JSON specs from disk and constructs a boto3 client — both
+are cold-start costs you want to pay **once**, in module scope, so they are
+reused across warm invocations (and frozen by SnapStart).
+
+```python
+# handler.py — module scope runs once per execution environment (cold start).
+import json
+import boto3
+from graphddb_runtime import GraphDDBRuntime
+from generated import UserRepository
+
+_runtime = GraphDDBRuntime(
+    dynamodb_client=boto3.client("dynamodb"),
+    manifest_path="generated/manifest.json",
+    operations_path="generated/operations.json",
+    table_mapping={"UserPermissions": "UserPermissions-prod"},
+)
+_users = UserRepository(_runtime)
+
+
+def handler(event, context):
+    user = _users.get_user_by_email(email=event["queryStringParameters"]["email"])
+    if user is None:
+        return {"statusCode": 404, "body": "not found"}
+    return {"statusCode": 200, "body": json.dumps(user)}
+```
+
+### SnapStart
+
+Lambda SnapStart snapshots the initialized execution environment after the
+module-scope code runs, so the global client + `GraphDDBRuntime(...)` construction
+is captured in the snapshot and skipped on restore.
+
+- **Initialize the runtime and repositories in module scope** (as above), never
+  inside the handler — that is what gets snapshotted.
+- **Do not cache short-lived state across the snapshot** (credentials/tokens with
+  an expiry, random seeds). The DynamoDB client and the loaded specs are safe to
+  snapshot; refresh anything time-sensitive inside the handler.
+
+### Packaging
+
+The deployment artifact needs three things: this runtime package, the generated
+bindings, and the two JSON specs. boto3/botocore are provided by the Lambda Python
+runtime, so they need not be vendored (pin them only if you require a specific
+version).
+
+```bash
+mkdir -p build
+pip install graphddb-runtime --target build    # the runtime
+cp -r generated build/generated                # manifest.json, operations.json, *.py
+cp handler.py build/
+( cd build && zip -r ../function.zip . )        # handler = handler.handler
+```
+
+Make sure the `manifest_path` / `operations_path` you pass to `GraphDDBRuntime`
+resolve relative to the deployed working directory (e.g. `generated/...` when the
+specs are zipped under a `generated/` folder at the artifact root).
+
+## License
+
+MIT

graphddb_runtime-0.1.0/README.md

@@ -0,0 +1,149 @@
+# graphddb-runtime
+
+Thin DynamoDB executor for [GraphDDB](https://www.npmjs.com/package/graphddb)-generated
+Python repositories.
+
+`graphddb-runtime` is the small, hand-written package that generated
+`repositories.py` modules import as `from graphddb_runtime import GraphDDBRuntime`.
+It interprets the `manifest.json` / `operations.json` specifications produced by
+`graphddb generate python` and executes the validated access patterns against
+DynamoDB through boto3 — no scans, no hand-written key logic.
+
+## Features
+
+- **Single-operation core** — `GetItem` / `Query` reads and
+  `PutItem` / `UpdateItem` / `DeleteItem` writes.
+- **Relations & assembly** — relation traversal, multi-operation assembly,
+  `BatchGetItem`, result limits, and `explain`.
+- **Conditional & transactional writes** — conditional writes, declarative
+  transactions (`execute_transaction`, with `forEach` / `when` expansion and
+  `TransactWriteItems` batching up to 25 items).
+- **Async adapter** — `AsyncGraphDDBRuntime` exposes an `await`-able surface
+  with behavior identical to the synchronous runtime.
+
+## Install
+
+```bash
+pip install graphddb-runtime
+```
+
+Requires Python 3.9+ and boto3.
+
+> **Versioning.** `graphddb-runtime` tracks the `graphddb` npm package version:
+> a given runtime release matches the `graphddb` CLI of the same version, so the
+> generated `manifest.json` / `operations.json` and the runtime that interprets
+> them always stay in sync. Install the `graphddb-runtime` whose version equals
+> the `graphddb` CLI you generated with.
+
+## Usage
+
+Point the runtime at the two JSON specs emitted by `graphddb generate python`
+and pass a boto3 DynamoDB client. The generated repositories wrap it with typed
+methods:
+
+```python
+import boto3
+from graphddb_runtime import GraphDDBRuntime
+from generated import UserRepository
+
+runtime = GraphDDBRuntime(
+    dynamodb_client=boto3.client("dynamodb"),
+    manifest_path="generated/manifest.json",
+    operations_path="generated/operations.json",
+    # Map logical table names to deployed physical names when they differ.
+    table_mapping={"UserPermissions": "UserPermissions-prod"},
+)
+
+users = UserRepository(runtime)
+user = users.get_user_by_email(email="alice@example.com")
+```
+
+### Async
+
+boto3 is a synchronous SDK, so the runtime core is synchronous.
+`AsyncGraphDDBRuntime` is a thin adapter that runs each blocking call in a worker
+thread via `asyncio.to_thread`, giving an `await`-able surface with identical
+behavior (same params, specs, results, and error types). It does not require
+`aioboto3`.
+
+```python
+import boto3
+from graphddb_runtime import GraphDDBRuntime, AsyncGraphDDBRuntime
+
+sync = GraphDDBRuntime(
+    dynamodb_client=boto3.client("dynamodb"),
+    manifest_path="generated/manifest.json",
+    operations_path="generated/operations.json",
+)
+runtime = AsyncGraphDDBRuntime(sync)
+
+user = await runtime.execute_query("getUser", {"userId": "alice"})
+await runtime.execute_transaction("addManyMembers", {"groupId": "eng", "members": [...]})
+```
+
+The wrapped synchronous runtime is available as `runtime.sync` for callers that
+need the blocking API directly.
+
+## AWS Lambda
+
+The runtime loads the JSON specs from disk and constructs a boto3 client — both
+are cold-start costs you want to pay **once**, in module scope, so they are
+reused across warm invocations (and frozen by SnapStart).
+
+```python
+# handler.py — module scope runs once per execution environment (cold start).
+import json
+import boto3
+from graphddb_runtime import GraphDDBRuntime
+from generated import UserRepository
+
+_runtime = GraphDDBRuntime(
+    dynamodb_client=boto3.client("dynamodb"),
+    manifest_path="generated/manifest.json",
+    operations_path="generated/operations.json",
+    table_mapping={"UserPermissions": "UserPermissions-prod"},
+)
+_users = UserRepository(_runtime)
+
+
+def handler(event, context):
+    user = _users.get_user_by_email(email=event["queryStringParameters"]["email"])
+    if user is None:
+        return {"statusCode": 404, "body": "not found"}
+    return {"statusCode": 200, "body": json.dumps(user)}
+```
+
+### SnapStart
+
+Lambda SnapStart snapshots the initialized execution environment after the
+module-scope code runs, so the global client + `GraphDDBRuntime(...)` construction
+is captured in the snapshot and skipped on restore.
+
+- **Initialize the runtime and repositories in module scope** (as above), never
+  inside the handler — that is what gets snapshotted.
+- **Do not cache short-lived state across the snapshot** (credentials/tokens with
+  an expiry, random seeds). The DynamoDB client and the loaded specs are safe to
+  snapshot; refresh anything time-sensitive inside the handler.
+
+### Packaging
+
+The deployment artifact needs three things: this runtime package, the generated
+bindings, and the two JSON specs. boto3/botocore are provided by the Lambda Python
+runtime, so they need not be vendored (pin them only if you require a specific
+version).
+
+```bash
+mkdir -p build
+pip install graphddb-runtime --target build    # the runtime
+cp -r generated build/generated                # manifest.json, operations.json, *.py
+cp handler.py build/
+( cd build && zip -r ../function.zip . )        # handler = handler.handler
+```
+
+Make sure the `manifest_path` / `operations_path` you pass to `GraphDDBRuntime`
+resolve relative to the deployed working directory (e.g. `generated/...` when the
+specs are zipped under a `generated/` folder at the artifact root).
+
+## License
+
+MIT

graphddb_runtime-0.1.0/graphddb_runtime/__init__.py

@@ -0,0 +1,58 @@
+"""GraphDDB Python runtime (issue #44, single-operation core).
+
+Public surface consumed by generated ``repositories.py`` and applications:
+
+- :class:`GraphDDBRuntime` — the executor.
+- :class:`RuntimeLimits` — execution-time bounds.
+- the :class:`GraphDDBError` family.
+"""
+
+from __future__ import annotations
+
+from .cursor import decode_cursor, encode_cursor
+from .errors import (
+    CommandNotFoundError,
+    ContractArityError,
+    ContractNotFoundError,
+    GraphDDBError,
+    HydrationError,
+    LimitExceededError,
+    MultiOperationNotSupportedError,
+    OperationExecutionError,
+    ParameterValidationError,
+    QueryNotFoundError,
+    TransactionNotFoundError,
+)
+from .async_runtime import AsyncGraphDDBRuntime
+from .concurrency import RELATION_TRAVERSAL_CONCURRENCY, map_with_concurrency
+from .limits import RuntimeLimits
+from .per_key_cursor import (
+    decode_per_key_cursor,
+    encode_per_key_cursor,
+    serialize_contract_key,
+)
+from .runtime import GraphDDBRuntime
+
+__all__ = [
+    "GraphDDBRuntime",
+    "AsyncGraphDDBRuntime",
+    "RuntimeLimits",
+    "RELATION_TRAVERSAL_CONCURRENCY",
+    "map_with_concurrency",
+    "GraphDDBError",
+    "QueryNotFoundError",
+    "CommandNotFoundError",
+    "TransactionNotFoundError",
+    "ContractNotFoundError",
+    "ContractArityError",
+    "ParameterValidationError",
+    "LimitExceededError",
+    "OperationExecutionError",
+    "HydrationError",
+    "MultiOperationNotSupportedError",
+    "encode_cursor",
+    "decode_cursor",
+    "serialize_contract_key",
+    "encode_per_key_cursor",
+    "decode_per_key_cursor",
+]

graphddb_runtime-0.1.0/graphddb_runtime/async_runtime.py

@@ -0,0 +1,110 @@
+"""Async adapter over the sync :class:`GraphDDBRuntime` (issue #46, Phase 4).
+
+boto3 is a synchronous SDK, so the runtime core is synchronous. This module
+provides a **thin** async wrapper that runs each blocking call in a worker
+thread via :func:`asyncio.to_thread`, giving an ``await``-able surface with
+**behavior equivalent** to the sync runtime (same params, same specs, same
+results, same error types) without duplicating the executor.
+
+It does not require ``aioboto3``; the wrapped sync runtime keeps using boto3.
+For a project that wants a fully non-blocking DynamoDB client, ``aioboto3`` can
+be adopted later behind the same interface — but for the common Lambda / request
+handler case, ``asyncio.to_thread`` is sufficient and keeps a single executor
+implementation (no TS/Python or sync/async divergence to test twice).
+
+Usage::
+
+    import boto3
+    from graphddb_runtime import GraphDDBRuntime, AsyncGraphDDBRuntime
+
+    sync = GraphDDBRuntime(boto3.client("dynamodb"), manifest, operations)
+    runtime = AsyncGraphDDBRuntime(sync)
+
+    user = await runtime.execute_query("getUser", {"userId": "alice"})
+    await runtime.execute_transaction("addManyMembers", {...})
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Mapping, Optional
+
+from .runtime import GraphDDBRuntime
+
+
+class AsyncGraphDDBRuntime:
+    """An ``await``-able adapter delegating to a sync :class:`GraphDDBRuntime`.
+
+    Every method runs its synchronous counterpart in a thread, so a slow boto3
+    round trip does not block the event loop. The wrapped runtime is exposed as
+    :attr:`sync` for callers that need the blocking API directly.
+    """
+
+    def __init__(self, runtime: GraphDDBRuntime) -> None:
+        self.sync = runtime
+
+    async def execute_query(
+        self,
+        query_id: str,
+        params: Mapping[str, Any],
+        options: Optional[Mapping[str, Any]] = None,
+    ) -> Optional[dict]:
+        return await asyncio.to_thread(
+            self.sync.execute_query, query_id, params, options
+        )
+
+    async def execute_query_method(
+        self,
+        contract_name: str,
+        method_name: str,
+        key_or_keys: Any,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        """Async wrapper over :meth:`GraphDDBRuntime.execute_query_method` (#62)."""
+        return await asyncio.to_thread(
+            self.sync.execute_query_method,
+            contract_name,
+            method_name,
+            key_or_keys,
+            params,
+        )
+
+    async def execute_command(
+        self,
+        command_id: str,
+        params: Mapping[str, Any],
+        options: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        await asyncio.to_thread(
+            self.sync.execute_command, command_id, params, options
+        )
+
+    async def execute_command_method(
+        self,
+        contract_name: str,
+        method_name: str,
+        key_or_keys: Any,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        """Async wrapper over :meth:`GraphDDBRuntime.execute_command_method` (#64)."""
+        await asyncio.to_thread(
+            self.sync.execute_command_method,
+            contract_name,
+            method_name,
+            key_or_keys,
+            params,
+        )
+
+    async def execute_transaction(
+        self,
+        transaction_id: str,
+        params: Mapping[str, Any],
+    ) -> None:
+        await asyncio.to_thread(
+            self.sync.execute_transaction, transaction_id, params
+        )
+
+    async def explain(self, query_id: str, params: Mapping[str, Any]) -> dict:
+        # `explain` does not touch DynamoDB, but keeping it on the async surface
+        # lets call sites use one runtime object uniformly.
+        return await asyncio.to_thread(self.sync.explain, query_id, params)

graphddb_runtime-0.1.0/graphddb_runtime/batch.py

@@ -0,0 +1,218 @@
+"""BatchGetItem chunking + UnprocessedKeys retry (issue #45).
+
+Port of the TypeScript batch semantics (``src/operations/batch-retry.ts`` /
+``src/executor/batch-executor.ts``):
+
+- keys are **deduped** before the request (``planBatchGetForQueryKeys`` /
+  ``dedupeDynamoKeys``);
+- split into chunks of at most :data:`BATCH_GET_MAX_KEYS` (100) keys;
+- each chunk retries ``UnprocessedKeys`` with exponential backoff
+  (``50 * 2^(attempt-1)`` ms, capped at 1000ms) up to
+  :data:`BATCH_MAX_RETRY_ATTEMPTS` (10) attempts, then raises.
+
+The sleep is injected so unit tests can observe the backoff schedule without
+real delays.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, List, Mapping, Optional
+
+# Mirrors src/operations/batch-retry.ts.
+BATCH_GET_MAX_KEYS = 100
+BATCH_WRITE_MAX_ITEMS = 25
+BATCH_MAX_RETRY_ATTEMPTS = 10
+
+
+def compute_backoff_delay(attempt: int) -> float:
+    """Backoff for a 1-based attempt: ``50 * 2^(attempt-1)`` ms, capped at 1000ms."""
+    return min(1000.0, 50.0 * (2 ** (attempt - 1))) / 1000.0
+
+
+def chunk(items: List[Any], size: int) -> List[List[Any]]:
+    return [items[i : i + size] for i in range(0, len(items), size)]
+
+
+def serialize_key(key: Mapping[str, Any]) -> str:
+    """Stable string form of a (plain) key for dedup / parent matching.
+
+    Mirrors the TS ``dedupeDynamoKeys`` / ``serializeQueryKey`` ordering
+    (attributes sorted by name).
+    """
+    import json
+
+    return json.dumps(sorted(key.items()), separators=(",", ":"), default=str)
+
+
+class BatchGetExecutor:
+    """Executes a deduped, chunked, retrying BatchGetItem against a boto3 client.
+
+    The client is the low-level ``boto3.client("dynamodb")`` (AttributeValue
+    shapes). ``request_extra`` carries the optional ``ProjectionExpression`` /
+    ``ExpressionAttributeNames``. Returns the flat list of raw (AttributeValue)
+    items across all chunks/retries.
+    """
+
+    def __init__(
+        self,
+        client: Any,
+        *,
+        boto_errors: tuple = (),
+        on_request: Optional[Callable[[int], None]] = None,
+        sleep: Callable[[float], None] = time.sleep,
+        max_batch_get_items: int = BATCH_GET_MAX_KEYS,
+    ) -> None:
+        self._client = client
+        self._boto_errors = boto_errors
+        self._on_request = on_request
+        self._sleep = sleep
+        self._max_batch_get_items = max_batch_get_items
+
+    def get(
+        self,
+        physical_table: str,
+        serialized_keys: List[Dict[str, Any]],
+        request_extra: Optional[Dict[str, Any]] = None,
+    ) -> List[Dict[str, Any]]:
+        if not serialized_keys:
+            return []
+
+        items: List[Dict[str, Any]] = []
+        for batch in chunk(serialized_keys, self._max_batch_get_items):
+            items.extend(
+                self._get_chunk(physical_table, batch, request_extra or {})
+            )
+        return items
+
+    def _get_chunk(
+        self,
+        physical_table: str,
+        keys: List[Dict[str, Any]],
+        request_extra: Dict[str, Any],
+    ) -> List[Dict[str, Any]]:
+        pending = keys
+        attempt = 0
+        out: List[Dict[str, Any]] = []
+
+        while pending:
+            table_request = {"Keys": pending, **request_extra}
+            if self._on_request is not None:
+                self._on_request(len(pending))
+            try:
+                resp = self._client.batch_get_item(
+                    RequestItems={physical_table: table_request}
+                )
+            except self._boto_errors as exc:  # type: ignore[misc]
+                from .errors import OperationExecutionError
+
+                raise OperationExecutionError(
+                    f"BatchGetItem failed for table {physical_table!r}: {exc}",
+                    original=exc,
+                ) from exc
+
+            out.extend(resp.get("Responses", {}).get(physical_table, []))
+
+            unprocessed = (
+                resp.get("UnprocessedKeys", {})
+                .get(physical_table, {})
+                .get("Keys", [])
+            )
+            if not unprocessed:
+                break
+
+            if attempt >= BATCH_MAX_RETRY_ATTEMPTS:
+                from .errors import OperationExecutionError
+
+                raise OperationExecutionError(
+                    f"BatchGet exceeded the maximum of {BATCH_MAX_RETRY_ATTEMPTS} "
+                    f"retry attempts with {len(unprocessed)} key(s) still "
+                    f"unprocessed for table {physical_table!r} (likely sustained "
+                    f"throttling)."
+                )
+
+            pending = unprocessed
+            attempt += 1
+            self._sleep(compute_backoff_delay(attempt))
+
+        return out
+
+
+class BatchWriteExecutor:
+    """Executes a chunked, retrying ``BatchWriteItem`` against a boto3 client.
+
+    Port of the TypeScript batch-write semantics
+    (``src/operations/batch-retry.ts`` ``batchWriteChunkWithRetry`` +
+    ``src/operations/batch.ts`` ``executeBatchWrite``): the per-table write
+    requests (``{"PutRequest": {"Item": …}}`` / ``{"DeleteRequest": {"Key": …}}``,
+    AttributeValue shapes) are split into chunks of at most
+    :data:`BATCH_WRITE_MAX_ITEMS` (25); each chunk retries ``UnprocessedItems``
+    with the same exponential backoff as :class:`BatchGetExecutor` up to
+    :data:`BATCH_MAX_RETRY_ATTEMPTS` attempts, then raises.
+
+    ``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
+    so unit tests can observe the backoff schedule without real delays.
+    """
+
+    def __init__(
+        self,
+        client: Any,
+        *,
+        boto_errors: tuple = (),
+        on_request: Optional[Callable[[int], None]] = None,
+        sleep: Callable[[float], None] = time.sleep,
+        max_batch_write_items: int = BATCH_WRITE_MAX_ITEMS,
+    ) -> None:
+        self._client = client
+        self._boto_errors = boto_errors
+        self._on_request = on_request
+        self._sleep = sleep
+        self._max_batch_write_items = max_batch_write_items
+
+    def write(self, physical_table: str, requests: List[Dict[str, Any]]) -> None:
+        """Apply every write request to ``physical_table``, chunked + retried."""
+        if not requests:
+            return
+        for batch in chunk(requests, self._max_batch_write_items):
+            self._write_chunk(physical_table, batch)
+
+    def _write_chunk(
+        self, physical_table: str, requests: List[Dict[str, Any]]
+    ) -> None:
+        pending = requests
+        attempt = 0
+
+        while pending:
+            if self._on_request is not None:
+                self._on_request(len(pending))
+            try:
+                resp = self._client.batch_write_item(
+                    RequestItems={physical_table: pending}
+                )
+            except self._boto_errors as exc:  # type: ignore[misc]
+                from .errors import OperationExecutionError
+
+                raise OperationExecutionError(
+                    f"BatchWriteItem failed for table {physical_table!r}: {exc}",
+                    original=exc,
+                ) from exc
+
+            unprocessed = resp.get("UnprocessedItems", {}).get(physical_table, [])
+            if not unprocessed:
+                break
+
+            if attempt >= BATCH_MAX_RETRY_ATTEMPTS:
+                from .errors import OperationExecutionError
+
+                raise OperationExecutionError(
+                    f"BatchWrite exceeded the maximum of {BATCH_MAX_RETRY_ATTEMPTS} "
+                    f"retry attempts with {len(unprocessed)} item(s) still "
+                    f"unprocessed for table {physical_table!r} (likely sustained "
+                    f"throttling)."
+                )
+
+            pending = unprocessed
+            attempt += 1
+            self._sleep(compute_backoff_delay(attempt))