Timer

Implementations to handle timers on the RequestHandler.

Includes various time incremental operations to manage increasing of time between requests with various mathematical formulae.

Useful to handle backoff for requests on sensitive HTTP services which often return a ‘429 - Too Many Requests’ status.

Classes:

Timer([initial])	Base interface for all timers.
CountTimer([initial, count])	Abstract implementation of a Timer which will increment a maximum number of times.
StepCountTimer([initial, count, step])	Increases timer value by a given step amount a distinct number of times.
GeometricCountTimer([initial, count, factor])	Increases timer value by multiplying the current value by a given factor a distinct number of times.
PowerCountTimer([initial, count, exponent])	Increases timer value by raising the current value to a given exponent a distinct number of times.
CeilingTimer([initial, final])	Abstract implementation of a Timer which will increment until a maximum value is reached.
StepCeilingTimer([initial, final, step])	Increases timer value by a given step amount until a maximum value is reached.
GeometricCeilingTimer([initial, final, factor])	Increases timer value by multiplying the current value by a given factor until a maximum value is reached.
PowerCeilingTimer([initial, final, exponent])	Increases timer value by raising the current value to a given exponent until a maximum value is reached.

class aiorequestful.timer.Timer(initial=0)

Bases: SupportsInt, SupportsFloat, ABC

Base interface for all timers.

Parameters:

initial (int | float (default: 0)) – The starting value to use.

Attributes:

initial	The initial starting timer value in seconds.
final	The maximum possible timer value in seconds.
total	The sum of all possible timer values in seconds.
total_remaining	The sum of all possible remaining timer values in seconds not including the current value.
count	The total amount of times this timer can be increased.
counter	The number of times this timer has been increased.
count_remaining	The remaining number of times this timer can be increased.
can_increase	Check whether this timer can be increased

Methods:

increase()	Increase the timer value.
reset()	Reset the timer to its initial settings.
wait()	Sleep for the current time set for this timer.

property initial: int | float

The initial starting timer value in seconds.

abstract property final: int | float | None

The maximum possible timer value in seconds.

abstract property total: int | float | None

The sum of all possible timer values in seconds.

abstract property total_remaining: int | float | None

The sum of all possible remaining timer values in seconds not including the current value.

abstract property count: int | None

The total amount of times this timer can be increased.

property counter: int | None

The number of times this timer has been increased.

property count_remaining: int | None

The remaining number of times this timer can be increased.

abstract property can_increase: bool

Check whether this timer can be increased

abstractmethod increase()

Increase the timer value.

Returns:

bool – True if timer was increased, False if not.

reset()

Reset the timer to its initial settings.

Return type:

None

wait()

Sleep for the current time set for this timer.

Return type:

None

class aiorequestful.timer.CountTimer(initial=1, count=None)

Bases: Timer

Abstract implementation of a Timer which will increment a maximum number of times.

Parameters:

• initial (int | float (default: 1)) – The starting value to use.

• count (int (default: None)) – The amount of times to increase the value.

Attributes:

count	The total amount of times this timer can be increased.
can_increase	Check whether this timer can be increased

property count

The total amount of times this timer can be increased.

property can_increase: bool

Check whether this timer can be increased

class aiorequestful.timer.StepCountTimer(initial=0, count=None, step=1)

Bases: CountTimer

Increases timer value by a given step amount a distinct number of times.

Parameters:

• initial (int | float (default: 0)) – The starting value to use.

• count (int (default: None)) – The amount of times to increase the value.

• step (int | float (default: 1)) – The amount to increase the value by for each value increase.

Attributes:

final	The maximum possible timer value in seconds.
total	The sum of all possible timer values in seconds.
total_remaining	The sum of all possible remaining timer values in seconds not including the current value.
step	The amount to increase the timer value by in seconds.

Methods:

increase()

Increase the timer value.

property final

The maximum possible timer value in seconds.

property total

The sum of all possible timer values in seconds.

property total_remaining

The sum of all possible remaining timer values in seconds not including the current value.

property step: int | float

The amount to increase the timer value by in seconds.

increase()

Increase the timer value.

Returns:

bool – True if timer was increased, False if not.

class aiorequestful.timer.GeometricCountTimer(initial=1, count=None, factor=2)

Bases: CountTimer

Increases timer value by multiplying the current value by a given factor a distinct number of times.

Parameters:

• initial (int | float (default: 1)) – The starting value to use.

• count (int (default: None)) – The amount of times to increase the value.

• factor (int | float (default: 2)) – The amount to multiply the current value by for each value increase.

Attributes:

final	The maximum possible timer value in seconds.
total	The sum of all possible timer values in seconds.
total_remaining	The sum of all possible remaining timer values in seconds not including the current value.
factor	The amount to multiply the timer value by in seconds.

Methods:

increase()

Increase the timer value.

property final

The maximum possible timer value in seconds.

property total

The sum of all possible timer values in seconds.

property total_remaining

The sum of all possible remaining timer values in seconds not including the current value.

property factor: int | float

The amount to multiply the timer value by in seconds.

increase()

Increase the timer value.

Returns:

bool – True if timer was increased, False if not.

class aiorequestful.timer.PowerCountTimer(initial=1, count=None, exponent=2)

Bases: CountTimer

Increases timer value by raising the current value to a given exponent a distinct number of times.

Parameters:

• initial (int | float (default: 1)) – The starting value to use.

• count (int (default: None)) – The amount of times to increase the value.

• exponent (int | float (default: 2)) – The power to raise the value by for each value increase.

Attributes:

final	The maximum possible timer value in seconds.
total	The sum of all possible timer values in seconds.
total_remaining	The sum of all possible remaining timer values in seconds not including the current value.
exponent	The power value to apply to the timer value in seconds.

Methods:

increase()

Increase the timer value.

property final

The maximum possible timer value in seconds.

property total

The sum of all possible timer values in seconds.

property total_remaining

The sum of all possible remaining timer values in seconds not including the current value.

property exponent: int | float

The power value to apply to the timer value in seconds.

increase()

Increase the timer value.

Returns:

bool – True if timer was increased, False if not.

class aiorequestful.timer.CeilingTimer(initial=1, final=None)

Bases: Timer

Abstract implementation of a Timer which will increment until a maximum value is reached.

Parameters:

• initial (int | float (default: 1)) – The starting value to use.

• final (int | float (default: None)) – The value at which to stop increasing.

Attributes:

final	The maximum possible timer value in seconds.
total	The sum of all possible timer values in seconds.
total_remaining	The sum of all possible remaining timer values in seconds not including the current value.
count	The total amount of times this timer can be increased.
can_increase	Check whether this timer can be increased

property final

The maximum possible timer value in seconds.

property total

The sum of all possible timer values in seconds.

property total_remaining

The sum of all possible remaining timer values in seconds not including the current value.

property count

The total amount of times this timer can be increased.

property can_increase: bool

Check whether this timer can be increased

class aiorequestful.timer.StepCeilingTimer(initial=1, final=None, step=1)

Bases: CeilingTimer

Increases timer value by a given step amount until a maximum value is reached.

Parameters:

• initial (int | float (default: 1)) – The starting value to use.

• final (int | float (default: None)) – The value at which to stop increasing.

• step (int | float (default: 1)) – The amount to increase the value by for each value increase.

Attributes:

step	The amount to increase the timer value by in seconds.

Methods:

increase()

Increase the timer value.

property step: int | float

The amount to increase the timer value by in seconds.

increase()

Increase the timer value.

Returns:

bool – True if timer was increased, False if not.

class aiorequestful.timer.GeometricCeilingTimer(initial=1, final=None, factor=2)

Bases: CeilingTimer

Increases timer value by multiplying the current value by a given factor until a maximum value is reached.

Parameters:

• initial (int | float (default: 1)) – The starting value to use.

• final (int | float (default: None)) – The value at which to stop increasing.

• factor (int | float (default: 2)) – The amount to multiply the current value by for each value increase.

Attributes:

factor

The amount to multiply the timer value by in seconds.

Methods:

increase()

Increase the timer value.

property factor: int | float

The amount to multiply the timer value by in seconds.

increase()

Increase the timer value.

Returns:

bool – True if timer was increased, False if not.

class aiorequestful.timer.PowerCeilingTimer(initial=1, final=None, exponent=2)

Bases: CeilingTimer

Increases timer value by raising the current value to a given exponent until a maximum value is reached.

Parameters:

• initial (int | float (default: 1)) – The starting value to use.

• final (int | float (default: None)) – The value at which to stop increasing.

• exponent (int | float (default: 2)) – The power to raise the value by for each value increase.

Attributes:

exponent

The power value to apply to the timer value in seconds.

Methods:

increase()

Increase the timer value.

property exponent: int | float

The power value to apply to the timer value in seconds.

increase()

Increase the timer value.

Returns:

bool – True if timer was increased, False if not.