doclib 1.4

A chatbot library for euphoria.io.

DocLib

A chatbot library for euphoria.io.

Usage

Installation

To install, use pip or pip3:

pip3 install doclib

When beginning a new bot, import the Bot class:

from doclib import Bot

Basic Bots

A basic bot will be a Bot object, constructed with a nick(the bot's name, shown in the room), a room(where the bot is sent by default, defaults to bots or test in debug mode), and an owner(your euphoria username.):

sampleBot = Bot(nick = 'bugBot', room = 'test', owner = 'sample user')

Other Constructor Options

option	default	usage
password	blank string	room password (used for private rooms)
help	"[nick] is a bot made with Doctor Number Four's Python 3 bot library, DocLib (link: https://github.com/milovincent/DocLib) by @[owner].\nIt follows botrulez and does not have a custom !help message yet."	your custom !help command response. can also be set by adding a "^!help @[nick w/o spaces]$" command to your regexes
ping	"Pong!"	your custom !ping response.
important	False	if True, the bot will only be killable by a roomhost or the owner. NOT RECOMMENDED FOR SIMPLE BOTS OR BOTS PRONE TO SPAM.
killed	"/me has died"	your custom message sent when bot is !killed.
API_timeout	10	ADVANCED: number of API responses to check for command responses. You should not need to change this unless the room is particularly active.

Once constructed, the user should assign a regex dictionary for non-advanced use cases:

sampleBot.set_regexes({r'^!command$' : function, r'(?i)word' : 'response'})

Regex Formatting

DocLib uses the default python re library for regex formatting.

Custom Function Responses

Regexes with a function value run the function with a Bot object (chatbot), an AttrDict (msg), and the regex match object (matches). Functions can utilise any of the numerous Bot methods:

Method	Parameters	Effect
send_msg	parent (AttrDict or string), msg (string)	Sends msg as a reply to parent, where parent can either be a string containing the message id returned by the API or an AttrDict with the structure of a send-reply generated by the API (recommended: use the msg parameter given to your custom function)
set_nick	nick (string)	Sets the bot's name to nick
get_userlist	none	returns an array of user AttrDicts currently in the room, including bots, accounts, and agents.
move_to	roomName (string), password (string, default is an empty string)	Moves the bot to a different room, specified by roomName, and, if necessary, attempts to log into it using password.
restart	none	Restarts the bot.
kill	none	Kills the bot.

Example:

Regex:

sampleBot.set_regexes({'^!alive$' : alive})

Function (defined above bot start)

def alive(chatbot, msg, matches):
    chatbot.send_msg(parent = msg, msg = '/me IS ALIVE!')
    chatbot.set_nick('Thunder')
    chatbot.send_msg(parent = msg, msg = '/me crashes')
    chatbot.set_nick('sampleBot')

Custom Handlers

To set custom function handlers for any API response (when using simple_start, this does not include ping-events, send-events, errors, or bounce-events), use set_handler:

sampleBot.set_handler(eventString = "join-event", on_join)

All handler functions, including the universal function parameter for advanced_start, are passed the API response (msg) as an AttrDict every time the corresponding event is received. Custom handlers take precedence over advanced_start's universal handler.

Startup

Once the bot is set up and populated with commands, the user can connect and start it:

sampleBot.connect()
sampleBot.simple_start()

Advanced Usage

Using advanced_start instead of simple_start enables the user to set a universal handler for all API events, in addition to any custom handlers:

sampleBot.advanced_start(handler_function)