Merge remote-tracking branch 'upstream/master'

Author: GauthierPLM

doc/source/conf.py

@@ -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/history.rst

@@ -1,6 +1,17 @@
 Changelog
 =========
 
+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)
 -------------------
 

doc/source/index.rst

@@ -12,6 +12,10 @@ 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.
 
+.. 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 :doc:`history` carefully anytime you upgrade!
+
 Features
 --------
 
@@ -21,12 +25,6 @@ The main features are:
 * 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).
-
 For a more detailed list of features see the :doc:`history`.
 
 Links

doc/source/install.rst

@@ -37,6 +37,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/client.py

@@ -207,6 +207,17 @@ def register(self, nick=None, user_name=None, real_name=None, password=None):
         self._send_message(messages.user(
             self._configured_user_name, self._configured_real_name))
 
+    def change_nick(self, nick):
+        """ Change the nick name of the client.
+
+        Note that the clients :py:attr:`.nick`-property will not change
+        directly, but only after the server acknowledged the new nick name.
+
+        Args:
+            nick (str): The new nick name.
+        """
+        self._send_message(messages.nick(nick))
+
     def join(self, channel, *channels):
         """ Join the specified channel(s).
 
@@ -278,10 +289,6 @@ def kick(self, user, channel, reason=None):
         """
         self._send_message(messages.kick((channel,), (user,), reason))
 
-    def pong(self):
-        """ Send a pong message to the server. """
-        self._send_message(messages.pong(self._state.server))
-
     def give_op(self, user, channel):
         """ Grant operator rights to a user on a channel.
 
@@ -356,6 +363,10 @@ def has_voice_in(self, channel):
         """
         return channel.lower() in self._state.has_voice_in
 
+    def pong(self):
+        """ Send a pong message to the server. """
+        self._send_message(messages.pong(self._state.server))
+
     # --- Private methods ---
 
     def _send_message(self, message):

fredirc/handler.py

@@ -45,41 +45,6 @@ def handle_register(self):
         """ The client successfully registered to the server. """
         pass
 
-    def handle_ping(self, server):
-        """ Received a ping message from the server.
-
-        Args:
-            server (str): name or ip of the server.
-        """
-        pass
-
-    def handle_response(self, response, message):
-        """ A numeric response was received from the server.
-
-        See the IRC client protocol specification for valid numeric response
-        codes and their meaning. There are extra handler methods for many
-        common responses, but this general handler is always called first.
-
-        Args:
-            response (int): 3-digit response code (between 0 and 399)
-            message (str): the whole, raw message
-        """
-        pass
-
-    def handle_error(self, error, **params):
-        """ An irc error message was received from the server.
-
-        The error codes are defined in :py:class:`Err<fredirc.Err>`.
-        The contents of the params dictionary depend on the specific error.
-        See the documentation of :py:class:`Err<fredirc.Err>` for details.
-
-        Args:
-            error (int): 3-digit error code (between 400 and 599)
-            params (dict): Parameters of the error message, each consisting of \
-                a parameter name and a value.
-        """
-        pass
-
     def handle_channel_message(self, channel, message, sender=None):
         """ Received a message to a channel.
 
@@ -107,7 +72,7 @@ def handle_private_message(self, message, sender=None):
         pass
 
     def handle_join(self, channel, nick):
-        """ Called when a user joined the channel.
+        """ Called when another user joined the channel.
 
         To handle joins of the IRCClient itself, use
         :py:meth:`.handle_own_join`.
@@ -129,7 +94,7 @@ def handle_own_join(self, channel):
         pass
 
     def handle_part(self, channel, nick, message=None):
-        """ Called when a user left the channel.
+        """ Called when another user left the channel.
 
         To handle partings of the IRCClient itself, use
         :py:meth:`.handle_own_part`.
@@ -152,9 +117,7 @@ def handle_own_part(self, channel):
         pass
 
     def handle_kick(self, channel, nick, initiator, reason):
-        """ A user got kicked from a channel.
-
-        Might be the IRCClient itself.
+        """ Another user got kicked from a channel.
 
         Args:
             channel (str): the channel
@@ -163,8 +126,17 @@ def handle_kick(self, channel, nick, initiator, reason):
         """
         pass
 
+    def handle_own_kick(self, channel, initiator, reason):
+        """ The IRCClient got kicked from a channel.
+
+        Args:
+            channel (str): the channel
+            reason (str): reason for the kick (might be None)
+        """
+        pass
+
     def handle_got_op(self, channel, nick, initiator):
-        """ A user received operator status.
+        """ Another user received operator status.
 
         Args:
             channel (str): name of the channel
@@ -173,8 +145,17 @@ def handle_got_op(self, channel, nick, initiator):
         """
         pass
 
+    def handle_own_got_op(self, channel, initiator):
+        """ The IRCClient received operator status.
+
+        Args:
+            channel (str): name of the channel
+            initiator (str): the user who granted the operator rights
+        """
+        pass
+
     def handle_lost_op(self, channel, nick, initiator):
-        """ A user lost operator status.
+        """ Another user lost operator status.
 
         Args:
             channel (str): name of the channel
@@ -183,8 +164,17 @@ def handle_lost_op(self, channel, nick, initiator):
         """
         pass
 
+    def handle_own_lost_op(self, channel, initiator):
+        """ The IRCClient lost operator status.
+
+        Args:
+            channel (str): name of the channel
+            initiator (str): the user who initiated the mode change
+        """
+        pass
+
     def handle_got_voice(self, channel, nick, initiator):
-        """ A user received voice rights.
+        """ Another user received voice rights.
 
         Args:
             channel (str): name of the channel
@@ -193,8 +183,17 @@ def handle_got_voice(self, channel, nick, initiator):
         """
         pass
 
+    def handle_own_got_voice(self, channel, initiator):
+        """ The IRCClient received voice rights.
+
+        Args:
+            channel (str): name of the channel
+            initiator (str): the user who granted the voice rights
+        """
+        pass
+
     def handle_lost_voice(self, channel, nick, initiator):
-        """ A user lost voide rights.
+        """ Another user lost voice rights.
 
         Args:
             channel (str): name of the channel
@@ -203,6 +202,74 @@ def handle_lost_voice(self, channel, nick, initiator):
         """
         pass
 
+    def handle_own_lost_voice(self, channel, initiator):
+        """ The IRCClient lost voice rights.
+
+        Args:
+            channel (str): name of the channel
+            initiator (str): the user who initiated the mode change
+        """
+        pass
+
+    def handle_nick_change(self, old_nick, new_nick):
+        """ A user's nick name changed.
+
+        To handle nick changes of the IRCClient itself, use
+        :py:meth:`.handle_own_nick_change`.
+
+        Args:
+            old_nick (str): The nick name of the user until now.
+            new_nick (str): The new nick name of the user.
+        """
+        pass
+
+    def handle_own_nick_change(self, old_nick, new_nick):
+        """ The IRCCLient's nick name changed.
+
+        The :py:attr:`nick<.IRCClient.nick>`-property will already hold
+        the new nick when this handler is called.
+
+        Args:
+            old_nick (str): The old nick name.
+            new_nick (str): The new nick name.
+        """
+        pass
+
+    def handle_response(self, response, message):
+        """ A numeric response was received from the server.
+
+        See the IRC client protocol specification for valid numeric response
+        codes and their meaning. There are extra handler methods for many
+        common responses, but this general handler is always called first.
+
+        Args:
+            response (int): 3-digit response code (between 0 and 399)
+            message (str): the whole, raw message
+        """
+        pass
+
+    def handle_error(self, error, **params):
+        """ An irc error message was received from the server.
+
+        The error codes are defined in :py:class:`Err<fredirc.Err>`.
+        The contents of the params dictionary depend on the specific error.
+        See the documentation of :py:class:`Err<fredirc.Err>` for details.
+
+        Args:
+            error (int): 3-digit error code (between 400 and 599)
+            params (dict): Parameters of the error message, each consisting of \
+                a parameter name and a value.
+        """
+        pass
+
+    def handle_ping(self, server):
+        """ Received a ping message from the server.
+
+        Args:
+            server (str): name or ip of the server.
+        """
+        pass
+
     def handle_unhandled_message(self, message):
         """ This handler is called whenever a message is not handled by any
             other handler.