mode.utils.times — mode-ng 0.4.0 documentation

# `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.