Skip to content

xtr_rate_limiter.exception

Every error this library raises.

All of them derive from :class:RateLimiterError, so one except catches anything a limiter can go wrong with, and a narrower one handles a single cause. Each carries the data a caller needs as typed attributes rather than forcing a message to be parsed.

InvalidArgumentError

InvalidArgumentError(reason: str)

Bases: RateLimiterError, ValueError

A limiter, a factory or a storage was given an argument it cannot work with.

Raised where the argument is given — a limit below one, more tokens than a limiter can ever hold, a policy option that belongs to another policy — rather than on the first hit.

Also a :class:ValueError, so code that already guards its configuration with except ValueError keeps working without learning a new exception.

Attributes:

  • reason (str) –

    What is wrong with the argument.

Record what is wrong with the argument.

InvalidIntervalError

InvalidIntervalError(interval: object, reason: str)

Bases: InvalidArgumentError

An interval could not be read, or is not long enough to count anything in.

Attributes:

  • interval (object) –

    The interval as it was given.

Record the interval and what is wrong with it.

MaxWaitDurationExceededError

MaxWaitDurationExceededError(wait_duration: float, max_time: float, rate_limit: RateLimit)

Bases: RateLimiterError

A reservation would have to wait longer than its caller agreed to.

Nothing was reserved: the limiter's state is left as it was.

Attributes:

  • wait_duration (float) –

    The seconds the tokens would have taken to be free.

  • max_time (float) –

    The seconds the caller agreed to wait.

  • rate_limit (RateLimit) –

    The limit as it stands, rejected.

Record how long the wait would have been, and the limit it was measured against.

RateLimitExceededError

RateLimitExceededError(rate_limit: RateLimit)

Bases: RateLimiterError

A hit the caller insisted on was not accepted.

Raised by :meth:RateLimit.ensure_accepted <xtr_rate_limiter.rate_limit.RateLimit.ensure_accepted>, for code that would rather fail than branch on the answer.

Attributes:

  • rate_limit (RateLimit) –

    The rejected limit.

Record the rejected limit.

retry_after property

retry_after: datetime

When the tokens asked for become available.

remaining_tokens property

remaining_tokens: int

How many tokens are left.

limit property

limit: int

How many tokens the limiter holds when full.

RateLimiterError

Bases: Exception

Base class for every error raised by this library.

Catch this to handle anything limiting can go wrong with; catch a subclass to handle one cause. Every subclass carries the data a caller needs as typed attributes and composes its own message from them.

RateLimiterStorageError

RateLimiterStorageError(reason: str)

Bases: RateLimiterError

The server keeping a limiter's state failed to answer.

Raised rather than answering as if the limiter were empty: whether a limit fails open or closed is the caller's decision, not the storage's.

Attributes:

  • reason (str) –

    What the server said, or why it could not be reached.

Record why the state could not be read or written.

ReserveNotSupportedError

ReserveNotSupportedError(limiter: str)

Bases: RateLimiterError

A limiter was asked to reserve, which it cannot do.

A compound limiter answers only :meth:consume: reserving on several limiters would book tokens on some of them while another refuses.

Attributes:

  • limiter (str) –

    The name of the limiter's class.

Record which limiter refused.