Skip to content

Latest commit

 

History

History
77 lines (51 loc) · 3.46 KB

README.md

File metadata and controls

77 lines (51 loc) · 3.46 KB
Raw

Cardinal

Meet Cardinal.

Build Status Coverage Status

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.