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

entry_points = {
    'pmxbot_handlers': [
        'plugin name = pmxbot.mymodule',
    ],
},

'plugin name = pmxbot.mymodule:initialize_func'

from pmxbot.core import command, contains, regexp, execdelay, execat`.

@command(aliases=('tt', 'tear', 'cry'))
def tinytear(rest):
  "I cry a tiny tear for you."
  if rest:
    return "/me sheds a single tear for %s" % rest
  else:
    return "/me sits and cries as a single tear slowly trickles down its cheek"

@contains("sqlonrails")
def yay_sor():
  karma.Karma.store.change('sql on rails', 1)
  return "Only 76,417 lines..."

@regexp("jira", r"(?<![a-zA-Z0-9/])(OPS|LIB|SALES|UX|GENERAL|SUPPORT)-\d\d+")
def jira(client, event, channel, nick, match):
    return "https://jira.example.com/browse/%s" % match.group()

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:

0. Install with pmxbot[irc].

1. Enable the IRC Gateway <https://slack.zendesk.com/hc/en-us/articles/201727913-Connecting-to-Slack-over-IRC-and-XMPP>.

2. Create an e-mail for the bot.

3. Create the account for the bot in Slack and activate its account.

4. Log into Slack using that new account and get the IRC gateway password <https://my.slack.com/account/gateways> for that account.

5. Configure the pmxbot as you would for an IRC server, but use these settings for the connection:

   message rate limit: 2.5 password: <gateway password> server_host: <team name>.irc.slack.com server_port: 6667

   The rate limit is necessary because Slack will kick the bot if it issues more than 25 messages in 10 seconds, so throttling it to 2.5 messages per second avoids hitting the limit.

6. Consider leaving ‘log_channels’ and ‘other_channels’ empty, especially if relying on Slack logging. Slack will automatically re-join pmxbot to any channels to which it has been /invited.

For Enterprise

Available as part of the Tidelift Subscription.

This project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use.

Learn more.