API Reference¶
Loop¶
- class guilded.ext.tasks.Loop¶
A background task helper/interface.
It is recommended to create a loop with the
loop()
decorator.- @after_loop¶
A decorator that register a function to be called after the loop finished running.
The function must take no arguments (except
self
in a class).Note
This function 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()
isTrue
or not.
- @before_loop¶
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
guilded.Client.wait_until_ready()
.The coroutine must take no arguments (except
self
in a class).
- @error¶
A decorator that registers a function to be called if the task encounters an unhandled exception.
The function must take only one argument the exception raised (except
self
in a class).By default this prints to
sys.stderr
, however it could be overridden to have a different implementation.
- property next_iteration¶
When the next iteration of the loop will occur.
- Type
Optional[
datetime.datetime
]
- await __call__(*args, **kwargs)¶
Calls the internal callback that the task holds.
- Parameters
*args – The posiitonal arguments to use.
**kwargs – The keyword arguments to use.
- Returns
The return value of the callback.
- Return type
Any
- start(*args, **kwargs)¶
Starts the internal task in the event loop.
- Parameters
*args – The posiitonal arguments to use.
**kwargs – The keyword arguments to use.
- Returns
The task that has been created.
- Return type
- Raises
RuntimeError – A task has already been launched and is running.
- stop()¶
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 usecancel()
instead.
- cancel()¶
Cancels the internal task, if it is running.
- restart(*args, **kwargs)¶
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 to use.
**kwargs – The keyword arguments to use.
- add_exception_type(*exceptions)¶
Adds exception types to be handled during the reconnect logic.
By default the exception types handled are those handled by
guilded.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 not inherited from BaseException.
- clear_exception_types()¶
Removes all exception types that are handled.
Note
This operation obviously cannot be undone!
- remove_exception_type(*exceptions)¶
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
- get_task()¶
Fetches the internal task or None if there isn’t one running.
- Returns
The internal task.
- Return type
Optional[
asyncio.Task
]
- change_interval(*, seconds=0, minutes=0, hours=0)¶
Changes the interval for the sleep time.
Note
This only applies on the next loop iteration. If it is desirable for the change of interval to be applied right away, you should
cancel()
the task.- Parameters
- Raises
ValueError – An invalid value was given.
loop¶
- guilded.ext.tasks.loop(*, seconds=0, minutes=0, hours=0, count=None, reconnect=True, loop=None)¶
A decorator that schedules a task in the background for you with optional reconnect logic.
- 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.count (
float
) – The number of loops to do. Defaults toNone
, which means it will run infinitely.reconnect (
bool
) – Whether to handle errors and restart the task using an exponential back-off algorithm similar to the one used inguilded.Client.connect()
. Defaults toTrue
.loop (
asyncio.AbstractEventLoop
) – The loop for registering tasks, defaults toasyncio.get_event_loop()
if not provided.
- Raises
ValueError – An invalid value was given.
TypeError – The function was not a coroutine.