tasklane 0.1.0__py3-none-any.whl

tasklane/__init__.py

@@ -0,0 +1,40 @@
+"""tasklane: bounded-concurrency async for Python.
+
+Run, map, and stream awaitables with a concurrency limit, retries, backoff,
+rate limiting, and progress reporting — in one typed call.
+
+Quickstart::
+
+    import asyncio
+    import tasklane
+
+    async def fetch(url: str) -> int:
+        await asyncio.sleep(0.1)
+        return len(url)
+
+    async def main() -> None:
+        urls = ["https://example.com"] * 100
+        # At most 10 concurrent calls, each retried up to 3 times.
+        sizes = await tasklane.amap(fetch, urls, limit=10, retries=3)
+        print(sum(sizes))
+
+    asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+from tasklane._core import amap, gather, stream
+from tasklane._lane import Lane
+from tasklane._progress import Progress
+from tasklane._retry import Backoff
+
+__all__ = [
+    "Backoff",
+    "Lane",
+    "Progress",
+    "amap",
+    "gather",
+    "stream",
+]
+
+__version__ = "0.1.0"

tasklane/_core.py

@@ -0,0 +1,492 @@
+"""Core engine: a bounded worker pool over an async queue.
+
+Both :func:`amap` and :func:`stream` are thin policy layers over the private
+``_imap_unordered`` generator, which runs ``limit`` workers that pull items off
+a bounded input queue, apply retries/timeout/rate-limiting, and emit completions
+as they finish. The bounded input queue gives natural backpressure, so even an
+infinite async iterable is processed in constant memory.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import (
+    AsyncGenerator,
+    AsyncIterable,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Iterable,
+    Sized,
+)
+from dataclasses import dataclass, field
+from time import monotonic
+from typing import Any, Generic, Literal, TypeVar, overload
+
+from tasklane._progress import Progress
+from tasklane._ratelimit import RateLimiter
+from tasklane._retry import Backoff
+
+__all__ = ["amap", "gather", "stream"]
+
+T = TypeVar("T")
+R = TypeVar("R")
+
+#: A type, a tuple of types, or a predicate deciding whether to retry an error.
+RetryOn = type[BaseException] | tuple[type[BaseException], ...] | Callable[[BaseException], bool]
+
+DEFAULT_LIMIT = 16
+_DEFAULT_BACKOFF = Backoff()
+
+
+class _WorkerExit:
+    """Sentinel a worker emits when it has consumed its stop signal."""
+
+    __slots__ = ()
+
+
+_WORKER_EXIT = _WorkerExit()
+
+
+@dataclass(slots=True)
+class _Completed:
+    index: int
+    value: Any
+    exc: BaseException | None
+
+
+@dataclass(slots=True)
+class _Counters:
+    #: Incremented by workers as they pick up items; read by the consumer to
+    #: derive ``in_flight``. Completed/succeeded/failed are counted consumer-side
+    #: so progress snapshots advance one-per-completion instead of in worker-batches.
+    started: int = 0
+
+
+@dataclass(slots=True)
+class _Settings(Generic[T, R]):
+    func: Callable[[T], Awaitable[R]]
+    limit: int
+    retries: int
+    backoff: Backoff
+    retry_on: RetryOn
+    timeout: float | None
+    rate_limiter: RateLimiter | None
+    on_progress: Callable[[Progress], None] | None = field(default=None)
+
+
+def _validate(limit: int, retries: int, timeout: float | None, rate_limit: float | None) -> None:
+    if limit < 1:
+        raise ValueError("limit must be >= 1")
+    if retries < 0:
+        raise ValueError("retries must be >= 0")
+    if timeout is not None and timeout <= 0:
+        raise ValueError("timeout must be > 0")
+    if rate_limit is not None and rate_limit <= 0:
+        raise ValueError("rate_limit must be > 0")
+
+
+def _make_settings(
+    func: Callable[[T], Awaitable[R]],
+    *,
+    limit: int,
+    retries: int,
+    backoff: Backoff | None,
+    retry_on: RetryOn,
+    timeout: float | None,
+    rate_limit: float | None,
+    on_progress: Callable[[Progress], None] | None,
+) -> _Settings[T, R]:
+    _validate(limit, retries, timeout, rate_limit)
+    return _Settings(
+        func=func,
+        limit=limit,
+        retries=retries,
+        backoff=backoff if backoff is not None else _DEFAULT_BACKOFF,
+        retry_on=retry_on,
+        timeout=timeout,
+        rate_limiter=RateLimiter(rate_limit) if rate_limit is not None else None,
+        on_progress=on_progress,
+    )
+
+
+def _len_or_none(items: Iterable[T] | AsyncIterable[T]) -> int | None:
+    return len(items) if isinstance(items, Sized) else None
+
+
+async def _aiter(items: Iterable[T] | AsyncIterable[T]) -> AsyncIterator[T]:
+    if isinstance(items, AsyncIterable):
+        async for item in items:
+            yield item
+    else:
+        for item in items:
+            yield item
+
+
+def _should_retry(exc: BaseException, retry_on: RetryOn) -> bool:
+    if isinstance(retry_on, (tuple, type)):
+        return isinstance(exc, retry_on)
+    return bool(retry_on(exc))
+
+
+def _normalize_timeout(exc: BaseException) -> BaseException:
+    """Surface asyncio timeouts as the builtin ``TimeoutError`` on every version.
+
+    On Python 3.10, ``asyncio.wait_for`` raises ``asyncio.TimeoutError``, which is
+    a distinct type from the builtin ``TimeoutError`` (the two were unified in
+    3.11). Re-mapping it means ``except TimeoutError`` and ``retry_on=TimeoutError``
+    behave identically across the supported 3.10-3.14 range.
+    """
+    if isinstance(exc, asyncio.TimeoutError) and not isinstance(exc, TimeoutError):
+        normalized = TimeoutError(str(exc))
+        normalized.__cause__ = exc.__cause__
+        return normalized
+    return exc
+
+
+async def _run_one(item: T, s: _Settings[T, R]) -> tuple[Any, BaseException | None]:
+    """Run ``func(item)`` with retries, backoff, timeout, and rate limiting."""
+    attempt = 0
+    while True:
+        try:
+            if s.rate_limiter is not None:
+                await s.rate_limiter.acquire()
+            if s.timeout is not None:
+                return await asyncio.wait_for(s.func(item), s.timeout), None
+            return await s.func(item), None
+        except asyncio.CancelledError:
+            raise
+        except BaseException as exc:
+            error = _normalize_timeout(exc)
+            if attempt >= s.retries or not _should_retry(error, s.retry_on):
+                return None, error
+            delay = s.backoff.delay_for(attempt)
+            attempt += 1
+            if delay > 0:
+                await asyncio.sleep(delay)
+
+
+async def _imap_unordered(
+    items: Iterable[T] | AsyncIterable[T],
+    s: _Settings[T, R],
+) -> AsyncGenerator[_Completed, None]:
+    """Yield completions in the order tasks finish (not input order)."""
+    start = monotonic()
+    total = _len_or_none(items)
+    counters = _Counters()
+    input_q: asyncio.Queue[tuple[int, T] | None] = asyncio.Queue(maxsize=s.limit)
+    output_q: asyncio.Queue[_Completed | _WorkerExit] = asyncio.Queue()
+    feeder_error: BaseException | None = None
+
+    async def feeder() -> None:
+        nonlocal feeder_error
+        index = 0
+        try:
+            async for item in _aiter(items):
+                await input_q.put((index, item))
+                index += 1
+        except asyncio.CancelledError:
+            raise
+        except BaseException as exc:
+            feeder_error = exc
+        finally:
+            for _ in range(s.limit):
+                await input_q.put(None)
+
+    async def worker() -> None:
+        while True:
+            got = await input_q.get()
+            if got is None:
+                await output_q.put(_WORKER_EXIT)
+                return
+            index, item = got
+            counters.started += 1
+            value, exc = await _run_one(item, s)
+            await output_q.put(_Completed(index, value, exc))
+
+    tasks = [asyncio.create_task(feeder())]
+    tasks.extend(asyncio.create_task(worker()) for _ in range(s.limit))
+    exited = 0
+    completed = 0
+    succeeded = 0
+    failed = 0
+    try:
+        while exited < s.limit:
+            msg = await output_q.get()
+            if isinstance(msg, _WorkerExit):
+                exited += 1
+                continue
+            completed += 1
+            if msg.exc is None:
+                succeeded += 1
+            else:
+                failed += 1
+            if s.on_progress is not None:
+                s.on_progress(
+                    Progress(
+                        completed=completed,
+                        total=total,
+                        succeeded=succeeded,
+                        failed=failed,
+                        in_flight=counters.started - completed,
+                        elapsed=monotonic() - start,
+                    )
+                )
+            yield msg
+        if feeder_error is not None:
+            raise feeder_error
+    finally:
+        for task in tasks:
+            task.cancel()
+        while not input_q.empty():
+            try:
+                input_q.get_nowait()
+            except asyncio.QueueEmpty:  # pragma: no cover - defensive
+                break
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+
+# --------------------------------------------------------------------------- #
+# Public API
+# --------------------------------------------------------------------------- #
+
+
+@overload
+async def amap(
+    func: Callable[[T], Awaitable[R]],
+    items: Iterable[T] | AsyncIterable[T],
+    *,
+    limit: int = ...,
+    retries: int = ...,
+    backoff: Backoff | None = ...,
+    retry_on: RetryOn = ...,
+    timeout: float | None = ...,
+    return_exceptions: Literal[False] = ...,
+    rate_limit: float | None = ...,
+    on_progress: Callable[[Progress], None] | None = ...,
+) -> list[R]: ...
+
+
+@overload
+async def amap(
+    func: Callable[[T], Awaitable[R]],
+    items: Iterable[T] | AsyncIterable[T],
+    *,
+    limit: int = ...,
+    retries: int = ...,
+    backoff: Backoff | None = ...,
+    retry_on: RetryOn = ...,
+    timeout: float | None = ...,
+    return_exceptions: Literal[True],
+    rate_limit: float | None = ...,
+    on_progress: Callable[[Progress], None] | None = ...,
+) -> list[R | BaseException]: ...
+
+
+async def amap(
+    func: Callable[[T], Awaitable[R]],
+    items: Iterable[T] | AsyncIterable[T],
+    *,
+    limit: int = DEFAULT_LIMIT,
+    retries: int = 0,
+    backoff: Backoff | None = None,
+    retry_on: RetryOn = Exception,
+    timeout: float | None = None,
+    return_exceptions: bool = False,
+    rate_limit: float | None = None,
+    on_progress: Callable[[Progress], None] | None = None,
+) -> list[Any]:
+    """Apply ``func`` to every item concurrently and return results in input order.
+
+    Args:
+        func: An async function called once per item.
+        items: A sync or async iterable of inputs.
+        limit: Maximum number of tasks running at once.
+        retries: How many times to retry a failing task (0 disables retries).
+        backoff: Delay strategy between retries (defaults to exponential w/ jitter).
+        retry_on: Exception type(s) or a predicate selecting which errors retry.
+        timeout: Per-attempt timeout in seconds.
+        return_exceptions: If true, failures are returned in place of values
+            instead of being raised (mirrors ``asyncio.gather``).
+        rate_limit: Maximum task starts per second across the whole run.
+        on_progress: Callback invoked with a :class:`Progress` snapshot after
+            each task finishes.
+
+    Returns:
+        A list of results aligned with ``items``. With ``return_exceptions=True``
+        the list may contain exception instances.
+    """
+    s = _make_settings(
+        func,
+        limit=limit,
+        retries=retries,
+        backoff=backoff,
+        retry_on=retry_on,
+        timeout=timeout,
+        rate_limit=rate_limit,
+        on_progress=on_progress,
+    )
+    total = _len_or_none(items)
+    out: list[Any] = [None] * total if total is not None else []
+    buffer: dict[int, Any] = {}
+    gen = _imap_unordered(items, s)
+    try:
+        async for c in gen:
+            result: Any
+            if c.exc is not None:
+                if not return_exceptions:
+                    raise c.exc
+                result = c.exc
+            else:
+                result = c.value
+            if total is not None:
+                out[c.index] = result
+            else:
+                buffer[c.index] = result
+    finally:
+        await gen.aclose()
+    if total is None:
+        out = [buffer[i] for i in range(len(buffer))]
+    return out
+
+
+@overload
+def stream(
+    func: Callable[[T], Awaitable[R]],
+    items: Iterable[T] | AsyncIterable[T],
+    *,
+    limit: int = ...,
+    retries: int = ...,
+    backoff: Backoff | None = ...,
+    retry_on: RetryOn = ...,
+    timeout: float | None = ...,
+    return_exceptions: Literal[False] = ...,
+    rate_limit: float | None = ...,
+    on_progress: Callable[[Progress], None] | None = ...,
+) -> AsyncIterator[R]: ...
+
+
+@overload
+def stream(
+    func: Callable[[T], Awaitable[R]],
+    items: Iterable[T] | AsyncIterable[T],
+    *,
+    limit: int = ...,
+    retries: int = ...,
+    backoff: Backoff | None = ...,
+    retry_on: RetryOn = ...,
+    timeout: float | None = ...,
+    return_exceptions: Literal[True],
+    rate_limit: float | None = ...,
+    on_progress: Callable[[Progress], None] | None = ...,
+) -> AsyncIterator[R | BaseException]: ...
+
+
+async def stream(
+    func: Callable[[T], Awaitable[R]],
+    items: Iterable[T] | AsyncIterable[T],
+    *,
+    limit: int = DEFAULT_LIMIT,
+    retries: int = 0,
+    backoff: Backoff | None = None,
+    retry_on: RetryOn = Exception,
+    timeout: float | None = None,
+    return_exceptions: bool = False,
+    rate_limit: float | None = None,
+    on_progress: Callable[[Progress], None] | None = None,
+) -> AsyncIterator[Any]:
+    """Like :func:`amap`, but yield each result as soon as it is ready.
+
+    Results arrive in completion order (not input order), which lets you react to
+    fast tasks without waiting for slow ones. Memory stays bounded even for very
+    large or infinite inputs.
+    """
+    s = _make_settings(
+        func,
+        limit=limit,
+        retries=retries,
+        backoff=backoff,
+        retry_on=retry_on,
+        timeout=timeout,
+        rate_limit=rate_limit,
+        on_progress=on_progress,
+    )
+    gen = _imap_unordered(items, s)
+    try:
+        async for c in gen:
+            if c.exc is not None:
+                if not return_exceptions:
+                    raise c.exc
+                yield c.exc
+            else:
+                yield c.value
+    finally:
+        await gen.aclose()
+
+
+@overload
+async def gather(
+    *coros: Awaitable[T],
+    limit: int = ...,
+    timeout: float | None = ...,
+    rate_limit: float | None = ...,
+    return_exceptions: Literal[False] = ...,
+    on_progress: Callable[[Progress], None] | None = ...,
+) -> list[T]: ...
+
+
+@overload
+async def gather(
+    *coros: Awaitable[T],
+    limit: int = ...,
+    timeout: float | None = ...,
+    rate_limit: float | None = ...,
+    return_exceptions: Literal[True],
+    on_progress: Callable[[Progress], None] | None = ...,
+) -> list[T | BaseException]: ...
+
+
+async def gather(
+    *coros: Awaitable[T],
+    limit: int = DEFAULT_LIMIT,
+    timeout: float | None = None,
+    rate_limit: float | None = None,
+    return_exceptions: bool = False,
+    on_progress: Callable[[Progress], None] | None = None,
+) -> list[Any]:
+    """A drop-in for :func:`asyncio.gather` with a concurrency ``limit``.
+
+    Awaits the given awaitables with at most ``limit`` running at once, preserving
+    result order. On fail-fast (the default), remaining awaitables are cancelled
+    and closed so no "coroutine was never awaited" warnings leak.
+    """
+    pending = list(coros)
+
+    async def _await(c: Awaitable[T]) -> T:
+        return await c
+
+    try:
+        if return_exceptions:
+            return await amap(
+                _await,
+                pending,
+                limit=limit,
+                timeout=timeout,
+                rate_limit=rate_limit,
+                return_exceptions=True,
+                on_progress=on_progress,
+            )
+        return await amap(
+            _await,
+            pending,
+            limit=limit,
+            timeout=timeout,
+            rate_limit=rate_limit,
+            return_exceptions=False,
+            on_progress=on_progress,
+        )
+    finally:
+        for c in pending:
+            close = getattr(c, "close", None)
+            if callable(close):
+                close()

tasklane/_lane.py

@@ -0,0 +1,100 @@
+"""A reusable, immutable bundle of concurrency settings."""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import AsyncIterable, AsyncIterator, Awaitable, Callable, Iterable
+from typing import Any, TypeVar
+
+from tasklane import _core
+from tasklane._core import DEFAULT_LIMIT, RetryOn
+from tasklane._progress import Progress
+from tasklane._retry import Backoff
+
+__all__ = ["Lane"]
+
+T = TypeVar("T")
+R = TypeVar("R")
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Lane:
+    """Configure concurrency once, then reuse it across many calls.
+
+    A ``Lane`` is an immutable bundle of the knobs you would otherwise repeat on
+    every :func:`tasklane.amap` call — handy when, say, one downstream API should
+    always be hit with the same concurrency, retry, and rate-limit policy::
+
+        api = Lane(limit=8, retries=3, rate_limit=20)
+        users = await api.map(fetch_user, user_ids)
+        async for post in api.stream(fetch_post, post_ids):
+            ...
+
+    Lanes are frozen; use :meth:`replace` to derive a tweaked copy. Each call runs
+    its own independent worker pool.
+    """
+
+    limit: int = DEFAULT_LIMIT
+    retries: int = 0
+    backoff: Backoff | None = None
+    retry_on: RetryOn = Exception
+    timeout: float | None = None
+    rate_limit: float | None = None
+    on_progress: Callable[[Progress], None] | None = None
+
+    def __post_init__(self) -> None:
+        _core._validate(self.limit, self.retries, self.timeout, self.rate_limit)
+
+    async def map(
+        self,
+        func: Callable[[T], Awaitable[R]],
+        items: Iterable[T] | AsyncIterable[T],
+    ) -> list[R]:
+        """Run :func:`tasklane.amap` with this lane's settings (fail-fast)."""
+        return await _core.amap(
+            func,
+            items,
+            limit=self.limit,
+            retries=self.retries,
+            backoff=self.backoff,
+            retry_on=self.retry_on,
+            timeout=self.timeout,
+            rate_limit=self.rate_limit,
+            on_progress=self.on_progress,
+        )
+
+    def stream(
+        self,
+        func: Callable[[T], Awaitable[R]],
+        items: Iterable[T] | AsyncIterable[T],
+    ) -> AsyncIterator[R]:
+        """Run :func:`tasklane.stream` with this lane's settings (fail-fast)."""
+        return _core.stream(
+            func,
+            items,
+            limit=self.limit,
+            retries=self.retries,
+            backoff=self.backoff,
+            retry_on=self.retry_on,
+            timeout=self.timeout,
+            rate_limit=self.rate_limit,
+            on_progress=self.on_progress,
+        )
+
+    async def gather(self, *coros: Awaitable[T]) -> list[T]:
+        """Run :func:`tasklane.gather` with this lane's limit/timeout/rate policy.
+
+        Note that ``retries`` and ``backoff`` do not apply: a coroutine can only
+        be awaited once, so failed coroutines cannot be retried.
+        """
+        return await _core.gather(
+            *coros,
+            limit=self.limit,
+            timeout=self.timeout,
+            rate_limit=self.rate_limit,
+            on_progress=self.on_progress,
+        )
+
+    def replace(self, **changes: Any) -> Lane:
+        """Return a copy of this lane with the given fields overridden."""
+        return dataclasses.replace(self, **changes)

tasklane/_progress.py

@@ -0,0 +1,55 @@
+"""Progress reporting types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["Progress"]
+
+
+@dataclass(frozen=True, slots=True)
+class Progress:
+    """A snapshot of progress, passed to an ``on_progress`` callback.
+
+    A new snapshot is produced each time a task finishes (successfully or not).
+    """
+
+    completed: int
+    """Number of tasks that have finished (succeeded + failed)."""
+
+    total: int | None
+    """Total number of tasks, or ``None`` if the input size is not known
+    (e.g. an unsized iterator or async iterable)."""
+
+    succeeded: int
+    """Number of tasks that finished without raising."""
+
+    failed: int
+    """Number of tasks that finished by raising (after exhausting retries)."""
+
+    in_flight: int
+    """Number of tasks currently running."""
+
+    elapsed: float
+    """Seconds elapsed since the run started (monotonic clock)."""
+
+    @property
+    def remaining(self) -> int | None:
+        """Tasks not yet completed, or ``None`` if ``total`` is unknown."""
+        if self.total is None:
+            return None
+        return self.total - self.completed
+
+    @property
+    def fraction(self) -> float | None:
+        """Completion ratio in ``[0, 1]``, or ``None`` if ``total`` is unknown."""
+        if self.total is None or self.total == 0:
+            return None
+        return self.completed / self.total
+
+    @property
+    def rate(self) -> float:
+        """Average completed tasks per second since the run started."""
+        if self.elapsed <= 0:
+            return 0.0
+        return self.completed / self.elapsed

tasklane/_ratelimit.py

@@ -0,0 +1,44 @@
+"""An async token-bucket rate limiter used to cap how fast tasks start."""
+
+from __future__ import annotations
+
+import asyncio
+from time import monotonic
+
+__all__ = ["RateLimiter"]
+
+
+class RateLimiter:
+    """Admits at most ``rate`` acquisitions per second on average.
+
+    Implemented as a token bucket. ``burst`` controls how many acquisitions may
+    happen back-to-back before the steady rate kicks in; the default of ``1``
+    enforces strict, evenly spaced starts.
+    """
+
+    __slots__ = ("_capacity", "_lock", "_rate", "_tokens", "_updated")
+
+    def __init__(self, rate: float, *, burst: int = 1) -> None:
+        if rate <= 0:
+            raise ValueError("rate must be > 0")
+        if burst < 1:
+            raise ValueError("burst must be >= 1")
+        self._rate = rate
+        self._capacity = float(burst)
+        self._tokens = float(burst)
+        self._updated = monotonic()
+        self._lock = asyncio.Lock()
+
+    async def acquire(self) -> None:
+        """Block until a token is available, then consume it."""
+        async with self._lock:
+            while True:
+                now = monotonic()
+                self._tokens = min(
+                    self._capacity, self._tokens + (now - self._updated) * self._rate
+                )
+                self._updated = now
+                if self._tokens >= 1:
+                    self._tokens -= 1
+                    return
+                await asyncio.sleep((1 - self._tokens) / self._rate)

tasklane/_retry.py

@@ -0,0 +1,89 @@
+"""Retry backoff strategies."""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+from typing import Literal
+
+__all__ = ["Backoff"]
+
+Mode = Literal["exponential", "linear", "constant"]
+
+
+@dataclass(frozen=True, slots=True)
+class Backoff:
+    """Computes the delay between retry attempts.
+
+    The default is exponential backoff with full jitter, which is a sane choice
+    for most network-bound work. Use the :meth:`constant` and :meth:`linear`
+    constructors for the other common strategies.
+
+    Args:
+        base: The base delay in seconds.
+        factor: Growth factor for ``"exponential"`` mode.
+        max_delay: Upper bound applied to every computed delay.
+        jitter: If true, the delay is randomized in ``[0, delay]`` (full
+            jitter), which spreads out retries from many callers.
+        mode: How the delay grows with the attempt number.
+    """
+
+    base: float = 0.1
+    factor: float = 2.0
+    max_delay: float = 30.0
+    jitter: bool = True
+    mode: Mode = "exponential"
+
+    def __post_init__(self) -> None:
+        if self.base < 0:
+            raise ValueError("base must be >= 0")
+        if self.factor <= 0:
+            raise ValueError("factor must be > 0")
+        if self.max_delay < 0:
+            raise ValueError("max_delay must be >= 0")
+
+    @classmethod
+    def exponential(
+        cls,
+        base: float = 0.1,
+        *,
+        factor: float = 2.0,
+        max_delay: float = 30.0,
+        jitter: bool = True,
+    ) -> Backoff:
+        """Exponential backoff: ``base * factor ** attempt`` (capped)."""
+        return cls(base=base, factor=factor, max_delay=max_delay, jitter=jitter, mode="exponential")
+
+    @classmethod
+    def linear(
+        cls,
+        step: float = 0.1,
+        *,
+        max_delay: float = 30.0,
+        jitter: bool = True,
+    ) -> Backoff:
+        """Linear backoff: ``step * (attempt + 1)`` (capped)."""
+        return cls(base=step, max_delay=max_delay, jitter=jitter, mode="linear")
+
+    @classmethod
+    def constant(cls, delay: float = 0.1, *, jitter: bool = False) -> Backoff:
+        """Constant delay between every attempt."""
+        return cls(base=delay, max_delay=delay, jitter=jitter, mode="constant")
+
+    def delay_for(self, attempt: int) -> float:
+        """Return the delay in seconds before retry ``attempt`` (0-indexed).
+
+        ``attempt=0`` is the first retry (i.e. after the initial call failed).
+        """
+        if attempt < 0:
+            raise ValueError("attempt must be >= 0")
+        if self.mode == "exponential":
+            raw = self.base * (self.factor**attempt)
+        elif self.mode == "linear":
+            raw = self.base * (attempt + 1)
+        else:  # constant
+            raw = self.base
+        delay = min(raw, self.max_delay)
+        if self.jitter:
+            delay = random.uniform(0, delay)
+        return delay

tasklane-0.1.0.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: tasklane
+Version: 0.1.0
+Summary: Bounded-concurrency async for Python: run, map, and stream awaitables with limits, retries, rate limiting, and progress — in one typed call.
+Project-URL: Homepage, https://github.com/jpwm2/tasklane
+Project-URL: Repository, https://github.com/jpwm2/tasklane
+Project-URL: Issues, https://github.com/jpwm2/tasklane/issues
+Project-URL: Changelog, https://github.com/jpwm2/tasklane/blob/main/CHANGELOG.md
+Author: jpwm2
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,asyncio,concurrency,gather,parallel,rate-limit,retry,semaphore,task-pool,throttle
+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.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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# tasklane
+
+**Bounded-concurrency async for Python — run, map, and stream awaitables with a
+concurrency limit, retries, backoff, rate limiting, and progress, in one typed call.**
+
+[![CI](https://github.com/jpwm2/tasklane/actions/workflows/ci.yml/badge.svg)](https://github.com/jpwm2/tasklane/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tasklane.svg)](https://pypi.org/project/tasklane/)
+[![Python](https://img.shields.io/pypi/pyversions/tasklane.svg)](https://pypi.org/project/tasklane/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Types: typed](https://img.shields.io/badge/types-100%25-blue.svg)](src/tasklane/py.typed)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+Every Python project that fans out async work eventually rewrites the same block:
+an `asyncio.Semaphore` to cap concurrency, a `try/except` retry loop, a counter
+for progress, maybe a sleep to stay under a rate limit. `tasklane` is that block,
+done once — correct, fully typed, and **zero runtime dependencies**.
+
+```python
+import asyncio
+import httpx
+import tasklane
+
+async def fetch(url: str) -> int:
+    async with httpx.AsyncClient() as client:
+        return len((await client.get(url)).text)
+
+async def main() -> None:
+    urls = [f"https://example.com/{i}" for i in range(1000)]
+
+    sizes = await tasklane.amap(
+        fetch, urls,
+        limit=20,          # at most 20 requests in flight
+        retries=3,         # retry failures up to 3x with exponential backoff
+        rate_limit=50,     # start at most 50 requests per second
+        timeout=10,        # per-attempt timeout (seconds)
+    )
+    print(sum(sizes))
+
+asyncio.run(main())
+```
+
+## Install
+
+```bash
+pip install tasklane
+# or
+uv add tasklane
+```
+
+Requires Python 3.10+. No third-party dependencies.
+
+## Why not just `asyncio.gather`?
+
+`asyncio.gather` starts **everything at once**. Fan out 10,000 requests and you
+open 10,000 sockets, trip rate limits, and OOM. The usual fixes are scattered
+across the stdlib and third-party libs; `tasklane` brings them together:
+
+|                              | `asyncio.gather` | `Semaphore` + `gather` | `aiometer` | **tasklane** |
+| ---------------------------- | :--------------: | :--------------------: | :--------: | :----------: |
+| Concurrency limit            |        ✗         |        manual          |     ✓      |      ✓       |
+| Results in input order       |        ✓         |          ✓             |     ✓      |      ✓       |
+| Stream results as completed  |   `as_completed` |        manual          |     ✓      |      ✓       |
+| Retries + backoff            |        ✗         |          ✗             |     ✗      |      ✓       |
+| Rate limiting (per second)   |        ✗         |          ✗             |     ✓      |      ✓       |
+| Progress callbacks           |        ✗         |          ✗             |     ✗      |      ✓       |
+| Per-task timeout             |        ✗         |        manual          |     ✗      |      ✓       |
+| Backpressure on huge inputs  |        ✗         |        manual          |     ✓      |      ✓       |
+| Runtime dependencies         |      stdlib      |        stdlib          |  `anyio`   |  **none**    |
+
+## Features
+
+### `amap` — concurrent map, results in order
+
+```python
+results = await tasklane.amap(fetch, urls, limit=10)
+# results[i] corresponds to urls[i]
+```
+
+Accepts both sync and **async** iterables, and works in constant memory thanks to
+a bounded internal queue — you can map over a million-item generator without
+materializing a million tasks.
+
+### `stream` — react to results as they finish
+
+```python
+async for size in tasklane.stream(fetch, urls, limit=10):
+    print(size)  # arrives in completion order, fastest first
+```
+
+### `gather` — a drop-in `asyncio.gather` with a limit
+
+```python
+results = await tasklane.gather(*(fetch(u) for u in urls), limit=10)
+```
+
+On fail-fast, the remaining coroutines are cancelled **and closed**, so you never
+see a `coroutine was never awaited` warning.
+
+### Retries with backoff
+
+```python
+from tasklane import Backoff
+
+await tasklane.amap(
+    fetch, urls,
+    retries=5,
+    backoff=Backoff.exponential(0.2, factor=2, max_delay=30),  # 0.2, 0.4, 0.8, ... + jitter
+    retry_on=(TimeoutError, ConnectionError),                  # type, tuple, or predicate
+)
+```
+
+`Backoff.exponential()` (the default when `retries > 0`), `Backoff.linear()`, and
+`Backoff.constant()` cover the common cases. `retry_on` accepts an exception type,
+a tuple of types, or a `Callable[[BaseException], bool]` predicate.
+
+### Rate limiting
+
+```python
+# Never start more than 100 tasks per second, regardless of the concurrency limit.
+await tasklane.amap(call_api, items, limit=50, rate_limit=100)
+```
+
+### Progress
+
+```python
+from tasklane import Progress
+
+def show(p: Progress) -> None:
+    print(f"{p.completed}/{p.total}  ({p.failed} failed)  {p.rate:.0f}/s")
+
+await tasklane.amap(fetch, urls, limit=10, on_progress=show)
+```
+
+`Progress` carries `completed`, `total`, `succeeded`, `failed`, `in_flight`, and
+`elapsed`, plus `remaining`, `fraction`, and `rate` helpers. Plug it into `tqdm`,
+a logger, or a web UI — no progress-bar dependency is imposed on you.
+
+### Collect errors instead of raising
+
+```python
+results = await tasklane.amap(fetch, urls, return_exceptions=True)
+ok = [r for r in results if not isinstance(r, Exception)]
+```
+
+### `Lane` — configure once, reuse everywhere
+
+```python
+from tasklane import Lane
+
+# One policy for a specific downstream API.
+github = Lane(limit=8, retries=3, rate_limit=20, timeout=10)
+
+repos = await github.map(fetch_repo, repo_names)
+async for issue in github.stream(fetch_issue, issue_ids):
+    ...
+
+# Lanes are immutable; derive a variant with .replace()
+bulk = github.replace(limit=32)
+```
+
+## How it works
+
+`tasklane` runs a fixed pool of `limit` worker coroutines that pull items off a
+bounded `asyncio.Queue`. The bounded queue is what gives you backpressure and
+constant memory; the worker pool is what enforces the concurrency limit exactly.
+Retries, per-attempt timeouts, and rate limiting are applied inside each worker,
+and completions are streamed back to the caller — collected into order for
+`amap`, or yielded as-they-finish for `stream`. On any early exit (fail-fast,
+`break`, or external cancellation) every in-flight task is cancelled and awaited,
+so nothing leaks.
+
+## API reference
+
+| Symbol | Description |
+| ------ | ----------- |
+| `amap(func, items, *, limit, retries, backoff, retry_on, timeout, return_exceptions, rate_limit, on_progress)` | Concurrent map; returns a list in input order. |
+| `stream(func, items, *, ...)` | Async iterator yielding results in completion order. |
+| `gather(*coros, limit, timeout, rate_limit, return_exceptions, on_progress)` | Concurrency-limited `asyncio.gather`. |
+| `Lane(...)` | Reusable, immutable bundle of settings with `.map`, `.stream`, `.gather`, `.replace`. |
+| `Backoff` | Retry delay strategy: `.exponential`, `.linear`, `.constant`. |
+| `Progress` | Immutable progress snapshot passed to `on_progress`. |
+
+Full signatures and docstrings ship with the package and are surfaced by your
+editor (the library is fully typed and marked with `py.typed`).
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). In short:
+
+```bash
+uv sync
+uv run pytest          # tests
+uv run ruff check .    # lint
+uv run mypy            # types
+```
+
+## License
+
+[MIT](LICENSE) © tasklane contributors

tasklane-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+tasklane/__init__.py,sha256=grvnKw3iu1eY13DAVCHoMHGqXKw2wa87SmJFpMLiLIE,921
+tasklane/_core.py,sha256=s-ySP5bqO3VN9yQR_KhGY0ZKiUx_apXlmSptJrymjD0,15201
+tasklane/_lane.py,sha256=gIZZeLSFioEsHTNU6_Ijmcesd7GebD6LycsLJQFLJ0k,3293
+tasklane/_progress.py,sha256=s2EWlys2DrfNy7HEKnYTlg55NwgubLmoRQJJJKGSFa4,1598
+tasklane/_ratelimit.py,sha256=HiYKMNu1dCWDfjSUCH4BesKapIjJxBPqmBRkTLVppOE,1472
+tasklane/_retry.py,sha256=aBiDn4J1qCgURP3Yivowf5-7KQqxwj15Zm4vkPXjznA,2887
+tasklane/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tasklane-0.1.0.dist-info/METADATA,sha256=nxPbWpMHxWN_gQjs1M9TjGY1biTvtwC0Y8hIkOG8M5o,8931
+tasklane-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tasklane-0.1.0.dist-info/licenses/LICENSE,sha256=Zgg_QI7BvWGwAqwvJ5jjpVkloDuW68XS3e956_LwFUk,1078
+tasklane-0.1.0.dist-info/RECORD,,

tasklane-0.1.0.dist-info/WHEEL

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

tasklane-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tasklane contributors
+
+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.