Skip to content

Rates

One limiter every process consults before it calls a counterparty. Declare a vendor’s quotas per scope; admit each call against all of them at once; keep the count where every process sharing the account can see it.

Install

  • common-rates: contracts, configs, the algebra, the in-memory backend, and the PostgreSQL backend through common-db.
  • common-rates[redis]: reserved for the Redis or Dragonfly backend; declared, not yet built.

Quotas and scopes

from common_rates import Quota, Reset, Scope
fmp = Scope(vendor="fmp", account="prod") # a non-secret account alias, never a key
minute = Quota.per_minute(300) # a rolling bucket: 300 refill over 60s
day = Quota.per_day(250_000, reset=Reset(zone="America/New_York")) # a window on their clock
weighted = Quota(name="units", limit=5, per=1.0) # a call's cost counts against it

A Quota is a limit exactly as the counterparty states it. ROLLING is a token bucket, limit units refilling evenly over per seconds up to burst at once. WINDOW is a fixed count that resets on the clock reset names; without one, windows align to the epoch. weighted=False counts every call as one regardless of cost.

A Scope is the vendor and the account the limit belongs to. Everything sharing that account coordinates on scope.key.

Declaring and admitting

from common_rates import Limiter, Refused
limiter = Limiter.memory().declare(fmp, minute, day)
async with limiter:
permit = await limiter.acquire(fmp) # Permit(scope, cost, waited, gated_by, granted_at)
permit = await limiter.acquire(fmp, cost=3.0) # a heavier call

acquire waits as long as the quotas demand and returns a Permit saying how long and which quota gated it. Past the config’s max_wait_sec it raises Refused with nothing charged. An undeclared scope raises Undeclared; a limiter never guesses a vendor’s limits. Declaring a scope with no quotas makes it unlimited on purpose.

Every quota must clear. When the minute has room and the day is full, the call waits for the day’s reset and the minute is not charged for it. When a bucket is short, the call is charged now and waits for the refill; that debt is what serialises competing processes fairly.

With common-http

from common_http import HttpClient
http = HttpClient.create(
base_url="https://financialmodelingprep.com/", admit=limiter.admission(fmp)
)

admission(scope, cost=1.0) returns the async callable the admit hook takes. It runs before every physical exchange, retries and redirects included. Build one admission per cost where endpoints differ.

Feedback from the counterparty

await limiter.hold(fmp, seconds=retry_after) # a 429's Retry-After, for everyone
balances = await limiter.balance(fmp) # Balance(quota, remaining, replenishes_at) per quota

A hold delays every admission on the scope until it lapses and never shortens a longer hold already set.

Backends

Limiter.memory() # one process; state dies with it
Limiter.postgres(dsn) # an owned pool from a DSN
Limiter.postgres(pool=pool) # a borrowed psycopg_pool.AsyncConnectionPool
Limiter.create({"backend": "postgres", "connection": {"dsn": dsn}, "max_wait_sec": 30})

The PostgreSQL backend reaches the database through common-db, so the connection is the one the container built for everything else; target picks a plane on a multi-target client. It keeps one row per scope and takes an advisory lock on the scope for the length of one reservation. The clock is the server’s, so processes cannot drift. Call await limiter.backend.initialize() once to create the schema and table; reads never migrate. Windows live in the database, so a daily quota survives a restart.

When the backend cannot be reached, unavailable="refuse" raises Unavailable, and unavailable="local" admits through a process-local bucket declared with the same quotas.

Inspection

limiter.info() reports the backend, its state and the declared scopes. Reports never carry secrets or payloads; a DSN never appears in a repr or a dump.