Documentation & tutoriel de pynspircd (en français)

Pynspircd

Pynspircd est un framework qui permet la création de "fake-bots" sur un "fake-ircd" pour les réseaux irc utilisant Inspircd. Son fonctionnement est très simple : il suffit instancier la classe Pynspircd avec les bons arguments pour créer l'ircd et y connecter les bots. Les bots sont des classes dérivées de la classe Bot, ils prennent un certain nombre d'attribut, et possèdent des méthodes permettant de réagir aux commandes envoyées à l'ircd. Optionnellement, il est possible d'utiliser un serveur Web pour interagir avec les bots.

Pynspircd (la classe)

Exemple d'utilisation de la classe :

from pynspircd import Pynspircd

if __name__ == '__main__':
    ircd = Pynspircd('irc.example.com:5667', 'password', 'services.example.com')
    ircd.run()

Après ceci, un "fake-ircd" sera lancé, et linké au serveur irc.example.com (sur le port 5667). L'ircd portera le nom de services.example.com. La méthode constructeur de la classe Pynspircd peut prendre un certain nombre d'autres arguments...

Arguments

• hub : Adresse du hub (ircd) auquel se connecter sous le format hôte:port (ex: irc.example.com:5667).
• password : Mot de passe configuré dans la configuration du hub pour le link.
• hostname : Nom d'hôte du serveur Pynspircd sur le réseau.
• description : Description du serveur.
• hops : Nombre de 'hops' jusqu'au hub central (??a vérifier ??).
• bots : Liste de références vers les classes de bots à instancier au démarrage du serveur (ex : [Botserv, Memoserv, Chanserv]).
• httpd_prefix_length : Taille du préfixe pour le serveur web embarqué (voir plus bas la partie sur le serveur web).
• httpd_ip : IP de l'interface sur laquelle le serveur HTTP va écouter.
• httpd_port : Port sur lequel le serveur HTTP va écouter.
• debug : Si 'True', le serveur affichera du joli texte de débuggage coloré :-).

L'API Pynspircd

Pynspircd offre plusieurs attributs et méthodes utiles pour le développement des bots. Elles sont accessible par les bots grace à l'attribut ''pynspircd''. Le fonctionnement de Pynspircd est en réalité séparé dans 4 classes distinctes : BotManager, qui comme son nom l'indique gère les bots (quels sont les bots en cours de fonctionnemet, sur quels channels sont-ils, etc.). Le ConnectionManager qui gère la connexion au hub. Le UsersManager qui gère les utilisateurs connectés au réseau IRC. Et le ChansManager qui gère les canaux existant sur le réseaux.

Le BotManager de Pynspircd est accessible par l'attribut Pynspircd.bots, le ConnectionManager par l'attribut Pynspircd.connection.

pynspircd.hostname

Contient le nom d'hôte du serveur Pynspircd.

pynspircd.hub

Contient l'adresse du hub sous le format adresse:port.

pynspircd.debugMessage(message, type='global', cont=False)

Permet d'afficher un message de débug sur la sortie standard quand le mode débug est activé.

'''Arguments :'''

• message : Message à afficher
• type : Peut être in (message entrant), out (message sortant), global (message générique), error (message d'erreur), continue (suite d'un message).
• cont : Peut être True ou False. Si True, le message n'est pas "terminé" (par un saut de ligne), on peut donc continuer d'écrire sur la ligne (avec type='continue')

pynspircd.connection.online

True ou False, indique si l'ircd est connecté au réseau IRC ou non.

pynspircd.connection.disconnect(message)

Déconnecte l'ircd du réseau IRC avec le ''message'' comme raison.

pynspircd.connection.sendMSG(message)

A utiliser pour envoyer une commande au hub. '''Il est fortement recommandé d'utiliser cette méthode pour l'envois de messages au hub, et non pas en accèdant directement au socket via pynspircd.connection.socket !!!'''

pynspircd.bots.bots

Liste des "objets" bots actuellement en fonctionnement.

pynspircd.bots.chanList

Dictionnaire des canaux utilisés sur l'ircd, chaque élément du dictionnaire contenant une liste des bots étant présent sur le canal.

Exemple :

{ '#pynspircd':[Bot1, Bot2],
'#test':[Bot3, Bot4] }

pynspircd.bots.joinChan(bot, channel)

Faire joindre un canal à un bot.

Arguments :

• bot : Objet bot à faire joindre.
• channel : Canal à joindre.

pynspircd.bots.searchBotWithNick(nick)

Recherche le bot qui porte le nickname ''nick'' et renvois son objet bot, ou ''None'' si aucun bot n'est trouvé.

pynspircd.bots.registerBot(bot_class, *args, **kwarg)

Enregistrer un nouveau bot sur le serveur. Le premier argument ''bot_class'' est la classe du bot à instancier. ''*args'' et **kwarg sont passés en argument à la méthode constructeur du bot. Lors de cette procédure, la méthode ''bot.firstTime() est d'abbord appelée juste après l'instanciation de la classe. Une fois que le bot est connectement "connecté" sur le réseau, la méthode bot.secondTime() est appelée. Si un bot portant le même nickname que le bot à enregistrer est déjà enregistré, la procédure échoue, elle renverra alors la valeur ''False''.

pynspircd.bots.unregisterBot(bot)

Désenregistrer le bot du serveur (le supprimer). Lors de cette procédure, la méthode bot.lastTime() est appelée juste avant que le bot ne parte de tout les canaux sur lesquels il est présent, puis soit détruit.

Programmation avancée

Il est possible de dériver la classe Pynspircd afin d'ajouter de nouveaux comportements lors de la reception de messages en provenance du hub. Par exemple, pour ajouter un comportement lors de reception d'un message JOIN (qui notifie du join d'un utilisateur sur un chan), il faut faire ceci :

from Pynspircd import Pynspircd
class MyPinspircd(Pynspircd):
    def cmd_join(self, emitter, cmd, args):
        print '%s est entré sur %s' % (emitter, args.split(' ')[0])

En résumé : il faut ajouter une méthode cmd_nomDeLaCommande (tout en minuscules).

Bots

Les fake-bots sont des classes dérivées de Bot. Elles portent un certain nombre d'attributs et de méthodes par défaut.

Attributs

Nom de l'attribut	Description	Valeur par défaut
nick	Nickname du bot sur le serveur (unique)	n/a
realname	Nom réel	Pynspircd fake-bot
ip	Adresse ip du bot (aucune signification, juste de l'affichage)	127.0.0.1
gecos	??	Vide
http_id	Identifiant sur le serveur HTTP, unique, voir la partie consacrée à l'HTTPD pour plus d'informations	Vide
modes	Liste de modes à appliquer au bot	['w', 's', 'i', 'x', 'b']
registeredCmds	Dictionnaire des commandes enregistrées (voir plus bas la partie sur les évènements)	Vide
hostname	Nom d'hôte du bot	Nom d'hôte de l'ircd
displayed_hostname	Nom d'hôte du bot (affiché)	Nom d'hôte de l'ircd
pynspircd	Référence vers l'objet Pynspircd	n/a (à ne pas modifier)

||'''Nom de l'attribut'''||'''Description'''||'''Valeur par défaut'''|| ||nick||Nickname du bot sur le serveur (unique)||n/a|| ||realname||Nom réel||Pynspircd fake-bot|| ||ip||Adresse ip du bot (aucune signification, juste de l'affichage)||127.0.0.1|| ||gecos||??||Vide|| ||http_id||Identifiant sur le serveur HTTP, unique, voir la partie consacrée à l'HTTPD pour plus d'informations||Vide|| ||modes||Liste de modes à appliquer au bot||['w', 's', 'i', 'x', 'b']|| ||registeredCmds||Dictionnaire des commandes enregistrées (voir plus bas la partie sur les évènements)||Vide|| ||hostname||Nom d'hôte du bot||Nom d'hôte de l'ircd|| ||displayed_hostname||Nom d'hôte du bot (affiché)||Nom d'hôte de l'ircd|| ||pynspircd||Référence vers l'objet Pynspircd||n/a (à ne pas modifier)||

Méthodes

||'''Nom de la méthode'''||'''Description'''||'''Utilisation'''|| ||changeNick(Nouveau nickname)||Changer de nick||A appeler|| ||firstTime()||Méthode appelée par Pynspircd juste après l'instanciation de la classe||A surcharger|| ||secondTime()||Méthode appelée par Pynspircd juste après l'enregistrement du bot sur le réseau irc||A surcharger||

Exemple de bot

Pour comprendre mieux l'utilisation de l'ap, voici un exemple de bot très simple qui enregistre les conversations des utilisateurs dans une simple liste.

class Logs(Bot):
    '''Bot d'enregistrement des conversations'''
    def firstTime(self):
        self.nick = 'Logs' # On définit le nom du bot (c'est le minimum)
        self.registeredCmds = dict(privmsg='logging') # On définit la méthode à appelé pour la commande PRIVMSG
        self.http_id = 'Conversations'
        self.logs = []

    def secondTime(self):
        self.pynspircd.debugMessage("Le bot d'enregistement des conversations est actif !")
        # debugMessage() permet d'afficher du texte sur la sortie standard en mode debug
        self.pynspircd.bots.joinChan(self, '#test')
        # pynspircd.bots.joinChan() permet de faire joindre un bot sur un canal

    def logging(self, emitter, command, args):
        '''Enregistrement des messages'''
        target, message = args.split(' ', 1)
        message = message[1:]
        self.logs.append((target, emitter, message))

    def act_view(self, **kwarg):
        '''Affichage des messages via l'interface web.
        Nous verrons plus en détail sur fonctionnement du
        serveur web dans la partie consacrée.'''
        logs = '<ul>\n'
        for line in self.logs:
            logs += '<li>%s &lt;-- &lt;%s&gt; %s</li>\n' % (line)
        logs += '</ul>'
        return logs