common_rates.contracts.quotas
Quotas and scopes: what a counterparty enforces, and whose it is.
A Quota is one limit exactly as the counterparty states it: so many units per
period, refilling continuously (a bucket) or resetting on a clock (a window). A
Scope is the vendor and account the limit belongs to: the key every process
that shares the account coordinates on. Both are plain values a limiter is
declared with. Counting, waiting, and sharing state across processes belong to
the limiters, never here.
Classes
Quota
Bases: BaseModel
One limit as the counterparty states it.
limit units per per seconds. A rolling quota may name a burst,
the units held at once; it defaults to the limit. A window quota may name
the reset clock; without one, windows align to the epoch. weighted
says whether a call’s cost counts, or every call counts one.
Example: Quota.per_minute(300) # FMP: 300 calls a minute Quota.per_day(100_000, reset=Reset()) # EODHD: 100k a day, UTC midnight Quota(name=“units”, limit=5, per=1.0, weighted=True)
Fields and properties declared here; inherited members belong to the bases above.
burst
burst: int | None = Field(default=None, gt=0, description='Rolling only: units held at once.')capacity
Read-only property.
capacity: floatUnits a rolling quota holds at once.
kind
kind: QuotaKind = Field(default=(QuotaKind.ROLLING), strict=False)limit
limit: int = Field(gt=0, description='Units per period.')name
name: _IdentityText = Field(description="The counterparty's word for it: minute, day.")per
per: float = Field(gt=0, allow_inf_nan=False, description='The period, in seconds.')refill_per_second
Read-only property.
refill_per_second: floatUnits a rolling quota gives back each second.
reset
reset: Reset | None = Field(default=None, description='Window only: the clock it resets on.')weighted
weighted: bool = Field(default=True, description="Whether a call's cost counts, else one.")per_day
@classmethoddef per_day(limit: int, *, name: str = 'day', reset: Reset | None = None) -> SelfA fixed daily window, resetting on reset or at UTC midnight.
per_hour
@classmethoddef per_hour(limit: int, *, name: str = 'hour', burst: int | None = None) -> Selfper_minute
@classmethoddef per_minute(limit: int, *, name: str = 'minute', burst: int | None = None) -> Selfper_second
@classmethoddef per_second(limit: int, *, name: str = 'second', burst: int | None = None) -> SelfQuotaKind
Bases: StrEnum
How a quota counts.
ROLLING is a token bucket: limit units refill evenly over per
seconds, up to burst held at once. WINDOW is a fixed window: limit
units per per seconds, the count resetting on the clock reset names.
Fields and properties declared here; inherited members belong to the bases above.
ROLLING
ROLLING = 'rolling'WINDOW
WINDOW = 'window'Reset
Bases: BaseModel
The wall clock a window quota resets on: midnight in the counterparty’s zone.
Windows shorter than a day align to this instant too, so an hourly window anchored at 00:30 turns at every half hour.
Fields and properties declared here; inherited members belong to the bases above.
hour
hour: int = Field(default=0, ge=0, le=23)minute
minute: int = Field(default=0, ge=0, le=59)zone
zone: str = Field(default='UTC', description='IANA zone of the clock: America/New_York.')Scope
Bases: BaseModel
Whose quota it is: a vendor, and the account at that vendor.
Every process sharing the account coordinates on this key. The account is a non-secret alias, never a credential.
Fields and properties declared here; inherited members belong to the bases above.
account
account: _IdentityText = 'default'key
Read-only property.
key: strThe one string the shared state is kept under.
vendor
vendor: _IdentityText