Latest commit cad6b56
======== 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 firstname.lastname@example.org. 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@example.com:<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.