Documentation

Below is the documentation for setting up and using the chatbot module. To see a basic chatbot for better understanding of the documentation, please refer to the examples.

Requirements

To use this, there is one requirement:

• requests

The easiest way to install requests, is through the Python Package Index, so you can install the latest release with pip install requests.

If you don’t have pip, get pip!

Installing

Installing chatbot is very simple, if using pip (see above). If using windows, open up cmd.exe/command prompt and execute pip install chatbot. If using Mac OS X, it is similar to this, but run in terminal. Execute pip install chatbot in terminal.

To make sure the installation worked, execute the following in your cmd.exe/terminal window:

If you received an error, try executing the pip command again/make sure you successfully installed pip.

Setting up

To first begin your script, you’ll need to import the module:

import chatbot

From here, you’ll need to inherit the class into your bot’s class.:

class MyBot(chatbot.ChatBot):

Now, you’ll need to set up the initalizing parts in the class, this will connect the bot.:

class MyBot(chatbot.ChatBot):
        def __init__(self):
                chatbot.ChatBot.__init__(self, "username", "password", "http://wiki.wikia.com")

After this, the bot has to be started. Starting is very simple to do when executing the file:

if __name__ == '__main__':
        bot = MyBot()
        bot.start()

The complete file, without any other data, should look like so:

import chatbot

class MyBot(chatbot.ChatBot):
        def __init__(self):
                chatbot.ChatBot.__init__(self, "username", "password", "http://wiki.wikia.com")

if __name__ == '__main__':
        bot = MyBot()
        bot.start()

Now, you might be thinking: “Where did start() come from?” It comes from the inherited class. It gathers all the instances in the MyBot class (see below), as well as the data specified to run the bot. So, it’s very important to include that data!

If you’re worried of privacy when putting the password down, please know: There is no way of knowing the information. It is all stored on your computer and is sent to the wiki to login (exactly the same way you log into the wiki).

Instances

In the chat, users can send message, go away, kick another user, etc. The following are the instances, so an action be performed as a result. For better understanding of how to include the instances, please see the examples page.

On a message:

def on_message(self, c, e):
        """
        When a message is sent by a user, anything here will be performed.
        """
        pass

When a user joins the chat:

def on_join(self, c, e):
        """
        When a user joins the chat, anything here will be performed.
        """
        pass

When a user leaves the chat:

def on_leave(self, c, e):
        """
        When a user leaves the chat, anything here will be performed.
        """
        pass

When a user goes “away” in chat:

def on_away(self, c, e):
        """
        When a user goes away in chat, anything here will be performed.
        """
        pass

When a user comes back from being “away” in chat:

def on_back(self, c, e):
        """
        When a user comes back from being away in chat, anything here will be performed.
        """
        pass

When a user is kicked from chat:

def on_kick(self, c, e):
        """
        When a user is kicked from chat, anything here will be performed.
        """
        pass

When a user is banned from chat:

def on_ban(self, c, e):
        """
        When a user is banned from chat, anything here will be performed.
        """
        pass

When a user is given chat moderator rights from chat:

def on_chatmod(self, c, e):
        """
        When a user is given the chat moderator rights in chat, anything here will be performed.
        """
        pass

When the bot joins the chat:

def on_welcome(self, c, e):
        """
        When the bot joins the chat, anything here will be performed.
        """
        pass

Connection/Client

After connecting to the chatroom, there are several connection commands that will allow a user/bot to perform actions.

c.send(message)

Sends a message to the chatroom

Parameters:message – Message to be sent

c.go_away()

Goes “away” in the chatroom, as the bot will not go “away” by default

c.come_back()

Comes back from the chat room, after being away

c.kick_user(user)

Kicks a user from the chatroom

Parameters:user – User to kick

Note

If the user/bot does not have the chatmoderator right, a kick will not preform.

c.ban_user(user[, time=3600[, reason="Misbehaving in chat"]])

Bans a user from the chatroom.

Parameters:

• user – User to ban
• time (integer) – Time of ban, in seconds
• reason (string) – Reason of the ban

Note

if the user/bot does not have the chatmoderator right, a ban will not preform

c.end_ban(user[, reason="Ending chat ban"])

Ends a chatban for a user

Parameters:

• user – User to unban
• reason (string) – Reason of the unbanning

Note

If the user/bot does not have the chatmoderator right, the ban can not be ended

c.give_chatmod(user)

Gives the chatmoderator right to a user.

Parameters:user – User to give the chat moderator right to

Note

If the user/bot does not have the sysop right, the chatmoderator right can not be given

Events

In the chat room, there are few events that can be gathered for information

e.user

Retrieves the user of the event.

Note: on_kick, on_chatmod and on_ban return arrays with the users involved.

Return type:string

e.text

Retrieves the text from the message.

Return type:string or None

e.status

Retrieves the status of the user for on_away and on_back.

Return type:string or None