pyrate_limiter.buckets.state_bucket module¶

Bucket and local stores for constant-state algorithms.

class pyrate_limiter.buckets.state_bucket.InMemoryStateStore¶

Bases: StateStore

State in a local attribute, guarded by a reentrant lock.

check(algorithm, rates, now, weight)¶: Apply algorithm.step to the stored state, atomically.

is_async = False¶: None means “ask the Leaker to probe” (a client that may be either).

read(algorithm, rates)¶: Current state. For reporting only - never the basis of a decision.

reset()¶

Forget everything, as though the key had never been used.

Return type:: None

class pyrate_limiter.buckets.state_bucket.MultiprocessStateStore(values, lock)¶

Bases: StateStore

State in a Manager list, guarded by a cross-process lock.

check(algorithm, rates, now, weight)¶: Apply algorithm.step to the stored state, atomically.

classmethod init()¶

Return type:: MultiprocessStateStore

is_async = False¶: None means “ask the Leaker to probe” (a client that may be either).

read(algorithm, rates)¶: Current state. For reporting only - never the basis of a decision.

reset()¶

Forget everything, as though the key had never been used.

Return type:: None

class pyrate_limiter.buckets.state_bucket.StateBucket(rates, algorithm=None, store=None, clock=None)¶

Bases: AbstractBucket

Bucket for constant-state algorithms - GCRA, TokenBucket.

Keeps a few numbers per key rather than an entry per consumed unit, so storage does not grow with traffic and the wait is exact without a lookup.

The log contract does not apply: peek() has nothing to return and leak() nothing to trim. Use count() for how many units are currently owed.

algorithm¶

close()¶

Release any resources held by the bucket.

Subclasses may override this method to perform any necessary cleanup (e.g., closing files, network connections, or releasing locks) when the bucket is no longer needed.

Return type:: None

count()¶

Units currently owed to the bucket - an estimate, not a log length.

Return type:: int | Awaitable[int]

flush()¶

Flush the whole bucket - Must remove failing-rate after flushing

Return type:: None | Awaitable[None]

is_async = False¶

leak(current_timestamp=None)¶

No-op: state is constant-size, so there is nothing to trim.

Shared stores expire idle keys themselves (Redis via a TTL).

Return type:: int

peek(index)¶

Always None: this bucket keeps no per-item log to peek into.

Return type:: RateItem | None

put(item)¶

Put an item (typically the current time) in the bucket return true if successful, otherwise false

Return type:: bool | Awaitable[bool]

store¶

waiting(item)¶

Wait recorded by the last put(), or re-derived for a different weight.

Never inspects a log the way the window buckets do - there is none. When the query does not match the last put, the wait is recomputed by replaying step() against the stored state, which spends nothing.

Return type:: int | Awaitable[int]