Limits how often each key may be used.
Functions#
__init__#
__init__(store) -> None| Parameter | Type | Description |
|---|---|---|
store | RateLimiterStoreService |
def __init__(self, store: RateLimiterStoreService) -> None:
self._store = storeconsume#
consume(*, key, limit, window, algorithm='fixed-window', on_exceeded='fail', tokens=1) -> Effect[ConsumeResult, RateLimiterError]Charge tokens (default 1) to key, allowed limit per
window (at least a millisecond) by algorithm. Over the
limit, on_exceeded says whether to fail or to reserve and
report a delay. A "fail" request for more than limit fails
at once, with the whole window to wait. A limit of zero or less
admits no positive request: "fail" rejects it and "delay"
gives an infinite delay, without touching the store.
| Parameter | Type | Description |
|---|---|---|
key | str | |
limit | float | |
window | DurationInput | |
algorithm | Algorithm = 'fixed-window' | |
on_exceeded | OnExceeded = 'fail' | |
tokens | float = 1 |
Returns Effect[ConsumeResult, RateLimiterError]
def consume(
self,
*,
key: str,
limit: float,
window: DurationInput,
algorithm: Algorithm = "fixed-window",
on_exceeded: OnExceeded = "fail",
tokens: float = 1,
) -> Effect[ConsumeResult, RateLimiterError]:
"""Charge ``tokens`` (default 1) to ``key``, allowed ``limit`` per
``window`` (at least a millisecond) by ``algorithm``. Over the
limit, ``on_exceeded`` says whether to fail or to reserve and
report a delay. A ``"fail"`` request for more than ``limit`` fails
at once, with the whole window to wait. A ``limit`` of zero or less
admits no positive request: ``"fail"`` rejects it and ``"delay"``
gives an infinite delay, without touching the store."""
window_millis = max(to_millis(window), 1.0)
exceeded = tokens > limit
if on_exceeded == "fail" and exceeded:
return _exceeded(key, millis(window_millis), limit)
if limit <= 0:
# A limit that never refills: answered without the store.
wait = _FOREVER if exceeded else zero
return succeed(ConsumeResult(wait, limit, limit - tokens, wait))
refill = divide_millis(window_millis, limit)
if algorithm == "fixed-window":
return self._fixed_window(
key=key,
limit=limit,
tokens=tokens,
on_exceeded=on_exceeded,
window_millis=window_millis,
refill=refill,
)
return self._token_bucket(key, limit, tokens, on_exceeded, refill)adaptive_consume#
adaptive_consume(*, key, tokens, fallback_limit, fallback_window) -> Effect[AdaptiveConsumeResult, RateLimiterError]Ask to send tokens to a server that limits key by
429 responses: no delay until one comes, then wait out its
Retry-After, learn how much the server accepts and pace to it.
Report each response with adaptive_feedback and the epoch
given here.
| Parameter | Type | Description |
|---|---|---|
key | str | |
tokens | float | |
fallback_limit | float | |
fallback_window | DurationInput |
Returns Effect[AdaptiveConsumeResult, RateLimiterError]
def adaptive_consume(
self, *, key: str, tokens: float, fallback_limit: float, fallback_window: DurationInput
) -> Effect[AdaptiveConsumeResult, RateLimiterError]:
"""Ask to send ``tokens`` to a server that limits ``key`` by
``429`` responses: no delay until one comes, then wait out its
``Retry-After``, learn how much the server accepts and pace to it.
Report each response with ``adaptive_feedback`` and the ``epoch``
given here."""
return self._store.adaptive_consume(
key=key,
tokens=tokens,
fallback_limit=fallback_limit,
fallback_window=from_input_unsafe(fallback_window),
)adaptive_feedback#
adaptive_feedback(*, key, epoch, tokens, status, retry_after) -> Effect[None, RateLimiterError]Report the response to an adaptive_consume: only a 429
with a retry_after changes anything, and only for the epoch it
was sent in.
| Parameter | Type | Description |
|---|---|---|
key | str | |
epoch | int | |
tokens | float | |
status | int | |
retry_after | DurationInput | None |
Returns Effect[None, RateLimiterError]
def adaptive_feedback(
self,
*,
key: str,
epoch: int,
tokens: float,
status: int,
retry_after: DurationInput | None,
) -> Effect[None, RateLimiterError]:
"""Report the response to an ``adaptive_consume``: only a ``429``
with a ``retry_after`` changes anything, and only for the epoch it
was sent in."""
return self._store.adaptive_feedback(
key=key,
epoch=epoch,
tokens=tokens,
status=status,
retry_after=None if retry_after is None else from_input_unsafe(retry_after),
)