paulosgf/cardinal

A Python IRC bot, designed to make adding functionality quick and simple.

Meet Cardinal.

Cardinal is a Python Twisted IRC bot with a focus on ease of development. It features reloadable asynchronous plugins, Python decorators for commands and IRC events, simple persistent JSON data storage, and a well-documented API.

You can join #cardinal on the DarkScience IRC network for questions or support. (irc.darkscience.net/+6697 — SSL required)

What can Cardinal do?

Anything, if you're creative! Cardinal does come with some plugins to get you started...

• Fetching URL titles
• Wolfram Alpha calculations
• Wikipedia definitions
• Urban Dictionary definitions
• Movie and TV show lookups
• Weather reports
• Reminders
• Google searches
• Now playing w/ Last.fm
• Stock ticker
• sed-like substitutions
• ... and more!

But the best part of Cardinal is how easy it is to add more!

Basic Usage

Configuration

1. Copy the config/config.example.json file to config/config.json (you can use another filename as well, such as config.freenode.json if you plan to run Cardinal on multiple networks).

2. Copy plugins/admin/config.example.json to plugins/admin/config.json and add your nick and vhost in order to take advantage of admin-only commands (such as reloading plugins, telling Cardinal to join a channel, or blacklisting plugins within a channel).

Running

Cardinal is run via Docker. To get started, install Docker and docker-compose.

If your config file is named something other than config/config.json, you will need to create a docker-compose.override.yml file like so:

version: "2.1"
services:
    cardinal:
        command: config/config_file_name.json

To start Cardinal, run docker-compose up -d. To restart Cardinal, run docker-compose restart. To stop Cardinal, run docker-compose down.

Writing Plugins

Cardinal was designed with ease of development in mind.

from cardinal.decorators import command, help

class HelloWorldPlugin:
    @command(['hello', 'hi'])
    @help("Responds to the user with a greeting.")
    @help("Syntax: .hello")
    def hello(self, cardinal, user, channel, msg):
        nick, ident, vhost = user
        cardinal.sendMsg(channel, "Hello {}!".format(nick))

entrypoint = HelloWorldPlugin

Cardinal also offers a lightweight database API. Visit the wiki for detailed information.

Contributing

Cardinal is a public, open-source project, licensed under the MIT License. Anyone may contribute.

When submitting a pull request, you may add your name to the CONTRIBUTORS file.