Awesome
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
-
Copy the
config/config.example.json
file toconfig/config.json
(you can use another filename as well, such asconfig.freenode.json
if you plan to run Cardinal on multiple networks). -
Copy
plugins/admin/config.example.json
toplugins/admin/config.json
and add yournick
andvhost
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.