User:Hairr/Chatbot/Documentation

= 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.

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. If using Mac OS X, it is similar to this, but run in terminal. Execute  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: From here, you'll need to inherit the class into your bot's class: Now, you'll need to set up the initalizing parts in the class, this will connect the bot: After this, the bot has to be started. Starting is very simple to do when executing the file:: The complete file, without any other data, should look like so: 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: When a user joins the chat: When a user leaves the chat: When a user goes "away" in chat: When a user comes back from being "away" in chat: When a user is kicked from chat: When a user is banned from chat: When a user is given chat moderator rights from chat: When the bot joins the chat::

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


 * 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


 * Paramters:
 * user - User to kick


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


 * 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 (reason) - Reason of the ban


 * If the user/bot does not have the chatmoderator right, a ban will not perform


 * 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


 * 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.


 * user - User to give the chat moderator right to


 * 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 in the instances.


 * e.user  ​¶​


 * Retrieves the user of the event.


 * Return type: string


 * Note:,   and   return arrays with the users involved.


 * e.text  ​¶​


 * Retrieves the text from the message.


 * Return type: string or None


 * e.status  ​¶​


 * Retrieves the status of the user for  and.


 * Return type: string or None