Multithreaded python IRC socket bot. Warning: This readme may be out of date. Karkat is undergoing thorough modifications to his plugin structure. The majority of former features are currently not ported to the new interface- this is reasonably easy to do, but I have not done so as I am cleaning them all up before re-adding them. Please be patient, and feel free to do it yourself.
If not already installed, the following packages must be installed:
- Docopt
- Requests
- PyYaml
- PyLast
Run sudo pip3 install docopt pyyaml requests pylast
to install them.
Create a config file. A sample file (Sample.yaml) is provided. For convenience, a config generator mkconf.py is provided.
Some modules require api keys. Create a file apikeys.conf in the config directory. Put your keys in there in the format specified by the module. For the keys currently required to get karkat to run, the format is:
bit.ly:
user: USERNAME
key: APIKEY
youtube:
channel: CHANNEL-STRING
appid: APPID
secret: SECRET
wolfram:
key: API_KEY
last.fm:
key: API_KEY
secret: API_SECRET
Karkat is run via ./karkat.py <config>
. Other options are available, see the full argspec via ./karkat.py -h.
This file loads all the plugins and spawns the server object. You may put code to replace the plugin system here (if, e.g you want to run a different bot's plugins on it).
The information below this point is outdated.
This file contains the threads Karkat uses to operate. For every connection:
- There is 1 Printer thread and 1 Connection thread. Currently, the connection thread doesn't actually exist and is just stuck at the bottom of
karkat.py
- There is a dynamic-sized array of Caller threads, as dictated by the
GP_CALLERS
constant defined inkarkat.py
This file contains some helper functions to parse IRC messages. The callback class provides some decorators which affect the behaviour of how a callback is handled by the connection thread.
This file contains some general text manipulation utilities. The design aesthetic of Karkat encourages short, multi-line output over information-dense, word-wrapped output.
All of the like, features are here. Currently they're just execfile()
'd after everything else is defined, so uh, be careful with that.
It also only is run if the -f flag is passed in for some reason.
The basic callback takes the arguments (words, line)
where words is the line split by spaces, and line is the raw line from the server. Put the function in the corresponding entry in flist (where the keys are .lower()
'd word[1]
s).
@Callback.threadsafe
marks a function as threadsafe, which allows it to utilise the extra callables.@Callback.background
marks a function as a background function (i.e low priority) which sticks it in an alternate caller.@Callback.msghandler
changes the function signature of the callback to(Address, context, Message)
Only works for callbacks of the form ":Address TYPE target :message"
@command(trigger, args=None or regexp, key=str.lower, help=None or str)
changes the function signature of the callback to(message, [arg1, arg2...])
Triggers the function only when the data matches the form [!@]trigger regexp
.
trigger
may be a string or a list of triggers. The key kwarg can be used to specify the key for what triggers are considered equivelant.
args
is a regular expression, with each group representing a new argument to give to the function. If None, no argument is matched.
help
is a string sent in place of the function's output if trigger matches, but args do not.
Only works for NOTICEs and PRIVMSGs
Debugging mode can be enabled with the -d [threshhold]
option. This sends server input to stdout, as well as provides warnings when the dispatcher loop takes longer than 0.15 or threshhold
seconds to complete.
Karkat also provides two interpretters, a bash one which may be used by sending $ COMMAND
to the bot, or a python interpretter with access to the global namespace via >>> command
or """command"""
. Note: bolded text will be messaged back to the sending context.
- A list of features is available at http://www.tetrap.us/karkat
Karkat's base system is undergoing renovations. Better documentation will be made available when the callback system is completed.