Loops#

This module contains the loop implementations in arc. Loops can be used to call a function repeatedly with a given interval.

CronLoop #

CronLoop(
    callback: Callable[P, Awaitable[None]],
    cron_format: str,
    *,
    timezone: timezone = datetime.timezone.utc
)

Bases: _LoopBase[P]

A simple interval loop that runs a coroutine at a specified interval.

Warning

To use this loop, you must install arc with the cron extra.

pip install hikari-arc[cron]

PARAMETER	DESCRIPTION
`callback`	The coroutine to run at the specified interval. TYPE: `Callable[P, Awaitable[None]]`
`cron_format`	The cron format to use. See https://en.wikipedia.org/wiki/Cron for more information. TYPE: `str`
`timezone`	The timezone to use for the cron loop. Defaults to UTC. TYPE: `timezone` DEFAULT: `utc`

RAISES	DESCRIPTION
`ImportError`	If the `croniter` package is not installed.
`CroniterBadCronError`	If the cron format is invalid.
`TypeError`	If the passed function is not a coroutine function.

Example

loop = CronLoop(my_coro, "*/5 * * * *")
loop.start()

You may also use the decorator @arc.utils.cron_loop to create a CronLoop from a coroutine function.

call `async` #

__call__(*args: args, **kwargs: kwargs) -> None

Call the underlying coroutine.

cancel #

cancel() -> None

Cancel the loop.

If you want to stop the loop gracefully, use stop() instead.

start #

start(*args: args, **kwargs: kwargs) -> None

Start the loop at the specified interval.

PARAMETER	DESCRIPTION
`args`	The positional arguments to pass to the coroutine every iteration. TYPE: `args` DEFAULT: `()`
`kwargs`	The keyword arguments to pass to the coroutine every iteration. TYPE: `kwargs` DEFAULT: `{}`

stop #

stop() -> None

Gracefully stop the loop. This will wait for the current iteration to finish.

IntervalLoop #

IntervalLoop(
    callback: Callable[P, Awaitable[None]],
    *,
    seconds: float | None = None,
    minutes: float | None = None,
    hours: float | None = None,
    days: float | None = None,
    run_on_start: bool = True
)

Bases: _LoopBase[P]

A simple interval loop that runs a coroutine at a specified interval.

PARAMETER	DESCRIPTION
`callback`	The coroutine to run at the specified interval. TYPE: `Callable[P, Awaitable[None]]`
`seconds`	The number of seconds to wait before running the coroutine again. TYPE: `float` DEFAULT: `None`
`minutes`	The number of minutes to wait before running the coroutine again. TYPE: `float` DEFAULT: `None`
`hours`	The number of hours to wait before running the coroutine again. TYPE: `float` DEFAULT: `None`
`days`	The number of days to wait before running the coroutine again. TYPE: `float` DEFAULT: `None`
`run_on_start`	Whether to run the callback immediately after starting the loop. If set to false, the loop will wait for the specified interval before first running the callback. TYPE: `bool` DEFAULT: `True`

RAISES	DESCRIPTION
`ValueError`	If no interval is specified.
`TypeError`	If the passed function is not a coroutine function.

Example

loop = IntervalLoop(my_coro, seconds=5)
loop.start()

You may also use the decorator @arc.utils.interval_loop to create an IntervalLoop from a coroutine function.

call `async` #

__call__(*args: args, **kwargs: kwargs) -> None

Call the underlying coroutine.

cancel #

cancel() -> None

Cancel the loop.

If you want to stop the loop gracefully, use stop() instead.

set_interval #

set_interval(
    *,
    seconds: float | None = None,
    minutes: float | None = None,
    hours: float | None = None,
    days: float | None = None
)

Set a new specified interval.

Note

You need to restart the loop if you want these changes to take effect immediately.

PARAMETER	DESCRIPTION
`seconds`	The number of seconds to wait before running the coroutine again. TYPE: `float \| None` DEFAULT: `None`
`minutes`	The number of minutes to wait before running the coroutine again. TYPE: `float \| None` DEFAULT: `None`
`hours`	The number of hours to wait before running the coroutine again. TYPE: `float \| None` DEFAULT: `None`
`days`	The number of days to wait before running the coroutine again. TYPE: `float \| None` DEFAULT: `None`

Example

loop = IntervalLoop(my_coro, seconds=5)
loop.start()
loop.set_interval(seconds=10)
loop.cancel()
loop.start()

start #

start(*args: args, **kwargs: kwargs) -> None

Start the loop at the specified interval.

PARAMETER	DESCRIPTION
`args`	The positional arguments to pass to the coroutine every iteration. TYPE: `args` DEFAULT: `()`
`kwargs`	The keyword arguments to pass to the coroutine every iteration. TYPE: `kwargs` DEFAULT: `{}`

stop #

stop() -> None

Gracefully stop the loop. This will wait for the current iteration to finish.

cron_loop #

cron_loop(
    cron_format: str, timezone: timezone = datetime.timezone.utc
) -> Callable[[Callable[P, Awaitable[None]]], CronLoop[P]]

Decorator to create a CronLoop out of a coroutine function.

Warning

To use this loop, you must install arc with the cron extra.

pip install hikari-arc[cron]

PARAMETER	DESCRIPTION
`cron_format`	The cron format to use. See https://en.wikipedia.org/wiki/Cron for more information. TYPE: `str`
`timezone`	The timezone to use for the cron loop. Defaults to UTC. TYPE: `timezone` DEFAULT: `utc`

RETURNS	DESCRIPTION
`Callable[[Callable[P, Awaitable[None]]], CronLoop[P]]`	The decorator.

RAISES	DESCRIPTION
`ImportError`	If the `croniter` package is not installed.
`CroniterBadCronError`	If the cron format is invalid.
`TypeError`	If the decorated function is not a coroutine function.

Example

import arc

# Run every 5th minute of every hour.
@arc.utils.cron_loop("*/5 * * * *")
async def my_loop():
    print("Hello, world!")

# Elsewhere...

my_loop.start()

interval_loop #

interval_loop(
    *,
    seconds: float | None = None,
    minutes: float | None = None,
    hours: float | None = None,
    days: float | None = None,
    run_on_start: bool = True
) -> Callable[[Callable[P, Awaitable[None]]], IntervalLoop[P]]

A decorator to create an IntervalLoop out of a coroutine function.

PARAMETER	DESCRIPTION
`seconds`	The number of seconds to wait before running the coroutine again. TYPE: `float` DEFAULT: `None`
`minutes`	The number of minutes to wait before running the coroutine again. TYPE: `float` DEFAULT: `None`
`hours`	The number of hours to wait before running the coroutine again. TYPE: `float` DEFAULT: `None`
`days`	The number of days to wait before running the coroutine again. TYPE: `float` DEFAULT: `None`
`run_on_start`	Whether to run the callback immediately after starting the loop. If set to false, the loop will wait for the specified interval before first running the callback. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`Callable[[Callable[P, Awaitable[None]]], IntervalLoop[P]]`	The decorator.

RAISES	DESCRIPTION
`ValueError`	If no interval is specified.
`TypeError`	If the decorated function is not a coroutine function.

Example

import arc

# Run every 5 seconds.
@arc.utils.interval_loop(seconds=5)
async def my_loop():
    print("Hello, loop!")

# Elsewhere...

my_loop.start()

Loops#

CronLoop #

__call__ async #

cancel #

start #

stop #

IntervalLoop #

__call__ async #

cancel #

set_interval #

start #

stop #

cron_loop #

interval_loop #

call `async` #

call `async` #