timedbatch 0.2.0__py3-none-any.whl

timedbatch/__init__.py

@@ -0,0 +1,21 @@
+"""Batch items by a max count and a max age, flushing when either limit is hit."""
+
+from __future__ import annotations
+
+from ._abatcher import AsyncTimedBatcher
+from ._abatching import abatched_by_time
+from ._batcher import TimedBatcher
+from ._batching import batched_by_time
+from ._errors import BatcherClosed, BatcherFull, FlushError
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AsyncTimedBatcher",
+    "BatcherClosed",
+    "BatcherFull",
+    "FlushError",
+    "TimedBatcher",
+    "abatched_by_time",
+    "batched_by_time",
+]

timedbatch/_abatcher.py

@@ -0,0 +1,195 @@
+"""The asyncio counterpart of TimedBatcher, for a single event loop."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+from collections.abc import Awaitable, Callable
+from types import TracebackType
+from typing import Generic
+
+from ._core import Buffer, Ledger, T, wait_event
+from ._errors import BatcherClosed, BatcherFull
+from ._limits import check_limits, check_timeout
+
+
+class AsyncTimedBatcher(Generic[T]):
+    """Collect items from coroutines and await ``flush(batch)`` in batches.
+
+    The same promises as :class:`TimedBatcher`: delivery on size, age (also while
+    idle), :meth:`flush` and :meth:`aclose`; one batch at a time, in order; every
+    accepted item delivered once or handed back once through ``on_error`` or a
+    :class:`FlushError`; ``max_pending`` makes :meth:`add` wait. Use it from one event
+    loop only, and close it (``async with``): there is no exit hook for coroutines. If
+    the flush task is cancelled (for example because the loop ends), the batcher closes
+    and the items it still held are handed back by the next call.
+    """
+
+    def __init__(
+        self,
+        flush: Callable[[list[T]], Awaitable[object]],
+        *,
+        max_items: int,
+        max_seconds: float,
+        max_pending: int | None = None,
+        on_error: Callable[[Exception, list[T]], object] | None = None,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if not callable(flush):
+            raise TypeError("flush must be callable")
+        items, seconds, self._max_pending = check_limits(max_items, max_seconds, max_pending)
+        self._sink = flush
+        self._on_error = on_error
+        self._buffer: Buffer[T] = Buffer(items, seconds, clock)
+        self._ledger: Ledger[T] = Ledger()
+        self._accepted = self._done = self._wanted = 0
+        self._closed = False
+        self._stopped: BaseException | None = None
+        self._task: asyncio.Task[None] | None = None
+        self._wake = self._progress = asyncio.Event()
+
+    @property
+    def pending(self) -> int:
+        """Items accepted and not yet delivered or handed back."""
+        return self._accepted - self._done
+
+    @property
+    def closed(self) -> bool:
+        """Whether :meth:`aclose` has been called or the flush task has stopped."""
+        return self._closed
+
+    async def add(self, item: T, timeout: float | None = None) -> None:
+        """Accept ``item``, waiting up to ``timeout`` seconds for room under ``max_pending``."""
+        timeout = check_timeout(timeout)
+        self._check_open()
+        self._start()
+        limit = self._max_pending
+        if limit is not None and self.pending >= limit:
+            if self._inside():
+                raise BatcherFull("add() inside the flush callback cannot wait for room")
+            await self._wait(lambda: self.pending < limit, timeout, BatcherFull)
+            self._check_open()
+        self._buffer.append(item)
+        self._accepted += 1
+        self._wake.set()
+
+    async def flush(self, timeout: float | None = None) -> None:
+        """Deliver every item accepted so far; raise ``TimeoutError`` if it takes longer."""
+        timeout = check_timeout(timeout)
+        self._refuse_inside("flush")
+        if self._task is not None:
+            target = self._wanted = max(self._wanted, self._accepted)
+            self._wake.set()
+            await self._wait(lambda: self._done >= target, timeout, TimeoutError)
+        self._ledger.raise_any()
+
+    async def aclose(self) -> None:
+        """Stop accepting items, deliver the rest and stop the task. Idempotent."""
+        self._refuse_inside("aclose")
+        self._closed = True
+        if self._task is not None and not self._task.done():
+            self._wake.set()
+            # wait() neither cancels the task if this caller is cancelled nor re-raises
+            # the task's own cancellation into a caller that was not cancelled.
+            await asyncio.wait({self._task})
+        self._reap()
+        self._ledger.raise_any()
+
+    async def __aenter__(self) -> AsyncTimedBatcher[T]:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    def _reap(self) -> None:
+        # A task that stopped abnormally (cancelled, even before it ever ran, or killed
+        # by a BaseException from the sink) closes the batcher and hands back its items.
+        task = self._task
+        if task is None or not task.done() or self._stopped is not None:
+            return
+        error = asyncio.CancelledError() if task.cancelled() else task.exception()
+        if error is None:
+            return
+        self._stopped, self._closed = error, True
+        while (batch := self._buffer.take(True)) is not None:
+            self._ledger.record(error, batch)
+            self._finish(batch)
+
+    def _check_open(self) -> None:
+        self._reap()
+        self._ledger.raise_any()
+        if self._stopped is not None:
+            raise BatcherClosed("the flush task stopped") from self._stopped
+        if self._closed:
+            raise BatcherClosed("the batcher is closed")
+
+    def _start(self) -> None:
+        if self._task is None:
+            self._wake, self._progress = asyncio.Event(), asyncio.Event()
+            self._task = asyncio.get_running_loop().create_task(self._loop())
+
+    def _inside(self) -> bool:
+        return self._task is not None and asyncio.current_task() is self._task
+
+    def _refuse_inside(self, name: str) -> None:
+        if self._inside():
+            raise RuntimeError(f"{name}() cannot be called from inside the flush callback")
+
+    async def _wait(
+        self, ready: Callable[[], bool], timeout: float | None, error: type[Exception]
+    ) -> None:
+        loop = asyncio.get_running_loop()
+        deadline = None if timeout is None else loop.time() + timeout
+        while not ready():
+            assert self._task is not None
+            if self._task.done():
+                self._check_open()
+            left = None if deadline is None else deadline - loop.time()
+            if left is not None and left <= 0:
+                raise error("timed out waiting for the flush task")
+            await wait_event(self._progress, left)
+
+    async def _loop(self) -> None:
+        while True:
+            batch = self._buffer.take(self._closed or self._wanted > self._done)
+            if batch is None:
+                if self._closed:
+                    return
+                self._wake.clear()
+                await wait_event(self._wake, self._buffer.remaining())
+                continue
+            try:
+                await self._sink(list(batch))
+            except Exception as error:
+                await self._report(error, batch)
+            except BaseException as error:
+                self._ledger.record(error, batch)
+                self._finish(batch)
+                raise
+            self._finish(batch)
+
+    async def _report(self, error: Exception, batch: list[T]) -> None:
+        if self._on_error is None:
+            self._ledger.record(error, batch)
+            return
+        try:
+            outcome = self._on_error(error, list(batch))
+            if inspect.isawaitable(outcome):
+                await outcome
+        except BaseException as handler_error:
+            self._ledger.record(handler_error, batch)
+            if not isinstance(handler_error, Exception):
+                self._finish(batch)
+                raise
+
+    def _finish(self, batch: list[T]) -> None:
+        self._done += len(batch)
+        # Waiters hold the old event; swapping in a fresh one wakes them all exactly once.
+        self._progress.set()
+        self._progress = asyncio.Event()

timedbatch/_abatching.py

@@ -0,0 +1,91 @@
+"""Batch an async iterable by count and age, flushing on time even while it is idle."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import time
+from collections.abc import AsyncGenerator, AsyncIterable, AsyncIterator, Callable
+from typing import Any, TypeVar
+
+from ._limits import check_limits
+
+_T = TypeVar("_T")
+
+
+def abatched_by_time(
+    aiterable: AsyncIterable[_T],
+    max_items: int,
+    max_seconds: float,
+    *,
+    clock: Callable[[], float] = time.monotonic,
+) -> AsyncGenerator[list[_T], None]:
+    """Yield batches from an async iterable, flushing on ``max_items`` or ``max_seconds``.
+
+    Unlike :func:`batched_by_time`, the age limit fires while the source is idle: a
+    partial batch is yielded ``max_seconds`` after its first item even if no further
+    item arrives. The pending read of the source is kept across those flushes, never
+    cancelled, so no item is lost; it is cancelled only when the iterator is closed. If
+    the source raises, the items already read are yielded first. ``clock`` must tick in
+    seconds; real waiting uses the event loop. Close it early with ``aclose()`` (or
+    :func:`contextlib.aclosing`): the read in flight is cancelled, and an item it had
+    already taken from the source is dropped, together with the partial batch. Each read
+    of the source runs in its own task, so context variables set by the source do not
+    carry over from one item to the next.
+    """
+    items, seconds, _ = check_limits(max_items, max_seconds)
+    if not isinstance(aiterable, AsyncIterable):
+        raise TypeError(f"expected an async iterable, not {type(aiterable).__name__}")
+    return _abatches(aiterable.__aiter__(), items, seconds, clock)
+
+
+async def _abatches(
+    source: AsyncIterator[_T], max_items: int, max_seconds: float, clock: Callable[[], float]
+) -> AsyncGenerator[list[_T], None]:
+    batch: list[_T] = []
+    started = 0.0
+    pending: asyncio.Future[Any] | None = None
+    try:
+        while True:
+            if pending is None:
+                try:
+                    step = source.__anext__()
+                except StopAsyncIteration:
+                    break
+                except Exception:
+                    if batch:
+                        yield batch
+                    raise
+                pending = asyncio.ensure_future(step)
+            timeout = None
+            if batch and not math.isinf(max_seconds):
+                timeout = max(0.0, started + max_seconds - clock())
+            # asyncio.wait, unlike wait_for, leaves the read running when it times out.
+            done, _ = await asyncio.wait({pending}, timeout=timeout)
+            if not done:
+                yield batch
+                batch = []
+                continue
+            read, pending = pending, None
+            try:
+                item = read.result()
+            except StopAsyncIteration:
+                break
+            except Exception:
+                if batch:
+                    yield batch
+                raise
+            if not batch:
+                started = clock()
+            batch.append(item)
+            if len(batch) >= max_items or clock() - started >= max_seconds:
+                yield batch
+                batch = []
+        if batch:
+            yield batch
+    finally:
+        if pending is not None:
+            pending.cancel()
+            await asyncio.wait({pending})
+            if not pending.cancelled():
+                pending.exception()

timedbatch/_batcher.py

@@ -0,0 +1,156 @@
+"""A thread-safe push batcher that flushes on size, age, demand, close and exit."""
+
+from __future__ import annotations
+
+import atexit
+import threading
+import time
+from collections.abc import Callable
+from types import TracebackType
+
+from ._core import Buffer, T, is_async
+from ._engine import Engine
+from ._errors import BatcherClosed
+from ._limits import check_limits, check_timeout
+
+
+class TimedBatcher(Engine[T]):
+    """Collect items from any thread and hand them to ``flush`` in batches.
+
+    A batch is delivered when it holds ``max_items`` items, when its oldest item is
+    ``max_seconds`` old, on :meth:`flush` and on :meth:`close`. Batches go to ``flush``
+    one at a time, in the order the items were accepted, and never exceed ``max_items``.
+    Every accepted item is delivered once or handed back once: to ``on_error(exc, batch)``
+    or inside a :class:`FlushError` raised by the next ``add``, ``poll``, ``flush`` or
+    ``close``. ``max_pending`` bounds items accepted but not yet delivered; ``add`` blocks
+    for room. With ``background=False`` there is no thread: due batches are delivered by
+    the caller on ``add`` and ``poll``, which makes an injected ``clock`` fully
+    deterministic. ``flush_at_exit`` closes a forgotten batcher when the interpreter exits.
+    """
+
+    def __init__(
+        self,
+        flush: Callable[[list[T]], object],
+        *,
+        max_items: int,
+        max_seconds: float,
+        max_pending: int | None = None,
+        on_error: Callable[[Exception, list[T]], object] | None = None,
+        clock: Callable[[], float] = time.monotonic,
+        background: bool = True,
+        flush_at_exit: bool = True,
+    ) -> None:
+        if not callable(flush):
+            raise TypeError("flush must be callable")
+        if is_async(flush) or is_async(on_error):
+            raise TypeError("flush and on_error must be plain functions; see AsyncTimedBatcher")
+        items, seconds, pending = check_limits(max_items, max_seconds, max_pending)
+        super().__init__(flush, on_error, Buffer(items, seconds, clock), pending)
+        self._at_exit = flush_at_exit
+        self._thread: threading.Thread | None = None
+        if background:
+            self._thread = threading.Thread(target=self._run, name="timedbatch", daemon=True)
+            self._thread.start()
+        if flush_at_exit:
+            atexit.register(self._close_at_exit)
+
+    @property
+    def pending(self) -> int:
+        """Items accepted and not yet delivered or handed back."""
+        with self._lock:
+            return self._accepted - self._done
+
+    @property
+    def closed(self) -> bool:
+        """Whether :meth:`close` has been called."""
+        return self._closed
+
+    def add(self, item: T, timeout: float | None = None) -> None:
+        """Accept ``item``, waiting up to ``timeout`` seconds for room under ``max_pending``.
+
+        Every exception it raises means the item was not accepted: :class:`BatcherClosed`,
+        :class:`BatcherFull`, or :class:`FlushError` for earlier failures not reported yet.
+        """
+        timeout = check_timeout(timeout)
+        with self._lock:
+            self._ledger.raise_any()
+            if self._closed:
+                raise BatcherClosed("the batcher is closed")
+            inside = self._delivering == threading.get_ident()
+            self._wait_for_room(timeout, inside)
+            self._buffer.append(item)
+            self._accepted += 1
+            if self._thread is not None:
+                if len(self._buffer) in (1, self._buffer.max_items):
+                    self._wake.notify()
+                return
+        if not inside:
+            # A batch failing here is reported by the next call, so that a FlushError from
+            # add() always means the item was not accepted.
+            self._drain()
+
+    def poll(self) -> None:
+        """Deliver every batch that is due now and report failures not reported yet."""
+        self._refuse_inside("poll")
+        if self._thread is None:
+            self._drain()
+        else:
+            with self._lock:
+                self._wake.notify()
+        self._raise_failures()
+
+    def flush(self, timeout: float | None = None) -> None:
+        """Deliver every item accepted so far; raise ``TimeoutError`` if it takes longer.
+
+        Without a background thread the caller delivers, so ``timeout`` has no effect.
+        """
+        timeout = check_timeout(timeout)
+        self._refuse_inside("flush")
+        with self._lock:
+            target = self._wanted = max(self._wanted, self._accepted)
+            self._wake.notify()
+        if self._thread is None:
+            self._drain()
+        else:
+            self._wait_until_done(target, timeout)
+        self._raise_failures()
+
+    def close(self, timeout: float | None = None) -> None:
+        """Stop accepting items, deliver the rest and stop the thread. Idempotent.
+
+        If this times out or is interrupted, the exit hook stays registered, so what is
+        left is still delivered when the interpreter exits.
+        """
+        self._shutdown(check_timeout(timeout), unregister=True)
+
+    def __enter__(self) -> TimedBatcher[T]:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def _close_at_exit(self) -> None:
+        # The atexit docs leave unregistering from inside a handler undefined.
+        self._shutdown(None, unregister=False)
+
+    def _shutdown(self, timeout: float | None, unregister: bool) -> None:
+        self._refuse_inside("close")
+        with self._lock:
+            self._closed = True
+            self._wake.notify()
+            self._progress.notify_all()
+        if self._thread is None:
+            self._drain()
+        else:
+            self._thread.join(timeout)
+            if self._thread.is_alive():
+                raise TimeoutError("the flush thread is still delivering")
+        # Only now: an interrupted or timed out close must leave the exit flush in place.
+        if unregister and self._at_exit:
+            atexit.unregister(self._close_at_exit)
+        self._raise_failures()

timedbatch/_batching.py

@@ -0,0 +1,60 @@
+"""Batch an iterable by both a maximum count and a maximum time window."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Iterable, Iterator
+from typing import TypeVar
+
+from ._limits import check_limits
+
+_T = TypeVar("_T")
+
+
+def batched_by_time(
+    iterable: Iterable[_T],
+    max_items: int,
+    max_seconds: float,
+    *,
+    clock: Callable[[], float] = time.monotonic,
+) -> Iterator[list[_T]]:
+    """Yield batches of items, flushing when either limit is reached.
+
+    A batch is emitted as soon as it holds ``max_items`` items or ``max_seconds``
+    have elapsed since its first item arrived, whichever comes first. The window is
+    checked only when an item arrives, so an idle source holds its partial batch
+    until the next item (use :func:`abatched_by_time` or :class:`TimedBatcher` to
+    flush on time while idle). Remaining items are flushed when the source is
+    exhausted. If the source raises, the items already read are yielded first and the
+    exception is raised on the next step. ``max_seconds`` may be ``math.inf`` to batch
+    by count only.
+
+    The ``clock`` returns a monotonic timestamp in seconds. Inject it to make the
+    behaviour deterministic in tests; it defaults to :func:`time.monotonic`.
+    """
+    items, seconds, _ = check_limits(max_items, max_seconds)
+    return _batches(iter(iterable), items, seconds, clock)
+
+
+def _batches(
+    source: Iterator[_T], max_items: int, max_seconds: float, clock: Callable[[], float]
+) -> Iterator[list[_T]]:
+    batch: list[_T] = []
+    started = 0.0
+    while True:
+        try:
+            item = next(source)
+        except StopIteration:
+            break
+        except Exception:
+            if batch:
+                yield batch
+            raise
+        if not batch:
+            started = clock()
+        batch.append(item)
+        if len(batch) >= max_items or clock() - started >= max_seconds:
+            yield batch
+            batch = []
+    if batch:
+        yield batch

timedbatch/_core.py

@@ -0,0 +1,119 @@
+"""State shared by the push-style batchers: the buffer and the failure ledger."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import math
+from collections.abc import Callable
+from typing import Generic, TypeVar
+
+from ._errors import FlushError
+
+T = TypeVar("T")
+
+
+class Buffer(Generic[T]):
+    """Items waiting for delivery, with the time each one arrived. Not thread-safe."""
+
+    def __init__(self, max_items: int, max_seconds: float, clock: Callable[[], float]) -> None:
+        self.max_items = max_items
+        self.max_seconds = max_seconds
+        self.clock = clock
+        self._items: list[T] = []
+        # One stamp per item: after a slow delivery the buffer can hold more than one
+        # batch, and the next batch's age must come from its own oldest item.
+        self._stamps: list[float] = []
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def append(self, item: T) -> None:
+        self._stamps.append(self.clock())
+        self._items.append(item)
+
+    def remaining(self) -> float | None:
+        """Seconds until the oldest item is due, or ``None`` when nothing will come due."""
+        if not self._items or math.isinf(self.max_seconds):
+            return None
+        return self._stamps[0] + self.max_seconds - self.clock()
+
+    def take(self, force: bool) -> list[T] | None:
+        """Remove and return the next batch if it is due (or ``force``), else ``None``."""
+        if not self._items:
+            return None
+        if (
+            not force
+            and len(self._items) < self.max_items
+            and self.clock() - self._stamps[0] < self.max_seconds
+        ):
+            return None
+        batch = self._items[: self.max_items]
+        del self._items[: self.max_items]
+        del self._stamps[: self.max_items]
+        return batch
+
+
+class Ledger(Generic[T]):
+    """Failed batches not yet reported to the producer."""
+
+    def __init__(self) -> None:
+        self._batches: list[list[T]] = []
+        self._errors: list[BaseException] = []
+
+    def record(self, error: BaseException, batch: list[T]) -> None:
+        self._batches.append(batch)
+        self._errors.append(error)
+
+    def raise_any(self) -> None:
+        if self._batches:
+            batches, errors = self._batches, self._errors
+            self._batches, self._errors = [], []
+            raise FlushError(list(batches), errors)
+
+
+def call_sink(
+    sink: Callable[[list[T]], object],
+    on_error: Callable[[Exception, list[T]], object] | None,
+    batch: list[T],
+) -> BaseException | None:
+    """Deliver ``batch``; return the exception that still needs reporting, if any."""
+    try:
+        # The sink gets its own list, so a sink that clears it cannot empty the copy we
+        # hand back on failure.
+        _plain(sink(list(batch)))
+    except Exception as error:
+        if on_error is None:
+            return error
+        try:
+            _plain(on_error(error, list(batch)))
+        except BaseException as handler_error:
+            return handler_error
+    except BaseException as error:
+        return error
+    return None
+
+
+def is_async(function: object) -> bool:
+    """Whether calling ``function`` returns a coroutine (functions and callable objects)."""
+    call = type(function).__call__
+    return inspect.iscoroutinefunction(function) or inspect.iscoroutinefunction(call)
+
+
+def _plain(outcome: object) -> None:
+    # A coroutine that is never awaited does nothing: treat it as a failed delivery.
+    if inspect.isawaitable(outcome):
+        if inspect.iscoroutine(outcome):
+            outcome.close()
+        raise TypeError("the flush function returned an awaitable; use AsyncTimedBatcher")
+
+
+async def wait_event(event: asyncio.Event, timeout: float | None) -> None:
+    """Wait for ``event`` at most ``timeout`` seconds, without raising on timeout."""
+    # asyncio.wait instead of wait_for: on 3.10 and 3.11 wait_for can swallow a
+    # cancellation that arrives as the event fires.
+    waiter = asyncio.ensure_future(event.wait())
+    try:
+        await asyncio.wait({waiter}, timeout=timeout)
+    finally:
+        waiter.cancel()

timedbatch/_engine.py

@@ -0,0 +1,116 @@
+"""The locking and delivery machinery behind TimedBatcher."""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+from typing import Generic
+
+from ._core import Buffer, Ledger, T, call_sink
+from ._errors import BatcherClosed, BatcherFull
+
+
+class Engine(Generic[T]):
+    """Buffer, counters and the one-at-a-time delivery loop, guarded by one lock."""
+
+    def __init__(
+        self,
+        sink: Callable[[list[T]], object],
+        on_error: Callable[[Exception, list[T]], object] | None,
+        buffer: Buffer[T],
+        max_pending: int | None,
+    ) -> None:
+        self._sink = sink
+        self._on_error = on_error
+        self._buffer = buffer
+        self._max_pending = max_pending
+        self._ledger: Ledger[T] = Ledger()
+        self._lock = threading.Lock()
+        self._wake = threading.Condition(self._lock)
+        self._progress = threading.Condition(self._lock)
+        self._order = threading.Lock()
+        self._accepted = self._done = self._wanted = 0
+        self._closed = False
+        self._delivering: int | None = None
+
+    def _refuse_inside(self, name: str) -> None:
+        with self._lock:
+            if self._delivering == threading.get_ident():
+                raise RuntimeError(f"{name}() cannot be called from inside the flush callback")
+
+    def _raise_failures(self) -> None:
+        with self._lock:
+            self._ledger.raise_any()
+
+    def _wait_for_room(self, timeout: float | None, inside: bool) -> None:
+        limit = self._max_pending
+        if limit is None or self._accepted - self._done < limit:
+            return
+        if inside:
+            raise BatcherFull("add() inside the flush callback cannot wait for room")
+        # Waiting uses the real clock: the injected one only measures batch age.
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while self._accepted - self._done >= limit:
+            left = None if deadline is None else deadline - time.monotonic()
+            if left is not None and left <= 0:
+                raise BatcherFull(f"no room under max_pending={limit} within {timeout} seconds")
+            self._progress.wait(_bounded(left))
+            if self._closed:
+                raise BatcherClosed("the batcher closed while add() was waiting")
+
+    def _wait_until_done(self, target: int, timeout: float | None) -> None:
+        deadline = None if timeout is None else time.monotonic() + timeout
+        with self._lock:
+            while self._done < target:
+                left = None if deadline is None else deadline - time.monotonic()
+                if left is not None and left <= 0:
+                    raise TimeoutError("flush() timed out before every item was delivered")
+                self._progress.wait(_bounded(left))
+
+    def _next_batch(self) -> list[T] | None:
+        batch = self._buffer.take(self._closed or self._wanted > self._done)
+        if batch is not None:
+            self._delivering = threading.get_ident()
+        return batch
+
+    def _deliver(self, batch: list[T]) -> BaseException | None:
+        error = call_sink(self._sink, self._on_error, batch)
+        with self._lock:
+            self._delivering = None
+            if error is not None:
+                self._ledger.record(error, batch)
+            self._done += len(batch)
+            self._progress.notify_all()
+        return error
+
+    def _drain(self) -> None:
+        with self._order:
+            while True:
+                with self._lock:
+                    batch = self._next_batch()
+                if batch is None:
+                    return
+                error = self._deliver(batch)
+                if error is not None and not isinstance(error, Exception):
+                    raise error
+
+    def _run(self) -> None:
+        with self._lock:
+            while True:
+                batch = self._next_batch()
+                if batch is None:
+                    if self._closed:
+                        return
+                    self._wake.wait(_bounded(self._buffer.remaining()))
+                    continue
+                self._lock.release()
+                try:
+                    self._deliver(batch)
+                finally:
+                    self._lock.acquire()
+
+
+def _bounded(seconds: float | None) -> float | None:
+    # Condition.wait raises OverflowError past TIMEOUT_MAX, which would kill the thread.
+    return None if seconds is None else min(seconds, threading.TIMEOUT_MAX)

timedbatch/_errors.py

@@ -0,0 +1,35 @@
+"""Exceptions raised by the batchers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class FlushError(Exception):
+    """One or more batches could not be delivered.
+
+    ``batches`` holds every failed batch, in delivery order, and ``errors`` the exception
+    each one raised, so the caller can retry or store them: no item is dropped silently.
+    """
+
+    def __init__(self, batches: list[list[Any]], errors: list[BaseException]) -> None:
+        if not errors or len(batches) != len(errors):
+            raise ValueError("FlushError needs one error per failed batch, and at least one")
+        count = sum(len(batch) for batch in batches)
+        noun = "batch" if len(batches) == 1 else "batches"
+        items = "item" if count == 1 else "items"
+        super().__init__(f"{len(batches)} {noun} ({count} {items}) failed to flush: {errors[0]!r}")
+        self.batches = batches
+        self.errors = errors
+        self.__cause__ = errors[0]
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (type(self), (self.batches, self.errors))
+
+
+class BatcherClosed(RuntimeError):
+    """The batcher was closed, so it accepts no more items."""
+
+
+class BatcherFull(TimeoutError):
+    """``add`` gave up waiting for room under ``max_pending``; the item was not accepted."""

timedbatch/_limits.py

@@ -0,0 +1,52 @@
+"""Validation of the batching limits shared by every entry point."""
+
+from __future__ import annotations
+
+import math
+import operator
+from decimal import Decimal
+from numbers import Real
+
+
+def _count(name: str, value: object) -> int:
+    if isinstance(value, bool):
+        raise TypeError(f"{name} must be an int, not bool")
+    try:
+        # operator.index accepts int and integer types such as NumPy's, never floats.
+        count = operator.index(value)  # type: ignore[arg-type]
+    except TypeError:
+        raise TypeError(f"{name} must be an int, not {type(value).__name__}") from None
+    if count < 1:
+        raise ValueError(f"{name} must be at least 1")
+    return count
+
+
+def _seconds(name: str, value: object) -> float:
+    if isinstance(value, bool) or not isinstance(value, (Real, Decimal)):
+        raise TypeError(f"{name} must be a real number, not {type(value).__name__}")
+    seconds = float(value)
+    # NaN compares false with everything, so it would silently disable a limit.
+    if math.isnan(seconds):
+        raise ValueError(f"{name} must not be NaN")
+    return seconds
+
+
+def check_limits(
+    max_items: object, max_seconds: object, max_pending: object = None
+) -> tuple[int, float, int | None]:
+    """Return the limits as exact types, or raise ``TypeError`` / ``ValueError``."""
+    items = _count("max_items", max_items)
+    seconds = _seconds("max_seconds", max_seconds)
+    if seconds <= 0:
+        raise ValueError("max_seconds must be greater than 0")
+    if max_pending is None:
+        return items, seconds, None
+    pending = _count("max_pending", max_pending)
+    if pending < items:
+        raise ValueError("max_pending must be at least max_items")
+    return items, seconds, pending
+
+
+def check_timeout(timeout: object) -> float | None:
+    """Return a wait timeout in seconds (``None`` waits forever); negative means now."""
+    return None if timeout is None else _seconds("timeout", timeout)

timedbatch-0.2.0.dist-info/METADATA

@@ -0,0 +1,247 @@
+Metadata-Version: 2.5
+Name: timedbatch
+Version: 0.2.0
+Summary: Batch items by a max count and a max age, for iterables, threads and asyncio, without losing items
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/timedbatch
+Project-URL: Issues, https://github.com/JaviLianes8/timedbatch/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/timedbatch/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,back-pressure,batch,batching,buffer,chunk,flush,iterator,streaming,time-window
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+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: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# timedbatch
+
+Batch items by a max count and a max age, flushing when either limit is hit. Typed, no
+dependencies, for plain iterables, for threads and for asyncio.
+
+## Install
+
+```
+pip install timedbatch
+```
+
+## Which one to use
+
+| You have | Use | Flushes while idle |
+|---|---|---|
+| An iterable you loop over | `batched_by_time` | No: the age is checked when an item arrives |
+| An async iterable | `abatched_by_time` | Yes |
+| Many places calling `add(item)` from threads | `TimedBatcher` | Yes, from a background thread |
+| Many coroutines calling `await add(item)` | `AsyncTimedBatcher` | Yes, from a background task |
+
+A batch is delivered as soon as it holds `max_items` items or its oldest item is
+`max_seconds` old, whichever comes first. `max_seconds` may be `math.inf` to batch by
+count only.
+
+## Iterables
+
+```python
+from timedbatch import batched_by_time
+
+now = 0.0
+
+
+def clock() -> float:  # inject a clock and tests never sleep
+    return now
+
+
+def events():
+    global now
+    for moment, name in [(0.0, "a"), (0.5, "b"), (0.6, "c"), (9.0, "d"), (9.1, "e")]:
+        now = moment
+        yield name
+
+
+for batch in batched_by_time(events(), max_items=2, max_seconds=5.0, clock=clock):
+    print(batch)  # ['a', 'b']
+    # ['c', 'd']
+    # ['e']
+```
+
+`['c', 'd']` closes on age: `d` arrives 8.4 seconds after `c`. If the source raises, the
+items already read are yielded first and the exception follows.
+
+## Threads: `TimedBatcher`
+
+```python
+from timedbatch import TimedBatcher
+
+
+def write_rows(batch: list[int]) -> None:
+    print("insert", batch)
+
+
+with TimedBatcher(write_rows, max_items=2, max_seconds=1.0) as batcher:
+    for row in range(5):
+        batcher.add(row)  # safe from any number of threads
+# insert [0, 1]
+# insert [2, 3]
+# insert [4]
+```
+
+What it promises:
+
+- **Size and age.** A full batch goes out at once; a partial one goes out `max_seconds`
+  after its oldest item, even if nothing else is added.
+- **Order and no overlap.** One background thread calls your function, one batch at a
+  time, in the order the items were accepted. A batch never exceeds `max_items`.
+- **Nothing lost, nothing twice.** Every accepted item is delivered once or handed back
+  once. When `add` raises, the item was not accepted (one exception: with
+  `background=False`, an interrupt raised inside your function passes through `add`,
+  and its batch comes back in the next `FlushError`).
+- **Failures.** Give `on_error(exc, batch)` to decide what to do with a failed batch.
+  Without it, failed batches are kept and raised as a `FlushError` (with `.batches` and
+  `.errors`) by the next `add`, `poll`, `flush` or `close`.
+- **Back-pressure.** `max_pending` caps items accepted but not yet delivered. `add` waits
+  for room, or raises `BatcherFull` (a `TimeoutError`) after `timeout` seconds.
+- **Shutdown.** `close()` (or leaving the `with` block) delivers the rest and stops the
+  thread; later calls to `add` raise `BatcherClosed`. A batcher you forget to close, or
+  whose `close(timeout=...)` timed out, is closed when the interpreter exits normally,
+  through `sys.exit` or an uncaught exception (`flush_at_exit=True`). That exit flush
+  waits for your function, so give it its own timeouts. Nothing can flush after
+  `os._exit`, a kill signal, or in a child created by `os.fork` (it has no thread).
+- **No deadlocks from inside.** Calling `flush`, `poll` or `close` from the flush
+  function raises `RuntimeError`, and an `add` there that would wait raises `BatcherFull`.
+
+Failures come back with their items:
+
+```python
+from timedbatch import FlushError, TimedBatcher
+
+
+def flaky(batch: list[str]) -> None:
+    raise ConnectionError("database is down")
+
+
+batcher = TimedBatcher(flaky, max_items=10, max_seconds=60.0)
+batcher.add("order-1")
+batcher.add("order-2")
+try:
+    batcher.close()
+except FlushError as error:
+    print(error.batches)  # [['order-1', 'order-2']]
+    print(error)  # 1 batch (2 items) failed to flush: ConnectionError('database is down')
+```
+
+### Deterministic tests
+
+`background=False` removes the thread: due batches are delivered by the caller inside
+`add` and `poll()`, so an injected clock drives every age decision (and the `timeout`
+of `flush` and `close` has nothing to wait for).
+
+```python
+from timedbatch import TimedBatcher
+
+now = 0.0
+sent: list[list[str]] = []
+batcher = TimedBatcher(
+    sent.append, max_items=100, max_seconds=5.0, clock=lambda: now, background=False
+)
+batcher.add("x")
+now = 4.9
+batcher.poll()
+print(sent)  # []
+now = 5.0
+batcher.poll()
+print(sent)  # [['x']]
+```
+
+## asyncio
+
+`abatched_by_time` yields a partial batch on time even while the source waits. It keeps
+the pending read across those flushes (it uses `asyncio.wait`, which does not cancel on
+timeout), so no item is lost. Each read runs in its own task, so context variables the
+source sets do not carry from one item to the next. Closing it early drops the partial
+batch and the read in flight.
+
+```python
+import asyncio
+from timedbatch import abatched_by_time
+
+
+async def ticks():
+    yield 1
+    yield 2
+    await asyncio.sleep(0.3)  # the source goes quiet
+    yield 3
+
+
+async def main() -> None:
+    async for batch in abatched_by_time(ticks(), max_items=10, max_seconds=0.1):
+        print(batch)  # [1, 2]
+        # [3]
+
+
+asyncio.run(main())
+```
+
+`AsyncTimedBatcher` is `TimedBatcher` for one event loop, with an async flush function
+(`on_error` may be sync or async). Close it with `async with` or `await aclose()`:
+coroutines cannot run at interpreter exit. If its flush task is cancelled, for example
+because the loop ended first, the batcher closes and the next call hands back what it
+held. `TimedBatcher` refuses an `async def` flush function instead of dropping batches.
+
+```python
+import asyncio
+from timedbatch import AsyncTimedBatcher
+
+
+async def send(batch: list[str]) -> None:
+    print("send", batch)
+
+
+async def main() -> None:
+    async with AsyncTimedBatcher(send, max_items=3, max_seconds=1.0, max_pending=100) as out:
+        for word in ["a", "b", "c", "d"]:
+            await out.add(word)  # waits when 100 items are already pending
+
+
+asyncio.run(main())
+# send ['a', 'b', 'c']
+# send ['d']
+```
+
+## Why
+
+Count-based batching is everywhere (`itertools.batched`, `more-itertools` `chunked`),
+but none of it closes a batch on elapsed time. Code that ships logs, events or metrics
+almost always wants both bounds: cap the size so a batch never grows without limit, and
+cap the latency so a slow stream still drains on schedule. The hard part is the rest:
+flushing an idle buffer, not losing items when the sink fails or the program exits,
+slowing producers down when the sink falls behind. `timedbatch` does that once, with tests
+that run hundreds of random timelines against a reference model and hammer the batchers
+from many threads and tasks.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

timedbatch-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+timedbatch/__init__.py,sha256=wA-qVQD-gl5METI1vGdVs2ndAuO2h2QZDAIq0g9vogU,524
+timedbatch/_abatcher.py,sha256=A7qNh28XYRbNG60VStPp8IOpxIdb_xWLsjphA1LG0wk,7811
+timedbatch/_abatching.py,sha256=oVzcvgxTH0C5rhPjxDg2zubIjBVWVvNef7e89lqp8XE,3465
+timedbatch/_batcher.py,sha256=YxwYzQ1leF-KWdWnZEPytXE54Oc7abT7_aF7sG3hZ98,6208
+timedbatch/_batching.py,sha256=-2n_oGVSvYLpCEr3ltZpJ0XXuwYsv_Uxb4yrjkPlC5g,2005
+timedbatch/_core.py,sha256=-KSq-jz2nEpESAvuUzj4T8elt5-6DAbjcqKa5YhGHTg,4130
+timedbatch/_engine.py,sha256=JLUR9o-Kqlj60z2O2DD6P3q_GG4yDE2kyrmERc5kZj4,4495
+timedbatch/_errors.py,sha256=dbI8v13zpp6EjpTXiZekGE8BuoyBQy8TJwvpd-ophiI,1295
+timedbatch/_limits.py,sha256=oOh1RUEOiVNdzkmAvgW5lmOho61HZ-JRneQW0zA3uUE,1942
+timedbatch/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+timedbatch-0.2.0.dist-info/METADATA,sha256=VxW2jewvU2EdmYiDWOOwCm9btxxt3QqxqY6gV7klSN8,8569
+timedbatch-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+timedbatch-0.2.0.dist-info/licenses/LICENSE,sha256=_WmABlQG__oqlx4Rzp-qDJ10xND5KCLScftbhXbLC_c,1070
+timedbatch-0.2.0.dist-info/RECORD,,

timedbatch-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

timedbatch-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.