Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

Python library for

Project description


Karelia is a library of functions for connecting a bot to the Heim chat platform at



bot represents a single bot for

To create a bot which only responds to a single nick, call, room) which will return a bot object. Alternatively, to have a bot respond to multiple names, call[list, of, nicks], room) which will present as the first nick in the list, but respond to stock commands send to all nicks.

If specific action is required when the bot receives the !kill command, a function can be written by the user and assigned to bot.on_kill.


__init__(self, name, room): Inits the bot object


connect(self, stealth=False): Connects to specified room and sets nick.

bot.connect() will connect to the room and then cause the bot to appear on the nicklist. bot.connect(stealth=True) will connect to the room, but not set the nick for the bot.


change_nick(self, nick=''): change_nick sends the nick command to Heim servers.

If the bot only has a single nick:

  • bot.change_nick() will cause the bot to set its nick to the previously specified value
  • bot.change_nick("nick") will cause the bot to set its nick to nick and store nick for future reference.

If the bot has multiple nicks specified:

  • bot.changenick() will cause the bot to set its nick to the first nick in its list
  • bot.changenick("nick") will cause the bot to set its nick to nick and store nick as the first value in its list


get_uptime(self): Called by the !uptime command. Returns time since connect as string.


send(self, message, parent=''): Unless the bot is paused, sends the supplied message. The parent message can be specified: send(message, parent = parent_id).

If the message argument has type dict, it will be sent as a packet. Otherwise, it will be treated as the body of a message.

With format send(message, parent):

  • message: either a complete packet, or the a message in string form.
  • parent: the id of the message being replied to. If not specified, karelia will send the message as a new parent i.e. bottom-level message.

bot.send('Top-level message') will send that as a top-level message.

bot.send('It's a reply!','02aa8y85m7hts') will send that message as a reply to the message with id 02aa8y85m7hts.

bot.send({'type': 'log', 'data': {'n':1000}}) will send a log request for the thousand most recent messages posted to the room.


reply(self, message): Wrapper around bot.send()

Sends the only argument as a reply to the most recently parse()d message.


disconnect(self): Attempts to close the connection at self.conn. If unsuccessful, it will log and raise an Exception.


parse(self): parse() handles the commands specified in the Botrulez ( and those required to stay alive.

parse() is a blocking function - that is, it will always wait until it receives a packet from heim before returning.

On receiving a packet, it will reply to pings (both global and specific), offer uptime, pause and unpause the bot, respond to help requests (again, both global and specific) and antighost commands, and kills the bot.

For all commands with a name attached, it will reply if any of the names stored in self.names match.

The responses to all botrulez-mandated commands (with the exception of uptime, as The Powers That Be disapprove of dissident response formats to it) can be altered with the bot.stock_responses dict. The following values are available:

key default value
'ping' 'Pong!'
'short_help' (no response)
'long_help' (no response)
'paused' '/me has been paused'
'unpaused' '/me has been unpaused'
'killed' '/me has been killed'

Regardless of actions taken, it will return the unaltered packet. If an error occurs, it will return an exception.

Note: as of 2017-03-16 if killed, it will disconnect automatically and return the string 'Killed'. Note: as of 2018-06-22 if killed, it will log the killer, run bot.on_kill(), and then exit.


normalise_nick(self, nick): Return the known-standard form (i.e., lowercase with no whitespace) of the supplied nick.


log(self, **kwargs): logs as much information as possible to an external file.

Optionally, specify log(event = "Event to Log", logfile = "bot_logs.log"). Otherwise, logs will be written to a file with the following format: botname_room.log

Project details

Download files

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

Files for Karelia, version 2.1.1
Filename, size File type Python version Upload date Hashes
Filename, size Karelia-2.1.1-py3-none-any.whl (19.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size Karelia-2.1.1.tar.gz (5.5 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page