Skip to content

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: float

Units 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: float

Units 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

@classmethod
def per_day(limit: int, *, name: str = 'day', reset: Reset | None = None) -> Self

A fixed daily window, resetting on reset or at UTC midnight.

per_hour

@classmethod
def per_hour(limit: int, *, name: str = 'hour', burst: int | None = None) -> Self

per_minute

@classmethod
def per_minute(limit: int, *, name: str = 'minute', burst: int | None = None) -> Self

per_second

@classmethod
def per_second(limit: int, *, name: str = 'second', burst: int | None = None) -> Self

QuotaKind

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: str

The one string the shared state is kept under.

vendor

vendor: _IdentityText