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 keyminute = Quota.per_minute(300) # a rolling bucket: 300 refill over 60sday = Quota.per_day(250_000, reset=Reset(zone="America/New_York")) # a window on their clockweighted = Quota(name="units", limit=5, per=1.0) # a call's cost counts against itA 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 callacquire 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 everyonebalances = await limiter.balance(fmp) # Balance(quota, remaining, replenishes_at) per quotaA 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 itLimiter.postgres(dsn) # an owned pool from a DSNLimiter.postgres(pool=pool) # a borrowed psycopg_pool.AsyncConnectionPoolLimiter.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.