Skip to content

common_rates.limiters.base

The limiter algebra: declared quotas, one admission verb, and the decision written once.

A limiter is declared with quotas per scope, then asked to admit calls. Every admission must clear every quota of its scope at once: a call that fits the minute but not the day is not admitted, and the minute is not charged for it. The decision, how long to wait and what to reserve, is one pure function on the scope’s state and the backend’s clock. Variants keep that state somewhere and run the decision under a lock; they carry no counting of their own.

Sections: 1 · INIT config, declarations, lifecycle state; no resource 2 · PROPERTIES config, backend, state, the declared scopes 3 · DECLARE the quotas of a scope 4 · ACQUIRE admit one call, or refuse; the admission hook for HTTP 5 · BALANCE what remains, and a hold from the counterparty’s feedback 6 · THE DECISION the pure algebra: buckets, windows, holds, the budget 7 · SEAMS what a variant fills: open, close, reserve, read 8 · LIFECYCLE open and close, async context 9 · DISPLAY

Classes

BaseLimiter

Bases: ABC

One limiter over one backend.

Carried state: the config, the quotas declared per scope, the lifecycle state, and, when the fail-safe policy is local, a process-local limiter built on first need. The counts themselves live in the backend.

__init__

def __init__(config: AnyConfig) -> None

Fields and properties declared here; inherited members belong to the bases above.

BACKEND

BACKEND: str = ''

backend

Read-only property.

backend: str

config

Read-only property.

config: AnyConfig

scopes

Read-only property.

scopes: tuple[Scope, ...]

Every scope declared on this limiter.

state

Read-only property.

state: Literal['new', 'open', 'closed']

aclose

async def aclose() -> None

acquire

async def acquire(scope: Scope, cost: float = 1.0) -> Permit

Admit one call of cost units against every quota of scope.

Waits as long as the quotas demand, up to the config’s max_wait_sec; past that it raises Refused with nothing charged. A backend that cannot be reached raises Unavailable, or admits through the local fail-safe when the config says local.

admission

def admission(scope: Scope, cost: float = 1.0) -> Callable[..., Awaitable[None]]

The one callable an HTTP client’s admit hook takes.

It ignores what it is handed, the request, and admits against scope at cost. Cost per endpoint is the consumer’s knowledge; build one admission per cost where it differs.

balance

async def balance(scope: Scope) -> tuple[Balance, ...]

Each quota’s standing for the scope, in declaration order.

declare

def declare(scope: Scope, *quotas: Quota) -> Self

State a scope’s quotas, replacing any earlier declaration.

No quotas means the scope is unlimited on purpose. Two quotas of one name refuse, since the state is kept by name.

declared

def declared(scope: Scope) -> tuple[Quota, ...]

The quotas of a scope; an undeclared scope raises.

hold

async def hold(scope: Scope, seconds: float) -> None

Admit nothing for seconds: the counterparty’s own word, a 429’s Retry-After.

A later, shorter hold never shortens a longer one already set.

info

def info() -> LimiterInfo

open

async def open() -> Self

Decision

What the algebra decided for one admission.

reserved True: the cost is charged, proceed after wait. False: nothing was charged; a window is full, try again after wait. refused: the wait exceeds the caller’s budget, nothing was charged. gated_by names the quota that set the wait, None when nothing did.

__init__

def __init__(wait: float, reserved: bool, gated_by: str | None, refused: bool = False) -> None

Fields and properties declared here; inherited members belong to the bases above.

gated_by

gated_by: str | None

refused

refused: bool = False

reserved

reserved: bool

wait

wait: float