hallazzang/asyncio-throttle

Simple, easy-to-use throttler for asyncio.

asyncio-throttle

Simple, easy-to-use throttler for asyncio.

Example

import time
import random
import asyncio

from asyncio_throttle import Throttler

async def worker(no, throttler, n):
    for _ in range(n):
        await asyncio.sleep(random.random() * 2)

        async with throttler:
            print(time.time(), 'Worker #%d: Bang!' % no)

async def main():
    throttler = Throttler(rate_limit=5)

    tasks = [
        loop.create_task(worker(no, throttler, 10))
            for no in range(5)
    ]
    await asyncio.wait(tasks)

loop = asyncio.get_event_loop()
loop.run_until_complete(main())
loop.close()

Here I limited work rate to 5/sec while there are 5 workers. And the result:

1508273760.3462772 Worker #2: Bang!
1508273760.590009 Worker #3: Bang!
1508273760.856431 Worker #0: Bang!
1508273761.0110679 Worker #2: Bang!
1508273761.086856 Worker #4: Bang!
1508273761.350699 Worker #3: Bang!
1508273761.5906 Worker #1: Bang!
1508273761.8655958 Worker #4: Bang!
1508273762.224158 Worker #0: Bang!
1508273762.600234 Worker #2: Bang!
1508273762.694332 Worker #2: Bang!
1508273762.726774 Worker #0: Bang!
1508273762.944273 Worker #4: Bang!

Installation

$ pip install asyncio-throttle

It requires Python 3.6 or later.

Usage

asyncio_throttle.Throttler introduces simple APIs: flush() and acquire(). But you will not be interested in those because you can just use it within with statement and it looks nicer.

First, create a throttler given desired rate limit. For example if you want to limit rate to 500/min, you can make it as:

from asyncio_throttle import Throttler

throttler = Throttler(rate_limit=500, period=60)

Then whenever you want to do some jobs which should have limited rate(e.g. sending request to server), Put it in async with statement:

async with throttler:
    send_a_request()

It's that easy. asyncio_throttler can be easily integrated with aiohttp too:

async def worker(throttler, session):
    while True:
        async with throttler:
            async with session.get('http://example.com') as resp:
                do_some_job_with(await resp.text())

        await asyncio.sleep(0.05)

asyncio-throttle's Issues

Suggestion: add an example for REST polling use case

It may be helpful to add an example of using this package for REST polling (e.g., continuously fetching data from a REST API), because specifying a relatively long period (e.g., 60 seconds) can cause an unnecessary spike in the number of requests at the beginning of every period. Additionally, users of this package may likely be interested in this specific use case.

For instance, if I set throttler = Throttler(rate_limit=500, period=60), 500 requests would be made at the very beginning of the 60 seconds period, and then nothing would happen until the next 60 seconds mark. This resulted in a lot of 429 (too many requests) response codes. To get around this, I had to specify rate_limit as 1 and period as 60/500. Of course, the possibility of getting 429 responses also depend on the tolerance of the API server in question.

That said, I believe the above issue is worth considering, unless I am doing something wrong or do not know what I was doing. Anyways, thanks for maintaining this package!