Programmer en python pour xchat - 1

Creer des commandes simples en python pour Xchat

Avec le plugin python pour xchat, il est tres simple de creer des commandes personnelles. Nous allons voir comment creer soi-meme un petit script qui vous permettra de comprendre comment creer celles de votre choix.

Pour commencer, nous allons faire un squelette de script python pour xchat.

#-------------------------------------------------------------------
__module_name__ = "Nom de notre script" 
__module_version__ = "Numero de version de notre script" 
__module_description__ = "Description de notre script"
__module_author__ = "Auteur de notre script"
#-------------------------------------------------------------------
import xchat
#-------------------------------------------------------------------
def fonction_cb(word, word_eol, userdata):


#-------------------------------------------------------------------
print "%s %s loaded" % (__module_name__, __module_version__)

Voyons voir chaque partie de notre script pour comprendre a quoi elle sert.

La premiere partie decrit le script que l'on cree.
Le "import xchat", qui charge le module xchat est indispensable pour que python charge l'api xchat
La derniere partie (le print), sert a afficher dans xchat que le script a bien ete chargé. Dans le cas present, ca vous affichera :

"Nom de notre script Numero de version de notre script loaded"

Reste la partie interressante, le script a proprement parler. Avec la ligne def fonction_cb(word, word_eol, userdata):, nous definissons une fonction qui s'appelle "fonction_cb". Pour appeller cette fonction, nous utilisont les fonctions HOOK de l'api xchat.

Dans le cas present, nous allons regarder la fonction xchat.hook.command qui va nous permettre d'ajouter des nouvelles commandes.
Imaginons que nous souhaitons creer une commande qui va "flooder" une personne en notices...
Pour cette commande, il faudra plusieurs arguments :

Le nombre de messages a envoyer

Le pseudo de la victime

Le message a envoyer

Nous appellerons cette commande "flood". Nous ajoutons donc a notre squelette la ligne suivante :

xchat.hook_command("FLOOD", fonction_cb, help="/flood <nombre> <pseudo> <message>\nEnvoit <nombre> de <message> en NOTICE a <pseudo>")

Cette ligne aura pour effet que, lorsque la commande /flood sera tapée dans xchat, elle executera la fonction "fonction_cb". Et lorsque vous taperez "/help flood", le texte contenu dans help="" sera affiché a l'ecran comme l'aide normale des commandes. Dans le texte d'aide, les caracteres \n servent a passer a la ligne. Nous placeront cette ligne a la fin du script, juste au dessus de "print".

Nous avons maintenant un script qui reconnais la commande flood et execute une fonction lorsqu'elle est appellee. Cette fonction necessitant plusieurs parametres, nous allons donc verifier sommairement l'existence d'au moins 3 parametres dans la commande.

if len(word) < 3:

        print "Cette fonction necessite au moins 3 parametres, tapez /help flood pour obtenir une aide."

else:

Comme il est expliqué dans la documentation python pour xchat, "word" contient les parametres que l'utilisateur a entré lors de la commande. "LEN(word)" determine le nombre de parametres dans la commande.

Comme c'est explique, word[0] correspond au nom de la commande, dans le cas present, "FLOOD"
word[1] doit etre le nombre de messages a envoyer
word[2] doit etre le pseudo de la cible
word_eol[3] est le message a envoyer (On utilise word_eol qui signifie : du mot word[3] jusqu'a la fin de la ligne)

Dans le cas present cette verification est quasiment inutile puisqu'on demande de taper un message a envoyer, le texte lui meme fera surement plus de 3 mots et cette verification n'aura que peu d'interet. Il aurait ete plus indiqué de creer une fonction pour verifier que le word[1] est bien un chiffre et que le word[2] est un pseudo existant, mais ne compliquons pas les choses pour l'instant (d'autant que j'ai la flemme de decrire tout ca). Vous devrez donc faire en sorte de ne pas vous tromper dans les parametres a transmettre lors de l'appel de la commande pour eviter d'avoir un message d'erreur.

Reste maintenant a envoyer la commandes en elle-meme. Nous allons donc creer un timer pour eviter de lagguer en envoyant les commandes. Considerons que le rythme maximum de commandes possibles a envoyer au serveur est de 2 secondes par commande.

xchat.command("timer -refnum 1 -repeat %s 2 notice %s %s" % (word[1] , word [2] , word_eol[3]))

La fonction xchat.command() :

Entre les parentheses on retrouve la commande a executer comme elle le sera dans xchat, sans le / avant.
Les %s sont les termes qui seront remplacés dans la commande par les valeures des variables que l'on trouve apres le %, entre parentheses. Ces %s sont mis dans l'ordre ou ils apparaissent.
Donc si on tape la commande "/flood 10 marcel flood qui pue dans ta face" dans xchat, word[1] vaudra "10", word[2] vaudra "marcel" et word_eol[3] vaudra "flood qui pue dans ta face". Ce qui donnera comme commande envoyée a xchat :

/timer -refnum 1 -repeat 10 2 notice marcel flood qui pue dans ta face

Il ne nous reste plus qu'a signaler que notre fonction est terminee avec la commande return.

L'option EAT_* va nous permettre de decider si xchat ou d'autres plugins/scripts peuvent voir les notices envoyées par celui ci ainsi que la commande utilisée

Si on ne veut pas qu'un autre plugin voit la commande, on choisit EAT_PLUGIN
Si on ne veut pas que xchat voit l'evenement (inutile dans le cas present, mais pourrait servir pour un hook_print), on utilise EAT_XCHAT
Si on ne veut pas que ni xchat, ni d'autres plugins voient l'evenement, on utilise EAT_ALL
Si on veut que xchat et les autres plugins puissent voir l'evenement, on utilise EAT_NONE

Dans le cas present, on va considerer qu'on ne veut pas qu'un autre plugin voit la commande, on utilisera donc EAT_ALL :

return xchat.EAT_ALL

Et voila, notre script est fini, et xchat dispose d'une nouvelle commande : flood. n'oublions pas que le python demande de respecter l'indentation des programmes, le code final sera donc le suivant :

__module_name__ = "Nom de notre script" 
__module_version__ = "1.0" 
__module_description__ = "Description de notre script"
__module_author__ = "Auteur de notre script"

import xchat

def fonction_cb(word, word_eol, userdata):

 if len(word) < 3:
  print "Cette fonction necessite au moins 3 parametres, tapez /help flood pour obtenir une aide."
 else:
  xchat.command("timer -refnum 1 -repeat %s 2 notice %s %s" % (word[1] , word [2] , word_eol[3]))
 return xchat.EAT_ALL


xchat.hook_command("FLOOD", fonction_cb, help="/flood <nombre> <pseudo> <message>\nEnvoie <nombre> de <message> en NOTICE a <pseudo>")
print "%s %s loaded" % (__module_name__, __module_version__) 
 

Bien sur ce script n'a absolument aucun interet, et il serait beaucoup plus simple et pratique de faire la meme chose avec l'option "commandes utilisateur" de xchat, ce n'est qu'un exemple pour vous permettre de creer vos propres commandes. De plus ce script est tout a fait mediocre dans la mesure ou la verification des variables est inadaptée, et que le flood generé risque de vous faire lagguer si vous tapez un message pendant son execution ou si le parametrage de l'ircd ou la commande est utilisé impose aux utilisateurs une durée superieure a 2 secondes entre chaque message.




Reference : Page d'informations sur le plugin python pour xchat (en anglais)