discord.ext.tasks¶

Ajouté dans la version 1.1.0.

L’une des opérations les plus courantes lors de la création d’un bot est d’avoir une boucle s’exécutant en arrière-plan à un intervalle spécifié. Ce modèle est très courant, mais présente de nombreux éléments auxquels il faut faire attention :

Comment gérer asyncio.CancelledError ?
Que faire si la connexion Internet est interrompue ?
Quelle est la durée maximale en secondes pendant laquelle je peux attendre avant d’annuler l’exécution ?

L’objectif de cette extension Pycord est d’abstraire toutes ces préoccupations pour vous.

Exemples¶

Une tâche en arrière-plan simple dans un 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

Ajouter une exception à gérer lors de la reconnexion :

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

Boucler un certain nombre de fois avant de quitter :

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

Attendre que le bot soit prêt avant le début de la boucle :

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

Faire quelque chose pendant l’annulation :

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

Référence de l’API¶

Attributes

current_loop
hours
minutes
next_iteration
seconds
time

Methods

async__call__
defadd_exception_type
@after_loop
@before_loop
defcancel
defchange_interval
defclear_exception_types
@error
deffailed
defget_task
defis_being_cancelled
defis_running
defremove_exception_type
defrestart
defstart
defstop

class discord.ext.tasks.Loop(coro, seconds, hours, minutes, time, count, reconnect, loop, overlap)[source]¶

Un utilitaire pour les tâches en arrière-plan qui abstrait pour vous la logique de boucle et de reconnexion.

L’interface principale pour créer ceci est à travers loop().

Paramètres:

coro (TypeVar(LF, bound= Callable[..., Awaitable[Any]]))
seconds (float)
hours (float)
minutes (float)
time (time | Sequence[time])
count (int | None)
reconnect (bool)
loop (AbstractEventLoop)
overlap (bool | int)

@after_loop(coro)[source]¶

Un décorateur qui enregistre une coroutine à appeler après l’exécution de la boucle.

La coroutine ne doit prendre aucun argument (sauf self dans un contexte de classe).

Note

Cette coroutine est appelée même en cas d’annulation. Si vous souhaitez distinguer si quelque chose a été annulé ou non, vérifiez si is_being_cancelled() est True ou non.

Paramètres:: coro (TypeVar(FT, bound= Callable[..., Awaitable[Any]])) – La coroutine à enregistrer après la fin de la boucle.
Lève:: TypeError – La fonction n’était pas une coroutine.
Type renvoyé:: :sphinx_autodoc_typehints_type:`:py:class:`~typing.TypeVar`\ \(`````, bound= :py:data:``~typing.Callable`\\\\[:py:data:`…<Ellipsis>`, :py:class::`~typing.Awaitable`\\[:py:data:::`~typing.Any])`

@before_loop(coro)[source]¶

Un décorateur qui enregistre une coroutine à appeler avant le début de l’exécution de la boucle.

Ceci est utile si vous voulez attendre un état du bot avant le début de la boucle, comme discord.Client.wait_until_ready().

La coroutine ne doit prendre aucun argument (sauf self dans un contexte de classe).

Paramètres:: coro (TypeVar(FT, bound= Callable[..., Awaitable[Any]])) – La coroutine à enregistrer avant l’exécution de la boucle.
Lève:: TypeError – La fonction n’était pas une coroutine.
Type renvoyé:: :sphinx_autodoc_typehints_type:`:py:class:`~typing.TypeVar`\ \(`````, bound= :py:data:``~typing.Callable`\\\\[:py:data:`…<Ellipsis>`, :py:class::`~typing.Awaitable`\\[:py:data:::`~typing.Any])`

@error(coro)[source]¶

Un décorateur qui enregistre une coroutine à appeler si la tâche rencontre une exception non gérée.

La coroutine ne doit prendre qu’un seul argument l’exception levée (sauf self dans un contexte de classe).

Par défaut, cela imprime dans sys.stderr, mais cela peut être remplacé par une autre implémentation.

Ajouté dans la version 1.4.

Paramètres:: coro (TypeVar(ET, bound= Callable[[Any, BaseException], Awaitable[Any]])) – La coroutine à exécuter en cas d’exception non gérée.
Lève:: TypeError – La fonction n’était pas une coroutine.
Type renvoyé:: TypeVar(ET, bound= Callable[[Any, BaseException], Awaitable[Any]])

property seconds: float | None¶: Valeur en lecture seule représentant le nombre de secondes entre chaque itération. None si une valeur time explicite a été passée à la place.

Ajouté dans la version 2.0.

property minutes: float | None¶: Valeur en lecture seule représentant pour le nombre de minutes entre chaque itération. None si une valeur time explicite a été passée à la place.

Ajouté dans la version 2.0.

property hours: float | None¶: Valeur en lecture seule représentant pour le nombre d’heures entre chaque itération. None si une valeur time explicite a été passée à la place.

Ajouté dans la version 2.0.

property time: list[time] | None¶: Liste en lecture seule des temps exacts auxquels cette boucle s’exécute. None si du temps relatifs a été passées a la place.

Ajouté dans la version 2.0.

property current_loop: int¶: L’itération actuelle de la boucle.

property next_iteration: datetime | None¶: Quand l’itération suivante de la boucle se produira.

Ajouté dans la version 1.3.

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

This function is a coroutine.

Appelle la fonction de rappel interne que la tâche détient.

Ajouté dans la version 1.6.

Paramètres:

*args (Any) – Les arguments à utiliser.
**kwargs (Any) – Les arguments de mot-clé à utiliser.

Type renvoyé:

Any

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

Démarre la tâche interne dans la boucle d’événement.

Paramètres:

*args (Any) – Les arguments à utiliser.
**kwargs (Any) – Les arguments de mot-clé à utiliser.

Lève:

RuntimeError – Une tâche a déjà été lancée et est en cours d’exécution.

Renvoie:

La tâche qui a été créée.

Type renvoyé:

Task[None]

stop()[source]¶

Empêche la tâche de s’exécuter proprement.

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

Note

Si la fonction interne lève une erreur pouvant être gérée avant la fin, elle sera réessayée jusqu’à ce qu’elle réussisse.

Si cela est indésirable, soit retirez la gestion des erreurs avant d’arrêter via clear_exception_types(), soit utilisez cancel() à la place.

Ajouté dans la version 1.2.

Type renvoyé:: None

cancel()[source]¶

Annule la tâche interne si elle est en cours d’exécution.

Type renvoyé:: None

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

Une méthode pratique pour redémarrer la tâche interne.

Note

En raison de la façon dont cette fonction fonctionne, la tâche n’est pas retournée comme start().

Paramètres:

*args (Any) – Les arguments à utiliser.
**kwargs (Any) – Les arguments de mot-clé à utiliser.

Type renvoyé:

None

add_exception_type(*exceptions)[source]¶

Ajoute les types d’exception à traiter pendant la logique de reconnexion.

Par défaut, les types d’exceptions gérés sont ceux traités par discord.Client.connect(), ce qui inclut de nombreux types d’erreurs de déconnexion Internet.

Cette fonction est utile si vous interagissez avec une bibliothèque tierce qui augmente son propre ensemble d’exceptions.

Paramètres:: *exceptions (type[BaseException]) – Une liste d’arguments de classes d’exception à gérer.
Lève:: TypeError – Une exception passée n’est soit pas une classe, soit elle n’est pas héritée de BaseException.
Type renvoyé:: None

clear_exception_types()[source]¶

Removes all exception types that are handled.

Note

Cette opération ne peut évidemment pas être annulée !

Type renvoyé:: None

remove_exception_type(*exceptions)[source]¶

Supprime les types d’exceptions qui ne sont pas gérés pendant la logique de reconnexion.

Paramètres:: *exceptions (type[BaseException]) – Une liste d’arguments de classes d’exception à gérer.
Renvoie:: Si toutes les exceptions ont bien été supprimées.
Type renvoyé:: bool

get_task()[source]¶

Récupère la tâche interne ou None s’il n’y en a pas.

Type renvoyé:: Task[None] | None

is_being_cancelled()[source]¶

Si la tâche est en cours d’annulation.

Type renvoyé:: bool

failed()[source]¶

Whether the internal task has failed.

Ajouté dans la version 1.2.

Type renvoyé:: bool

is_running()[source]¶

Check if the task is currently running.

Ajouté dans la version 1.4.

Type renvoyé:: bool

change_interval(*, seconds=0, minutes=0, hours=0, time=...)[source]¶

Modifie l’intervalle de temps de veille.

Ajouté dans la version 1.2.

Paramètres:

seconds (float) – Le nombre de secondes entre chaque itération.
minutes (float) – Le nombre de minutes entre chaque itération.
hours (float) – Le nombre d’heures entre chaque itération.
time (time | Sequence[time]) – Les heures exactes auxquelles exécuter cette boucle. Vous devez passer soit une liste non vide, soit une seule valeur de datetime.time. Cela ne peut pas être utilisé en conjonction avec les paramètres de temps relatifs. .. versionadded:: 2.0 .. note:: Les heures dupliquées seront ignorées et exécutées une seule fois.

Lève:

ValueError – Une valeur non valide a été donnée.
TypeError – Une valeur invalide pour le paramètre time a été passée, ou le paramètre time a été passé en conjonction avec des paramètres de temps relatifs.

Type renvoyé:

None

discord.ext.tasks.loop(*, seconds=..., minutes=..., hours=..., time=..., count=None, reconnect=True, loop=..., overlap=False)[source]¶

Un décorateur qui planifie une tâche en arrière-plan pour vous avec une logique de reconnexion optionnelle. Le décorateur renvoie une Loop.

Paramètres:

seconds (float) – Le nombre de secondes entre chaque itération.
minutes (float) – Le nombre de minutes entre chaque itération.
hours (float) – Le nombre d’heures entre chaque itération.
time (time | Sequence[time]) – Les heures exactes auxquelles exécuter cette boucle. Vous devez passer soit une liste non vide, soit une seule valeur de datetime.time. Les fuseaux horaires sont pris en charge. Si aucun fuseau horaire n’est spécifié pour les heures, il est supposé qu’elles représentent l’heure UTC. Cela ne peut pas être utilisé en conjonction avec les paramètres de temps relatifs. .. note:: Les heures dupliquées seront ignorées et exécutées une seule fois. .. versionadded:: 2.0
count (int | None) – Le nombre de boucles à faire, None si elle doit être une boucle infinie.
reconnect (bool) – Si vous voulez gérer les erreurs et redémarrer la tâche en utilisant un algorithme de back-off exponentiel similaire à celui utilisé dans discord.Client.connect().
loop (AbstractEventLoop) – The loop to use to register the task, if not given the default event loop is used via asyncio.get_event_loop() if it exists or one is created via asyncio.new_event_loop().
overlap (bool | int) –
Controls whether overlapping executions of the task loop are allowed. Set to False (default) to run iterations one at a time, True for unlimited overlap, or an int to cap the number of concurrent runs.

Ajouté dans la version 2.7.

Lève:

ValueError – Une valeur non valide a été donnée.
TypeError – La fonction n’est pas une coroutine, une valeur invalide a été passée pour le paramètre time, ou le paramètre time a été passé en conjonction avec des paramètres de temps relatifs.

Type renvoyé:

Callable[[TypeVar(LF, bound= Callable[..., Awaitable[Any]])], Loop[TypeVar(LF, bound= Callable[..., Awaitable[Any]])]]