irclib -- Internet Relay Chat (IRC) protocol client library

README 3.4KB

    irclib -- Internet Relay Chat (IRC) protocol client library<br>-----------------------------------------------------------<br><br>The home of irclib.py is now:<br><br> http://python-irclib.sourceforge.net<br><br>This library is intended to encapsulate the IRC protocol at a quite<br>low level. It provides an event-driven IRC client framework. It has<br>a fairly thorough support for the basic IRC protocol, CTCP and DCC<br>connections.<br><br>In order to understand how to make an IRC client, I'm afraid you more<br>or less must understand the IRC specifications. They are available<br>here:<br><br> http://www.irchelp.org/irchelp/rfc/<br><br>Requirements:<br><br> * Python 2.2 or newer.<br><br>Installation:<br><br> * Run "python setup.py install" or copy irclib.py and/or ircbot.py<br> to an appropriate Python module directory.<br><br>The main features of the IRC client framework are:<br><br> * Abstraction of the IRC protocol.<br> * Handles multiple simultaneous IRC server connections.<br> * Handles server PONGing transparently.<br> * Messages to the IRC server are done by calling methods on an IRC<br> connection object.<br> * Messages from an IRC server triggers events, which can be caught<br> by event handlers.<br> * Reading from and writing to IRC server sockets are normally done<br> by an internal select() loop, but the select()ing may be done by<br> an external main loop.<br> * Functions can be registered to execute at specified times by the<br> event-loop.<br> * Decodes CTCP tagging correctly (hopefully); I haven't seen any<br> other IRC client implementation that handles the CTCP<br> specification subtilties.<br> * A kind of simple, single-server, object-oriented IRC client class<br> that dispatches events to instance methods is included.<br> * DCC connection support.<br><br>Current limitations:<br><br> * The IRC protocol shines through the abstraction a bit too much.<br> * Data is not written asynchronously to the server (and DCC peers),<br> i.e. the write() may block if the TCP buffers are stuffed.<br> * Like most projects, documentation is lacking...<br><br>Unfortunately, this library isn't as well-documented as I would like<br>it to be. I think the best way to get started is to read and<br>understand the example program irccat, which is included in the<br>distribution.<br><br>The following files might be of interest:<br><br> * irclib.py<br><br> The library itself. Read the code along with comments and<br> docstrings to get a grip of what it does. Use it at your own risk<br> and read the source, Luke!<br><br> * irccat<br><br> A simple example of how to use irclib.py. irccat reads text from<br> stdin and writes it to a specified user or channel on an IRC<br> server.<br><br> * irccat2<br><br> The same as above, but using the SimpleIRCClient class.<br><br> * servermap<br><br> Another simple example. servermap connects to an IRC server,<br> finds out what other IRC servers there are in the net and prints<br> a tree-like map of their interconnections.<br><br> * testbot.py<br><br> An example bot that uses the SingleServerIRCBot class from<br> ircbot.py. The bot enters a channel and listens for commands in<br> private messages or channel traffic. It also accepts DCC<br> invitations and echos back sent DCC chat messages.<br><br> * dccreceive<br><br> Receives a file over DCC.<br><br> * dccsend<br><br> Sends a file over DCC.<br><br><br>NOTE: If you're running one of the examples on a unix command line, you need to escape the # symbol in the channel. For example, use \#test instead of #test.<br><br><br>Enjoy.<br><br>Maintainer:<br>keltus <keltus@users.sourceforge.net><br><br>Original Author:<br>Joel Rosdahl <joel@rosdahl.net><br>