Migrating from 0.x¶
1.0 is a breaking release. It needs Python 3.11 or newer, renames the public names, and replaces two settings with one. The library's behaviour changed in places where 0.x was wrong; those changes are listed under Behaviour.
Names¶
| 0.x | 1.0 |
|---|---|
from ratelimit_io.rate_limit import ... |
from ratelimit_io import ... |
RatelimitIO(backend, ...) |
RateLimiter(client, ...) |
LimitSpec(5, seconds=1) |
Limit(5, seconds=1) |
RatelimitIOError |
RateLimitError |
RatelimitExceededError |
RateLimitExceededError |
ScriptLoadError |
removed: the limiter reloads its script itself, and Redis errors propagate unchanged |
limiter.wait(key, spec) |
limiter.acquire_sync(key, limit=spec) |
await limiter.a_wait(key, spec) |
await limiter.acquire(key, limit=spec) |
async with limiter: |
removed: there is nothing to set up or tear down |
Settings¶
| 0.x | 1.0 |
|---|---|
default_limit= |
limit= |
default_key= |
key= |
is_incoming=True |
max_wait=0, the default |
is_incoming=False |
max_wait=10, or any other budget in seconds |
wait(..., max_wait_time=) |
acquire_sync(..., max_wait=) |
backoff_start=, backoff_max= |
removed: a waiting request reserves its slot and sleeps until it |
decorator unique_key='x' |
decorator key='x' |
kwargs['ip'] picked up as the key |
key=Key('{ip}') |
Behaviour¶
- Refusals carry
retry_after.RateLimitExceededErrorhas thelimitthat refused the request andretry_afterin seconds. The HTTP-flavouredstatus_codeanddetailattributes are gone; answer with429yourself. - The decorator raises
RateLimitExceededError. 0.x turned an exhausted wait inside@limiter(...)into a bareRuntimeError. - A waiting request reserves its slot. 0.x polled Redis until a slot freed up; 1.0 reserves the next free slot in one round trip and sleeps until it, serving waiters in arrival order. A wait cancelled during its sleep still uses its slot.
- Functions get their own bucket by qualified name. 0.x used
__name__, so two methods calledgeton different classes shared one limit. 0.x also gave sync and async functions separate buckets for the same key. - The limiter's
keyis shared by the functions it decorates. In 0.x adefault_keywas still split per function. ipis no longer magic. 0.x readkwargs['ip']and silently fell back to one shared"unknown_key"bucket whenipwas passed positionally. Name the key explicitly.- No silent fallback key.
acquire()without a key on a limiter without one raisesValueError. 0.x counted such calls in"unknown_key". - Redis errors propagate. 0.x turned every Redis failure, a refused
connection included, into
ScriptLoadError. - Validation is strict.
Limitrefuses negative, infinite and fractional request counts and periods under a millisecond. Keys must be non-empty strings,max_waita number of seconds. A mismatch between the client and the call style (acquire()on a sync client, a coroutine function decorated on a sync client) raisesTypeErrorwith the fix in the message. - Import from
ratelimit_ioonly. The modules inside the package are private and may move between releases.
Buckets start empty¶
The bucket names changed: they now carry the algorithm and the limit, so layered limits on one key no longer collide. Counters from 0.x are not read after the upgrade and expire on their own within one period.