Metadata-Version: 2.1
Name: async-throttle
Version: 0.1.0
Summary: Multipurpose asyncio throttle
License: MIT
Author: Joe Nudell
Author-email: jnu@stanford.edu
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Description-Content-Type: text/markdown

Async Throttle
===

Multipurpose concurrency primitive for `asyncio` coroutines.

## Features

This throttle is configured with two related, but different parameters:

```py
Throttle(rate: float, concurrency: int)
```

`rate` - The **rate limit** (in operations-per-second) for tasks.

`concurrency` - The number of jobs that can be executing at a given time.

Usually, servers will set policies on both of these dimensions, and will suspend clients that violate either of them.

### `Throttle#pause(td: int)`

The `pause` method will lock the throttle for the given number of seconds.

For example, if an API bans your client from accessing resources due to violating their rate-limit, you can tell your code to sleep for a period of time and try again later.

## Usage

The throttle can be a drop-in replacement for another primitive like `asyncio.Semaphore`.
In fact, it's really just an `asyncio.Semaphore` (which handles the `concurrency` limit) mixed with a token bucket to provide rate limiting.

```py
throttle = Throttle(10, 2)  # Two concurrent coros limited to 10qps (total).

async with throttle:
    # Do some (async) thing
```

Like other `asyncio` primitives, `Throttle` is not thread-safe.

