discord.ext.tasks – asyncio.Task helpers

New in version 1.1.0.

One of the most common operations when making a bot is having a loop run in the background at a specified interval. This pattern is very common but has a lot of things you need to look out for:

  • How do I handle asyncio.CancelledError?

  • What do I do if the internet goes out?

  • What is the maximum number of seconds I can sleep anyway?

The goal of this discord.py extension is to abstract all these worries away from you.

Recipes

A simple background task in a Cog:

from discord.ext import tasks, commands

class MyCog(commands.Cog):
    def __init__(self):
        self.index = 0
        self.printer.start()

    def cog_unload(self):
        self.printer.cancel()

    @tasks.loop(seconds=5.0)
    async def printer(self):
        print(self.index)
        self.index += 1

Adding an exception to handle during reconnect:

import asyncpg
from discord.ext import tasks, commands

class MyCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.data = []
        self.batch_update.add_exception_type(asyncpg.PostgresConnectionError)
        self.batch_update.start()

    def cog_unload(self):
        self.batch_update.cancel()

    @tasks.loop(minutes=5.0)
    async def batch_update(self):
        async with self.bot.pool.acquire() as con:
            # batch update here...
            pass

Looping a certain amount of times before exiting:

from discord.ext import tasks

@tasks.loop(seconds=5.0, count=5)
async def slow_count():
    print(slow_count.current_loop)

@slow_count.after_loop
async def after_slow_count():
    print('done!')

slow_count.start()

Waiting until the bot is ready before the loop starts:

from discord.ext import tasks, commands

class MyCog(commands.Cog):
    def __init__(self, bot):
        self.index = 0
        self.bot = bot
        self.printer.start()

    def cog_unload(self):
        self.printer.cancel()

    @tasks.loop(seconds=5.0)
    async def printer(self):
        print(self.index)
        self.index += 1

    @printer.before_loop
    async def before_printer(self):
        print('waiting...')
        await self.bot.wait_until_ready()

Doing something during cancellation:

from discord.ext import tasks, commands
import asyncio

class MyCog(commands.Cog):
    def __init__(self, bot):
        self.bot= bot
        self._batch = []
        self.lock = asyncio.Lock(loop=bot.loop)
        self.bulker.start()

    async def do_bulk(self):
        # bulk insert data here
        ...

    @tasks.loop(seconds=10.0)
    async def bulker(self):
        async with self.lock:
            await self.do_bulk()

    @bulker.after_loop
    async def on_bulker_cancel(self):
        if self.bulker.is_being_cancelled() and len(self._batch) != 0:
            # if we're cancelled and we have some data left...
            # let's insert it to our database
            await self.do_bulk()

API Reference

class discord.ext.tasks.Loop

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

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

current_loop

The current iteration of the loop.

Type

int

start(*args, **kwargs)

Starts the internal task in the event loop.

Parameters
  • *args – The arguments to 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()

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.

New in version 1.2.0.

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(exc)

Adds an exception type to be handled during the reconnect logic.

By default the exception types handled are those handled by discord.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

exc (Type[BaseException]) – The exception class to handle.

Raises

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

clear_exception_types()

Removes all exception types that are handled.

Note

This operation obviously cannot be undone!

remove_exception_type(exc)

Removes an exception type from being handled during the reconnect logic.

Parameters

exc (Type[BaseException]) – The exception class to handle.

Returns

Whether it was successfully removed.

Return type

bool

get_task()

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

is_being_cancelled()

Whether the task is being cancelled.

failed()

bool: Whether the internal task has failed.

New in version 1.2.0.

exception()

Optional[Exception]: The exception that the internal task failed with.

New in version 1.3.0.

before_loop(coro)

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 discord.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.

after_loop(coro)

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.

change_interval(*, seconds=0, minutes=0, hours=0, time=None)

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, cancel the task with cancel().

New in version 1.2.0.

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[Sequence[datetime.time], datetime.time]) –

    The exact times to run this loop at. Either a list or a single value of datetime.time should be passed. Note that this cannot be mixed with the relative time parameters.

    New in version 1.3.0.

Raises
  • ValueError – An invalid value was given.

  • TypeError – Mixing time parameter with relative time parameter or passing an improper type for the time parameter.

discord.ext.tasks.loop(*, seconds=0, minutes=0, hours=0, count=None, time=None, reconnect=True, loop=None)

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.

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

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

    The exact times to run this loop at. Either a list or a single value of datetime.time should be passed. Note that this cannot be mixed with the relative time parameters.

    New in version 1.3.0.

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

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

Raises