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) -> NoneFields and properties declared here; inherited members belong to the bases above.
BACKEND
BACKEND: str = ''backend
Read-only property.
backend: strconfig
Read-only property.
config: AnyConfigscopes
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() -> Noneacquire
async def acquire(scope: Scope, cost: float = 1.0) -> PermitAdmit 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) -> SelfState 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) -> NoneAdmit 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() -> LimiterInfoopen
async def open() -> SelfDecision
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) -> NoneFields and properties declared here; inherited members belong to the bases above.
gated_by
gated_by: str | Nonerefused
refused: bool = Falsereserved
reserved: boolwait
wait: float