throttles

Rate limiting primitives.

AwaitableMixin

class aiothrottles.throttles.AwaitableMixin

Awaitable object.

This enables the idiom:

await throttle

as an alternative to:

await throttle.acquire()

ContextManagerMixin

class aiothrottles.throttles.ContextManagerMixin

Context manager.

This enables the following idiom for acquiring and releasing a throttle around a block:

async with throttle:
    <block>

DecoratorMixin

class aiothrottles.throttles.DecoratorMixin

Coroutine decorator.

This enables decorating of a coroutine that always need acquiring and releasing a throttle:

@throttle('3/s')
async def coroutine():
    <block>

RateMixin

class aiothrottles.throttles.RateMixin(rate: str)

Encapsulation of a rate limiting.

This enables setting the limiting rate in the following formats:

  • "{integer limit}/{unit time}"
  • "{limit's numerator}/{limit's denominator}{unit time}"

Examples of usage:

  • "1/s", "2/m", "3/h", "4/d"
  • "5/second", "6/minute", "7/hour", "8/day"
  • "1/3s", "12/37m", "1/5h", "8/3d"

Throttle

class aiothrottles.throttles.Throttle(rate, *, loop=None)

Primitive throttle objects.

A primitive throttle is a synchronization primitive that manages an internal counter and has a trace. A primitive throttle is in one of two states, ‘locked’ or ‘unlocked’. It is not owned by a particular coroutine when locked.

Each acquire() call:

  1. appends the coroutine to a FIFO queue
  2. blocks until the throttle is ‘locked’
  3. decrements the counter

Each release() call:

  1. appends current timestamp at the and of the trace
  2. increments the counter

Each locked() call:

  1. removes expired timestamps from the trace
  2. returns True if the length of the trace exceeds the limit or the counter is equal to zero

Usage:

throttle = Throttle()
...
await throttle
try:
    ...
finally:
    throttle.release()

Context manager usage:

throttle = Throttle()
...
async with throttle:
    ...

Throttle objects can be tested for locking state:

if not throttle.locked():
    await throttle
else:
    # throttle is acquired
    ...
Throttle.locked() → bool

Return True if throttle can not be acquired immediately.

Returns:
bool
Throttle.acquire() → None

Acquire a throttle.

Throttle.release() → None

Release a throttle.

Raises:
ValueError: when Throttle aleready released