Commits

Jason R. Coombs committed b0a132d

Added .rst extensions to changes and readme docs for better rendering. Include changes doc in long_description.

  • Participants
  • Parent commits bf9b21f
  • Tags 8.0

Comments (0)

Files changed (5)

CHANGES

-8.0
-===
-
-This release brings several backward-incompatible changes to the scheduled
-commands.
-
-* Refactored implementation of schedule classes. No longer do they override
-  the datetime constructor, but now only provide suitable classmethods for
-  construction in various forms.
-* Removed backward-compatible references from irc.client.
-* Remove 'arguments' parameter from scheduled commands.
-
-Clients that reference the schedule classes from irc.client or that construct
-them from the basic constructor will need to update to use the new class
-methods::
-
-  - DelayedCommand -> DelayedCommand.after
-  - PeriodicCommand -> PeriodicCommand.after
-
-Arguments may no longer be passed to the 'function' callback, but one is
-encouraged instead to use functools.partial to attach parameters to the
-callback. For example::
-
-    DelayedCommand.after(3, func, ('a', 10))
-
-becomes::
-
-    func = functools.partial(func, 'a', 10)
-    DelayedCommand.after(3, func)
-
-This mode puts less constraints on the both the handler and the caller. For
-example, a caller can now pass keyword arguments instead::
-
-    func = functools.partial(func, name='a', quantity=10)
-    DelayedCommand.after(3, func)
-
-Readability, maintainability, and usability go up.
-
-7.1.2
-=====
-
-* Issue #13: TypeError on Python 3 when constructing PeriodicCommand (and thus
-  execute_every).
-
-7.1.1
-=====
-
-* Fixed regression created in 7.0 where PeriodicCommandFixedDelay would only
-  cause the first command to be scheduled, but not subsequent ones.
-
-7.1
-===
-
-* Moved scheduled command classes to irc.schedule module. Kept references for
-  backwards-compatibility.
-
-7.0
-===
-
-* PeriodicCommand now raises a ValueError if it's created with a negative or
-  zero delay (meaning all subsequent commands are immediately due). This fixes
-  #12.
-* Renamed the parameters to the IRC object. If you use a custom event loop
-  and your code constructs the IRC object with keyword parameters, you will
-  need to update your code to use the new names, so::
-
-    IRC(fn_to_add_socket=adder, fn_to_remove_socket=remover, fn_to_add_timeout=timeout)
-
-  becomes::
-
-    IRC(on_connect=adder, on_disconnect=remover, on_schedule=timeout)
-
-  If you don't use a custom event loop or you pass the parameters
-  positionally, no change is necessary.
-
-6.0.1
-=====
-
-* Fixed some unhandled exceptions in server client connections when the client
-  would disconnect in response to messages sent after select was called.
-
-6.0
-===
-
-* Moved `LineBuffer` and `DecodingLineBuffer` from client to buffer module.
-  Backward-compatible references have been kept for now.
-* Removed daemon mode and log-to-file options for server.
-* Miscellaneous bugfixes in server.
-
-5.1.1
-=====
-
-* Fix error in 2to3 conversion on irc/server.py (issue #11).
-
-5.1
-===
-
-The IRC library is now licensed under the MIT license.
-
-* Added irc/server.py, based on hircd by Ferry Boender.
-* Added support for CAP command (pull request #10), thanks to Danneh Oaks.
-
-5.0
-===
-
-Another backward-incompatible change. In irc 5.0, many of the unnecessary
-getter functions have been removed and replaced with simple attributes. This
-change addresses issue #2. In particular:
-
- - Connection._get_socket() -> Connection.socket (including subclasses)
- - Event.eventtype() -> Event.type
- - Event.source() -> Event.source
- - Event.target() -> Event.target
- - Event.arguments() -> Event.arguments
-
-The `nm_to_*` functions were removed. Instead, use the NickMask class
-attributes.
-
-These deprecated function aliases were removed from irc.client::
-
- - parse_nick_modes -> modes.parse_nick_modes
- - parse_channel_modes -> modes.parse_channel_modes
- - generated_events -> events.generated
- - protocol_events -> events.protocol
- - numeric_events -> events.numeric
- - all_events -> events.all
- - irc_lower -> strings.lower
-
-Also, the parameter name when constructing an event was renamed from
-`eventtype` to simply `type`.
-
-4.0
-===
-
-* Removed deprecated arguments to ServerConnection.connect. See notes on the
-  3.3 release on how to use the connect_factory parameter if your application
-  requires ssl, ipv6, or other connection customization.
-
-3.6.1
-=====
-
-* Filter out disconnected sockets when processing input.
-
-3.6
-===
-
-* Created two new exceptions in `irc.client`: `MessageTooLong` and
-  `InvalidCharacters`.
-* Use explicit exceptions instead of ValueError when sending data.
-
-3.5
-===
-
-* SingleServerIRCBot now accepts keyword arguments which are passed through
-  to the `ServerConnection.connect` method. One can use this to use SSL for
-  connections::
-
-    factory = irc.connection.Factory(wrapper=ssl.wrap_socket)
-    bot = irc.bot.SingleServerIRCBot(..., connect_factory = factory)
-
-
-3.4.2
-=====
-
-* Issue #6: Fix AttributeError when legacy parameters are passed to
-  `ServerConnection.connect`.
-* Issue #7: Fix TypeError on `iter(LineBuffer)`.
-
-3.4.1
-=====
-
-3.4 never worked - the decoding customization feature was improperly
-implemented and never tested.
-
-* The ServerConnection now allows custom classes to be supplied to customize
-  the decoding of incoming lines. For example, to disable the decoding of
-  incoming lines,
-  replace the `buffer_class` on the ServerConnection with a version that
-  passes through the lines directly::
-
-    irc.client.ServerConnection.buffer_class = irc.client.LineBuffer
-
-  This fixes #5.
-
-3.4
-===
-
-*Broken Release*
-
-3.3
-===
-
-* Added `connection` module with a Factory for creating socket connections.
-* Added `connect_factory` parameter to the ServerConnection.
-
-It's now possible to create connections with custom SSL parameters or other
-socket wrappers. For example, to create a connection with a custom SSL cert::
-
-    import ssl
-    import irc.client
-    import irc.connection
-    import functools
-
-    irc = irc.client.IRC()
-    server = irc.server()
-    wrapper = functools.partial(ssl.wrap_socket, ssl_cert=my_cert())
-    server.connect(connect_factory = irc.connection.Factory(wrapper=wrapper))
-
-With this release, many of the parameters to `ServerConnection.connect` are
-now deprecated:
-
-    - localaddress
-    - localport
-    - ssl
-    - ipv6
-
-Instead, one should pass the appropriate values to a `connection.Factory`
-instance and pass that factory to the .connect method. Backwards-compatibility
-will be maintained for these parameters until the release of irc 4.0.
-
-3.2.3
-=====
-
-* Restore Python 2.6 compatibility.
-
-3.2.2
-=====
-
-* Protect from UnicodeDecodeError when decoding data on the wire when data is
-  not properly encoded in ASCII or UTF-8.
-
-3.2.1
-=====
-
-* Additional branch protected by mutex.
-
-3.2
-===
-
-* Implemented thread safety via a reentrant lock guarding shared state in IRC
-  objects.
-
-3.1.1
-=====
-
-* Fix some issues with bytes/unicode on Python 3
-
-3.1
-===
-
-* Distribute using setuptools rather than paver.
-* Minor tweaks for Python 3 support. Now installs on Python 3.
-
-3.0.1
-=====
-
-* Added error checking when sending a message - for both message length and
-  embedded carriage returns. Fixes #4.
-* Updated README.
-
-3.0
-===
-
-* Improved Unicode support. Fixes failing tests and errors lowering Unicode
-  channel names.
-* Issue #3541414 - The ServerConnection and DCCConnection now encode any
-  strings as UTF-8 before transmitting.
-* Issue #3527371 - Updated strings.FoldedCase to support comparison against
-  objects of other types.
-* Shutdown the sockets before closing.
-
-Applications that are currently encoding unicode as UTF-8 before passing the
-strings to `ServerConnection.send_raw` need to be updated to send Unicode
-or ASCII.
-
-2.0.4
-=====
-
-This release officially deprecates 2.0.1-2.0.3 in favor of 3.0.
-
-* Re-release of irc 2.0 (without the changes from 2.0.1-2.0.3) for
-  correct compatibility indication.
-
-2.0
-===
-
-* DelayedCommands now use the local time for calculating 'at' and 'due'
-  times. This will be more friendly for simple servers. Servers that expect
-  UTC times should either run in UTC or override DelayedCommand.now to
-  return an appropriate time object for 'now'. For example::
-
-    def startup_bot():
-        irc.client.DelayedCommand.now = irc.client.DelayedCommand.utcnow
-        ...
-
-1.1
-===
-
-* Added irc.client.PeriodicCommandFixedDelay. Schedule this command
-  to have a function executed at a specific time and then at periodic
-  intervals thereafter.
-
-1.0
-===
-
-* Removed `irclib` and `ircbot` legacy modules.
-
-0.9
-===
-
-* Fix file saving using dccreceive.py on Windows. Fixes #2863199.
-* Created NickMask class from nm_to_* functions. Now if a source is
-  a NickMask, one can access the .nick, .host, and .user attributes.
-* Use correct attribute for saved connect args. Fixes #3523057.
-
-0.8
-===
-
-* Added ServerConnection.reconnect method. Fixes #3515580.
-
-0.7.1
-=====
-
-* Added missing events. Fixes #3515578.
-
-0.7
-===
-
-* Moved functionality from irclib module to irc.client module.
-* Moved functionality from ircbot module to irc.bot module.
-* Retained irclib and ircbot modules for backward-compatibility. These
-  will be removed in 1.0.
-* Renamed project to simply 'irc'.
-
-To support the new module structure, simply replace references to the irclib
-module with irc.client and ircbot module with irc.bot. This project will
-support that interface through all versions of irc 1.x, so if you've made
-these changes, you can safely depend on `irc >= 0.7, <2.0dev`.
-
-0.6.3
-=====
-
-* Fixed failing test where DelayedCommands weren't being sorted properly.
-  DelayedCommand a now subclass of the DateTime object, where the command's
-  due time is the datetime. Fixed issue #3518508.
-
-0.6.2
-=====
-
-* Fixed incorrect usage of Connection.execute_delayed (again).
-
-0.6.0
-=====
-
-* Minimum Python requirement is now Python 2.6. Python 2.3 and earlier should use 0.5.0
-  or earlier.
-* Removed incorrect usage of Connection.execute_delayed. Added Connection.execute_every.
-  Fixed issue 3516241.
-* Use new-style classes.
+Changes
+-------
+
+8.0
+===
+
+This release brings several backward-incompatible changes to the scheduled
+commands.
+
+* Refactored implementation of schedule classes. No longer do they override
+  the datetime constructor, but now only provide suitable classmethods for
+  construction in various forms.
+* Removed backward-compatible references from irc.client.
+* Remove 'arguments' parameter from scheduled commands.
+
+Clients that reference the schedule classes from irc.client or that construct
+them from the basic constructor will need to update to use the new class
+methods::
+
+  - DelayedCommand -> DelayedCommand.after
+  - PeriodicCommand -> PeriodicCommand.after
+
+Arguments may no longer be passed to the 'function' callback, but one is
+encouraged instead to use functools.partial to attach parameters to the
+callback. For example::
+
+    DelayedCommand.after(3, func, ('a', 10))
+
+becomes::
+
+    func = functools.partial(func, 'a', 10)
+    DelayedCommand.after(3, func)
+
+This mode puts less constraints on the both the handler and the caller. For
+example, a caller can now pass keyword arguments instead::
+
+    func = functools.partial(func, name='a', quantity=10)
+    DelayedCommand.after(3, func)
+
+Readability, maintainability, and usability go up.
+
+7.1.2
+=====
+
+* Issue #13: TypeError on Python 3 when constructing PeriodicCommand (and thus
+  execute_every).
+
+7.1.1
+=====
+
+* Fixed regression created in 7.0 where PeriodicCommandFixedDelay would only
+  cause the first command to be scheduled, but not subsequent ones.
+
+7.1
+===
+
+* Moved scheduled command classes to irc.schedule module. Kept references for
+  backwards-compatibility.
+
+7.0
+===
+
+* PeriodicCommand now raises a ValueError if it's created with a negative or
+  zero delay (meaning all subsequent commands are immediately due). This fixes
+  #12.
+* Renamed the parameters to the IRC object. If you use a custom event loop
+  and your code constructs the IRC object with keyword parameters, you will
+  need to update your code to use the new names, so::
+
+    IRC(fn_to_add_socket=adder, fn_to_remove_socket=remover, fn_to_add_timeout=timeout)
+
+  becomes::
+
+    IRC(on_connect=adder, on_disconnect=remover, on_schedule=timeout)
+
+  If you don't use a custom event loop or you pass the parameters
+  positionally, no change is necessary.
+
+6.0.1
+=====
+
+* Fixed some unhandled exceptions in server client connections when the client
+  would disconnect in response to messages sent after select was called.
+
+6.0
+===
+
+* Moved `LineBuffer` and `DecodingLineBuffer` from client to buffer module.
+  Backward-compatible references have been kept for now.
+* Removed daemon mode and log-to-file options for server.
+* Miscellaneous bugfixes in server.
+
+5.1.1
+=====
+
+* Fix error in 2to3 conversion on irc/server.py (issue #11).
+
+5.1
+===
+
+The IRC library is now licensed under the MIT license.
+
+* Added irc/server.py, based on hircd by Ferry Boender.
+* Added support for CAP command (pull request #10), thanks to Danneh Oaks.
+
+5.0
+===
+
+Another backward-incompatible change. In irc 5.0, many of the unnecessary
+getter functions have been removed and replaced with simple attributes. This
+change addresses issue #2. In particular:
+
+ - Connection._get_socket() -> Connection.socket (including subclasses)
+ - Event.eventtype() -> Event.type
+ - Event.source() -> Event.source
+ - Event.target() -> Event.target
+ - Event.arguments() -> Event.arguments
+
+The `nm_to_*` functions were removed. Instead, use the NickMask class
+attributes.
+
+These deprecated function aliases were removed from irc.client::
+
+ - parse_nick_modes -> modes.parse_nick_modes
+ - parse_channel_modes -> modes.parse_channel_modes
+ - generated_events -> events.generated
+ - protocol_events -> events.protocol
+ - numeric_events -> events.numeric
+ - all_events -> events.all
+ - irc_lower -> strings.lower
+
+Also, the parameter name when constructing an event was renamed from
+`eventtype` to simply `type`.
+
+4.0
+===
+
+* Removed deprecated arguments to ServerConnection.connect. See notes on the
+  3.3 release on how to use the connect_factory parameter if your application
+  requires ssl, ipv6, or other connection customization.
+
+3.6.1
+=====
+
+* Filter out disconnected sockets when processing input.
+
+3.6
+===
+
+* Created two new exceptions in `irc.client`: `MessageTooLong` and
+  `InvalidCharacters`.
+* Use explicit exceptions instead of ValueError when sending data.
+
+3.5
+===
+
+* SingleServerIRCBot now accepts keyword arguments which are passed through
+  to the `ServerConnection.connect` method. One can use this to use SSL for
+  connections::
+
+    factory = irc.connection.Factory(wrapper=ssl.wrap_socket)
+    bot = irc.bot.SingleServerIRCBot(..., connect_factory = factory)
+
+
+3.4.2
+=====
+
+* Issue #6: Fix AttributeError when legacy parameters are passed to
+  `ServerConnection.connect`.
+* Issue #7: Fix TypeError on `iter(LineBuffer)`.
+
+3.4.1
+=====
+
+3.4 never worked - the decoding customization feature was improperly
+implemented and never tested.
+
+* The ServerConnection now allows custom classes to be supplied to customize
+  the decoding of incoming lines. For example, to disable the decoding of
+  incoming lines,
+  replace the `buffer_class` on the ServerConnection with a version that
+  passes through the lines directly::
+
+    irc.client.ServerConnection.buffer_class = irc.client.LineBuffer
+
+  This fixes #5.
+
+3.4
+===
+
+*Broken Release*
+
+3.3
+===
+
+* Added `connection` module with a Factory for creating socket connections.
+* Added `connect_factory` parameter to the ServerConnection.
+
+It's now possible to create connections with custom SSL parameters or other
+socket wrappers. For example, to create a connection with a custom SSL cert::
+
+    import ssl
+    import irc.client
+    import irc.connection
+    import functools
+
+    irc = irc.client.IRC()
+    server = irc.server()
+    wrapper = functools.partial(ssl.wrap_socket, ssl_cert=my_cert())
+    server.connect(connect_factory = irc.connection.Factory(wrapper=wrapper))
+
+With this release, many of the parameters to `ServerConnection.connect` are
+now deprecated:
+
+    - localaddress
+    - localport
+    - ssl
+    - ipv6
+
+Instead, one should pass the appropriate values to a `connection.Factory`
+instance and pass that factory to the .connect method. Backwards-compatibility
+will be maintained for these parameters until the release of irc 4.0.
+
+3.2.3
+=====
+
+* Restore Python 2.6 compatibility.
+
+3.2.2
+=====
+
+* Protect from UnicodeDecodeError when decoding data on the wire when data is
+  not properly encoded in ASCII or UTF-8.
+
+3.2.1
+=====
+
+* Additional branch protected by mutex.
+
+3.2
+===
+
+* Implemented thread safety via a reentrant lock guarding shared state in IRC
+  objects.
+
+3.1.1
+=====
+
+* Fix some issues with bytes/unicode on Python 3
+
+3.1
+===
+
+* Distribute using setuptools rather than paver.
+* Minor tweaks for Python 3 support. Now installs on Python 3.
+
+3.0.1
+=====
+
+* Added error checking when sending a message - for both message length and
+  embedded carriage returns. Fixes #4.
+* Updated README.
+
+3.0
+===
+
+* Improved Unicode support. Fixes failing tests and errors lowering Unicode
+  channel names.
+* Issue #3541414 - The ServerConnection and DCCConnection now encode any
+  strings as UTF-8 before transmitting.
+* Issue #3527371 - Updated strings.FoldedCase to support comparison against
+  objects of other types.
+* Shutdown the sockets before closing.
+
+Applications that are currently encoding unicode as UTF-8 before passing the
+strings to `ServerConnection.send_raw` need to be updated to send Unicode
+or ASCII.
+
+2.0.4
+=====
+
+This release officially deprecates 2.0.1-2.0.3 in favor of 3.0.
+
+* Re-release of irc 2.0 (without the changes from 2.0.1-2.0.3) for
+  correct compatibility indication.
+
+2.0
+===
+
+* DelayedCommands now use the local time for calculating 'at' and 'due'
+  times. This will be more friendly for simple servers. Servers that expect
+  UTC times should either run in UTC or override DelayedCommand.now to
+  return an appropriate time object for 'now'. For example::
+
+    def startup_bot():
+        irc.client.DelayedCommand.now = irc.client.DelayedCommand.utcnow
+        ...
+
+1.1
+===
+
+* Added irc.client.PeriodicCommandFixedDelay. Schedule this command
+  to have a function executed at a specific time and then at periodic
+  intervals thereafter.
+
+1.0
+===
+
+* Removed `irclib` and `ircbot` legacy modules.
+
+0.9
+===
+
+* Fix file saving using dccreceive.py on Windows. Fixes #2863199.
+* Created NickMask class from nm_to_* functions. Now if a source is
+  a NickMask, one can access the .nick, .host, and .user attributes.
+* Use correct attribute for saved connect args. Fixes #3523057.
+
+0.8
+===
+
+* Added ServerConnection.reconnect method. Fixes #3515580.
+
+0.7.1
+=====
+
+* Added missing events. Fixes #3515578.
+
+0.7
+===
+
+* Moved functionality from irclib module to irc.client module.
+* Moved functionality from ircbot module to irc.bot module.
+* Retained irclib and ircbot modules for backward-compatibility. These
+  will be removed in 1.0.
+* Renamed project to simply 'irc'.
+
+To support the new module structure, simply replace references to the irclib
+module with irc.client and ircbot module with irc.bot. This project will
+support that interface through all versions of irc 1.x, so if you've made
+these changes, you can safely depend on `irc >= 0.7, <2.0dev`.
+
+0.6.3
+=====
+
+* Fixed failing test where DelayedCommands weren't being sorted properly.
+  DelayedCommand a now subclass of the DateTime object, where the command's
+  due time is the datetime. Fixed issue #3518508.
+
+0.6.2
+=====
+
+* Fixed incorrect usage of Connection.execute_delayed (again).
+
+0.6.0
+=====
+
+* Minimum Python requirement is now Python 2.6. Python 2.3 and earlier should use 0.5.0
+  or earlier.
+* Removed incorrect usage of Connection.execute_delayed. Added Connection.execute_every.
+  Fixed issue 3516241.
+* Use new-style classes.

README

-Internet Relay Chat (IRC) protocol client library
--------------------------------------------------
-
-The home of irclib is:
-
-    http://bitbucket.org/jaraco/irc
-
-You can `download project releases from PyPI
-<http://pypi.python.org/pypi/irc>`_.
-
-Some legacy content is still available at the `foundational SourceForge site
-<http://sourceforge.net/projects/python-irclib/>`_.
-
-Tests are `continuously run <https://travis-ci.org/#!/jaraco/irc>`_ using
-Travis-CI.
-
-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/
-
-Installation
-============
-
-IRC requires Python 2.6 or newer (including Python 3).
-
-You have several options to install the IRC project.
-
-  * Use "easy_install irc" or "pip install irc" to grab the latest
-    version from the cheeseshop (recommended).
-  * Run "python setup.py install" (from the source distribution) or
-  * Run "paver install" (from repo checkout, requires paver) or
-  * Copy irc directory to appropriate site-packages directory.
-
-Client Features
-===============
-
-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:
-
-  * irc/client.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!
-
-  * irc/bot.py
-
-    An IRC bot implementation.
-
-  * irc/server.py
-
-    A basic IRC server implementation. Suitable for testing, but not
-    production quality.
-
-Examples
-========
-
-Example scripts in the scripts directory:
-
-  * irccat
-
-    A simple example of how to use the IRC client.  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
-
-    An example bot that uses the SingleServerIRCBot class from
-    irc.bot.  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 or "#test"
-instead of #test.
-
-Decoding Input
-==============
-
-By default, the IRC library does attempt to decode all incoming streams as
-UTF-8, but the author acknowledges that there are cases where decoding is
-undesirable or a custom decoding option is desirable. To support these cases,
-since irc 3.4.2, the ServerConnection class may be customized. The
-'buffer_class' attribute on the ServerConnection determines what class is used
-for buffering lines from the input stream. By default it is
-DecodingLineBuffer, but may be re-assigned with another class, such as irc
-client.LineBuffer, which does not decode the lines and passes them through as
-byte strings. The 'buffer_class' attribute may be assigned for all instances
-of ServerConnection by overriding the class attribute::
-
-    irc.client.ServerConnection.buffer_class = irc.client.LineBuffer
-
-or it may be overridden on a per-instance basis (as long as it's overridden before the connection is established)::
-
-    server = irc.client.IRC().server()
-    server.buffer_class = irc.client.LineBuffer
-    server.connect()
-
-
-Notes and Contact Info
-======================
-
-Enjoy.
-
-Maintainer:
-Jason R. Coombs <jaraco@jaraco.com>
-
-Original Author:
-Joel Rosdahl <joel@rosdahl.net>
+Internet Relay Chat (IRC) protocol client library
+-------------------------------------------------
+
+The home of irclib is:
+
+    http://bitbucket.org/jaraco/irc
+
+You can `download project releases from PyPI
+<http://pypi.python.org/pypi/irc>`_.
+
+Some legacy content is still available at the `foundational SourceForge site
+<http://sourceforge.net/projects/python-irclib/>`_.
+
+Tests are `continuously run <https://travis-ci.org/#!/jaraco/irc>`_ using
+Travis-CI.
+
+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/
+
+Installation
+============
+
+IRC requires Python 2.6 or newer (including Python 3).
+
+You have several options to install the IRC project.
+
+  * Use "easy_install irc" or "pip install irc" to grab the latest
+    version from the cheeseshop (recommended).
+  * Run "python setup.py install" (from the source distribution) or
+  * Run "paver install" (from repo checkout, requires paver) or
+  * Copy irc directory to appropriate site-packages directory.
+
+Client Features
+===============
+
+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:
+
+  * irc/client.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!
+
+  * irc/bot.py
+
+    An IRC bot implementation.
+
+  * irc/server.py
+
+    A basic IRC server implementation. Suitable for testing, but not
+    production quality.
+
+Examples
+========
+
+Example scripts in the scripts directory:
+
+  * irccat
+
+    A simple example of how to use the IRC client.  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
+
+    An example bot that uses the SingleServerIRCBot class from
+    irc.bot.  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 or "#test"
+instead of #test.
+
+Decoding Input
+==============
+
+By default, the IRC library does attempt to decode all incoming streams as
+UTF-8, but the author acknowledges that there are cases where decoding is
+undesirable or a custom decoding option is desirable. To support these cases,
+since irc 3.4.2, the ServerConnection class may be customized. The
+'buffer_class' attribute on the ServerConnection determines what class is used
+for buffering lines from the input stream. By default it is
+DecodingLineBuffer, but may be re-assigned with another class, such as irc
+client.LineBuffer, which does not decode the lines and passes them through as
+byte strings. The 'buffer_class' attribute may be assigned for all instances
+of ServerConnection by overriding the class attribute::
+
+    irc.client.ServerConnection.buffer_class = irc.client.LineBuffer
+
+or it may be overridden on a per-instance basis (as long as it's overridden before the connection is established)::
+
+    server = irc.client.IRC().server()
+    server.buffer_class = irc.client.LineBuffer
+    server.connect()
+
+
+Notes and Contact Info
+======================
+
+Enjoy.
+
+Maintainer:
+Jason R. Coombs <jaraco@jaraco.com>
+
+Original Author:
+Joel Rosdahl <joel@rosdahl.net>
 import setuptools
 
 def read_long_description():
-    with open('README') as f:
+    with open('README.rst') as f:
         data = f.read()
+    with open('CHANGES.rst') as f:
+        data += '\n\n' + f.read()
     return data
 
 importlib_req = ['importlib'] if sys.version_info < (2,7) else []