CHANGES.txt

@@ -1,2 +1,2 @@
-
-v0.1.0
+The list of changes can be found at:
+https://worblehat.github.io/FredIRC/history.html

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013, Tobias Marquardt
+Copyright (c) 2014, Tobias Marquardt
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.rst

@@ -1,25 +1,35 @@
 
 FredIRC
 =======
+
 FredIRC is an event-driven Python framework for
 `IRC (Internet Relay Chat) <http://en.wikipedia.org/wiki/Internet_Relay_Chat>`_
-bots. It aims to provide a high-level abstraction of
+bots. It provides a high-level abstraction of
 `IRC's internals <http://tools.ietf.org/search/rfc2812>`_, an easy-to-use API
 and convenient utilities related to bot development.
 
-FredIRC is open source and distributed under terms of the
-`BSD 2-Clause license <http://opensource.org/licenses/BSD-2-Clause>`_.
-
-Links:
-------
+| **Requires:** Python 3.3+
+| **License:** `2-clause BSD <http://opensource.org/licenses/BSD-2-Clause>`_
 
-* Releases: https://github.com/worblehat/FredIRC/releases
-* Documentation: https://worblehat.github.io/FredIRC
-* Source code: https://github.com/worblehat/FredIRC
-* Issue tracker: https://github.com/worblehat/FredIRC/issues
+.. warning:: While fully usable, FredIRC is still pre-1.0 software and has no
+   backwards compatibility guarantees until the 1.0 release occurs. Please make
+   sure to read the changelog carefully anytime you upgrade!
 
-Contact:
+Features
 --------
 
-Please use the `issue tracker <https://github.com/worblehat/FredIRC/issues>`_
-or contact me via mail (tm[at]tobix[dot]eu).
+The main features are:
+
+* Easy-to-use interface for IRC bots
+* Internal event-loop that dispatches high-level IRC events
+* Different kinds of tasks which can be scheduled by the user
+
+Links
+-----
+
+* `Homepage <https://worblehat.github.io/FredIRC>`_
+* `PyPI <https://pypi.python.org/pypi/FredIRC>`_
+* `Changelog <https://worblehat.github.io/FredIRC/history.html>`_
+* `Source Code <https://github.com/worblehat/FredIRC>`_
+* `Issue Tracker <https://github.com/worblehat/FredIRC/issues>`_
+

doc/source/api.rst

@@ -42,6 +42,12 @@ interest to anyone who uses FredIRC:
 .. no idea why we have to exclude __call__ although :special-members:
    is not specified
 
+``ChannelInfo`` Class
+---------------------
+.. autoclass:: fredirc.ChannelInfo
+    :members:
+    :undoc-members:
+
 ``Task`` Class
 --------------
 

doc/source/conf.py

@@ -47,16 +47,16 @@
 
 # General information about the project.
 project = 'FredIRC'
-copyright = '2014, Tobias Marquardt'
+copyright = '2014-2015, Tobias Marquardt'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.1.0'
+release = '0.3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -252,3 +252,5 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
+
+autodoc_member_order = 'bysource'

doc/source/guide.rst

@@ -114,7 +114,25 @@ to respond to someone who sends 'Hello Fred' to the channel:
 
         def handle_channel_message(self, channel, message, sender):
             if messsage.strip() == "Hello " + self.client.nick:
-                self.client.send_message("Hi " + sender + ". How are you?")
+                self.client.send_message(channel, "Hi " + sender + ". How are you?")
+
+Reconnect to the Server
+-----------------------
+
+Many IRC clients automatically reconnect to the server after unexpectedly
+loosing the connection. This behaviour is desirable for bots, too. To achieve
+this you can
+:py:meth:`handle disconnects <fredirc.IRCHandler.handle_disconnect()>` and call
+:py:meth:`reconnect()<fredirc.IRCClient.reconnect()>`.
+
+.. code-block:: python
+
+    class MyBot(BaseIRCHandler):
+
+        (...)
+
+        def handle_disconnect(self):
+            self.client.reconnect()
 
 .. _guide_handle-errors:
 
@@ -142,7 +160,7 @@ previous nick:
 
         def handle_error(self, num, **params):
             if num == Err.NICKNAMEINUSE:
-                new_nick = params['nick'] + Random().randint(1, 9)
+                new_nick = params['nick'] + str(Random().randint(1, 9))
                 self.client.register(nick = new_nick)
 
 The parameter ``num`` contains a number that can be used to identify the error
@@ -203,10 +221,14 @@ The complete code from above in one listing:
 
         def handle_channel_message(self, channel, message, sender):
             if messsage.strip() == "Hello " + self.client.nick:
-                self.client.send_message("Hi " + sender + ". How are you?")
+                self.client.send_message(channel, "Hi " + sender + ". How are you?")
+
+        def handle_disconnect(self):
+            self.client.reconnect()
 
         def handle_error(self, num, **params):
             if num == Err.NICKNAMEINUSE:
-                new_nick = params['nick'] + Random().randint(1, 9)
+                new_nick = params['nick'] + str(Random().randint(1, 9))
                 self.client.register(nick = new_nick)
 
+

doc/source/history.rst

@@ -1,7 +1,55 @@
 Changelog
 =========
 
+v0.3.0 (2015-12-09)
+-------------------
+
+**Attention**: This release contains some backward-incompatible changes (marked with **(!)** below).
+
+* ChannelInfo-class with information about a channel like current topic and members
+
+  * access via IRCClient.channel_info
+
+* changing the nick name of the client
+* handle nick changes
+* handle quits
+* handle changes to operator- and voice-status
+* introduced handle_own_kick()-method
+
+  * **(!)** when the bot gets kicked, this can only be handled in
+    handle_own_kick() instead of handle_kick() now
+
+* optional delay for channel messages
+* the delay of a Task can be changed now
+* **(!)** IRCClient.channels now returns an iterator instead of a tuple
+
+v0.2.2 (2015-04-11)
+-------------------
+
+* bug fix: client tried to process partially received messages
+* bug fix: processing of operator- and voice-mode changes resulted in inconsistent data structures
+
+v0.2.1 (2015-04-10)
+-------------------
+
+* bug fix: the bot no longer received messages from a channel after another user got kicked from it
+
+v0.2.0 (2015-03-05)
+-------------------
+
+* handling disconnects
+* ability to reconnect to the server
+* IRCClient can be terminated manually
+* handling changes to channel modes operator and voice
+* changing channel modes operator and voice
+* sending private messages
+* handling kicks and kick other users from channels
+
 v0.1.0 (2014-12-30)
 -------------------
 
-* Initial release
+* basic handling methods (messages, joins, parts, numeric responses and errors)
+* connecting to a single server
+* joining multiple channels
+* sending channel messages
+* scheduling delayed and periodic tasks

doc/source/index.rst

@@ -1,31 +1,5 @@
-Welcome to FredIRC's documentation!
-===================================
 
-FredIRC is an event-driven Python framework for
-`IRC (Internet Relay Chat) <http://en.wikipedia.org/wiki/Internet_Relay_Chat>`_
-bots. It aims to provide a high-level abstraction of
-`IRC's internals <http://tools.ietf.org/search/rfc2812>`_, an easy-to-use API
-and convinient utilities related to bot development.
-
-FredIRC is developed in `Python <http://www.python.org/>`_ and requires at
-least version 3.3. It only depends on
-`asyncio <https://pypi.python.org/pypi/asyncio>`_ which is part of the
-standard library since Python 3.4 anyway.
-
-Features
---------
-
-The main features are:
-
-* Easy-to-use interface for IRC bots
-* Internal event-loop that dispatches high-level IRC events
-* Different kinds of tasks which can be scheduled by the user
-
-.. note:: FredIRC is **already usable** but the project is still in an early
-          stage of development. So far only the very basics needed to write
-          simple IRC bots are implemented. As long as FredIRC has a 0.x.x
-          version number, backward-incompatible API changes might be
-          introduced (but mentioned in the change log).
+.. include:: ../../README.rst
 
 Documentation
 -------------
@@ -38,42 +12,33 @@ Documentation
     api
     history
 
+Contact
+-------
+
+If you have problems, questions or ideas for improvement, please use the Github
+`issue tracker <https://github.com/worblehat/FredIRC/issues>`_
+or contact me directly via tmarq.contact@gmail.com.
+
 Development
 -----------
 
 FredIRC is **open source** and distributed under terms of the
-`BSD 2-Clause license <http://opensource.org/licenses/BSD-2-Clause>`_.
-Contributions (code, docs, ...) are always welcome!
-
-Resources
-+++++++++
-
-* See the :doc:`Changelog <history>` for the history of FredIRC
-* The source code repository is hosted at
-  `Github <https://github.com/worblehat/FredIRC>`_
-* For problems, questions and suggested improvements regarding FredIRC,
-  please use the Github
-  `issue tracker <https://github.com/worblehat/FredIRC/issues>`_ or
-  contact me directly via tm[at]tobix[dot].eu
-* Besides the :doc:`public API reference <api>` there is a reference that
-  also includes the internal modules and classes not intended for use by the
-  end user: :doc:`Internal API reference <api_internal>`
-
-IRC Protocol
-++++++++++++
+`2-clause BSD license <http://opensource.org/licenses/BSD-2-Clause>`_.
+Contributions (code, documentation, ideas,...) are always welcome!
 
-FredIRC tries to implement RFC2812. But as this is no strict standard,
-there might be problems with specific IRC Deamons. It was mostly tested with
-ircd-hybrid.
+The source code repository is hosted at `Github <https://github.com/worblehat/FredIRC>`_
 
 Wishlist
 ++++++++
 
-* Implement more of the
-  `IRC client protocol <http://tools.ietf.org/search/rfc2812>`_, especially the
-  channel operation messages.
-* Allow multiple server connections
-* Allow multiple IRCClient instances at the same time
-* (X)DCC functionality
+* More commands (e.g. KICK, TOPIC,...)
+* Querying user modes for other users
+* Advanced logging of chat histories
+* Allow multiple IRCClient instances and/or to re-run a terminated IRCClient
+* SSL-support
+* Some kind of plugin system for more flexibility und reusability
+* Utility classes for general bot development
+* Multiple server connections
+* (X)DCC-support
 * Port to Python 3.0/3.1/3.2 (maybe by using
   `Trollius <http://trollius.readthedocs.org/>`_)

doc/source/install.rst

@@ -4,6 +4,10 @@ Installation
 **Prerequisites**: Make sure you have **Python 3.3 or above** as well as
 `pip <https://pip.pypa.io>`_ installed on your system.
 
+FredIRC depends on `asyncio <https://pypi.python.org/pypi/asyncio>`_ which
+is part of the standard library since Python 3.4. For Python 3.3 asyncio must be
+installed separately (``pip install`` will take care of this automatically).
+
 Installation via PyPI
 ----------------------
 
@@ -37,6 +41,16 @@ can be installed by:
 
     $ pip install dist/FredIRC-X.X.X.tar.gz
 
+**Alternative:**
+
+If you really want to avoid using
+pip and miss `all its benefits <https://pip.pypa.io/en/stable/user_guide.html>`_
+you can just use the `setup.py`-script of course:
+
+.. code-block:: bash
+
+    $ python setup.py install
+
 Build the Documentation
 -----------------------
 

fredirc/__init__.py

@@ -5,6 +5,7 @@
 from .client import *
 from .errors import *
 from .handler import *
+from .info import *
 from .messages import *
 from .parsing import *
 from .processor import *
@@ -14,6 +15,7 @@
         client.__all__ +
         errors.__all__ +
         handler.__all__ +
+        info.__all__ +
         messages.__all__ +
         parsing.__all__ +
         processor.__all__ +