Md Readme

README.md

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