pmxbot


Namepmxbot JSON
Version 1122.15.0 PyPI version JSON
download
home_pagehttps://github.com/pmxbot/pmxbot
SummaryIRC bot - full featured, yet extensible and customizable
upload_time2023-06-25 04:05:08
maintainerJason R. Coombs
docs_urlNone
authorYouGov, Plc.
requires_python>=3.8
license
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            .. image:: https://img.shields.io/pypi/v/pmxbot.svg
   :target: https://pypi.org/project/pmxbot

.. image:: https://img.shields.io/pypi/pyversions/pmxbot.svg

.. image:: https://github.com/pmxbot/pmxbot/workflows/tests/badge.svg
   :target: https://github.com/pmxbot/pmxbot/actions?query=workflow%3A%22tests%22
   :alt: tests

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json
    :target: https://github.com/astral-sh/ruff
    :alt: Ruff

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black
   :alt: Code style: Black

.. image:: https://readthedocs.org/projects/pmxbot/badge/?version=latest
   :target: https://pmxbot.readthedocs.io/en/latest/?badge=latest

.. image:: https://img.shields.io/badge/skeleton-2023-informational
   :target: https://blog.jaraco.com/skeleton

.. image:: https://tidelift.com/badges/package/pypi/pmxbot
   :target: https://tidelift.com/subscription/pkg/pypi-pmxbot?utm_source=pypi-pmxbot&utm_medium=readme

pmxbot is bot for IRC and Slack written in
`Python <https://python.org>`_. Originally built for internal use
at `YouGov <https://yougov.com/>`_,
it's been sanitized and set free upon the world. You can find out more details
on `the project website <https://github.com/pmxbot/pmxbot>`_.

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
<https://packaging.python.org/installing/#installing-setuptools-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 <https://pypi.org/project/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 <https://github.com/pmxbot/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:

 - `motivation <https://github.com/pmxbot/motivation>`_.
 - `wolframalpha <https://github.com/jaraco/wolframalpha>`_.
 - `jaraco.translate <https://github.com/jaraco/jaraco.translate>`_.
 - `excuses <https://github.com/pmxbot/excuses>`_.

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 <https://api.slack.com/bot-users>`_. 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 <https://tidelift.com/subscription/pkg/pypi-pmxbot?utm_source=pypi-pmxbot&utm_medium=referral&utm_campaign=github>`_.

Security Contact
================

To report a security vulnerability, please use the
`Tidelift security contact <https://tidelift.com/security>`_.
Tidelift will coordinate the fix and disclosure.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/pmxbot/pmxbot",
    "name": "pmxbot",
    "maintainer": "Jason R. Coombs",
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "jaraco@jaraco.com",
    "keywords": "",
    "author": "YouGov, Plc.",
    "author_email": "dev@yougov.com",
    "download_url": "https://files.pythonhosted.org/packages/d3/a3/cca7d75f657cff90e75752116a9d0fd078c68b20030bdc3c9b0dc53228b9/pmxbot-1122.15.0.tar.gz",
    "platform": null,
    "description": ".. image:: https://img.shields.io/pypi/v/pmxbot.svg\n   :target: https://pypi.org/project/pmxbot\n\n.. image:: https://img.shields.io/pypi/pyversions/pmxbot.svg\n\n.. image:: https://github.com/pmxbot/pmxbot/workflows/tests/badge.svg\n   :target: https://github.com/pmxbot/pmxbot/actions?query=workflow%3A%22tests%22\n   :alt: tests\n\n.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json\n    :target: https://github.com/astral-sh/ruff\n    :alt: Ruff\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n   :target: https://github.com/psf/black\n   :alt: Code style: Black\n\n.. image:: https://readthedocs.org/projects/pmxbot/badge/?version=latest\n   :target: https://pmxbot.readthedocs.io/en/latest/?badge=latest\n\n.. image:: https://img.shields.io/badge/skeleton-2023-informational\n   :target: https://blog.jaraco.com/skeleton\n\n.. image:: https://tidelift.com/badges/package/pypi/pmxbot\n   :target: https://tidelift.com/subscription/pkg/pypi-pmxbot?utm_source=pypi-pmxbot&utm_medium=readme\n\npmxbot is bot for IRC and Slack written in\n`Python <https://python.org>`_. Originally built for internal use\nat `YouGov <https://yougov.com/>`_,\nit's been sanitized and set free upon the world. You can find out more details\non `the project website <https://github.com/pmxbot/pmxbot>`_.\n\nCommands\n========\n\npmxbot listens to commands prefixed by a '!'\nIf it's a command, it knows it will reply, take an action, etc.\nIt can search the web, store quotes you, track karma, make decisions,\nand do just about anything else you could want. It stores logs and quotes\nand karma in either a sqlite or MongoDB\ndatabase, and there's a web interface for reviewing the logs and karma.\n\nContains\n========\n\npmxbot will respond to things you say if it detects words and phrases it's\nbeen told to recognize. For example, mention sql on rails.\n\nRequirements\n============\n\n`pmxbot` requires Python 3. It also requires a few python packages as defined\nin setup.py. Some optional dependencies are installed with\n`extras\n<https://packaging.python.org/installing/#installing-setuptools-extras>`_:\n\n- mongodb: Enable MongoDB persistence (instead of sqlite).\n- irc: IRC bot client.\n- slack: Slack bot client.\n- viewer: Enable the web viewer application.\n\nTesting\n=======\n\n`pmxbot` includes a test suite that does some functional tests written against\nthe Python IRC server and quite a few unit tests as well. Install\n`tox <https://pypi.org/project/tox>`_ and run ``tox`` to invoke the tests.\n\nConfiguration\n=============\n\nConfiguration is based on very easy YAML files. Check out config.yaml in the\nsource tree for an example.\n\nUsage\n=====\n\nOnce you've setup a config file, you just need to call ``pmxbot config.yaml``\nand it will join and connect. We recommend running pmxbot under\nyour favorite process supervisor to make it\nautomatically restart if it crashes (or terminates due to a planned\nrestart).\n\nCustom Features\n===============\n\nSetuptools Entry Points Plugin\n------------------------------\n\n``pmxbot`` provides an extension mechanism for adding commands, and uses this\nmechanism even for its own built-in commands.\n\nTo create a setuptools\nentry point plugin, package your modules using\nthe setuptools tradition and install it alongside pmxbot. Your package\nshould define an entry point in the group ``pmxbot_handlers`` by including\nsomething similar to the following in the package's setup.py::\n\n    entry_points = {\n        'pmxbot_handlers': [\n            'plugin name = pmxbot.mymodule',\n        ],\n    },\n\nDuring startup,\npmxbot will load ``pmxbot.mymodule``. ``plugin name`` can be anything, but should\nbe a name suitable to identify the plugin (and it will be displayed during\npmxbot startup).\n\nNote that the ``pmxbot`` package is a namespace package, and you're welcome\nto use that namespace for your plugin (e.g.\n`pmxbot.nsfw <https://github.com/pmxbot/pmxbot.nsfw>`_).\n\nIf your plugin requires any initialization, specify an initialization function\n(or class method) in the entry point. For example::\n\n    'plugin name = pmxbot.mymodule:initialize_func'\n\nOn startup, pmxbot will call ``initialize_func`` with no parameters.\n\nWithin the script you'll want to import the decorator(s) you need to use with::\n\n    from pmxbot.core import command, contains, regexp, execdelay, execat`.\n\nYou'll\nthen decorate each function with the appropriate line so pmxbot registers it.\n\nA command (!g) gets the @command decorator::\n\n  @command(aliases=('tt', 'tear', 'cry'))\n  def tinytear(rest):\n    \"I cry a tiny tear for you.\"\n    if rest:\n      return \"/me sheds a single tear for %s\" % rest\n    else:\n      return \"/me sits and cries as a single tear slowly trickles down its cheek\"\n\nA response (when someone says something) uses the @contains decorator::\n\n  @contains(\"sqlonrails\")\n  def yay_sor():\n    karma.Karma.store.change('sql on rails', 1)\n    return \"Only 76,417 lines...\"\n\nEach handler may solicit any of the following parameters:\n\n - channel (the channel in which the message occurred)\n - nick (the nickname that triggered the command or behavior)\n - rest (any text after the command)\n\nA more complicated response (when you want to extract data from a message) uses\nthe @regexp decorator::\n\n    @regexp(\"jira\", r\"(?<![a-zA-Z0-9/])(OPS|LIB|SALES|UX|GENERAL|SUPPORT)-\\d\\d+\")\n    def jira(client, event, channel, nick, match):\n        return \"https://jira.example.com/browse/%s\" % match.group()\n\nFor an example of how to implement a setuptools-based plugin, see one of the\nmany examples in the pmxbot project itself or one of the popular third-party\nprojects:\n\n - `motivation <https://github.com/pmxbot/motivation>`_.\n - `wolframalpha <https://github.com/jaraco/wolframalpha>`_.\n - `jaraco.translate <https://github.com/jaraco/jaraco.translate>`_.\n - `excuses <https://github.com/pmxbot/excuses>`_.\n\nWeb Interface\n=============\n\npmxbot includes a web server for allowing users to view the logs, read the\nhelp, and check karma. You specify the host, port, base path, logo, title,\netc with the same YAML config file. Just run like ``pmxbotweb config.yaml``\nand it will start up. Like pmxbot, use of a supervisor is recommended to\nrestart the process following termination.\n\npmxbot as a Slack bot (native)\n==============================\n\nTo use pmxbot as a Slack bot, install with ``pmxbot[slack]``,\nand set ``slack token`` in your config to the token from your\n`Bot User <https://api.slack.com/bot-users>`_. Easy, peasy.\n\npmxbot as a Slack bot (IRC)\n===========================\n\nAs Slack provides an IRC interface, it's easy to configure pmxbot for use\nin Slack. Here's how:\n\n0. Install with ``pmxbot[irc]``.\n1. `Enable the IRC Gateway <https://slack.zendesk.com/hc/en-us/articles/201727913-Connecting-to-Slack-over-IRC-and-XMPP>`.\n2. Create an e-mail for the bot.\n3. Create the account for the bot in Slack and activate its account.\n4. Log into Slack using that new account and `get the IRC gateway\n   password <https://my.slack.com/account/gateways>` for that\n   account.\n5. Configure the pmxbot as you would for an IRC server, but use these\n   settings for the connection:\n\n    message rate limit: 2.5\n    password: <gateway password>\n    server_host: <team name>.irc.slack.com\n    server_port: 6667\n\n   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\n   second avoids hitting the limit.\n6. Consider leaving 'log_channels' and 'other_channels' empty, especially\n   if relying on Slack logging. Slack will automatically re-join pmxbot to\n   any channels to which it has been ``/invited``.\n\nFor Enterprise\n==============\n\nAvailable as part of the Tidelift Subscription.\n\nThis 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.\n\n`Learn more <https://tidelift.com/subscription/pkg/pypi-pmxbot?utm_source=pypi-pmxbot&utm_medium=referral&utm_campaign=github>`_.\n\nSecurity Contact\n================\n\nTo report a security vulnerability, please use the\n`Tidelift security contact <https://tidelift.com/security>`_.\nTidelift will coordinate the fix and disclosure.\n",
    "bugtrack_url": null,
    "license": "",
    "summary": "IRC bot - full featured, yet extensible and customizable",
    "version": "1122.15.0",
    "project_urls": {
        "Homepage": "https://github.com/pmxbot/pmxbot"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "d39ff0fc874f93c26754376032ba598bbd07c0844b8576c4d49078debd41af39",
                "md5": "9bcffd90e024b8dbc5808932a9087b19",
                "sha256": "8ac53384ab56a8e0ee7666e030023b62d98033c61aa81578cc36c9cbc2d30278"
            },
            "downloads": -1,
            "filename": "pmxbot-1122.15.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "9bcffd90e024b8dbc5808932a9087b19",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 156674,
            "upload_time": "2023-06-25T04:05:06",
            "upload_time_iso_8601": "2023-06-25T04:05:06.753967Z",
            "url": "https://files.pythonhosted.org/packages/d3/9f/f0fc874f93c26754376032ba598bbd07c0844b8576c4d49078debd41af39/pmxbot-1122.15.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "d3a3cca7d75f657cff90e75752116a9d0fd078c68b20030bdc3c9b0dc53228b9",
                "md5": "70f025c9608190371dad532ba80b776d",
                "sha256": "3b19dd2af7d1cae7370027e96c1d8b992119f63425a0cbd4a2cdfc8c7bde70b7"
            },
            "downloads": -1,
            "filename": "pmxbot-1122.15.0.tar.gz",
            "has_sig": false,
            "md5_digest": "70f025c9608190371dad532ba80b776d",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 205163,
            "upload_time": "2023-06-25T04:05:08",
            "upload_time_iso_8601": "2023-06-25T04:05:08.933999Z",
            "url": "https://files.pythonhosted.org/packages/d3/a3/cca7d75f657cff90e75752116a9d0fd078c68b20030bdc3c9b0dc53228b9/pmxbot-1122.15.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-06-25 04:05:08",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "pmxbot",
    "github_project": "pmxbot",
    "travis_ci": false,
    "coveralls": true,
    "github_actions": true,
    "requirements": [],
    "tox": true,
    "lcname": "pmxbot"
}
        
Elapsed time: 0.08530s