WakaBot – Créer un Module

< Retour au projet

Architecture du Module

Le module est composé d’un dossier contenant les fichiers `manifest.conf` et `__init__.py` :

<name>/
├──  manifest.conf
└──  __init__.py

Méta-données du Module

Le fichier `manifest.conf` sert à stocker les méta-données du module et se compose des sections et options suivantes :

[plugin]
# Nom du module
name = Test
# Mainteneur du module
author = Foo <foo@example.com>
# Version de l’API du WakaBot (pour connaître la compatibilité)
version = 1.0.0
# Description du module (utilisé pour l’aide)
description = C’est un exemple
# Module utilisable que par les administrateurs ?
operator-only = no

[command]
# Nom de la commande pour appeler le module
name = test
# Description des paramètres de la commande (utilisé pour l’aide)
parameters = [argument]…
# Alias disponibles pour appeler le module (séparé par des espaces)
aliases = t

Les options `description` et `parameters` seront utilisées par la commande `help` de WakaBot pour afficher comment utiliser le module.

Exemple, avec le fichier du dessus, on obtiendra le résultat suivant :

> .help test
test [argument]… – C’est un exemple (aliases: t)

Définition du Module

Le fichier `__init__.py` va contenir le code Python utilisé par WakaBot pour effectuer les actions disponibles.

💡 Il s’agit d’un script Python, donc il est possible d’étendre au besoin les fonctions pour en faire ce que l’on veut.

Les fonctions sont appelées avec l’argument `message` qui est une instance de l’objet `WakabotMessage` du module `wakabot.message`.

Ces fonctions retournent toutes une liste de chaînes de caractères, qui seront affichées par le robot sur le salon dans lequel l’évènement aura eu lieu.

# Répondre à une commande demandée par une personne
def call(message) -> list[str]:
    return []

# Intervenir quand une personne se connecte dans un salon
def join(message) -> list[str]:
    return []

# Intervenir quand une personne est éjectée d’un salon
def kick(message) -> list[str]:
    return []

# Réagir à un message envoyé par une personne sur un salon.
def listen(message) -> list[str]:
    return []

# Intervenir quand une personne quitte un salon ou le serveur
def part(message) -> list[str]:
    return []

💡 Il n’est pas nécessaire d’ajouter les fonctions, si le module n’en a pas besoin.

Voici la liste des attributs disponibles pour l’objet `message` reçu par chacune des fonctions :

class WakabotMessage:
    # Le nom du salon dans lequel le message a été envoyé
    room: str
    # Le nom de la personne qui a envoyé le message
    user: str
    # Le contenu du message
    text: str
    # Le nom du robot (pour détecter si le message vient du robot)
    bot_name: str
    # Les options du module venant du fichier de configuration de WakaBot
    config: ConfigParser | None
    # Le dossier de stockage dédié au module
    storage: Path | None

La méthode `get_config_from_storage` est aussi disponible pour récupérer une instance de configuration d’un fichier présent dans le stockage.

💡 Cette méthode est là pour gagner du temps, car c’est possible de le faire manuellement via `message.storage` et `ConfigParser`.

Elle fonctionne de la manière suivante :

message.get_config_from_storage("foo.ini", section="bar")

L’argument `section` permet de créer la section dans l’instance de configuration si elle n’y est pas.

Configuration du Module

Les modules peuvent être configuré depuis le fichier de configuration du WakaBot.

Les sections qui sont préfixées par le mot-clé `modules.` permettent de définir des options qui seront ensuite accessible depuis le module.

Par exemple, le module `test` aura une option `maximum-size` dont la valeur sera 5 :

[modules.test]
maximum-size = 5

Ces options seront ensuite accessible dans l’instance de l’objet `WakabotMessage` via l’attribut `config`. Il s’agit d’une instance de `ConfigParser`, donc les méthodes de cette classe sont accessibles.

La section dans laquelle seront enregistré les options venant du fichier de configuration est nommée `data`.

Par exemple, pour accéder à la valeur qu’on a spécifiée plus haut, il suffit de faire le code suivant dans une des méthodes d’évènements :

message.config.getint("data", "maximum-size", fallback=1)

–––

Liens permanents :

gemini://projects.kawateam.dev/wakabot/module.gmi

https://projects.kawateam.dev/wakabot/module.html