Plugin-based single-server IRC bot written in Python 3. This is a private project, meaning no promises of backwards compatibility and no guarantees of safety/security running the program yourself.
Instructions for linux-like systems only. If you use Windows, you're on your own.
Make sure you have python 3, pip and virtualenv installed. If either of the following commands return nothing, you don't have that thing installed and should google how install it.
$ which python3
/usr/bin/python3
$ which pip
/usr/local/bin/pip
$ which virtualenv
/usr/local/bin/virtualenv
Create a virtualenv (you only have to do this once):
$ virtualenv -p python3 .virtualenv
Activate the virtualenv:
$ source ./.virtualenv/bin/activate
Install requirements (you only have to do this once):
$ pip install -r requirements/base.txt
Copy config.example.yml
to config.yml
and edit it to your likings, then run the bot:
$ python -m botologist
Plugins can be added globally or to individual channels:
global_plugins:
- default
- twitter
channels:
mychannel:
plugins:
- koth
The name of the plugin corresponds to the name of the python file in the plugins
directory.
As long as the plugin class matches the module (file) name, you don't need to do anything more than that. For example, foo.py
should contain the class FooPlugin
. If the plugin class name differs from the module, you need to register an alias in the config. This can also be used to import plugins that are part of an external module.
plugins:
foo: plugins.foo.RandomlyNamedPlugin
bar: externalmodule.ExternalPlugin
global_plugins:
- foo
- bar
Just a plugin with simple functionality that doesn't deserve its own plugin.
Get the results of conversion queries like "100 kg to stones" or "100 eur in usd".
Run a king of the hill tournament (winner stays on). Admins have access to the following commands:
Regular users have access to these commands:
Admins have access to !addstream <stream_url>
and !delstream <stream_url>
.
Users have access to !sub <stream>
and !unsub <stream>
, which toggles notification via highlighting when that stream goes online. Note that notifications are stored in a dictionary of IRC hostmask => streams, so if your user changes hostmask, your subscriptions will be reset.
!sub
with no argument can be used to list your subscriptions. !streams
can be used to list currently online streams.
!elo <nick> [modes]
can be used to fetch a player's ELO from QLranks.com. [modes]
can be omitted, or be a comma-separated list of game modes to fetch ELO for. For example:
!elo raziel2p
!elo raziel2p tdm,ca
When a twitter link is pasted into IRC, fetches and announces the tweet body. Requires the twitter_api
config values to be present in config.yml
.
When a shortened link (is.gd, t.co, goo.gl etc) is posted, the real URL will be announced.
Install dev dependencies with pip install -r requirements/dev.txt
.
To run tests, pytest
. Note that not all parts of the code is under test, so do try to actually run the bot with your new functionaliy before you decide it's a success.
To run code linting, use pylint
. You have to specify which module to lint, so to lint everything, do pylint botologist plugins
. Note that linting will show some false positives, but important ones should show up in red.
How to effectively make a pull request:
git remote add fork git@github.com:my_user/botologist
git checkout -b my_branch
git push fork
When you've made one pull request, making the next one is simpler:
git checkout master
and git pull --ff-only origin master
(assuming "origin" is the original repository, not your fork). This will ensure that you aren't making changes based on an old version of the code.botologist/__main__.py
is the main entry point for running the bot. It reads the config file, sets up logging, instantiates the Bot object and starts the bot's IRC connection.
botologist/protocol
contains multiple protocol or client abstractions. These allow the bot to work with multiple chat protocols, though for now there's only 2: local (for testing locally) and IRC.
The botologist/bot.py
module contains 1 main class: botologist.bot.Bot
- which wraps the protocol client object and adds bot-like features such as keeping track of what users are present in channels, as well as the ability to add commands, replies and timed repeating tasks via plugins.
The core plugin classes and functionality is defined in botologist/plugin.py
. Various plugins extend the botologist.plugin.Plugin
class to provide a plugin. Plugins can be associated with channels via the config.yml
file.
Plugins define functionality such as commands, replies, join handlers and tickers via method decorators. The best way to see how to do this is to look at an existing plugin.
The contents of this repository are released under the MIT license. See the LICENSE file included for more information.