Metadata-Version: 1.0
Name: pmxbot
Version: 1005
Summary: IRC bot - full featured, yet extensible and customizable
Home-page: http://bitbucket.org/yougov/pmxbot
Author: chmullig
Author-email: chmullig@gmail.com
License: MIT
Description: -*- restructuredtext -*-
        
        ======
        pmxbot
        ======
        
        pmxbot is an IRC bot written in python. Originally built for internal use,
        it's been sanitized and set free upon the world. You can find out  more details
        on the website, http://bitbucket.org/yougov/pmxbot, and especially the wiki
        https://bitbucket.org/yougov/pmxbot/wiki/Home
        
        
        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, quote you, track karma, make decisions,
        and do just about anything else you could want. It logs text in a sqlite3
        database, and eventually we'll write a web interface to it.
        
        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, of course. Probably 2.5+. It also requires a few python
        packages:
        
        * python-irclib
        * pyyaml
        * json (standard library for 2.6+) or simplejson
        * feedparser
        * httplib2
        * sqlite3
        
        The web interface requires cherrypy and jinja2.
        
        Optionally nosetests for the test suite.
        
        Testing
        =======
        We have a basic nose test suite that does some functional tests with an
        included TCL IRC daemon, and some basic unit tests as well. Just run them from
        the pmxbot root directory with "nosetests" and it should do it all for you.
        You'll need TCL and nosetests to do it though.
        
        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 djb's
        daemontools to make it automatically restart if it crashes. 
        
        
        Custom Features
        ===============
        
        Setuptools Entry Points Plugin
        ------------------------------
        
        To create a setuptools (or distribute or compatible packaging tool)
        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 = mylib.mymodule:initialize_func',
                ],
            },
        
        During startup (and after loading the traditional script-based plugins),
        pmxbot will load `mylib.mymodule` and call `initialize_func` from that
        module (with no parameters).
        `plugin_name` can be anything, but should be a name suitable to
        identify the plugin. It is not necessary that initialize_func do
        anything at all, but it must be present, and will be called during
        startup.
        
        Within the script you'll want to import the decorates you need to use with:
        `from pmxbot.botbase import command, contains, execdelay, execat`. You'll then
        decorate each function with the appropriate line so pmxbot registers it.
        
        A command (!g) gets the @command decorator::
        
          @command("tinytear", aliases=('tt', 'tear', 'cry'), doc="I cry a tiny tear for you.")
          def tinytear(client, event, channel, nick, rest):
          	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(client, event, channel, nick, rest):
          	karmaChange(botbase.logger.db, 'sql on rails', 1)
          	return "Only 76,417 lines..."
        
        For an example of how to implement a setuptools-based plugin, see
        the `wolframalpha plugin
        <http://bitbucket.org/yougov/pmxbot-wolframalpha>`_.
        
        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. I suggest using a tool like supervisor, daemontools,
        cherryd or somesuch to keep it running.
        
        
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 2.5
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Communications :: Chat :: Internet Relay Chat
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
