A chatbot library for euphoria.io.
Project description
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 AttrDict s 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-event
s, send-event
s, error
s, or bounce-event
s), 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)
If unspecified, advanced_start
uses a filler function that does nothing, enabling the user to use entirely custom handlers for every API response.
Command Line Options
When running any bot in the command line, the user has access to a few options:
option | usage |
---|---|
-t , --test , --debug |
Used to debug dev builds. Sends bot to &test instead of its default room. |
--room ROOM , -r ROOM |
Sends bot to &ROOM instead of its default room. |
--password PASSWORD , -p PASSWORD |
Password to use should the room be locked. |
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.