======== bosnobot

bosnobot is a Python IRC bot. It will pretty much do whatever you want it to do. It is very easy to get up and running.

Dependancies

Like most software there will be some dependancy. bosnobot currently depends on:

* Python 2.5.1 (Could work with pre-2.5, but not tested.)
* Twisted 2.4 (Twisted 2.4 ships with OS X 10.5, but I have also tested
  with 8.0.1.)

If you decide you want to use the built-in DatabaseLogger you will also need:

* SQLAlchemy 0.4.6

Installation

To get bosnobot on your local machine you will need to grab a clone of it from GitHub. To do this you should have git installed on your system. Once that is installed you can execute::

git clone git://github.com/brosner/bosnobot.git

This will create a new directory in your current working directory named bosnobot. You will then need to get bosnobot on your PYTHONPATH::

export PYTHONPATH=`pwd`/bosnobot

You are all set! In the future there will be a provided setup.py file that can take care doing the installation into site-packages.

Configuration

To get up and running you will need to have a settings file read to rock and roll. This file is a Python script that sets up the configuration for the bot.

Currently this file must be set in an environment variable, BOSNOBOT_SETTINGS_MODULE. Create the file bosnobot_settings.py somewhere on your PYTHONPATH. Then you can execute::

export BOSNOBOT_SETTINGS_MODULE=bosnobot_settings

BOT_NICKNAME

Default: '' (Empty string)

This will be the nickname that the bot uses to identify itself on the IRC server.

BOT_PASSWORD

Default: '' (Empty string)

The password associated with the nickname to verify your identity on the IRC server.

BOT_CHANNELS

Default: () (Empty tuple)

A tuple of channels the bot should auto-join once connected to the server. This could potentionally look like::

BOT_CHANNELS = (
    "#django",
)

BOT_IRC_SERVER

Default: '' (Empty string)

The IRC server the bot should establish a connection.

BOT_IRC_PORT

Default: 6667

The port on which BOT_IRC_SERVER listens on.

MESSAGE_HANDLERS

Default: () (Empty tuple)

A tuple of strings that indicate the Python class to use as a message handler. bosnobot comes with a few message handlers. Let's say you want to log all messages to a database, this would look like::

MESSAGE_HANDLERS = (
    "bosnobot.message_handlers.database_logger.DatabaseLogger",
)

Be sure to read the message handler documentation before running with scissors with this setting. TODO: write that documentation.

Running the Bot

To run the bot based on its installation above you can simply execute::

python -m bosnobot

Need more help?

You can give our mailing list a shot on Google Groups (http://groups.google.com/group/bosnobot) or via e-mail [email protected].

We also hang out on freenode (irc.freenode.org) on the #bosnobot channel.

Contributing

When others contribute to an open-source project it makes it that much better. If you are so inclined to assist me with making bosnobot even better here is the run down you need to know.

bosnobot is hosted on GitHub. This makes it painless to fork bosnobot for development. Grab an account or just click the fork icon on GitHub. This will create a copy of the repo for your own use. Then hop into a shell and type::

git clone [email protected]:<your-user-name>/bosnobot.git

This will give you a local copy. Be sure to read git documentation if you have never used it before. I am really telling you what GitHub is doing, so go check out their documentation for more information.

Once you have done some super awesome patch you will want to notify brosner that your work is done. You can issue a pull request. This documentation has no idea how that works on GitHub. Maybe your first patch is fixing this file.