This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

IRC bot - full featured, yet extensible and customizable

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.

License

License is indicated in the project metadata (typically one or more of the Trove classifiers). For more details, see this explanation.

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:

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

During startup, pmxbot will load pmxbot.mymodule. plugin name can be anything, but should be a name suitable to identify the plugin (and it will be displayed during pmxbot startup).

Note that the pmxbot package is a namespace package, and you’re welcome to use that namespace for your plugin (e.g. pmxbot.nsfw).

If your plugin requires any initialization, specify an initialization function (or class method) in the entry point. For example:

'plugin name = pmxbot.mymodule:initialize_func'

On startup, pmxbot will call initialize_func with no parameters.

Within the script you’ll want to import the decorator(s) you need to use with:

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

You’ll then decorate each function with the appropriate line so pmxbot registers it.

A command (!g) gets the @command decorator:

@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"

A response (when someone says something) uses the @contains decorator:

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

Each handler may solicit any of the following parameters:

  • channel (the channel in which the message occurred)
  • nick (the nickname that triggered the command or behavior)
  • rest (any text after the command)

A more complicated response (when you want to extract data from a message) uses the @regexp decorator:

@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()

For an example of how to implement a setuptools-based plugin, see one of the many examples in the pmxbot project itself or one of the popular third-party projects:

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:

  1. Install with pmxbot[irc].

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

  3. Create an e-mail for the bot.

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

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

  6. 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.

  7. 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.

Release History

Release History

This version
History Node

1118.3.1

History Node

1118.3.0

History Node

1118.2.1

History Node

1118.2.0

History Node

1118.1.0

History Node

1118.0.4

History Node

1118.0.3

History Node

1118.0.2

History Node

1118.0.1

History Node

1118.0

History Node

1117.4.3

History Node

1117.4.2

History Node

1117.4.1

History Node

1117.4

History Node

1117.3.9

History Node

1117.3.8

History Node

1117.3.7

History Node

1117.3.6

History Node

1117.3.5

History Node

1117.3.4

History Node

1117.3.2

History Node

1117.3.1

History Node

1117.3

History Node

1117.2.4

History Node

1117.2.3

History Node

1117.2.2

History Node

1117.2.1

History Node

1117.2

History Node

1117.0.2

History Node

1117.0.1

History Node

1117.0

History Node

1116.0

History Node

1115.5

History Node

1115.4.1

History Node

1115.4

History Node

1115.3.2

History Node

1115.3.1

History Node

1115.3

History Node

1115.2.1

History Node

1115.2

History Node

1115.1

History Node

1115.0

History Node

1114.0

History Node

1113.6

History Node

1113.5

History Node

1113.4

History Node

1113.3

History Node

1113.2

History Node

1113.1

History Node

1113.0

History Node

1112.2.2

History Node

1112.2.1

History Node

1112.2

History Node

1112.1

History Node

1112.0

History Node

1111.1

History Node

1111.0.2

History Node

1111.0.1

History Node

1111.0

History Node

1110.7.1

History Node

1110.7

History Node

1110.6

History Node

1110.5

History Node

1110.4.1

History Node

1110.4

History Node

1110.3.1

History Node

1110.3

History Node

1110.2

History Node

1110.1.1

History Node

1110.1

History Node

1110.0

History Node

1109.3

History Node

1109.2

History Node

1109.0

History Node

1108.4.1

History Node

1108.4

History Node

1108.3.1

History Node

1108.3

History Node

1108.2

History Node

1108.1

History Node

1108.0

History Node

1107.4

History Node

1107.2

History Node

1107.1

History Node

1107.0

History Node

1106.4.1

History Node

1106.4

History Node

1106.3

History Node

1106.2

History Node

1106.1.4

History Node

1106.1.3

History Node

1106.1.2

History Node

1106.1.1

History Node

1106.1

History Node

1106.0

History Node

1105.7

History Node

1105.6

History Node

1105.5

History Node

1105.4.2

History Node

1105.4.1

History Node

1105.4

History Node

1105.3.1

History Node

1105.3

History Node

1105.2.2

History Node

1105.2.1

History Node

1105.1.1

History Node

1105.0.1

History Node

1105.0

History Node

1104.4.3

History Node

1104.4.2

History Node

1104.4.1

History Node

1104.4

History Node

1104.3.1

History Node

1104.3

History Node

1104.2

History Node

1104.1

History Node

1104.0

History Node

1103.7.1dev

History Node

1103.7

History Node

1103.6.5

History Node

1103.6.4

History Node

1103.6.3

History Node

1103.6.2

History Node

1103.6.1

History Node

1103.6

History Node

1103.5.1

History Node

1103.4.5

History Node

1103.4.4

History Node

1103.4.3

History Node

1103.4.2

History Node

1103.4.1

History Node

1103.4

History Node

1103.3.2

History Node

1103.3.1

History Node

1103.3

History Node

1103.2

History Node

1103.1.10

History Node

1103.1.9

History Node

1103.1.8

History Node

1103.1.7

History Node

1103.1.6

History Node

1103.1.5

History Node

1103.1.4

History Node

1103.1.3

History Node

1103.1.2

History Node

1103.1.1

History Node

1103.1

History Node

1103.0.4

History Node

1103.0.3

History Node

1103.0.2

History Node

1103.0

History Node

1102.0

History Node

1101.9.2

History Node

1101.9.1

History Node

1101.8.2

History Node

1101.8.1

History Node

1101.8

History Node

1101.7.4

History Node

1101.7.3

History Node

1101.7.1

History Node

1101.7

History Node

1101.6

History Node

1101.6b1

History Node

1101.5

History Node

1101.4

History Node

1101.3

History Node

1101.3b1

History Node

1101.2

History Node

1101.1.4

History Node

1101.1.2

History Node

1101.1.1

History Node

1101.1

History Node

1101.0.1

History Node

1101.0

History Node

1100.8.5

History Node

1100.8.1

History Node

1100.6

History Node

1100.5.8

History Node

1100.5.7

History Node

1100.5.6

History Node

1100.5.5

History Node

1100.5.4

History Node

1100.5.3

History Node

1100.5.2

History Node

1100.5.1

History Node

1100.5

History Node

1100.3

History Node

1100.2

History Node

1100.1.1dev

History Node

1100.1

History Node

1100.0

History Node

1100b7

History Node

1100b4

History Node

1100b3

History Node

1100b2

History Node

1100b1

History Node

1005

History Node

1005b2

History Node

1005b1

History Node

1004.4

History Node

1004.3

History Node

1004.2

History Node

1004

History Node

1004-beta16

History Node

1004-beta15

History Node

1004-beta14

History Node

1004-beta13

History Node

1004-beta12

History Node

1004-beta11

History Node

1004-beta10

History Node

1004-beta8

History Node

1004-beta7

History Node

1004-beta6

History Node

1004-beta5

History Node

1004-beta4

History Node

1004-beta3

History Node

1004-beta2

History Node

1004-beta1

History Node

1003-beta5

History Node

1003-beta4

History Node

1003-beta3

History Node

1003-beta2

History Node

1003-beta1

History Node

1002

History Node

1002-beta3

History Node

1002-beta2

History Node

1002-beta

History Node

1001

History Node

1000

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
pmxbot-1118.3.1-py2.py3-none-any.whl (166.3 kB) Copy SHA256 Checksum SHA256 3.6 Wheel May 24, 2017
pmxbot-1118.3.1.tar.gz (193.3 kB) Copy SHA256 Checksum SHA256 Source May 24, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting