rotapool 0.1.0__py3-none-any.whl

rotapool/__init__.py

@@ -0,0 +1,15 @@
+from importlib.metadata import version as _version
+
+from .exceptions import CooldownResource, DisableResource, PoolExhausted
+from .models import Resource
+from .pool import Pool
+
+__version__ = _version("rotapool")
+__all__ = [
+    "CooldownResource",
+    "DisableResource",
+    "Pool",
+    "PoolExhausted",
+    "Resource",
+    "__version__",
+]

rotapool/exceptions.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+
+class CooldownResource(Exception):
+    """Raise from a user operation to mark the resource as cooling_down.
+
+    cooldown_seconds: explicit cooldown duration (e.g. derived from a Retry-After
+        header). If None, the framework's default cooldown table applies based on
+        consecutive_cooldown count.
+    reason: free-form string surfaced in logs and metrics.
+    """
+
+    def __init__(
+        self, cooldown_seconds: float | None = None, reason: str | None = None
+    ) -> None:
+        super().__init__(reason or "resource cooldown")
+        self.cooldown_seconds = cooldown_seconds
+        self.reason = reason
+
+
+class DisableResource(Exception):
+    """Raise from a user operation to mark the resource as disabled."""
+
+    def __init__(self, reason: str | None = None) -> None:
+        super().__init__(reason or "resource disabled")
+        self.reason = reason
+
+
+class PoolExhausted(Exception):
+    """Raised by the framework when the pool cannot satisfy a request.
+
+    Covers three scenarios:
+    - No eligible resource exists (all disabled, cooling down, or at capacity).
+    - Max retry attempts exhausted.
+    - Deadline exceeded.
+    """

rotapool/models.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class Resource(Generic[T]):
+    """A single rotatable resource.
+
+    `cooldown_until` and `last_acquired_at` are `time.monotonic()` readings, not epoch
+    timestamps. They are only meaningful when compared to another `time.monotonic()`
+    call in the same process — do not log, persist, or pass to `datetime.fromtimestamp`.
+    """
+
+    resource_id: str
+    value: T
+
+    max_in_flight: int | None = None  # None = unbounded concurrency
+    status: str = "healthy"
+    cooldown_until: float = 0.0
+    last_acquired_at: float = 0.0
+    consecutive_cooldown: int = 0
+
+
+@dataclass
+class Usage:
+    """One in-flight use of a resource.
+
+    `acquired_at` is a `time.monotonic()` reading, not an epoch timestamp — only
+    meaningful relative to other `time.monotonic()` calls in this process.
+
+    `task` holds a cancellable handle for the in-flight operation:
+    - `asyncio.Task` when the operation returned a coroutine (framework wrapped it).
+    - `asyncio.Future` when the operation directly returned a Future.
+    - `None` when the operation returned a plain Awaitable with no `.cancel()`
+      method. In that case `cancel_younger_usages` silently no-ops on this usage
+      and it runs to natural completion -- cancellation is best-effort by design.
+    """
+
+    usage_id: str
+    request_id: str
+    resource_id: str
+    acquired_at: float
+    task: asyncio.Future | None = None
+    status: str = "in_flight"  # in_flight | done | cancelled

rotapool/pool.py

@@ -0,0 +1,424 @@
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import time
+import uuid
+from typing import Any, Awaitable, Callable, Generic, TypeVar
+
+from .exceptions import CooldownResource, DisableResource, PoolExhausted
+from .models import Resource, Usage
+
+T = TypeVar("T")
+R = TypeVar("R")
+
+_DEFAULT_COOLDOWN_TABLE: tuple[float, ...] = (30.0, 120.0, 300.0, 600.0)
+
+
+class Pool(Generic[T]):
+    """A pool of rotatable resources sharing the same usage policy.
+
+    Selection prefers resources with fewer in-flight usages, then older last acquisition
+    time, excludes cooling down and disabled resources.
+    """
+
+    def __init__(
+        self,
+        resources: list[Resource[T]] | dict[str, Resource[T]],
+        max_attempts: int = 3,
+        cooldown_table: tuple[float, ...] = _DEFAULT_COOLDOWN_TABLE,
+    ) -> None:
+        # resource_id -> resource
+        self._resources: dict[str, Resource[T]] = self._build_resources(resources)
+        if not self._resources:
+            raise ValueError("Pool requires at least one resource")
+
+        # Total attempts per `run()` call, not per-resource. Each attempt selects a
+        # fresh resource via the pool's normal selection rules; a resource that
+        # triggered cooldown or disable on one attempt is skipped on the next.
+        # Effectively capped at `len(resources)`: once every resource has been tried and
+        # none is eligible, `run()` raises `PoolExhausted` rather than retrying any one
+        # twice.
+        self._max_attempts: int = max_attempts
+
+        # Cooldown times before a resource can be reactivated, indexed by
+        # consecutive_cooldown count.
+        self._cooldown_table: tuple[float, ...] = cooldown_table
+
+        # Guards all possibly racing states.
+        self._lock: asyncio.Lock = asyncio.Lock()
+
+        # usage_id -> Usage
+        self._usages: dict[str, Usage] = {}
+
+        # resource_id -> { usage_id_set }
+        self._inflight_by_resource: dict[str, set[str]] = {}
+
+    async def run(
+        self,
+        operation: Callable[[Resource[T]], Awaitable[R]],
+        *,
+        max_attempts: int | None = None,
+        deadline: float | None = None,
+        retry_delay: float = 0.5,
+        request_id: str | None = None,
+    ) -> R:
+        """Drive the retry loop for one logical request.
+
+        operation: callable receiving the selected resource and returning an Awaitable.
+            May raise CooldownResource or DisableResource to signal resource health. Any
+            other exception is treated as resource OK and propagates to the caller (so
+            user-side bugs do not poison the pool).
+
+            The returned awaitable can be:
+            - a coroutine (the typical case for `async def` operations) -- the framework
+              wraps it in an `asyncio.Task` so younger sibling cancellation works.
+            - an `asyncio.Future` -- cancellable directly via its `.cancel()` method.
+            - any other Awaitable (custom `__await__` object, etc.) -- awaited directly,
+              with cancellation a silent best-effort no-op for this usage.
+
+            Returning a non-awaitable raises `TypeError` (treated as a user bug; the
+            resource is marked healthy and the error propagates to the caller).
+
+        max_attempts: per-call override of Pool.__init__ max_attempts.
+            This is a total budget across resource switches, not per resource.
+            Effective value is ``min(max_attempts, len(resources))``.
+
+        deadline: absolute time.monotonic() value bounding total time across retries.
+            None disables the deadline.
+
+        retry_delay: pause between failed attempts to let cooling resources recover and
+            to avoid hammering the pool.
+
+        request_id: opaque string attached to every `Usage` created by this call.
+            Useful for correlating logs, metrics, or tracing back to the original
+            caller (e.g. an HTTP request-id header). Auto-generated UUID when None.
+        """
+        rid = request_id or str(uuid.uuid4())
+        cap = max_attempts if max_attempts is not None else self._max_attempts
+        effective_attempts = min(cap, len(self._resources))
+        last_error: BaseException | None = None
+
+        for attempt_num in range(effective_attempts):
+            if deadline is not None and time.monotonic() >= deadline:
+                raise PoolExhausted(f"deadline exceeded after {attempt_num} attempt(s)")
+
+            acquired = await self._acquire(rid)
+            if acquired is None:
+                raise PoolExhausted("no eligible resource in pool")
+            resource, usage = acquired
+
+            try:
+                awaited = operation(resource)
+
+                if inspect.iscoroutine(awaited):
+                    # Wrap in Task so younger-usage cancellation can fire. No await
+                    # between create_task and the assignment -- atomically safe in
+                    # single-loop asyncio; no other coroutine interleaves.
+                    task = asyncio.create_task(awaited)
+                    usage.task = task
+                    result = await task
+                elif isinstance(awaited, asyncio.Future):
+                    # Future is cancellable via .cancel() without wrapping.
+                    usage.task = awaited
+                    result = await awaited
+                elif inspect.isawaitable(awaited):
+                    # Plain awaitable with no cancel handle. Cancellation of younger
+                    # usages on this resource is best-effort -- this usage runs to
+                    # natural completion if a sibling fails.
+                    result = await awaited
+                else:
+                    raise TypeError(
+                        f"operation must return an Awaitable, got {type(awaited).__name__}"
+                    )
+
+                await self._on_ok(usage)
+                return result
+
+            except CooldownResource as e:
+                await self._on_cooldown(usage, cooldown_seconds=e.cooldown_seconds)
+                last_error = e
+                if attempt_num < effective_attempts - 1:
+                    await asyncio.sleep(retry_delay)
+                continue
+
+            except DisableResource as e:
+                await self._on_disable(usage)
+                last_error = e
+                if attempt_num < effective_attempts - 1:
+                    await asyncio.sleep(retry_delay)
+                continue
+
+            except asyncio.CancelledError:
+                # Distinguish "outer caller cancelled us" (re-raise so shutdown is
+                # honored) from "we cancelled our own handle via _on_cooldown /
+                # _on_disable" (swallow and retry). _collect_younger_usages_locked sets
+                # usage.status = "cancelled" under the lock *before* invoking .cancel()
+                # on the handle, so seeing "cancelled" here means a sibling on the same
+                # resource cancelled us. Works on any Python 3.10+ (no
+                # asyncio.Task.cancelling() dependency). Cleanup runs in finally.
+                cancelled_internally = usage.status == "cancelled"
+                usage.status = "cancelled"
+                if not cancelled_internally:
+                    raise
+                last_error = asyncio.CancelledError()
+                if attempt_num < effective_attempts - 1:
+                    await asyncio.sleep(retry_delay)
+                continue
+
+            except Exception:
+                # Ordinary user/business exception: the resource is fine.
+                # Mark OK and propagate the exception unchanged to the caller.
+                await self._on_ok(usage)
+                raise
+
+            finally:
+                await self._cleanup_usage(usage)
+
+        # Loop only exits without returning when an attempt failed and set last_error;
+        # a clean exit (no failure) returns from inside the loop.
+        raise PoolExhausted(
+            f"max_attempts={effective_attempts} exhausted: {last_error!r}"
+        )
+
+    def rotated(
+        self,
+        *,
+        max_attempts: int | None = None,
+        deadline: float | None = None,
+        retry_delay: float = 0.5,
+        request_id: str | None = None,
+    ) -> Callable[[Callable[..., Awaitable[R]]], Callable[..., Awaitable[R]]]:
+        """Decorator factory: wrap a callable so every call goes through ``self.run()``
+        with resource rotation and retry.
+
+        The decorated function receives a ``Resource[T]`` as its first positional
+        argument (injected by the wrapper), followed by whatever the caller passes.
+
+        Any callable returning an Awaitable is accepted -- typically `async def`
+        functions, but plain functions returning a coroutine, an `asyncio.Future`, or
+        any awaitable also work. Cancellation of younger sibling usages is best-effort:
+        it works for coroutines and Futures, and silently no-ops for plain awaitables.
+        A callable that returns a non-awaitable raises `TypeError` at call time.
+        """
+
+        def decorator(func: Callable[..., Awaitable[R]]) -> Callable[..., Awaitable[R]]:
+            @functools.wraps(func)
+            async def wrapper(*args: Any, **kwargs: Any) -> R:
+                return await self.run(
+                    lambda resource: func(resource, *args, **kwargs),
+                    max_attempts=max_attempts,
+                    deadline=deadline,
+                    retry_delay=retry_delay,
+                    request_id=request_id,
+                )
+
+            return wrapper
+
+        return decorator
+
+    def snapshot(self) -> dict[str, dict[str, Any]]:
+        """Return a point-in-time summary of every resource in the pool.
+
+        Thread-safe without the lock -- reads simple types (str, int, float) and
+        Python-int counters that change atomically under the GIL. Good enough for
+        metrics / /status.
+        """
+        now = time.monotonic()
+        result: dict[str, dict[str, Any]] = {}
+        for rid, r in self._resources.items():
+            inflight = len(self._inflight_by_resource.get(rid, set()))
+            cooldown_remaining = (
+                max(r.cooldown_until - now, 0.0) if r.status == "cooling_down" else 0.0
+            )
+            result[rid] = {
+                "status": r.status,
+                "in_flight": inflight,
+                "consecutive_cooldown": r.consecutive_cooldown,
+                "cooldown_seconds_remaining": cooldown_remaining,
+                "last_acquired_at": r.last_acquired_at,
+            }
+        return result
+
+    @staticmethod
+    def _build_resources(
+        resources: list[Resource[T]] | dict[str, Resource[T]],
+    ) -> dict[str, Resource[T]]:
+        if isinstance(resources, list):
+            result: dict[str, Resource[T]] = {}
+            for r in resources:
+                if r.resource_id in result:
+                    raise ValueError(
+                        f"Duplicate resource_id in pool: {r.resource_id!r}"
+                    )
+                result[r.resource_id] = r
+            return result
+        return dict(resources)
+
+    async def _acquire(self, request_id: str) -> tuple[Resource[T], Usage] | None:
+        """Atomically select an eligible resource and register a usage on it.
+
+        Returns (resource, usage) on success or None if no resource is eligible (all
+        disabled, all cooling down, or all at `max_in_flight` capacity). Selection and
+        registration share one lock acquisition to keep the derived in-flight count
+        consistent.
+        """
+        now = time.monotonic()
+
+        async with self._lock:
+            candidates: list[Resource[T]] = []
+
+            for r in self._resources.values():
+                if r.status == "disabled":
+                    continue
+
+                if r.status == "cooling_down":
+                    if r.cooldown_until <= now:
+                        r.status = "healthy"
+                    else:
+                        continue
+
+                current = len(self._inflight_by_resource.get(r.resource_id, set()))
+                if r.max_in_flight is not None and current >= r.max_in_flight:
+                    continue
+
+                candidates.append(r)
+
+            if not candidates:
+                return None
+
+            candidates.sort(
+                key=lambda r: (
+                    len(self._inflight_by_resource.get(r.resource_id, set())),
+                    r.last_acquired_at,
+                )
+            )
+            selected = candidates[0]
+            selected.last_acquired_at = now
+            usage = Usage(
+                usage_id=str(uuid.uuid4()),
+                request_id=request_id,
+                resource_id=selected.resource_id,
+                acquired_at=now,
+            )
+            self._usages[usage.usage_id] = usage
+            self._inflight_by_resource.setdefault(selected.resource_id, set()).add(
+                usage.usage_id
+            )
+            return selected, usage
+
+    async def _on_ok(self, usage: Usage) -> None:
+        """Resource is operational. Reset cooldown state.
+
+        Called whenever the user operation returns normally OR raises a non-resource
+        exception -- anything that proves the resource itself works, regardless of
+        business outcome.
+
+        Only resets cooldown state when the resource is currently healthy. If a
+        concurrent failure has since moved it to cooling_down or disabled, that more
+        recent signal wins -- e.g. an older usage that started before a 429 succeeds
+        after a younger sibling triggered the cooldown; its success does not prove
+        the rate limit lifted, so we leave the cooldown in place.
+        """
+        async with self._lock:
+            usage.status = "done"
+            resource = self._resources.get(usage.resource_id)
+            if resource is not None and resource.status == "healthy":
+                resource.cooldown_until = 0.0
+                resource.consecutive_cooldown = 0
+
+    async def _on_cooldown(
+        self, usage: Usage, cooldown_seconds: float | None = None
+    ) -> None:
+        """Resource is temporarily over capacity. Mark cooling_down and cancel younger
+        usages on the same resource so they can retry elsewhere.
+
+        cooldown_seconds: explicit duration (e.g. from a Retry-After header). If None,
+            falls back to this pool's cooldown_table.
+        """
+        now = time.monotonic()
+        to_cancel: list[Usage] = []
+
+        async with self._lock:
+            usage.status = "done"
+            resource = self._resources.get(usage.resource_id)
+            if resource is None or resource.status == "disabled":
+                return
+
+            resource.consecutive_cooldown += 1
+
+            if cooldown_seconds is not None:
+                cd = cooldown_seconds
+            else:
+                idx = max(resource.consecutive_cooldown - 1, 0)
+                idx = min(idx, len(self._cooldown_table) - 1)
+                cd = self._cooldown_table[idx]
+
+            resource.status = "cooling_down"
+            resource.cooldown_until = max(resource.cooldown_until, now + cd)
+
+            to_cancel = self._collect_younger_usages_locked(usage)
+
+        self._cancel_tasks(to_cancel)
+
+    async def _on_disable(self, usage: Usage) -> None:
+        """Resource is permanently bad. Mark disabled and cancel younger usages on the
+        same resource so they can retry elsewhere.
+
+        The triggering usage itself is excluded from cancellation -- its own cleanup is
+        handled by `run()`'s finally block.
+        """
+        to_cancel: list[Usage] = []
+
+        async with self._lock:
+            usage.status = "done"
+            resource = self._resources.get(usage.resource_id)
+            if resource is not None:
+                resource.status = "disabled"
+
+            to_cancel = self._collect_younger_usages_locked(usage)
+
+        self._cancel_tasks(to_cancel)
+
+    async def _cleanup_usage(self, usage: Usage) -> None:
+        """Remove a usage from tracking. Implicitly decrements the derived in-flight
+        count for the resource. Idempotent."""
+        async with self._lock:
+            ids = self._inflight_by_resource.get(usage.resource_id)
+            if ids is not None:
+                ids.discard(usage.usage_id)
+                if not ids:
+                    self._inflight_by_resource.pop(usage.resource_id, None)
+
+            self._usages.pop(usage.usage_id, None)
+
+    def _collect_younger_usages_locked(self, failed_usage: Usage) -> list[Usage]:
+        """Mark and return usages on the same resource with acquired_at > failed.
+
+        MUST be called with `self._lock` held. Older usages are NOT touched -- they may
+        still succeed (e.g. an upstream request that the remote side already accepted).
+        The failed usage itself is also excluded.
+        """
+        to_cancel: list[Usage] = []
+        ids = self._inflight_by_resource.get(failed_usage.resource_id, set())
+        for usage_id in ids:
+            other = self._usages.get(usage_id)
+            if other is None:
+                continue
+            if (
+                other.status == "in_flight"
+                and other.acquired_at > failed_usage.acquired_at
+                and other.usage_id != failed_usage.usage_id
+            ):
+                other.status = "cancelled"
+                to_cancel.append(other)
+        return to_cancel
+
+    @staticmethod
+    def _cancel_tasks(usages: list[Usage]) -> None:
+        # Cancel outside the lock -- task.cancel() can trigger callbacks that try to
+        # reacquire it.
+        for u in usages:
+            if u.task is not None:
+                u.task.cancel()

rotapool-0.1.0.dist-info/METADATA

@@ -0,0 +1,396 @@
+Metadata-Version: 2.4
+Name: rotapool
+Version: 0.1.0
+Summary: Generic async resource pool with rotation, cooldown, and retry
+Project-URL: Source, https://github.com/zydo/rotapool
+Project-URL: Issues, https://github.com/zydo/rotapool/issues
+Author: zydo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,pool,rate-limit,resource-management,retry,rotation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# rotapool
+
+Async resource pool with inline health feedback, automatic cooldown, and retry — for API keys, proxies, GPU workers, or anything that can rate-limit you or go down.
+
+## Core idea
+
+Most resource pools are passive — they hand out resources round-robin or at random, and rely on external health checks to detect and remove bad ones. `rotapool` closes that gap: every call through the pool is also a health probe. The pool learns from caller signals in real time and immediately adjusts which resources to offer — no external probers or manual updates needed.
+
+Not every failure means the resource is bad — an HTTP 400 is your bug, but a 429 is the key's problem. You tell `rotapool` which is which by raising exceptions from inside your operation, and the pool reacts accordingly:
+
+| Signal                              | Meaning                                 |
+| ----------------------------------- | --------------------------------------- |
+| normal return / any other exception | Resource is healthy                     |
+| `CooldownResource`                  | Temporarily overloaded (e.g. 429)       |
+| `DisableResource`                   | Permanently unusable (e.g. revoked key) |
+
+`rotapool` handles the rest — picks the best resource, cools down bad ones, cancels doomed in-flight work, and retries automatically.
+
+## Install
+
+```bash
+pip install rotapool
+# or
+uv add rotapool
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+### Initialize the pool
+
+```python
+from rotapool import CooldownResource, DisableResource, Pool, Resource
+
+# Define your resources (e.g. API keys)
+pool = Pool(
+    # A list or dict of Resource objects. Dict keys are used as resource IDs.
+    resources=[
+        Resource(
+            resource_id="key-1",                 # Unique identifier (used in logs, metrics, snapshot)
+            value="sk-aaa",                      # The actual resource value (generic type T)
+            # max_in_flight=None,                # Max concurrent usages per resource (None = unlimited)
+        ),
+        Resource(resource_id="key-2", value="sk-bbb"),
+        Resource(resource_id="key-3", value="sk-ccc"),
+    ],
+    max_attempts=3,                              # Total retry budget per run() call (capped at len(resources))
+    cooldown_table=(30.0, 120.0, 300.0, 600.0),  # Escalation: 1st=30s, 2nd=120s, 3rd=300s, 4th+=600s
+)
+```
+
+### Option 1: Use the decorator
+
+```python
+# Resource rotation happens automatically.
+# All parameters are optional and forward to pool.run() on every call.
+@pool.rotated(
+    max_attempts=None,       # Override the pool's max_attempts for this decorated function
+    deadline=None,           # Absolute time.monotonic() deadline; None = no deadline
+    retry_delay=0.5,         # Seconds to pause between failed attempts
+    request_id=None,         # Opaque string attached to every Usage (e.g. HTTP request-id); auto-UUID if None
+)
+async def call_upstream(resource, url, payload):
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            url,
+            headers={"Authorization": f"Bearer {resource.value}"},
+            json=payload,
+        )
+
+    if resp.status_code == 429:
+        raise CooldownResource(
+            cooldown_seconds=parse_retry_after(resp.headers.get("retry-after")),
+            reason="rate limited",
+        )
+
+    if resp.status_code == 401:
+        raise DisableResource(reason="invalid key")
+
+    return resp.json()
+
+# Call it — the framework picks the best key and retries on failure
+result = await call_upstream("https://api.example.com/v1/chat", {"prompt": "hi"})
+```
+
+### Option 2: Direct `run()`
+
+`@pool.rotated()` is a thin shim over `pool.run()`. Use `run()` directly when you want per-call overrides or when the call site can't be decorated:
+
+```python
+async def call_upstream(resource, url, payload):
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            url,
+            headers={"Authorization": f"Bearer {resource.value}"},
+            json=payload,
+        )
+
+    if resp.status_code == 429:
+        raise CooldownResource(reason="rate limited")
+    if resp.status_code == 401:
+        raise DisableResource(reason="invalid key")
+
+    return resp.json()
+
+# Operation receives the selected Resource as its first argument.
+result = await pool.run(
+    lambda resource: call_upstream(resource, "https://api.example.com/v1/chat", {"prompt": "hi"}),
+    max_attempts=None,               # Override the pool's max_attempts for this call only
+    deadline=time.monotonic() + 30,  # Absolute time.monotonic() deadline bounding total retry time
+    retry_delay=0.5,                 # Seconds to pause between failed attempts
+    request_id="req-abc",            # Opaque string attached to every Usage; auto-UUID when None
+)
+```
+
+## How it works
+
+### Selection
+
+When multiple resources are healthy, the pool picks the one with:
+
+1. **Fewest in-flight usages** (load spreading)
+2. **Oldest `last_acquired_at`** (round-robin fairness)
+
+Selection and usage registration are atomic under one lock acquisition.
+
+### Cooldown escalation
+
+Each consecutive `CooldownResource` from the same resource escalates the cooldown:
+
+| Consecutive count | Cooldown |
+| ----------------- | -------- |
+| 1st               | 30s      |
+| 2nd               | 120s     |
+| 3rd               | 300s     |
+| 4th+              | 600s     |
+
+You can override per-event: `CooldownResource(cooldown_seconds=5)` (e.g. from a `Retry-After` header). The counter resets on the next success.
+
+Custom tables are supported per pool:
+
+```python
+pool = Pool(
+    resources=[...],
+    cooldown_table=(10.0, 30.0, 60.0, 120.0),
+)
+```
+
+### In-flight cancellation (best-effort)
+
+When a resource receives a `CooldownResource` or `DisableResource` signal, the framework cancels **younger** in-flight usages on the same resource. Older usages are left alone — they may still succeed. This maximises throughput while avoiding doomed requests.
+
+Cancellation is **best-effort**: it works when the operation returns a coroutine (the framework wraps it in an `asyncio.Task`) or an `asyncio.Future` (cancelled directly). For plain awaitables with no `.cancel()` handle, cancellation silently no-ops for that usage and it runs to natural completion. Within a coroutine, the underlying I/O is only truly aborted if the operation uses cancellation-aware async libs (`httpx.AsyncClient`, `aiohttp`).
+
+### Retry
+
+`pool.run()` drives the retry loop. `@pool.rotated()` is a thin decorator shim over it. Attempts are capped at `min(max_attempts, len(resources))` — more retries than resources is pointless.
+
+### Cancellation discrimination
+
+The framework distinguishes external cancellation (client disconnect, shutdown — re-raised) from internal cancellation (resource failure — swallowed and retried) by checking `usage.status`. The cooldown/disable handler sets the status to `"cancelled"` under the pool lock *before* invoking `.cancel()` on the handle, so observing that status when `CancelledError` arrives reliably means "we cancelled ourselves." Works on any Python 3.10+.
+
+## API reference
+
+### `rotapool.Pool[T]`
+
+```python
+pool = Pool(
+    resources: list[Resource[T]] | dict[str, Resource[T]],
+    # resources:       A list of Resource objects, or a dict mapping resource_id -> Resource.
+    #                  Duplicate resource_ids in list form raise ValueError.
+
+    max_attempts: int = 3,
+    # max_attempts:    Total retry budget per run() call. Each attempt picks a fresh
+    #                  resource. Effectively capped at len(resources) — once every
+    #                  resource has been tried and none is eligible, run() raises
+    #                  PoolExhausted rather than retrying any one twice.
+
+    cooldown_table: tuple[float, ...] = (30.0, 120.0, 300.0, 600.0),
+    # cooldown_table:  Escalation table indexed by consecutive_cooldown count.
+    #                  1st cooldown → cooldown_table[0], 2nd → cooldown_table[1], etc.
+    #                  Out-of-range values clamp to the last entry.
+)
+```
+
+```python
+await pool.run(
+    operation: Callable[[Resource[T]], Awaitable[R]],
+    # operation:       Callable receiving the selected Resource and returning an
+    #                  Awaitable. Raise CooldownResource or DisableResource to
+    #                  signal resource health. Any other exception is treated as
+    #                  "resource is fine" and propagates to the caller.
+    #                  Accepted return types:
+    #                    - coroutine          (typical async def)        -- cancellable
+    #                    - asyncio.Future     (e.g. loop.create_future)  -- cancellable
+    #                    - any Awaitable      (custom __await__)         -- best-effort
+    #                  Returning a non-Awaitable raises TypeError at call time.
+
+    *,                 # All following parameters are keyword-only.
+
+    max_attempts: int | None = None,
+    # max_attempts:    Per-call override of the pool's max_attempts. None = use pool default.
+
+    deadline: float | None = None,
+    # deadline:        Absolute time.monotonic() value bounding total time across
+    #                  retries. Raises PoolExhausted if exceeded. None = no deadline.
+
+    retry_delay: float = 0.5,
+    # retry_delay:     Seconds to pause between failed attempts.
+
+    request_id: str | None = None,
+    # request_id:      Opaque string attached to every Usage created by this call.
+    #                  Auto-generated UUID when None.
+) -> R
+```
+
+```python
+@pool.rotated(
+    max_attempts: int | None = None,     # Per-call override; None = use pool default
+    deadline: float | None = None,       # Absolute time.monotonic() deadline
+    retry_delay: float = 0.5,            # Pause between failed attempts
+    request_id: str | None = None,       # Opaque string for Usage tracking
+)
+# Returns a decorator. The decorated function receives a Resource[T] as its
+# first positional argument (injected by the wrapper), followed by caller args.
+# Any callable returning an Awaitable is accepted (async def, sync function
+# returning a coroutine / Future / awaitable). A callable that returns a
+# non-Awaitable raises TypeError at call time.
+```
+
+```python
+pool.snapshot() -> dict[str, dict[str, Any]]
+# Returns a point-in-time summary of every resource. Thread-safe without the lock.
+# Example return value:
+# {
+#     "key-1": {
+#         "status": "healthy",                  # "healthy" | "cooling_down" | "disabled"
+#         "in_flight": 2,                       # Current in-flight usage count
+#         "consecutive_cooldown": 0,            # Escalation counter
+#         "cooldown_seconds_remaining": 0.0,    # Seconds until cooldown expires (0 if healthy)
+#         "last_acquired_at": 12345.67,         # time.monotonic() of last acquire
+#     },
+#     ...
+# }
+```
+
+### `rotapool.Resource[T]`
+
+```python
+resource = Resource(
+    resource_id: str,
+    # resource_id:          Unique identifier for this resource.
+
+    value: T,
+    # value:                The actual resource object (API key, proxy URL, etc.).
+
+    max_in_flight: int | None = None,
+    # max_in_flight:        Maximum concurrent usages. None = unlimited, 1 = exclusive.
+
+    status: str = "healthy",
+    # status:               Current health: "healthy", "cooling_down", or "disabled".
+    #                       Managed by the framework — do not set manually.
+
+    cooldown_until: float = 0.0,
+    # cooldown_until:       time.monotonic() deadline when status is "cooling_down".
+    #                       Managed by the framework — do not set manually.
+
+    last_acquired_at: float = 0.0,
+    # last_acquired_at:     time.monotonic() of most recent acquire. Affects selection
+    #                       order (oldest first). Managed by the framework.
+
+    consecutive_cooldown: int = 0,
+    # consecutive_cooldown: Number of consecutive CooldownResource signals. Indexes into
+    #                       the pool's cooldown_table. Resets to 0 on next success.
+    #                       Managed by the framework — do not set manually.
+)
+```
+
+### Exceptions
+
+| Exception          | Who raises it  | Meaning                                                        |
+| ------------------ | -------------- | -------------------------------------------------------------- |
+| `CooldownResource` | Your operation | Resource temporarily over capacity                             |
+| `DisableResource`  | Your operation | Resource permanently bad                                       |
+| `PoolExhausted`    | Framework      | No eligible resource, max attempts reached, or deadline passed |
+
+```python
+raise CooldownResource(
+    cooldown_seconds: float | None = None,
+    # Explicit cooldown duration (e.g. from Retry-After header).
+    # None = use the pool's cooldown_table based on consecutive_cooldown count.
+
+    reason: str | None = None,
+    # Free-form string surfaced in the exception message and logs.
+)
+```
+
+```python
+raise DisableResource(
+    reason: str | None = None,
+    # Free-form string surfaced in the exception message and logs.
+)
+```
+
+## Resource types
+
+`rotapool` is generic — `T` can be anything:
+
+```python
+# API keys (string bearer tokens)
+Resource(resource_id="key-1", value="sk-...")
+
+# HTTP proxies
+Resource(resource_id="proxy-1", value="http://proxy:8080", max_in_flight=10)
+
+# Browser sessions (exclusive)
+Resource(resource_id="session-1", value=<webdriver>, max_in_flight=1)
+
+# GPU workers
+Resource(resource_id="gpu-0", value="cuda:0", max_in_flight=1)
+```
+
+## Operation shapes
+
+`pool.run` and `@pool.rotated` accept any callable that returns an `Awaitable`. The framework picks the cancellation strategy at runtime based on what the callable returns:
+
+```python
+# 1. async def -- the typical case. Cancellation is full-strength: the
+#    framework wraps the coroutine in a Task and cancels younger siblings
+#    via task.cancel() on resource failure.
+@pool.rotated()
+async def call_async(resource, payload):
+    async with httpx.AsyncClient() as client:
+        return await client.post(url, json=payload,
+                                 headers={"Authorization": f"Bearer {resource.value}"})
+
+# 2. Sync function returning a coroutine -- previously rejected, now accepted.
+#    Useful when you want to construct the coroutine yourself or thread args.
+@pool.rotated()
+def call_returning_coro(resource, payload):
+    return some_async_helper(resource.value, payload)  # returns a coroutine
+
+# 3. Sync function returning an asyncio.Future -- accepted and cancellable
+#    via Future.cancel(). Useful for executor wrappers.
+@pool.rotated()
+def call_in_thread(resource, payload):
+    loop = asyncio.get_running_loop()
+    return loop.run_in_executor(None, blocking_request, resource.value, payload)
+
+# 4. Anything returning a plain Awaitable (custom __await__) is also accepted,
+#    but with no cancel handle: younger sibling cancellation silently no-ops
+#    for this usage and it runs to natural completion (best-effort).
+```
+
+A callable that returns a non-Awaitable (e.g. a plain `int`) raises `TypeError` at call time. The resource is marked healthy (your bug, not the resource's) and the error propagates to the caller.
+
+## Testing
+
+```bash
+# pip
+pip install -e ".[dev]"
+pytest
+
+# uv
+uv sync --all-extras
+uv run pytest
+```
+
+## License
+
+MIT

rotapool-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+rotapool/__init__.py,sha256=M3pN_KErkZCMcIIU9n0UdRqpFPrTjSMXt85ewKNh4JY,342
+rotapool/exceptions.py,sha256=M3pbGXVJ-vtSKLW-SVO9C8kOYcfPL0L6xDLcodhXENg,1196
+rotapool/models.py,sha256=Lx0ZL9SOjylHSuGlv0SOSsVrpdOB66foNkuBQrzMNc8,1603
+rotapool/pool.py,sha256=BrVkzetGF_0Ulz3w6zXRZE0J-pIgW_52CThbk5f4j8A,17723
+rotapool-0.1.0.dist-info/METADATA,sha256=k3cWRUEh-Ew3otirmLMbuGICxjiP4xZcXByBTo2HFW0,16294
+rotapool-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+rotapool-0.1.0.dist-info/licenses/LICENSE,sha256=TiqPFK8iuihgxQgdBdJ62hhfUl3LGcO61V0FBnZOTvw,1061
+rotapool-0.1.0.dist-info/RECORD,,

rotapool-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

rotapool-0.1.0.dist-info/licenses/LICENSE

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