Project description

pmxbot is bot for IRC and Slack written in
Python. Originally built for internal use
at YouGov,
it’s been sanitized and set free upon the world. You can find out more details
on the project website.

Commands

pmxbot listens to commands prefixed by a ‘!’
If it’s a command, it knows it will reply, take an action, etc.
It can search the web, store quotes you, track karma, make decisions,
and do just about anything else you could want. It stores logs and quotes
and karma in either a sqlite or MongoDB
database, and there’s a web interface for reviewing the logs and karma.

Contains

pmxbot will respond to things you say if it detects words and phrases it’s
been told to recognize. For example, mention sql on rails.

Requirements

pmxbot requires Python 3. It also requires a few python packages as defined
in setup.py. Some optional dependencies are installed with
extras:

mongodb: Enable MongoDB persistence (instead of sqlite).

irc: IRC bot client.

slack: Slack bot client.

viewer: Enable the web viewer application.

Testing

pmxbot includes a test suite that does some functional tests written against
the Python IRC server and quite a few unit tests as well. Install
tox and run tox to invoke the tests.

Configuration

Configuration is based on very easy YAML files. Check out config.yaml in the
source tree for an example.

Usage

Once you’ve setup a config file, you just need to call pmxbot config.yaml
and it will join and connect. We recommend running pmxbot under
your favorite process supervisor to make it
automatically restart if it crashes (or terminates due to a planned
restart).

Custom Features

Setuptools Entry Points Plugin

pmxbot provides an extension mechanism for adding commands, and uses this
mechanism even for its own built-in commands.

To create a setuptools
entry point plugin, package your modules using
the setuptools tradition and install it alongside pmxbot. Your package
should define an entry point in the group pmxbot_handlers by including
something similar to the following in the package’s setup.py:

Web Interface

pmxbot includes a web server for allowing users to view the logs, read the
help, and check karma. You specify the host, port, base path, logo, title,
etc with the same YAML config file. Just run like pmxbotweb config.yaml
and it will start up. Like pmxbot, use of a supervisor is recommended to
restart the process following termination.

pmxbot as a Slack bot (native)

To use pmxbot as a Slack bot, install with pmxbot[slack],
and set slack token in your config to the token from your
Bot User. Easy, peasy.

pmxbot as a Slack bot (IRC)

As Slack provides an IRC interface, it’s easy to configure pmxbot for use
in Slack. Here’s how: