Pybot/Readme

From Botdom Wiki

Jump to: navigation, search
This page could be in the process of being Moved to the Botdom Documentation Wiki.
Go to this article on the Documentation Wiki!
→

It is suggested that this page should be moved to Botdom Documentation.

Please do not move the page by hand. It will be moved by an administrator with the full edit history. In the meantime, you may continue to edit the page as normal. You can discuss this decision on the talk page.

The readme worthy material for Pybot was spread in seperate files. Here they are:

Contents

README.NOW

The code is provided as-is.

I won't be responsible if it screws up your 'puter or 
you get banned by a dA admin coz of it.

Z
radiositysg@gmail.com

INSTALL

(Transcript from INSTALL file included in the Pybot package.)
How to install Pybot:

  1. Download the following and install.
    Requirements:
  2. Edit config.xml and replace <nick>user</nick> with your own nick and <authkey>authkey</authkey> with your own auth key.
    Inside the <autojoin></autojoin>, type all the channels the bot should autojoin (separated by space).
  3. Open cmd window (Start > Run > Type cmd), and change directory to the bot /db folder.
    1. Type sqlite3 pybot.db (opens sqlite3 console)
    2. From inside the sqlite3 console type this (replace yourusername with your deviantART username):
      INSERT INTO users (id, nick, isadmin) VALUES (1, 'yourusername', 1);
    3. Type .quit
  4. Change directory back to main bot folder and type python launch_win.py and, if all goes well, it should load and autojoin all channels as listed in config.xml.

API.txt

Plugin Methods
==============
 _Construct_ ()		# Called when plugin is loaded
 _RegisterEvents_ ()	# Called to register events
 _Destruct_ ()		# Called when ReloadPlugin or UnloadPlugin is called

Bot Methods
===========
 Action (msg, chan)
 AddAutoJoinChannel (chan)
 AddTriggerAlias (aliasname)
 Ban (user, chan)
 Connect (hostname="chat.deviantart.com", port=3900)
 Disconnect ()
 GetChannels ()
 GetNicklist ()
 GetNicklist (chan)
 SetLogin (nick, authkey)
 SetTrigger (trig)
 GetRevision ()
 Say (msg, chan)
 Msg (msg, chan)
 
 Kick (user, chan, reason)
 
 SetTopic (chan, topic)
 SetTitle (chan, title)
 Part (chan)
 Join (chan)
  
 GetTime ()
 GetUptime ()
 UpdateLastPing ()
 SendPing () 
 
 GetDb ()
 
 Helper Methods
 --------------
 ReadXMLFile (filename)
 
 HttpPost(host, path, data, type=None)
 HttpGet (host, path)

Events.txt

Event Handlers Types
====================

EVT_ONTEXT : OnText
Params: From, Message, Channel

EVT_TIMER : OnTimer
Params: Uptime

EVT_ONPROCESSITEM : OnProcessItem
Params: Data

EVT_ONLOGIN : OnLogin
Params: -None-

EVT_ONLOGIN_OK :OnLoginOK
Params: -None-

EVT_ONLOGIN_FAILED : OnLoginFailed
Params: Error

EVT_UNHANDLED_ERROR  :OnUnhandledError
Params: Command, CommandParams

EVT_ONSELFJOIN_OK : OnSelfJoinOK
Params: Channel

EVT_ONSELFJOIN_FAILED : OnSelfJoinFailed
Params: Channel, Error

EVT_ONSELFPART_OK : OnSelfPartOK
Params: Channel

EVT_ONSELFPART_FAILED : OnSelfPartFailed
Params: Channel, Error

EVT_ONSELFKICKED : OnSelfKicked
Params: By, Channel, Reason

EVT_ONGETMEMBERSLIST : OnGetMembersList
Params: MembersList

EVT_ONGETTOPIC : OnGetTopic

EVT_ONGETTITLE : OnGetTitle

EVT_ONGETUSERINFO : OnGetUserinfo

EVT_ONACTION : OnAction
Params: Channel, From, Message

EVT_ONJOIN : OnJoin
Params: Channel, Symbol, RealName, Typename, From, PrivClass

EVT_ONKICKED : OnKicked

EVT_ONPART :OnPart
Params: Channel, Nickname, Reason

EVT_ONBANNED : OnBanned
Params: Target, BannedBy, Channel

EVT_ONPRIVCHG :OnPrivchg
Params: Target, ChangedBy, Channel, NewPC

EVT_ONPING : OnPing
Params: -None- 

EVT_ONSERVERSHUTDOWN : OnServerShutdown

EVT_ONDISCONNECT  : OnDisconnect

EVT_ONUNHANDLEDSERVER_PROTOMSG : OnUnhandledServerProtocolMsg

EVT_ONINCOMINGDATA : OnIncomingData
Params: Data
        
EVT_ONAUTOJOINCHANNELS : OnAutoJoinChannels
Params: Channels

EVT_ONTRIGGER  : OnTrigger	# Already in by default
Params: Nick, Message, Channel, Args, Trigger

EVT_UNHANDLED_RECVMSG : OnUnhandledRecvMsg
Params: RecvMsg, Message

Writing a Plugin.txt

Writing a Plugin
================
Writing a plugin involves deriving a new class from the base PybotPlugin Class. 
There is also a few other basic rules to follow. If any of these aren't followed, the 
plugin will not be loaded and be skipped.

1) Plugin has to be called BotPlugin and be derived from the PybotPlugin class this way:

	class BotPlugin (PybotPlugin):

On the top of this, you will need to include the 2 required imports:

	from pybclasses import PybotPlugin
	from pybdefines import *
	
2) At the very least, each plugin needs to define the _Construct_ method:
	
The _Construct_ () Method will be called by the PybotPlugin class's __init__ constructor 
and this is where users setup their plugin initialization and settings.

Inside _Construct_ () you will need to at LEAST define the ClassName_ attribute. This will 
be used to internally refer to the plugin as well as used to launch the default OnTrigger 
method.

e.g.:	
	self.ClassName_ = "SamplePlugin"
	
This will be used to launch the plugin trigger via !SamplePlugin
You can define additional triggers to point to this plugin with the AddTrigger () method. 
No two identical trigger aliases can exist.

def AddTrigger (TriggerName, List of Groups Allowed to have access to this trigger, or "all" for everyone) 

e.g.:	
	def _Construct_ (self):
		self.AddTrigger ("kick", ["all"], True)
		self.AddTrigger ("ban", ["all"], True)
		
	def OnTrigger (self, params):
		trigger = params.get ('Trigger')
		
		if trigger == "kick":	# User typed !kick
			# Do some kicking function
		elif trigger == "ban":	# User typed !ban
			# Do some banning function
			
The OnTrigger event will be triggered every time a trigger command is issued. If a plugin 
of name "trigger" was not found, the bot will then look in the alias list to find if any 
trigger command was aliased. The 2nd parameter specifies the groups allowed to run this particular
trigger. The third parameter specifies if this trigger should be exected in its own thread whenever
the trigger is called. This way, certain triggers which requires the bot not to be blocked (such
as network functions) will continue but trivial ones like 8ball executes immediately.

3) Registering events
EVT_ONTRIGGER event is automatically registered by default when you add at least one trigger
via AddAlias. In order to  register additional events, you create the _RegisterEvents_() method.

When the bot detects this method within the plugin, it will register the events returned 
by the method in the form of a list.

e.g.:
    def _RegisterEvents_ (self):
        EventsList = [ {EVT_ONTEXT:True, EVT_TIMER:False} ]
        return EventsList
             
This would mean that your plugin requested the registration of 2 events, EVT_ONTEXT and EVT_TIMER.
The bot will then proceed to look for 2 methods to match the event above: OnText and OnTimer.
If the method was not found, the plugin event would be skipped. The boolean parameter within each 
event key/value pair indicates if this event should run in its own thread. In this example EVT_ONTEXT
is requested to be threaded. EVT_TIMER can not be set to threaded, so setting it to true will be ignored.
Every other events can be threaded.

To thread the EVT_ONTRIGGER event, you pass the third parameter as True.

After the events above have been registered, every time the bot recieves text (OnAction has its own event), the data
will be passed to the OnText ()	method.

Each event handler will be passed a dict variable "params". params's contents will vary between event handlers.

In the example OnText, it will recieve the following parameters:
Parameters: From, Message, Channel

From: Who sent the message,
Message: what the actual message text is
Channel: Which channel it came from.

To get the param, you simply do a dict .get method like so:
	params.get ('Channel')	# To get Channel parameter
	
Database Access
===============
To get a database connection to the SQLite db file, invoke the bot.GetDb() method. This will return a database connection.
You can then proceed to get a cursor and then execute an SQL statement.

e.g.
	myCursor = bot.GetDb ().cursor()
	myCursor.execute ("select * from mytable")
	myRecords = myCursor.fetchall ()
	
	for rec in myRecords:
		... do some stuff ..
	
Additional Events, its handlers and parameter list is listed in "/docs/Events.txt"
Retrieved from "http://botdom.com/wiki/Pybot/Readme"
Personal tools