# TokenBucket

A synchronous, in-memory token-bucket rate limiter. Use it to control how often work starts, while allowing short bursts.

A bucket starts full. Each successful request consumes tokens; tokens replenish at `rate` tokens per second, up to `capacity`. Refill is calculated when an acquisition is attempted—there is no background thread or timer.

For example, `TokenBucket(rate=5, capacity=10)` allows an initial burst costing up to 10 tokens, then replenishes at 5 tokens per second. With valid inputs and an advancing clock, total successful consumption over an interval is bounded by the tokens available at its start plus the tokens replenished during it. This is not a strict “at most 5 requests in every one-second window” limit.

## Quick start

The examples assume you saved the supplied module as `token_bucket.py`:

```python
from token_bucket import TokenBucket

bucket = TokenBucket(rate=5, capacity=10)

if bucket.try_acquire():
    print("Proceed now")
else:
    print("No token available; skip or retry later")

# Block until one token is available.
bucket.acquire()
print("Proceed after waiting, if necessary")
```

The implementation uses only the Python standard library.

## API reference

### `TokenBucket(rate, capacity=None, clock=time.monotonic)`

Create a bucket with its initial token balance equal to its capacity.

| Parameter | Meaning |
| --- | --- |
| `rate` | Refill rate in tokens per second. Intended to be a positive, finite number; stored as a `float`. |
| `capacity` | Maximum stored tokens and initial balance. Defaults to `rate` when `None`; stored as a `float`. Use a positive, finite value. |
| `clock` | A callable returning time in seconds, used for refill and timeout calculations. Defaults to `time.monotonic`. Use a nondecreasing clock. It is called during construction. |

**Raises:** `ValueError("rate must be positive")` if the supplied `rate <= 0` check succeeds. Unsupported input types can raise `TypeError` or conversion errors. Exceptions from `clock` propagate.

**Validation limits:** `capacity` is not validated for positivity or finiteness, and the rate check does not reject all non-finite values. Treat positive, finite numeric values as caller requirements, not guarantees enforced by the constructor.

`rate` and `capacity` are public attributes. Treat them as read-only after construction: direct mutation is not synchronized or validated. Attributes beginning with `_`, including `_refill()`, are implementation details.

### `try_acquire(n=1) -> bool`

Attempt to consume `n` tokens without waiting for more tokens.

- Refills the bucket, then atomically checks and deducts the requested amount.
- Returns `True` if enough tokens are available.
- Returns `False` otherwise, without deducting tokens. Refill still updates the bucket's accounting.
- Raises `ValueError("request exceeds capacity")` if `n > capacity`.

`n` may be fractional. Use a positive, finite number no greater than the capacity.

“Without waiting” means it does not sleep for tokens; it can briefly wait to acquire the internal thread lock.

### `acquire(n=1, timeout=None) -> bool`

Attempt to consume `n` tokens, sleeping and retrying when necessary.

| Parameter | Meaning |
| --- | --- |
| `n` | Tokens to consume; defaults to `1`. Use a positive, finite number no greater than the capacity. |
| `timeout` | Optional time budget in seconds, measured with `clock`. `None` disables the deadline check. For intended use, provide a finite, nonnegative number. |

Returns `True` when tokens have been deducted, or `False` when its deadline check rejects the next calculated wait. No tokens are deducted on a `False` return.

When tokens are insufficient, it calculates:

```python
wait = (n - current_tokens) / rate
```

It releases the lock before sleeping with `time.sleep(wait)`, then retries. Other threads may consume tokens during the sleep, requiring further retries.

**Timeout semantics are limited:**

- The deadline is calculated once when the method is called.
- If the next calculated wait would extend beyond the deadline, the method returns `False` immediately. It does not wait out the remaining budget.
- It checks token availability before checking the deadline. Available tokens can therefore be acquired even with a zero or negative timeout, or after the deadline has passed.
- The timeout is not a strict upper bound on elapsed call time: lock contention, scheduling, and sleep overshoot can extend the call beyond it.
- Unlike `try_acquire`, this method does **not** reject `n > capacity`. Such a request cannot succeed under normal operation; with `timeout=None` it can wait forever. Validate `n` yourself.

## Examples

### Skip work when the bucket is empty

```python
bucket = TokenBucket(rate=2, capacity=4)

for job in jobs:  # An iterable supplied by your application.
    if bucket.try_acquire():
        process(job)  # Your application's processing function.
    else:
        print("Rate limit reached; skipping", job)
```

### Wait with a time budget

```python
bucket = TokenBucket(rate=2, capacity=2)
bucket.acquire(2)  # Consumes the initial balance immediately.

# One token needs roughly 0.5 seconds to replenish.
# This normally returns False immediately, rather than sleeping for 0.1 s.
if not bucket.acquire(timeout=0.1):
    print("The calculated wait exceeds the time budget")

if bucket.acquire(timeout=1.0):
    print("Token acquired")
```

The timeout is a check on the next estimated wait, not a hard execution deadline.

### Assign different costs to operations

```python
bucket = TokenBucket(rate=10, capacity=20)

if bucket.try_acquire(n=5):
    print("Run an operation costing five tokens")

if bucket.try_acquire(n=0.5):
    print("Run a lightweight operation")
```

The default capacity equals the rate. For a rate below one token per second, explicitly set a capacity of at least one if you want to acquire whole tokens:

```python
bucket = TokenBucket(rate=0.5, capacity=1)  # One token every two seconds.
bucket.acquire()  # Initial token is available immediately.
```

### Test refill without sleeping

```python
class ManualClock:
    def __init__(self):
        self.now = 0.0

    def __call__(self):
        return self.now

clock = ManualClock()
bucket = TokenBucket(rate=2, capacity=3, clock=clock)

assert bucket.try_acquire(3)
assert not bucket.try_acquire()

clock.now += 0.5
assert bucket.try_acquire()  # Half a second replenished one token.
```

A custom clock changes accounting, not the sleep mechanism: `acquire()` still uses real `time.sleep()`. A frozen manual clock can make a blocking acquisition repeat indefinitely. Use `try_acquire()` for deterministic manual-clock tests, or arrange a coordinated clock/sleep test setup.

## Caveats and operational guidance

- **Validate inputs.** Neither acquisition method rejects zero, negative, or non-finite `n` values explicitly. Negative requests can increase the balance instead of consuming tokens. Invalid numeric values can cause nonsensical accounting, exceptions, or nontermination. Require positive, finite `rate`, `capacity`, and `n`, with `n <= capacity`.
- **Share one instance between threads.** Acquisition methods protect refill and token deduction with a lock. This does not make external attribute mutation safe, and it does not coordinate separate instances or processes. Sharing a bucket across processes is not supported by its `threading.Lock`.
- **No fairness guarantee.** Waiting threads are not queued. Another caller can take tokens first, and a caller can starve under contention.
- **Blocking, not asynchronous.** `acquire()` blocks its calling thread. Do not call it directly on an async event-loop thread; use a worker thread or an async-specific limiter. There is no built-in cancellation facility.
- **Limit starts, not concurrency.** Tokens are spent, not borrowed. Completion of work does not return them, and the bucket does not cap the number of operations running at once. Use a semaphore separately if needed. There is no token-refund API.
- **Use monotonic time.** Backward clock movement contributes zero refill for that update, but still replaces the stored timestamp; later clock recovery can therefore affect accounting. Wall-clock adjustments are a reason to keep the default clock.
- **Timing is approximate.** Floating-point arithmetic, scheduler delays, and contention affect wakeup times. This is not a real-time scheduler.
- **State is local and transient.** A new instance starts full. There is no persistence, cross-process coordination, or distributed rate-limit enforcement.
