Skip to main content

A chatbot library for

Project description


A chatbot library for



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')

Constructor Options

option default usage
nick none, this is required The nick the bot will enter the room with.
room "bots" The default room for the bot to be sent to.
owner "nobody" The owner/creator of the bot (you).
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: by @[owner].
It 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.
customArgs False ADVANCED: Removes the set of default command-line arguments for bots.
sendable False If True, enables the bot to be sent to other rooms with the !send @bot &room command.
human False If True, the bot shows up in the People list. If used improperly, this is against Euphoria's ToS.
killChildren False If True, when killed, the bot will kill any copies it has made as well.

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

sampleBot.set_regexes({r'^!command$': function,
  r'(?i)word': 'response',
    "message": "nick to use",
    "second message": "different nick"
    "first message",
    "second message"

Regex Formatting

DocLib uses the default python re library for regex formatting.

Custom Function Responses

Responses 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 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.
copy_to roomName (string), password (string, default is an empty string) Creates a new Bot object set to appear in &roomName and returns it. The user can then start it in a separate thread with the start_in_new_thread function.
initiate_pm id (string), bot (Bot, default None) Starts a PM with the user id, placing bot in said PM room if specified, else a copy of the bot receiving the command.
login email (string), password (string) Logs bot in as a user. Takes effect on reconnect, and the bot will show up in the People list.

To log errors and info, use Bot.log with a message string and the optional error boolean. (note: NOT a Bot subfunction) To choose between a set of responses to a command randomly (including dictionaries, strings, and even functions), use Bot.randomize_between(*responses).

The regex string for any command may be replaced with a function that takes the relevant AttrDict msg object and returns a boolean (True to respond, False to continue).



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.send_msg(parent = msg, msgString = '/me crashes')

Custom Handlers

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

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


sampleBot.set_handlers({"joinEvent": 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.


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


To start a bot in a new thread (useful for copies), use the start_in_new_thread function instead:


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, function = 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 default 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.

To add new arguments, use the bot's add_command_line_arg function as you would the default Python argparse.add_argument function. It returns the value of the added argument if provided a name parameter. To remove the default arguments, set customArgs in the Bot constructor to True.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

doclib-1.8.4.tar.gz (12.8 kB view hashes)

Uploaded source

Built Distribution

doclib-1.8.4-py3-none-any.whl (26.1 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page