A chatbot library for euphoria.io.
Project description
DocLib
A chatbot library for euphoria.io.
Usage
Installation
WINDOWS USERS: YOU MUST INSTALL WSL AND RUN THIS ON IT IN ORDER FOR IT TO WORK
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. |
advanced |
False |
ADVANCED: if True , declares the bot as advanced, enabling the user to directly handle any API response (while still obeying botrulez) |
function |
None |
ADVANCED: specifies the universal advanced start handler function. |
sendable |
False |
If True , enables the bot to be sent to other rooms with the !send @bot &room command. |
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 and all return the API's reply as an AttrDict
:
Method | Parameters | Effect |
---|---|---|
send_msg |
parent (AttrDict or string), msgString (string) |
Sends msgString 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. |
copy_to |
roomName (string), password (string, default is an empty string) |
Copies the bot to &roomName , starting it in the background. |
initiate_pm |
id (string), bot (Bot , default None) |
Starts a PM with the user id , placing bot in said PM room if specified. Bot must be able to initiate PMs (i.e. be a host). |
To log errors and info, use botlog
with a message
string and the optional error
boolean. (note: NOT a Bot
subfunction)
Example:
Regex:
sampleBot.set_regexes({'^!alive$' : alive})
Function (defined above bot start)
def alive(chatbot, msg, matches):
chatbot.send_msg(parent = msg, msgString = '/me IS ALIVE!')
chatbot.set_nick('Thunder')
chatbot.send_msg(parent = msg, msgString = '/me crashes')
chatbot.set_nick('sampleBot')
Custom Handlers
To set custom function handlers for any API response (when not advanced
, 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.start()
Advanced Usage
Using an advanced
value of True
(whether in the bot's declaration or its start function) enables the user to set a universal handler for all API events, in addition to any custom handlers:
sampleBot.start(advanced = True, 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.