mode.utils.times

Time, date and timezone related utilities.

class mode.utils.times.Bucket(rate: Union[timedelta, int, float, str], over: Union[timedelta, int, float, str] = 1.0, *, fill_rate: Optional[Union[timedelta, int, float, str]] = None, capacity: Optional[Union[timedelta, int, float, str]] = None, raises: Optional[Type[BaseException]] = None, loop: Optional[AbstractEventLoop] = None)

Rate limiting state.

A bucket “pours” tokens at a rate of rate per second (or over’).

Calling bucket.pour(), pours one token by default, and returns True if that amount can be poured now, or False if the caller has to wait.

If this returns False, it’s prudent to either sleep or raise an exception:

if not bucket.pour():
    await asyncio.sleep(bucket.expected_time())

If you want to consume multiple tokens in one go then specify the number:

if not bucket.pour(10):
    await asyncio.sleep(bucket.expected_time(10))

This class can also be used as an async. context manager, but in that case can only consume one tokens at a time:

async with bucket:
    # do something

By default the async. context manager will suspend the current coroutine and sleep until as soon as the time that a token can be consumed.

If you wish you can also raise an exception, instead of sleeping, by providing the raises keyword argument:

# hundred tokens in one second, and async with: raises TimeoutError

class MyError(Exception):
    pass

bucket = Bucket(100, over=1.0, raises=MyError)

async with bucket:
    # do something
capacity: float
abstract expected_time(tokens: int = 1) float
property fill_rate: float
abstract pour(tokens: int = 1) bool
rate: float
abstract property tokens: float
mode.utils.times.Seconds

Seconds can be expressed as float or timedelta,

alias of Union[timedelta, int, float, str]

class mode.utils.times.TokenBucket(rate: Union[timedelta, int, float, str], over: Union[timedelta, int, float, str] = 1.0, *, fill_rate: Optional[Union[timedelta, int, float, str]] = None, capacity: Optional[Union[timedelta, int, float, str]] = None, raises: Optional[Type[BaseException]] = None, loop: Optional[AbstractEventLoop] = None)

Rate limiting using the token bucket algorithm.

expected_time(tokens: int = 1) float
pour(tokens: int = 1) bool
property tokens: float
mode.utils.times.humanize_seconds(secs: float, *, prefix: str = '', suffix: str = '', sep: str = '', now: str = 'now', microseconds: bool = False) str

Show seconds in human form.

For example, 60 becomes “1 minute”, and 7200 becomes “2 hours”.

Parameters:
  • secs – Seconds to format (as float or int).

  • prefix (str) – can be used to add a preposition to the output (e.g., ‘in’ will give ‘in 1 second’, but add nothing to ‘now’).

  • suffix (str) – same as prefix, adds suffix unless ‘now’.

  • sep (str) – separator between prefix and number.

  • now (str) – Literal ‘now’.

  • microseconds (bool) – Include microseconds.

mode.utils.times.humanize_seconds_ago(secs: float, *, prefix: str = '', suffix: str = ' ago', sep: str = '', now: str = 'just now', microseconds: bool = False) str

Show seconds in “3.33 seconds ago” form.

If seconds are less than one, returns “just now”.

mode.utils.times.rate(r: float | str | int | None) float
mode.utils.times.rate(r: int | float) float
mode.utils.times.rate(r: int | float) float
mode.utils.times.rate(r: str) float
mode.utils.times.rate(r: None) float

Convert rate string (“100/m”, “2/h” or “0.5/s”) to seconds.

mode.utils.times.rate_limit(rate: float, over: ~typing.Union[~datetime.timedelta, int, float, str] = 1.0, *, bucket_type: ~typing.Type[~mode.utils.times.Bucket] = <class 'mode.utils.times.TokenBucket'>, raises: ~typing.Optional[~typing.Type[BaseException]] = None, loop: ~typing.Optional[~asyncio.events.AbstractEventLoop] = None) Bucket

Create rate limiting manager.

mode.utils.times.want_seconds(s: int | float | str | datetime.timedelta) float
mode.utils.times.want_seconds(s: int | float) float
mode.utils.times.want_seconds(s: int | float) float
mode.utils.times.want_seconds(s: str) float
mode.utils.times.want_seconds(s: timedelta) float

Convert Seconds to float.