You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
126 lines
3.2 KiB
126 lines
3.2 KiB
``discord.ext.tasks`` -- asyncio.Task helpers
|
|
====================================================
|
|
|
|
.. versionadded:: 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 :exc:`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 :class:`~discord.ext.commands.Cog`:
|
|
|
|
.. code-block:: python3
|
|
|
|
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:
|
|
|
|
.. code-block:: python3
|
|
|
|
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:
|
|
|
|
.. code-block:: python3
|
|
|
|
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:
|
|
|
|
.. code-block:: python3
|
|
|
|
from discord.ext import tasks, commands
|
|
|
|
class MyCog(commands.Cog):
|
|
def __init__(self, bot):
|
|
self.index = 0
|
|
self.printer.before_loop(bot.wait_until_ready())
|
|
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
|
|
|
|
:meth:`~.tasks.Loop.before_loop` can be used as a decorator as well:
|
|
|
|
.. code-block:: python3
|
|
|
|
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()
|
|
|
|
API Reference
|
|
---------------
|
|
|
|
.. autoclass:: discord.ext.tasks.Loop()
|
|
:members:
|
|
|
|
.. autofunction:: discord.ext.tasks.loop
|
|
|