async-batcher 0.2.2__tar.gz → 0.3.0__tar.gz

async_batcher-0.3.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: async-batcher
+Version: 0.3.0
+Summary: Async Python batching for bulk functions, database writes, messaging, and model inference.
+Keywords: asyncio,batching,bulk-processing,inference,backpressure
+Author: Hussein Awala
+Author-email: Hussein Awala <hussein@awala.fr>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Dist: aioboto3>=15.5,<16 ; extra == 'aws'
+Requires-Dist: aiohttp>=3.14.4,<4 ; extra == 'aws'
+Requires-Dist: urllib3>=2.8.0,<3 ; extra == 'aws'
+Requires-Dist: idna>=3.15,<4 ; extra == 'aws'
+Requires-Dist: aiokafka>=0.15.0,<1 ; extra == 'kafka'
+Requires-Dist: keras>=3.15.1,<4 ; extra == 'keras'
+Requires-Dist: pygments>=2.20,<3 ; extra == 'keras'
+Requires-Dist: pymongo>=4.19,<5 ; extra == 'mongodb'
+Requires-Dist: pinecone>=10.3,<11 ; extra == 'pinecone'
+Requires-Dist: scylla-driver>=3.29.13,<4 ; extra == 'scylla'
+Requires-Dist: scikit-learn>=1.9.1,<2 ; extra == 'sklearn'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.10,<3 ; extra == 'sqlalchemy'
+Requires-Python: >=3.11, <4.0
+Project-URL: Repository, https://github.com/hussein-awala/async-batcher
+Project-URL: Bug Tracker, https://github.com/hussein-awala/async-batcher/issues
+Project-URL: Documentation, https://hussein.awala.fr/async-batcher/
+Provides-Extra: aws
+Provides-Extra: kafka
+Provides-Extra: keras
+Provides-Extra: mongodb
+Provides-Extra: pinecone
+Provides-Extra: scylla
+Provides-Extra: sklearn
+Provides-Extra: sqlalchemy
+Description-Content-Type: text/markdown
+
+# AsyncBatcher
+
+[Documentation](https://hussein.awala.fr/async-batcher/0.3.0/) ·
+[Release notes](https://hussein.awala.fr/async-batcher/release-notes/)
+
+AsyncBatcher combines concurrent Python requests into batches and routes each result back to its caller.
+Wrap an existing bulk function, subclass `AsyncBatcher`, or use an adapter for a supported database,
+messaging client, or prediction model. The core package has no runtime dependencies.
+
+## Start with your workload
+
+| You need to… | Start here |
+| --- | --- |
+| Combine concurrent web requests into model predictions or writes | [Function quickstart](#quickstart), then the [FastAPI lifespan recipe](https://hussein.awala.fr/async-batcher/0.3.0/fastapi-recipe/) |
+| Import a large file or consume an async stream without keeping all results | [Bounded maps](https://hussein.awala.fr/async-batcher/0.3.0/bulk-processing/), [SQLite imports](https://hussein.awala.fr/async-batcher/0.3.0/cookbook/#import-a-file-or-async-stream-into-sqlite), and [recovery choices](https://hussein.awala.fr/async-batcher/0.3.0/cookbook/#choose-an-import-or-recovery-policy) |
+| Use an existing database, messaging, or prediction client | Choose its [adapter](#optional-adapters) and read its failure/ownership rules |
+| Send embeddings to a vector store | [Two-stage pipeline](https://hussein.awala.fr/async-batcher/0.3.0/cookbook/#connect-embedding-and-vector-storage-stages) and [Pinecone](https://hussein.awala.fr/async-batcher/0.3.0/pinecone/) |
+| Keep tenants, model revisions, or backend destinations separate | [Compatible request groups](https://hussein.awala.fr/async-batcher/0.3.0/grouped-batching/) and the [workload guide](https://hussein.awala.fr/async-batcher/0.3.0/workloads/) |
+| Limit bytes, tokens, or estimated work as well as request count | [Cost budgets](https://hussein.awala.fr/async-batcher/0.3.0/cost-aware-batching/) |
+
+Start with a [bounded importer or interactive service](https://hussein.awala.fr/async-batcher/0.3.0/starting-configurations/).
+The [workload guide](https://hussein.awala.fr/async-batcher/0.3.0/workloads/) helps choose limits, preserve routing metadata, and decide
+whether batching fits your backend. Batching requires a useful bulk operation; it is not a rate
+limiter, durable queue, or exactly-once delivery system.
+
+## Install
+
+Python 3.11 or newer is required. This README targets **Async Batcher 0.3.0**;
+check the [release history](https://hussein.awala.fr/async-batcher/release-notes/)
+for publication status. Install the package into your application's environment:
+
+```bash
+python -m pip install 'async-batcher==0.3.0'
+```
+
+The core has no runtime dependencies. Add only the extras you need, for example:
+
+```bash
+python -m pip install 'async-batcher[aws]==0.3.0'
+```
+
+See [installation](https://hussein.awala.fr/async-batcher/0.3.0/installation/) for uv, other extras, and repository recipes,
+and [migration from 0.2.2](https://hussein.awala.fr/async-batcher/0.3.0/migration/) before upgrading. Core and adapter usage
+does not need a source checkout. Runnable files under `examples/` are repository
+recipes, with separate [setup instructions](https://hussein.awala.fr/async-batcher/0.3.0/installation/#run-the-repository-recipes).
+
+## Quickstart
+
+Save this as `demo.py` and run `python demo.py` in the environment where you installed the package:
+
+```python
+import asyncio
+
+from async_batcher import AsyncBatcher
+
+
+async def double_many(values: list[int]) -> list[int]:
+    return [value * 2 for value in values]
+
+
+async def main():
+    async with AsyncBatcher.from_callable(
+        double_many, max_batch_size=5, max_queue_size=20, max_queue_time=0.01, concurrency=2
+    ) as batcher:
+        results = await asyncio.gather(*(batcher.process(i) for i in range(10)))
+        print(results)  # [0, 2, 4, 6, 8, 10, 12, 14, 16, 18]
+
+
+asyncio.run(main())
+```
+
+`process()` is a coroutine: submit calls concurrently to form batches. A loop that awaits each
+call before submitting the next normally produces single-item batches. Processing starts
+automatically. Stop the batcher before closing its clients, model resources, or executor.
+Existing [subclasses](https://hussein.awala.fr/async-batcher/0.3.0/api/) and adapters support the same managed lifecycle.
+
+## Guides
+
+- [Compatibility and migration](https://hussein.awala.fr/async-batcher/0.3.0/migration/): published features, Python requirements, and upgrade checks.
+- [Bounded starting configurations](https://hussein.awala.fr/async-batcher/0.3.0/starting-configurations/): copyable importer and interactive service examples.
+- [Choose by workload](https://hussein.awala.fr/async-batcher/0.3.0/workloads/): request compatibility, safe metadata, and configuration ownership.
+- [Batch an existing function](https://hussein.awala.fr/async-batcher/0.3.0/functions/): callable processors and managed cleanup.
+- [Bulk and streaming producers](https://hussein.awala.fr/async-batcher/0.3.0/bulk-processing/): bounded maps and waiting for queue space.
+- [Cost budgets](https://hussein.awala.fr/async-batcher/0.3.0/cost-aware-batching/): byte, token, or work limits alongside batch counts.
+- [Variable-length inference](https://hussein.awala.fr/async-batcher/0.3.0/variable-length-inference/): padding, conservative token budgets, and per-request output shapes.
+- [Operational visibility](https://hussein.awala.fr/async-batcher/0.3.0/observability/): snapshots and payload-free completion events.
+- [Grouped batching](https://hussein.awala.fr/async-batcher/0.3.0/grouped-batching/): isolate compatible requests with bounded child ownership.
+- [In-flight coalescing](https://hussein.awala.fr/async-batcher/0.3.0/coalescing/): share equivalent concurrent requests with bounded ownership.
+- [Cookbook](https://hussein.awala.fr/async-batcher/0.3.0/cookbook/): runnable SQLite imports, embedding pipelines, and measured batch sizes.
+- [Resumable imports](https://hussein.awala.fr/async-batcher/0.3.0/resumable-import/): immutable JSONL input with atomic SQLite checkpoints.
+- [Rejected-record imports](https://hussein.awala.fr/async-batcher/0.3.0/rejected-import/): continue past known input errors and retain a metadata-only audit.
+- [Durable embedding handoff](https://hussein.awala.fr/async-batcher/0.3.0/durable-embeddings/): save vectors before delivery and replay unfinished upserts.
+- [Provider quota and retry policy](https://hussein.awala.fr/async-batcher/0.3.0/provider-policy/): shared pacing, finite throttling retries, and cancellation.
+- [Cohere to Pinecone](https://hussein.awala.fr/async-batcher/0.3.0/cohere-pinecone/): real embeddings into an existing compatible vector index.
+- [FastAPI recipe](https://hussein.awala.fr/async-batcher/0.3.0/fastapi-recipe/): lifespan-managed predictions, SQLite writes, and HTTP overload handling.
+- [Operational recipes](https://hussein.awala.fr/async-batcher/0.3.0/operations/): separate deadlines, shared backend capacity, thread lifetime, and bounded telemetry.
+- [Core API and lifecycle](https://hussein.awala.fr/async-batcher/0.3.0/api/): limits, result mapping, errors, shutdown, restart, and executors.
+- [Contributing](https://github.com/hussein-awala/async-batcher/blob/0.3.0/CONTRIBUTING.md): locked development environments, test selection, integration services, and CI.
+- [Benchmarks](https://github.com/hussein-awala/async-batcher/blob/0.3.0/BENCHMARK.md): reproducible core measurements and archived application results.
+- [Public type contracts](https://hussein.awala.fr/async-batcher/0.3.0/typing/): inferred results, typed options, and installed-package checks.
+- [Security reporting](https://github.com/hussein-awala/async-batcher/blob/0.3.0/SECURITY.md) and [Code of Conduct](https://github.com/hussein-awala/async-batcher/blob/0.3.0/CODE_OF_CONDUCT.md).
+
+## Optional adapters
+
+The eight extras are independent; importing `async_batcher` does not import their clients.
+All adapters use the core lifecycle, with the limits and resource ownership described in each guide.
+
+| Extra | Operations | Guide |
+| --- | --- | --- |
+| `aws` | DynamoDB reads/writes; Kinesis and Firehose records | [DynamoDB](https://hussein.awala.fr/async-batcher/0.3.0/dynamodb/), [AWS streams](https://hussein.awala.fr/async-batcher/0.3.0/aws-streams/) |
+| `sqlalchemy` | SQLAlchemy inserts and ORM updates | [SQLAlchemy](https://hussein.awala.fr/async-batcher/0.3.0/databases/#sqlalchemy) |
+| `scylla` | cqlengine insert/update/delete batches | [ScyllaDB](https://hussein.awala.fr/async-batcher/0.3.0/databases/#scylladb) |
+| `mongodb` | Ordered native PyMongo writes | [MongoDB](https://hussein.awala.fr/async-batcher/0.3.0/databases/#mongodb) |
+| `kafka` | Native aiokafka producer batches | [Kafka](https://hussein.awala.fr/async-batcher/0.3.0/kafka/) |
+| `pinecone` | Vector upsert/fetch/delete | [Pinecone](https://hussein.awala.fr/async-batcher/0.3.0/pinecone/) |
+| `keras` | Dense-input Keras inference | [Keras](https://hussein.awala.fr/async-batcher/0.3.0/machine-learning/#keras) |
+| `sklearn` | Dense or sparse scikit-learn inference | [scikit-learn](https://hussein.awala.fr/async-batcher/0.3.0/machine-learning/#scikit-learn) |
+
+Services that do not offer a suitable bulk operation need a custom `process_batch` implementation.
+Batching alone does not enforce a service's request-rate limit or guarantee exactly-once side effects.

async_batcher-0.3.0/README.md

@@ -0,0 +1,120 @@
+# AsyncBatcher
+
+[Documentation](https://hussein.awala.fr/async-batcher/0.3.0/) ·
+[Release notes](https://hussein.awala.fr/async-batcher/release-notes/)
+
+AsyncBatcher combines concurrent Python requests into batches and routes each result back to its caller.
+Wrap an existing bulk function, subclass `AsyncBatcher`, or use an adapter for a supported database,
+messaging client, or prediction model. The core package has no runtime dependencies.
+
+## Start with your workload
+
+| You need to… | Start here |
+| --- | --- |
+| Combine concurrent web requests into model predictions or writes | [Function quickstart](#quickstart), then the [FastAPI lifespan recipe](https://hussein.awala.fr/async-batcher/0.3.0/fastapi-recipe/) |
+| Import a large file or consume an async stream without keeping all results | [Bounded maps](https://hussein.awala.fr/async-batcher/0.3.0/bulk-processing/), [SQLite imports](https://hussein.awala.fr/async-batcher/0.3.0/cookbook/#import-a-file-or-async-stream-into-sqlite), and [recovery choices](https://hussein.awala.fr/async-batcher/0.3.0/cookbook/#choose-an-import-or-recovery-policy) |
+| Use an existing database, messaging, or prediction client | Choose its [adapter](#optional-adapters) and read its failure/ownership rules |
+| Send embeddings to a vector store | [Two-stage pipeline](https://hussein.awala.fr/async-batcher/0.3.0/cookbook/#connect-embedding-and-vector-storage-stages) and [Pinecone](https://hussein.awala.fr/async-batcher/0.3.0/pinecone/) |
+| Keep tenants, model revisions, or backend destinations separate | [Compatible request groups](https://hussein.awala.fr/async-batcher/0.3.0/grouped-batching/) and the [workload guide](https://hussein.awala.fr/async-batcher/0.3.0/workloads/) |
+| Limit bytes, tokens, or estimated work as well as request count | [Cost budgets](https://hussein.awala.fr/async-batcher/0.3.0/cost-aware-batching/) |
+
+Start with a [bounded importer or interactive service](https://hussein.awala.fr/async-batcher/0.3.0/starting-configurations/).
+The [workload guide](https://hussein.awala.fr/async-batcher/0.3.0/workloads/) helps choose limits, preserve routing metadata, and decide
+whether batching fits your backend. Batching requires a useful bulk operation; it is not a rate
+limiter, durable queue, or exactly-once delivery system.
+
+## Install
+
+Python 3.11 or newer is required. This README targets **Async Batcher 0.3.0**;
+check the [release history](https://hussein.awala.fr/async-batcher/release-notes/)
+for publication status. Install the package into your application's environment:
+
+```bash
+python -m pip install 'async-batcher==0.3.0'
+```
+
+The core has no runtime dependencies. Add only the extras you need, for example:
+
+```bash
+python -m pip install 'async-batcher[aws]==0.3.0'
+```
+
+See [installation](https://hussein.awala.fr/async-batcher/0.3.0/installation/) for uv, other extras, and repository recipes,
+and [migration from 0.2.2](https://hussein.awala.fr/async-batcher/0.3.0/migration/) before upgrading. Core and adapter usage
+does not need a source checkout. Runnable files under `examples/` are repository
+recipes, with separate [setup instructions](https://hussein.awala.fr/async-batcher/0.3.0/installation/#run-the-repository-recipes).
+
+## Quickstart
+
+Save this as `demo.py` and run `python demo.py` in the environment where you installed the package:
+
+```python
+import asyncio
+
+from async_batcher import AsyncBatcher
+
+
+async def double_many(values: list[int]) -> list[int]:
+    return [value * 2 for value in values]
+
+
+async def main():
+    async with AsyncBatcher.from_callable(
+        double_many, max_batch_size=5, max_queue_size=20, max_queue_time=0.01, concurrency=2
+    ) as batcher:
+        results = await asyncio.gather(*(batcher.process(i) for i in range(10)))
+        print(results)  # [0, 2, 4, 6, 8, 10, 12, 14, 16, 18]
+
+
+asyncio.run(main())
+```
+
+`process()` is a coroutine: submit calls concurrently to form batches. A loop that awaits each
+call before submitting the next normally produces single-item batches. Processing starts
+automatically. Stop the batcher before closing its clients, model resources, or executor.
+Existing [subclasses](https://hussein.awala.fr/async-batcher/0.3.0/api/) and adapters support the same managed lifecycle.
+
+## Guides
+
+- [Compatibility and migration](https://hussein.awala.fr/async-batcher/0.3.0/migration/): published features, Python requirements, and upgrade checks.
+- [Bounded starting configurations](https://hussein.awala.fr/async-batcher/0.3.0/starting-configurations/): copyable importer and interactive service examples.
+- [Choose by workload](https://hussein.awala.fr/async-batcher/0.3.0/workloads/): request compatibility, safe metadata, and configuration ownership.
+- [Batch an existing function](https://hussein.awala.fr/async-batcher/0.3.0/functions/): callable processors and managed cleanup.
+- [Bulk and streaming producers](https://hussein.awala.fr/async-batcher/0.3.0/bulk-processing/): bounded maps and waiting for queue space.
+- [Cost budgets](https://hussein.awala.fr/async-batcher/0.3.0/cost-aware-batching/): byte, token, or work limits alongside batch counts.
+- [Variable-length inference](https://hussein.awala.fr/async-batcher/0.3.0/variable-length-inference/): padding, conservative token budgets, and per-request output shapes.
+- [Operational visibility](https://hussein.awala.fr/async-batcher/0.3.0/observability/): snapshots and payload-free completion events.
+- [Grouped batching](https://hussein.awala.fr/async-batcher/0.3.0/grouped-batching/): isolate compatible requests with bounded child ownership.
+- [In-flight coalescing](https://hussein.awala.fr/async-batcher/0.3.0/coalescing/): share equivalent concurrent requests with bounded ownership.
+- [Cookbook](https://hussein.awala.fr/async-batcher/0.3.0/cookbook/): runnable SQLite imports, embedding pipelines, and measured batch sizes.
+- [Resumable imports](https://hussein.awala.fr/async-batcher/0.3.0/resumable-import/): immutable JSONL input with atomic SQLite checkpoints.
+- [Rejected-record imports](https://hussein.awala.fr/async-batcher/0.3.0/rejected-import/): continue past known input errors and retain a metadata-only audit.
+- [Durable embedding handoff](https://hussein.awala.fr/async-batcher/0.3.0/durable-embeddings/): save vectors before delivery and replay unfinished upserts.
+- [Provider quota and retry policy](https://hussein.awala.fr/async-batcher/0.3.0/provider-policy/): shared pacing, finite throttling retries, and cancellation.
+- [Cohere to Pinecone](https://hussein.awala.fr/async-batcher/0.3.0/cohere-pinecone/): real embeddings into an existing compatible vector index.
+- [FastAPI recipe](https://hussein.awala.fr/async-batcher/0.3.0/fastapi-recipe/): lifespan-managed predictions, SQLite writes, and HTTP overload handling.
+- [Operational recipes](https://hussein.awala.fr/async-batcher/0.3.0/operations/): separate deadlines, shared backend capacity, thread lifetime, and bounded telemetry.
+- [Core API and lifecycle](https://hussein.awala.fr/async-batcher/0.3.0/api/): limits, result mapping, errors, shutdown, restart, and executors.
+- [Contributing](https://github.com/hussein-awala/async-batcher/blob/0.3.0/CONTRIBUTING.md): locked development environments, test selection, integration services, and CI.
+- [Benchmarks](https://github.com/hussein-awala/async-batcher/blob/0.3.0/BENCHMARK.md): reproducible core measurements and archived application results.
+- [Public type contracts](https://hussein.awala.fr/async-batcher/0.3.0/typing/): inferred results, typed options, and installed-package checks.
+- [Security reporting](https://github.com/hussein-awala/async-batcher/blob/0.3.0/SECURITY.md) and [Code of Conduct](https://github.com/hussein-awala/async-batcher/blob/0.3.0/CODE_OF_CONDUCT.md).
+
+## Optional adapters
+
+The eight extras are independent; importing `async_batcher` does not import their clients.
+All adapters use the core lifecycle, with the limits and resource ownership described in each guide.
+
+| Extra | Operations | Guide |
+| --- | --- | --- |
+| `aws` | DynamoDB reads/writes; Kinesis and Firehose records | [DynamoDB](https://hussein.awala.fr/async-batcher/0.3.0/dynamodb/), [AWS streams](https://hussein.awala.fr/async-batcher/0.3.0/aws-streams/) |
+| `sqlalchemy` | SQLAlchemy inserts and ORM updates | [SQLAlchemy](https://hussein.awala.fr/async-batcher/0.3.0/databases/#sqlalchemy) |
+| `scylla` | cqlengine insert/update/delete batches | [ScyllaDB](https://hussein.awala.fr/async-batcher/0.3.0/databases/#scylladb) |
+| `mongodb` | Ordered native PyMongo writes | [MongoDB](https://hussein.awala.fr/async-batcher/0.3.0/databases/#mongodb) |
+| `kafka` | Native aiokafka producer batches | [Kafka](https://hussein.awala.fr/async-batcher/0.3.0/kafka/) |
+| `pinecone` | Vector upsert/fetch/delete | [Pinecone](https://hussein.awala.fr/async-batcher/0.3.0/pinecone/) |
+| `keras` | Dense-input Keras inference | [Keras](https://hussein.awala.fr/async-batcher/0.3.0/machine-learning/#keras) |
+| `sklearn` | Dense or sparse scikit-learn inference | [scikit-learn](https://hussein.awala.fr/async-batcher/0.3.0/machine-learning/#scikit-learn) |
+
+Services that do not offer a suitable bulk operation need a custom `process_batch` implementation.
+Batching alone does not enforce a service's request-rate limit or guarantee exactly-once side effects.

async_batcher-0.3.0/async_batcher/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from async_batcher.batcher import AsyncBatcher
+from async_batcher.coalescing import CoalescingBatcher
+from async_batcher.exceptions import AsyncBatchException, QueueFullException
+from async_batcher.grouped import GroupedBatcher, GroupLimitError
+from async_batcher.map import MapOutcome
+from async_batcher.observability import BatcherStats, BatchEvent
+
+__all__ = [
+    "AsyncBatcher",
+    "MapOutcome",
+    "CoalescingBatcher",
+    "AsyncBatchException",
+    "QueueFullException",
+    "BatchEvent",
+    "BatcherStats",
+    "GroupedBatcher",
+    "GroupLimitError",
+]

async_batcher-0.3.0/async_batcher/_options.py

@@ -0,0 +1,40 @@
+"""Keyword types shared by the public constructor and callable factory."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Generic, TypedDict, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from concurrent.futures import Executor
+    from contextvars import Context
+    from numbers import Real
+
+    from async_batcher.observability import BatchEvent
+
+T = TypeVar("T")
+
+
+class LegacyOptions(TypedDict, total=False):
+    batch_size: int
+    sleep_time: object
+    buffering_time: object
+
+
+class CoreOptions(LegacyOptions, Generic[T], total=False):
+    """Shared options for adapters that declare their own count limit."""
+
+    max_queue_time: float
+    concurrency: int
+    max_queue_size: int
+    max_batch_cost: float | Real | None
+    item_cost: Callable[[T], float | Real] | None
+    executor: Executor | None
+    on_batch: Callable[[BatchEvent], None] | None
+    processor_context: Context | None
+    log_exceptions: bool
+    discard_cancelled: bool
+
+
+class BatcherOptions(CoreOptions[T], total=False):
+    max_batch_size: int

async_batcher-0.3.0/async_batcher/aws/_records.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import asyncio
+import random
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+
+class RecordBatchError(Exception):
+    """A record rejected by Kinesis or Firehose after bounded retries.
+
+    ``code`` and ``message`` are the service's error fields. ``attempts`` counts
+    calls containing this record, including the initial call. No payload is kept.
+    """
+
+    def __init__(self, code: str, message: str, attempts: int):
+        self.code = code
+        self.message = message
+        self.attempts = attempts
+        super().__init__(f"{code}: {message} (after {attempts} attempt(s))")
+
+
+def validate_options(max_batch_size: int, max_retries: int, retry_jitter: bool = False) -> None:
+    if not 1 <= max_batch_size <= 500:
+        raise ValueError("max_batch_size must be between 1 and 500")
+    if isinstance(max_retries, bool) or not isinstance(max_retries, int) or max_retries < 0:
+        raise ValueError("max_retries must be a non-negative integer")
+    if not isinstance(retry_jitter, bool):
+        raise TypeError("retry_jitter must be a boolean")
+
+
+async def send_records(
+    operation: Callable[..., Awaitable[dict[str, Any]]],
+    records: list[dict[str, Any]],
+    sizes: list[int],
+    *,
+    max_bytes: int,
+    max_retries: int,
+    response_key: str,
+    success_keys: tuple[str, ...],
+    retry_codes: set[str],
+    retry_jitter: bool = False,
+    **kwargs: Any,
+) -> list[dict[str, Any] | Exception]:
+    """Split by service limits and retry only explicitly rejected records."""
+    results: list[dict[str, Any] | Exception] = []
+    start = 0
+    while start < len(records):
+        end = start
+        size = 0
+        while end < len(records) and end - start < 500 and size + sizes[end] <= max_bytes:
+            size += sizes[end]
+            end += 1
+        if end == start:
+            raise ValueError("record exceeds the request byte limit")
+        pending = list(range(start, end))
+        # Every slot is replaced by an acknowledgement or an error below.
+        results.extend(RuntimeError("record was not processed") for _ in pending)
+        for attempt in range(max_retries + 1):
+            try:
+                response = await operation(Records=[records[index] for index in pending], **kwargs)
+                entries = response.get(response_key)
+                if not isinstance(entries, list) or len(entries) != len(pending):
+                    raise ValueError(f"{response_key} must contain one result per submitted record")
+                for entry in entries:
+                    if not isinstance(entry, dict):
+                        raise ValueError("record response must be a mapping")
+                    if "ErrorCode" in entry:
+                        if (
+                            not isinstance(entry["ErrorCode"], str)
+                            or not entry["ErrorCode"]
+                            or not isinstance(entry.get("ErrorMessage", ""), str)
+                        ):
+                            raise ValueError("record response contains an invalid error code or message")
+                    elif not all(isinstance(entry.get(key), str) and entry[key] for key in success_keys):
+                        raise ValueError("record response lacks an acknowledgement or error code")
+            except Exception as error:
+                # An earlier response may already have acknowledged other records.
+                # Do not replace those outcomes or resend them after a request error.
+                for index in pending:
+                    results[index] = error
+                break
+            retry = []
+            for index, entry in zip(pending, entries, strict=True):
+                code = entry.get("ErrorCode")
+                if code is None:
+                    results[index] = entry
+                elif code in retry_codes and attempt < max_retries:
+                    retry.append(index)
+                else:
+                    results[index] = RecordBatchError(code, entry.get("ErrorMessage", ""), attempt + 1)
+            if not retry:
+                break
+            pending = retry
+            delay = min(0.1 * 2 ** min(attempt, 6), 5.0)
+            await asyncio.sleep(random.uniform(0, delay) if retry_jitter else delay)
+        start = end
+    return results

async_batcher-0.3.0/async_batcher/aws/dynamodb/_retry.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from async_batcher.aws.dynamodb.exceptions import DynamoDBRetryError
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Awaitable, Callable
+
+
+def validate_max_retries(max_retries: int) -> None:
+    if isinstance(max_retries, bool) or not isinstance(max_retries, int) or max_retries < 0:
+        raise ValueError("max_retries must be a non-negative integer")
+
+
+async def batch_responses(
+    operation: Callable[..., Awaitable[dict[str, Any]]],
+    request_items: dict[str, Any],
+    unprocessed_key: str,
+    max_retries: int,
+    **kwargs: Any,
+) -> AsyncIterator[dict[str, Any]]:
+    delay = 0.1
+    for attempt in range(max_retries + 1):
+        response = await operation(RequestItems=request_items, **kwargs)
+        yield response
+        request_items = response.get(unprocessed_key, {})
+        if not request_items:
+            return
+        if attempt == max_retries:
+            raise DynamoDBRetryError(unprocessed_key, request_items, max_retries)
+        await asyncio.sleep(delay)
+        delay = min(delay * 2, 5.0)

async_batcher-0.3.0/async_batcher/aws/dynamodb/exceptions.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Any
+
+from async_batcher.exceptions import AsyncBatchException
+
+
+class DynamoDBRetryError(AsyncBatchException):
+    """A batch still contains unprocessed requests after its retry budget is exhausted.
+
+    Requests omitted from ``unprocessed_items`` may already have succeeded. A failed
+    batch write is not rolled back.
+    """
+
+    def __init__(self, response_key: str, unprocessed_items: dict[str, Any], max_retries: int):
+        self.unprocessed_items = unprocessed_items
+        super().__init__(f"DynamoDB returned {response_key} after {max_retries} retries")