API Reference#

Attributes
Methods
class defectio.ext.tasks.Loop[source]#

A background task helper that abstracts the loop and reconnection logic for you.

The main interface to create this is through loop().

@after_loop[source]#

A decorator that register a coroutine to be called after the loop finished running.

The coroutine must take no arguments (except self in a class context).

Note

This coroutine is called even during cancellation. If it is desirable to tell apart whether something was cancelled or not, check to see whether is_being_cancelled() is True or not.

Parameters

coro (coroutine) – The coroutine to register after the loop finishes.

Raises

TypeError – The function was not a coroutine.

@before_loop[source]#

A decorator that registers a coroutine to be called before the loop starts running.

This is useful if you want to wait for some bot state before the loop starts, such as defectio.Client.wait_until_ready().

The coroutine must take no arguments (except self in a class context).

Parameters

coro (coroutine) – The coroutine to register before the loop runs.

Raises

TypeError – The function was not a coroutine.

@error[source]#

A decorator that registers a coroutine to be called if the task encounters an unhandled exception. The coroutine must take only one argument the exception raised (except self in a class context). By default this prints to sys.stderr however it could be overridden to have a different implementation. :param coro: The coroutine to register in the event of an unhandled exception. :type coro: coroutine

Raises

TypeError – The function was not a coroutine.

property seconds#

Read-only value for the number of seconds between each iteration. None if an explicit time value was passed instead.

Type

Optional[float]

property minutes#

Read-only value for the number of minutes between each iteration. None if an explicit time value was passed instead.

Type

Optional[float]

property hours#

Read-only value for the number of hours between each iteration. None if an explicit time value was passed instead.

Type

Optional[float]

property time#

Read-only list for the exact times this loop runs at. None if relative times were passed instead.

Type

Optional[list[datetime.time]]

property current_loop#

The current iteration of the loop.

Type

int

property next_iteration#

When the next iteration of the loop will occur.

Type

Optional[datetime.datetime]

await __call__(*args, **kwargs)[source]#

This function is a coroutine. Calls the internal callback that the task holds.

Parameters

  • *args – The arguments to use.

  • **kwargs – The keyword arguments to use.

start(*args, **kwargs)[source]#

Starts the internal task in the event loop.

Parameters

  • *args – The arguments to use.

  • **kwargs – The keyword arguments to use.

Raises

RuntimeError – A task has already been launched and is running.

Returns

The task that has been created.

Return type

asyncio.Task

stop()[source]#

Gracefully stops the task from running.

Unlike cancel(), this allows the task to finish its current iteration before gracefully exiting.

Note

If the internal function raises an error that can be handled before finishing then it will retry until it succeeds.

If this is undesirable, either remove the error handling before stopping via clear_exception_types() or use cancel() instead.

cancel()[source]#

Cancels the internal task, if it is running.

restart(*args, **kwargs)[source]#

A convenience method to restart the internal task.

Note

Due to the way this function works, the task is not returned like start().

Parameters

  • *args – The arguments to use.

  • **kwargs – The keyword arguments to use.

add_exception_type(*exceptions)[source]#

Adds exception types to be handled during the reconnect logic.

By default the exception types handled are those handled by defectio.Client.connect(), which includes a lot of internet disconnection errors. This function is useful if you’re interacting with a 3rd party library that raises its own set of exceptions.

Parameters

*exceptions (Type[BaseException]) – An argument list of exception classes to handle.

Raises

TypeError – An exception passed is either not a class or not inherited from BaseException.

clear_exception_types()[source]#

Removes all exception types that are handled.

Note

This operation obviously cannot be undone!

remove_exception_type(*exceptions)[source]#

Removes exception types from being handled during the reconnect logic.

Parameters

*exceptions (Type[BaseException]) – An argument list of exception classes to handle.

Returns

Whether all exceptions were successfully removed.

Return type

bool

get_task()[source]#

Optional[asyncio.Task]: Fetches the internal task or None if there isn’t one running.

is_being_cancelled()[source]#

Whether the task is being cancelled.

failed()[source]#

bool: Whether the internal task has failed.

is_running()[source]#

bool: Check if the task is currently running.

change_interval(*, seconds=0, minutes=0, hours=0, time=None)[source]#

Changes the interval for the sleep time.

Parameters

  • seconds (float) – The number of seconds between every iteration.

  • minutes (float) – The number of minutes between every iteration.

  • hours (float) – The number of hours between every iteration.

  • time (Union[datetime.time, Sequence[datetime.time]]) –

    The exact times to run this loop at. Either a non-empty list or a single value of datetime.time should be passed. This cannot be used in conjunction with the relative time parameters.

    Note

    Duplicate times will be ignored, and only run once.

Raises

  • ValueError – An invalid value was given.

  • TypeError – An invalid value for the time parameter was passed, or the time parameter was passed in conjunction with relative time parameters.

defectio.ext.tasks.loop(*, seconds=None, minutes=None, hours=None, time=None, count=None, reconnect=True, loop=None)[source]#

A decorator that schedules a task in the background for you with optional reconnect logic. The decorator returns a Loop.

Parameters

  • seconds (float) – The number of seconds between every iteration.

  • minutes (float) – The number of minutes between every iteration.

  • hours (float) – The number of hours between every iteration.

  • time (Union[datetime.time, Sequence[datetime.time]]) –

    The exact times to run this loop at. Either a non-empty list or a single value of datetime.time should be passed. Timezones are supported. If no timezone is given for the times, it is assumed to represent UTC time. This cannot be used in conjunction with the relative time parameters.

    Note

    Duplicate times will be ignored, and only run once.

  • count (Optional[int]) – The number of loops to do, None if it should be an infinite loop.

  • reconnect (bool) – Whether to handle errors and restart the task using an exponential back-off algorithm similar to the one used in defectio.Client.connect().

  • loop (asyncio.AbstractEventLoop) – The loop to use to register the task, if not given defaults to asyncio.get_event_loop().

Raises

  • ValueError – An invalid value was given.

  • TypeError – The function was not a coroutine, an invalid value for the time parameter was passed, or time parameter was passed in conjunction with relative time parameters.