Permalink
Browse files

Improved Message documentation

+ Minor code improvements
  • Loading branch information...
borntyping committed Jun 23, 2012
1 parent 8ab5ee6 commit 40f8e925901296d14a1c2e29901fe847ded9ed2b
Showing with 112 additions and 33 deletions.
  1. +109 −27 aleph/protocols/irc/messages.py
  2. +3 −6 aleph/protocols/irc/parser.py
@@ -1,4 +1,4 @@
-""" Message() class - instances of IRC messages as described by RFC1459 """
+""" :class:`Message` class - instances of IRC messages as described by RFC1459 """
import re
@@ -88,11 +88,20 @@ def get_channel (self, chan):
@Message.Command
class QUIT (Message):
- """ 4.1.6
- QUIT :<reason> """
+ """
+ A user has quit the server
+
+ Remove the username from every channel's name lists
+
+ 4.1.6
+ QUIT :<reason>
+ """
def __init__ (self, *args):
Message.__init__(self, *args)
self.reason = self.trailing
+
+ for channel in self.channels:
+ channel.names.remove(self.nick)
def __str__ (self):
return self.output('{} [{}] quit: {reason}'.format(self.nick, self.source, self.reason))
@@ -101,8 +110,16 @@ def __str__ (self):
@Message.Command
class JOIN (Message):
- """ 4.2.1
- :nick JOIN #channel """
+ """
+ A user has joined a channel
+
+ Create a local channel object if Aleph is joining,
+ else add the name of the joing user to the channels names list
+
+ 4.2.1
+ :nick JOIN #channel
+ """
+
def __init__ (self, *args):
Message.__init__(self, *args)
# Create a channel object if I am joining the channel
@@ -117,8 +134,16 @@ def __str__ (self):
@Message.Command
class PART (Message):
- """ 4.2.2
- :nick PART #channel """
+ """
+ A user has left a channel
+
+ Clear the local channel object if Aleph is parting,
+ else remove the user's name from the channels names list.
+
+ 4.2.2
+ :nick PART #channel
+ """
+
def __init__ (self, *args):
Message.__init__(self, *args)
@@ -136,12 +161,17 @@ def __str__ (self):
""" 4.4 Sending messages """
class TextMessage (Message):
- """ Base class for 'PRIVMSG' and 'NOTICE'
+ """
+ Base class for :class:`PRIVMSG` and :class:`NOTICE`
+
+ ``TextMessage.text``
+ Contains the message, with the prepending nick stripped if it was directed at Aleph
+ ``TextMessage.pm``
+ True for messages sent only to Aleph
+ ``TextMessage.to_me``
+ True for a message either sent only to or directed at Aleph.
+ """
- TextMessage.text contains the message, with the nick stripped from the start if it was directed at me.
- TextMessage.pm is true for private messages.
- TextMessage.to_me is true for a message either sent in private or directed at me.
- """
def __init__ (self, *args):
super(TextMessage, self).__init__(*args)
@@ -168,9 +198,14 @@ def __init__ (self, *args):
@Message.Command
class PRIVMSG (TextMessage):
- """ 4.4.1 Private messages
+ """
+ An incoming message
+
+ 4.4.1 Private messages
Command: PRIVMSG
- Parameters: <receiver> <text to be sent> """
+ Parameters: <receiver> <text to be sent>
+ """
+
def msg (self, line):
""" Send a message to the channel the message originated from """
return self.server.privmsg(self.channel, line)
@@ -188,9 +223,17 @@ def __str__ (self):
@Message.Command
class NOTICE (TextMessage):
- """ 4.4.2 Notice
- Command:_NOTICE
- Parameters: <nickname> <text> """
+ """
+ A notice - Aleph should **never** reply to notices,
+
+ The IRC protocol declares that "automatic replies must never be
+ sent in response to a NOTICE message".
+
+ 4.4.2 Notice
+ Command: NOTICE
+ Parameters: <nickname> <text>
+ """
+
def __str__ (self):
return self.output('NOTICE from {} to {}: {}'.format(self.source.name(), self.channel, self.text))
@@ -200,12 +243,22 @@ def __str__ (self):
@Message.Reply(331)
class RPL_NOTOPIC (Message):
+ """
+ Marks the channel as having no topic
+
+ Sets ``Channel.topic`` to ``None``
+ """
def __init__ (self, *args):
Message.__init__(self, *args)
- self.get_channel(self.parameters[1]).topic = ""
+ self.get_channel(self.parameters[1]).topic = None
@Message.Reply(332)
class RPL_TOPIC (Message):
+ """
+ The topic for a channel
+
+ Sets ``Channel.topic`` to the new topic
+ """
def __init__ (self, *args):
Message.__init__(self, *args)
self.get_channel(self.parameters[1]).topic = self.trailing
@@ -217,45 +270,74 @@ def __str__ (self):
@Message.Reply(353)
class RPL_NAMREPLY (Message):
+ """
+ Part or all of the names list for a channel
+
+ If the RPL_NAMREPLY flag is not set on the channel, this is the
+ first set of names - the local names list should be cleared and
+ replaced with the canonical version.
+
+ The names in the message are added to the channels local names list
+ """
def __init__ (self, *args):
Message.__init__(self, *args)
channel = self.get_channel(self.parameters[2])
- # If the channel has previously sent a RPL_ENDOFNAMES,
- # start a new names list
if not 'RPL_NAMREPLY' in channel.flags:
channel.flags.append('RPL_NAMREPLY')
channel.names = list()
- # Add the names in the reply to the channels list
channel.names.extend(self.trailing.split())
@Message.Reply(366)
class RPL_ENDOFNAMES (Message):
+ """
+ Marks the end of the names list
+
+ Remove the RPL_NAMREPLY flag from the channel
+ """
def __init__ (self, *args):
Message.__init__(self, *args)
- # Set a flag on the channel to show that RPL_NAMREPLY has finished
+ #
channel = self.get_channel(self.parameters[1])
channel.flags.remove('RPL_NAMREPLY')
# Message of the day
@Message.Reply(375)
class RPL_MOTDSTART (Message):
- """ :- <server> Message of the day - """
+ """
+ Marks the start of the servers MOTD
+
+ Sets the local MOTD to ``""``
+
+ ::
+ :- <server> Message of the day -
+ """
def __init__ (self, *args):
Message.__init__(self, *args)
self.server.motd = ""
@Message.Reply(372)
class RPL_MOTD (Message):
- """ :- <text>"""
+ """
+ A line from the MOTD, which should be appended to the current MOTD
+
+ ::
+ :- <text>
+ """
def __init__ (self, *args):
Message.__init__(self, *args)
- line = self.trailing[2:] + "\n"
- self.server.motd += line
+ self.server.motd += self.trailing[2:] + "\n"
@Message.Reply(376)
class RPL_MOTDSTART (Message):
- """ :End of /MOTD command """
+ """
+ Marks the end of the server MOTD
+
+ Strips the trailing newline from the MOTD
+
+ ::
+ :End of /MOTD command
+ """
def __init__ (self, *args):
Message.__init__(self, *args)
# Strip the trailing \n from the MOTD
@@ -4,15 +4,12 @@
from data import Hostmask
-#: Splits a string at the first ' '
-split = lambda string: string.split(' ',1)
-
-#: Gets the next word from a string
-get_token = lambda string: split(string) if len(split(string)) > 1 else (split(string)[0], None)
-
def parse_message (string):
""" Parse an IRC message in the form ``[:<source> ]<command>[ <parameters>][ :<trailing>]`` """
+ split = lambda string: string.split(' ',1)
+ get_token = lambda string: split(string) if len(split(string)) > 1 else (split(string)[0], None)
+
# Default variables for parameters and trailing,
# as it is possible neither will be assigned
parameters, trailing = [], None

0 comments on commit 40f8e92

Please sign in to comment.