Metadata-Version: 1.0
Name: Gnotty
Version: 0.2.5
Summary: Gnotty ties the knot between the web and IRC. It is a web client and message archive for IRC.
Home-page: http://github.com/stephenmcd/gnotty
Author: Stephen McDonald
Author-email: stephen.mc@gmail.com
License: BSD
Description: ======
        Gnotty
        ======
        
        Created by `Stephen McDonald <http://twitter.com/stephen_mcd>`_
        
        Gnotty ties the knot between the web and IRC. It is designed to assist
        open source projects that host an IRC channel for collaboration on
        their project.
        Gnotty is `BSD licensed <http://www.linfo.org/bsdlicense.html>`_.
        
        Gnotty is comprised of several parts. Primarily Gnotty provides a
        modern web client and server for communicating with an IRC channel via
        a web browser. The web server uses `gevent <http://www.gevent.org>`_
        and `WebSockets <http://en.wikipedia.org/wiki/WebSockets>`_, which
        provides the communication layer between the IRC channel and the web
        browser. Twitter's `Bootstrap <http://twitter.github.com/bootstrap/>`_
        is used to style the web interface, providing a fully responsive
        layout, suitable for use with mobile devices. Customisable templates
        are also provided for skinning the web interface.
        
        Check out the `Gnotty live demo <http://gnotty.jupo.org>`_ to see the
        web interface in action.
        
        Secondly, Gnotty provides the ability to run a highly customisable
        IRC bot. Different classes of bots can be configured on startup, and
        bots can perform different services such as message logging and
        interacting with users in the IRC channel. Bots also contain webhooks,
        which allows bots to receive and act on input over HTTP from external
        services.
        
        Gnotty also provides an optional Django application that archives IRC
        messages, for browsing and searching via a web interface. By default
        the IRC bot uses Python's logging module to provide configurable
        logging handlers for IRC messages. When the Django application is
        used, a logging handler is added that logs all IRC messages to the
        Django project's database. The Django application then provides all
        the necessary views and templates for messages to be searched by
        keyword, or browsed by date using a calendar interface.
        
        Note that the Django application is entirely optional. Gnotty can
        be run without using Django at all, as a stand-alone gevent web
        server that provides the web interface to an IRC channel, with
        configurable IRC bots.
        
        
        Installation
        ============
        
        The easiest way to install Gnotty is directly from PyPi using
        `pip <http://www.pip-installer.org>`_ by running the command below::
        
            $ pip install -U gnotty
        
        Otherwise you can obtain Gnotty from the
        `GitHub <https://github.com/stephenmcd/gnotty>`_ or
        `Bitbucket <https://bitbucket.org/stephenmcd/gnotty>`_ repositories,
        and install it directly from source::
        
            $ python setup.py install
        
        
        Configuration
        =============
        
        Gnotty is configured via a handful of settings. When integrated
        with Django, these settings can be defined in your Django project's
        ``settings.py`` module. When Gnotty is run as a stand-alone
        client, these same settings can be defined via the command-line, or
        in a separate Python configuration module. See the "Stand-Alone Web
        Client" section below for details.
        
          * ``GNOTTY_HTTP_HOST`` - HTTP host address to serve from.
            *string, default: 127.0.0.1*
          * ``GNOTTY_HTTP_PORT`` - HTTP port to serve from.
            *integer, default: 8080*
          * ``GNOTTY_IRC_HOST`` - IRC host address to connect to.
            *string, default: irc.freenode.net*
          * ``GNOTTY_IRC_PORT`` - IRC port to connect to.
            *integer, default: 6667*
          * ``GNOTTY_IRC_CHANNEL`` - IRC channel to join.
            *string, default: #gnotty*
          * ``GNOTTY_IRC_CHANNEL_KEY`` - Optional key required to access
            the IRC channel.
            *string, default: None*
          * ``GNOTTY_BOT_CLASS`` - Dotted Python path to the IRC client bot
            class to run.
            *string, default: gnotty.bots.BaseBot*
          * ``GNOTTY_BOT_NICKNAME`` - IRC nickname the logging client will
            use.
            *string, default: gnotty*
          * ``GNOTTY_BOT_PASSWORD`` - Optional IRC password for the bot.
            *string, default: None*
          * ``GNOTTY_LOGIN_REQUIRED`` - Django login required for all URLs
            (Django only)
            *boolean, default: False*
          * ``GNOTTY_DAEMON`` - run in daemon mode.
            *boolean, default: False*
          * ``GNOTTY_PID_FILE`` - path to write PID file to when in daemon
            mode.
            *string, default: [tmp]/gnotty-[http-host]-[http-port].pid*
          * ``GNOTTY_LOG_LEVEL`` - Log level to use. ``DEBUG`` will spew out
            all IRC data.
            *string, default: INFO*
        
        To be clear: the IRC host and port are for specifying the IRC server
        to connect to. The HTTP host and port are what will be used to host
        the gevent/WebSocket server.
        
        
        Django Integration
        ==================
        
        With the above settings defined in your Django project's
        ``settings.py`` module, a few more steps are required. As with most
        Django apps, add ``gnotty`` to your ``INSTALLED_APPS`` setting, and
        ``gnotty.urls`` to your project's ``urls.py`` module::
        
            # settings.py
            INSTALLED_APPS = (
                # other apps here
                'gnotty',
            )
        
            # urls.py
            from django.conf.urls.defaults import patterns, include, url
            urlpatterns = patterns('',
                # other patterns here
                ('^irc/', include('gnotty.urls')),
            )
        
        As you can see we've mounted all of the urls Gnotty provides under
        the prefix ``/irc/`` - feel free to use whatever suits you here. With
        this prefix, the URL on our Django development server
        `http://127.0.0.1:8000/irc/ <http://127.0.0.1:8000/irc/>`_ will load
        the chat interface to the IRC channel, along with a search form for
        searching the message archive, and links to browsing the archive by
        date.
        
        The final step when integrated with Django is to run the Gnotty
        server itself. The Gnotty server is backed by gevent, and will host
        the WebSocket bridge to the IRC channel. It will also start up the
        IRC bot that will connect to the channel, and log all of the messages
        in the channel to the database archive.
        
        Running the Gnotty server when integrated with Django is simply a
        matter of running the ``gnottify`` Django management command::
        
            $ python manage.py gnottify [options]
        
        Note that each of the configuration options can also be specified as
        arguments to the ``gnottify`` management command. The names and
        formats used in this context are the same as those described next for
        the stand-alone web client. Any options provided as command-line
        arguments take precendence over those defined in your Django project's
        ``settings.py`` module.
        
        The ``gnottify_runserver`` command is also included, which will run
        both the Gnotty server and Django's ``runserver`` command at once,
        which is useful during development.
        
        Stand-Alone Web Client
        ======================
        
        As mentioned, Gnotty can also be run as a stand-alone web client
        without using Django at all. In this mode, only the web interface to
        the IRC channel is provided, along with whichever IRC bot class is
        configured. Message logging can be configured using standard handlers
        for the ``logging`` module in Python's standard library.
        
        Once installed, the command ``gnottify`` should be available on your
        system, and all of the options described earlier can be provided as
        arguments to it::
        
            $ gnottify --help
            Usage: gnottify [options]
        
            Options:
              --version             show program's version number and exit
              -h, --help            show this help message and exit
              -a HOST, --http-host=HOST
                                    HTTP host address to serve from
                                    [default: 127.0.0.1]
              -p PORT, --http-port=PORT
                                    HTTP port to serve from
                                    [default: 8080]
              -A HOST, --irc-host=HOST
                                    IRC host address to connect to
                                    [default: irc.freenode.net]
              -P PORT, --irc-port=PORT
                                    IRC port to connect to
                                    [default: 6667]
              -C CHANNEL, --irc-channel=CHANNEL
                                    IRC channel to join
                                    [default: #gnotty]
              -K CHANNEL_KEY, --irc-channel-key=CHANNEL_KEY
                                    Optional key required to access the IRC channel
              -c DOTTED_PYTHON_PATH, --bot-class=DOTTED_PYTHON_PATH
                                    Dotted Python path to the IRC client bot class to run
                                    [default: gnotty.bots.LoggingBot]
              -n NICKNAME, --bot-nickname=NICKNAME
                                    IRC nickname the bot will use
                                    [default: gnotty]
               -x PASSWORD, --bot-password=PASSWORD
                                    Optional IRC password for the bot
                                    [default: None]
              -D, --daemon          run in daemon mode
              -k, --kill            Shuts down a previously started daemon
              -F FILE_PATH, --pid-file=FILE_PATH
                                    path to write PID file to when in daemon mode
              -l INFO|DEBUG, --log-level=INFO|DEBUG
                                    Log level to use. DEBUG will spew out all IRC
                                    data.
                                    [default: INFO]
              -f FILE_PATH, --conf-file=FILE_PATH
                                    path to a Python config file to load options from
        
        Note the final argument in the list, ``--conf-file``. This can be used
        to provide the path to a Python config module, that contains each of
        the settings described earlier. Any options provided via command-line
        arguments will take precedence over any options defined in the Python
        configuration module.
        
        
        Daemon Mode
        ===========
        
        Gnotty can be configured to run as a background process when the
        ``GNOTTY_DAEMON`` setting is set to ``True`` (the ``--daemon`` arg
        when running stand-alone). When in daemon mode, Gnotty will write its
        process ID to the absolute file path specfified by the
        ``GNOTTY_PID_FILE`` setting (the ``--pid-file`` arg when running
        stand-alone). If the PID file path is not configured, Gnotty will use
        a file name based on the HTTP host and port, in your operating
        system's location for temporary files.
        
        When run in daemon mode, Gnotty will check for an existing PID file
        and if found, will attempt to shut down a previously started server
        with the same PID file.
        
        
        IRC Bots
        ========
        
        When running, Gnotty hosts an IRC bot that will connect to the
        configured IRC channel. The ``gnotty.bots.BaseBot`` bot is run by
        default, which implements message logging and support for commands
        issued within the IRC channel, and webhooks, which allow the IRC
        bot to receive data over HTTP.
        
        You can implement your own IRC bot simply by subclassing
        ``gnotty.bots.BaseBot`` and defining the Python dotted path to it on
        startup, via the ``GNOTTY_BOT_CLASS`` setting (the ``--bot-class`` arg
        when running stand-alone).
        
        The ``gnotty.bots.BaseBot`` class is derived from the third-party
        ``irclib`` package's ``irc.client.SimpleIRCClient`` class (and
        translated into a Python new-style class for sanity). The IRC
        bot will have all of the same methods and events available as the
        ``SimpleIRCClient`` class.
        
        These are the built-in IRC bot classes provided by the
        ``gnotty.bots`` package:
        
          * ``gnotty.bots.BaseBot`` - The default bot class that implements
            logging and handling for commands and webhooks. Your custom bot
            should subclass this.
          * ``gnotty.bots.ChatBot`` - A bot that demonstrates interacting with
            the IRC channel by greeting and responding to other users.
            Requires the ``nltk`` package to be installed.
          * ``gnotty.bots.commits.CommitMixin`` - A base bot mixin for
            receiving commit information for version control systems via bot
            webhooks, and relaying the commits to the IRC channel. Used as the
            base for the ``GitHubBot`` and ``BitBucketBot`` bots.
          * ``gnotty.bots.GitHubBot`` - ``CommitMixin`` subclass for
            `GitHub <http://github.com>`_
          * ``gnotty.bots.BitBucketBot`` - ``CommitMixin`` subclass for
            `Bitbucket <http://bitbucket.org>`_
          * ``gnotty.bots.CommandBot`` - A bot that implements a handful
            of basic commands that can be issued by users in the channel.
          * ``gnotty.bots.RSSBot`` - A bot that watches RSS feeds and posts
            new items from them to the IRC channel.
          * ``gnotty.bots.Voltron`` - All of the available bots, merged into
            one `super bot <http://www.youtube.com/watch?v=tZZv5Z2Iz_s>`_.
        
        Take a look at the source code for the ``gnotty.bots`` package. You'll
        see that the different features from all of the available bots are
        implemented as mixins, which you can mix and match together when
        building your own bot classes.
        
        
        Bot Events
        ==========
        
        Gnotty's IRC bots make use of an event handling system. Event handlers
        are implemented as methods on any of the classes used to build a bot.
        Each event handler gets wrapped with the decorator
        ``gnotty.bots.events.on``, which takes a single positional argument for
        the event name and marks the method as being a handler for that event.
        The decorator may also accept optional keyword arguments depending on
        the type of event. Several types of events are available:
        
          * IRC channel events, as implemented by the ``irclib`` package's
            ``irc.client.SimpleIRCClient`` class.
          * IRC commands, which are custom commands that can be triggered by
            users in the IRC channel. Each of these take a ``command`` keyword
            argument, which defines the command name.
          * Timer events, which are handlers that are periodically run at a
            defined time interval. Each of these take a ``seconds`` keyword
            argument, which defines the time interval.
          * Webhooks, which are handlers that accept data over HTTP. Each of
            take a ``urlpattern`` keyword argument which defines a regular
            expression to match against the webhook's URL, similar to Django's
            ``urlpatterns``.
        
        Here's an example IRC bot that implements all the above event types::
        
          from gnotty.bots import BaseBot, events
        
          class MyBot(BaseBot):
        
              @events.on("join")
              def my_join_handler(self, connection, event):
                  """IRC channel event - someone joined the channel."""
                  nickname = self.get_nickname(event)
                  self.message_channel("Hello %s" nickname)
        
              @events.on("timer", seconds=10)
              def my_timer(self):
                  """Do something every 10 seconds."""
                  msg = "Another 10 seconds has passed, are you annoyed yet?"
                  self.message_channel(msg)
        
              @events.on("command", command="!time")
              def my_time_command(self, connection, event):
                  """Write the time to the channel when someone types !time"""
                  from datetime import datetime
                  return "The date and time is %s" % datetime.now()
        
              @events.on("webhook", urlpattern="^/webhook/do/something/$")
              def my_webhook_handler(self, environ, url, params):
                  """Tell the channel that someone hit the webhook URL."""
                  ip = environ["REMOTE_ADDR"]
                  self.message_channel("The IP %s hit the URL %s" (ip, url))
        
        Given the above class in an importable Python module named ``my_bot.py``,
        Gnotty can be started with the bot using the following arguments::
        
          $ gnottify --http-host=127.0.0.1 --http-port=8000 --bot-class=my_bot.MyBot
        
        
        Channel Events
        ==============
        
        As described above, each of the IRC channel events implemented by the
        ``irclib`` package's ``irc.client.SimpleIRCClient`` class are available
        as event handlers for an IRC bot. Consult the ``irclib`` docs or source
        code for details about each of the IRC channel events that are
        implemented, as documenting all of these is beyond the scope of this
        document. Here are some of the common events to get you started:
        
          - ``events.on("welcome")``: Bot has connected to the server but not
            yet joined the channel.
          - ``events.on("namreply")``: Bot receives the initial list of
            nicknames in the channel once joined.
          - ``events.on("join")``: Someone new joined the channel.
          - ``events.on("quit")``: Someone left the channel.
          - ``events.on("pubmsg")``: A message was sent to the channel.
        
        Each of the channel events receive a ``connection`` and ``event``
        argument, which are objects for the connection to the IRC server, and
        information about the event that occurred.
        
        
        Command Events
        ==============
        
        Event handlers for simple commands can be implemented using the
        ``command`` event name for the ``gnotty.bots.events.on`` decorator.
        The decorator then takes a ``command`` keyword argument, which is the
        command name itself. Command events are then triggered by any public
        messages in the channel that contain the command name as the first word
        in the message. Each subsequent word in the message after the command
        is then passed as a separate argument to the event handler method for
        the command. In each command event handler method, the bot can then
        perform some task, and return a message back to the channel.
        
        
        Timer Events
        ============
        
        These event handlers are defined using the ``timer`` event name for the
        ``gnotty.bots.events.on`` decorator, and simply run repeatedly at a
        given interval. A ``seconds`` keyword argument to the decorator defines
        the interval in seconds as an integer. Note that the ``seconds``
        keyword argument is used to ``sleep`` after each time the event handler
        is run, in order to implement the interval, so an interval of 30
        seconds won't necessarily run precisely twice per minute, since the
        event handler itself will take time to execute, particularly if it
        accesses external resources over a network.
        
        
        Webhook Events
        ==============
        
        IRC bots run by Gnotty contain the ability to receive data over HTTP
        via webhooks. Webhooks are methods defined on the bot class with the
        ``webhook`` event handler name specified for the
        ``gnotty.bots.events.on`` decorator. The decorator also requires a
        ``urlpattern`` keyword argument, which is a regular expression for
        matching the webhook URL.
        
        The gevent web server will intercept any URLs prefixed
        with the path ``/webhook/``, and pass the request onto the bot which
        will match the URL to any of the URL patterns defined by webhook event
        handlers on the running bot class. A webhook event handler receives
        the following arguments:
        
          * ``environ`` - The raw environment dict supplied by the gevent web
            server that contains all information about the HTTP request.
          * ``url`` - The actual URL accessed.
          * ``params`` - A dictionary containing all of the POST and GET data.
        
        Note that the ``url`` and ``params`` arguments are simply provided for
        extra convenience, as their values (and all other environment
        information) are already available via the ``environ`` argument.
        
        
        Message Logging
        ===============
        
        By default, each IRC message in the channel is logged by the IRC bot
        run by Gnotty. Logging occurs using `Python's logging module
        <http://docs.python.org/library/logging.html>`_, to the logger named
        ``irc.message``.
        
        Each log record contains the following attributes, where ``record`` is
        the log record instance:
        
          * ``record.server`` - The IRC server the message occurred on.
          * ``record.channel`` - The IRC channel the message occurred on.
          * ``record.nickname`` - The nickname of the user who sent the
            message.
          * ``record.msg`` - The actual message string itself.
          * ``record.join_or_leave`` - ``True`` if the record was for a user
            joining or leaving the channel, otherwise ``False``.
        
        Here's an example of adding an extra logging handler for IRC messages::
        
          from logging import getLogger, StreamHandler
        
          class MyLogHandler(StreamHandler):
              def emit(self, record):
                  # Do something cool with the log record.
                  print record.msg
        
          getLogger("irc.message").addHandler(MyLogHandler())
        
        
        JavaScript Client
        =================
        
        The web client that Gnotty provides includes all the necessary
        JavaScript files for communicating with the WebSocket server, such as
        Douglas Crockford's ``json2.js``, and the ``socket.io.js`` library
        itself. Also provided is the file ``gnotty.js`` which implements a
        couple of public functions used by the web interface. The first is the
        ``gnotty`` JavaScript function, which deals directly with the HTML
        structure of the chat template::
        
            // Start up the default UI. This function isn't very
            // interesting, since it's bound to the HTML provided
            // by Gnotty's chat template.
            gnotty({
                httpHost:     '127.0.0.1',
                httpPort:     '8080',
                ircHost:      'irc.freenode.net',
                ircPort:      '6667',
                ircChannel:   '#gnotty'
            });
        
        The second interface is the ``IRCClient`` function. This is of
        particular interest if you'd like to create your own chat interface,
        as it deals exclusively with communication between the web browser and
        the WebSocket server. Here's an example client that simply writes
        events out to the console::
        
            // Prompt the user for a nickname and password,
            // and create an IRC client.
            var client = new IRCClient({
                httpHost:     '127.0.0.1',
                httpPort:     '8080',
                ircHost:      'irc.freenode.net',
                ircPort:      '6667',
                ircChannel:   '#gnotty',
                ircNickname:  prompt('Enter a nickname:')
                ircPassword:  prompt('Enter a password (optional):')
            });
        
            // When the client first joins the IRC channel,
            // send a message to the channel to say hello.
            client.onJoin = function() {
                console.log('joined the channel');
                client.message('Hello, is it me you\'re looking for?');
            };
        
            // When someone joins or leaves the channel, we're given the
            // entire user list. It'a an array of objects, each with a
            // nickname and color property.
            client.onNicknames = function(nicknames) {
                nicknames = $.map(nicknames, function(obj) {
                    return obj.nickname;
                }).join(', ');
                console.log('The user list changed, here it is: ' + nicknames);
            });
        
            // Whenever a message is received from the channel, it's an
            // object with nickname, message and color properties.
            client.onMessage = function(data) {
                console.log(data.nickname + ' wrote: ' + data.message);
            });
        
            // When we leave, reload the page.
            client.onLeave = function() {
                location.reload();
            };
        
            // The IRC server rejected the nickname.
            client.onInvalid = function() {
                console.log('Invalid nickname, please try again.');
            };
        
        As you may have guessed, the server-side settings configured for
        Gnotty are passed directly into the ``gnotty`` JavaScript function,
        which then creates its own ``IRCClient`` instance.
        
        You'll also see the data sent to the ``onMessage`` and ``onNickname``
        events contain color values that the interface can use for colorizing
        nicknames. These are calculated on the server, so that both the chat
        interface and message archive produce consistent colors every time
        a particular nickname is displayed.
        
        
        Hosting Private Chat Rooms
        ==========================
        
        Creating a private login-protected chat room for your team members
        to collaborate on is a breeze using Gnotty. By setting the
        ``GNOTTY_LOGIN_REQUIRED`` setting to ``True``, Gnotty will require
        each user to have a Django user account which they can authenticate
        with. The following steps should get you started:
        
          * Create a Django project with Gnotty installed, using the steps
            described above under `Django Integration`. Take a look at the
            ``example_project`` directory within Gnotty, which contains a
            working Django project with Gnotty configured.
          * Install an IRC server such as `ngIRCd <http://ngircd.barton.de/>`_.
            ngIRCd can be installed on both Linux or OSX with a single command
            (this works great for local development on OSX). Be sure to
            configure ngIRCd to only allow local connections, so that only
            Gnotty can connect to it.
        
        With the above setup, all that is then needed are the following
        Gnotty settings configured in your Django project's ``settings.py``
        module::
        
            GNOTTY_IRC_HOST = "127.0.0.1"
            GNOTTY_LOGIN_REQUIRED = True
            GNOTTY_IRC_CHANNEL = "#mychannel"  # This can be anything really.
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
