changeset 2116:7f579f5fd44b

Improve docstrings. s/type/msgtype/ to avoid name conflict with builtin.
author Karol 'grzywacz' Nowak <grzywacz@sul.uni.lodz.pl>
date Tue, 12 Jun 2007 13:29:04 +0200
parents 260d0dbded44
children 38c8f31be12e
files MoinMoin/events/messages.py jabberbot/xmlrpcbot.py jabberbot/xmppbot.py
diffstat 3 files changed, 103 insertions(+), 23 deletions(-) [+]
line wrap: on
line diff
--- a/MoinMoin/events/messages.py	Tue Jun 12 02:34:50 2007 +0200
+++ b/MoinMoin/events/messages.py	Tue Jun 12 13:29:04 2007 +0200
@@ -16,27 +16,36 @@
 class UnknownChangeType:
     pass
 
-def page_change_message(type, request, page, lang, **kwargs):
-    """Prepare a notification text for a page change of given type"""
+def page_change_message(msgtype, request, page, lang, **kwargs):
+    """Prepare a notification text for a page change of given type
+    
+    @param msgtype: a type of message to send (page_changed, attachment_added, ...)
+    @type msgtype: str or unicode
+    @param **kwargs: a dictionary of additional parameters, which depend on msgtype
+    
+    @return: a formatted, ready to send message
+    @rtype: unicode
+    
+    """
     
     _ = request.getText
     page._ = lambda s, formatted=True, r=request, l=lang: r.getText(s, formatted=formatted, lang=l)
     querystr = {}
     
-    if type == "page_changed": 
+    if msgtype == "page_changed": 
         revisions = kwargs['revisions']
         if len(kwargs['revisions']) >= 2:
             querystr = {'action': 'diff',
                     'rev2': str(revisions[0]),
                     'rev1': str(revisions[1])}
         
-    if type == "attachment_added":
+    if msgtype == "attachment_added":
         attachlink = request.getBaseURL() + \
                         getAttachUrl(page.page_name, kwargs['attach_name'], request)
         
     pagelink = request.getQualifiedURL(page.url(request, querystr, relative=False))
     
-    if type == "page_changed":
+    if msgtype == "page_changed":
         messageBody = _("Dear Wiki user,\n\n"
         'You have subscribed to a wiki page or wiki category on "%(sitename)s" for change notification.\n\n'
         "The following page has been changed by %(editor)s:\n"
@@ -59,7 +68,7 @@
             else:
                 messageBody = messageBody + _("No differences found!\n", formatted=False)
                 
-    elif type == "attachment_added":
+    elif msgtype == "attachment_added":
         messageBody = _("Dear Wiki user,\n\n"
         'You have subscribed to a wiki page "%(sitename)s" for change notification.\n\n'
         "An attachment has been added to the following page by %(editor)s:\n"
@@ -75,7 +84,7 @@
             'attach_get': attachlink,
         }
         
-    elif type == "page_deleted":
+    elif msgtype == "page_deleted":
         messageBody = _("Dear wiki user,\n\n"
             'You have subscribed to a wiki page "%(sitename)s" for change notification.\n\n'
             "The following page has been deleted by %(editor)s:\n"
--- a/jabberbot/xmlrpcbot.py	Tue Jun 12 02:34:50 2007 +0200
+++ b/jabberbot/xmlrpcbot.py	Tue Jun 12 13:29:04 2007 +0200
@@ -87,21 +87,38 @@
     
     
     def send_notification(self, jid, text):
-        """Instructs the XMPP component to send a notification"""           
+        """Instructs the XMPP component to send a notification
+        
+        @param jid: a jid to send a message to (bare jid)
+        @type jid: str or unicode
+        @param text: a message body
+        @type text: unicode
+        
+        """
         c = NotificationCommand(jid, text)
         self.commands.put_nowait(c)
         return True
     send_notification.export = True
     
     def addJIDToRoster(self, jid):
-        """Instructs the XMPP component to add a new JID to its roster"""  
+        """Instructs the XMPP component to add a new JID to its roster
+        
+        @param jid: a jid to add, this must be a bare jid
+        @type jid: str or unicode, 
+        
+        """  
         c = AddJIDToRosterCommand(jid)
         self.commands.put_nowait(c)
         return True
     addJIDToRoster.export = True
     
     def removeJIDFromRoster(self, jid):
-        """Instructs the XMPP component to remove a JID from its roster"""      
+        """Instructs the XMPP component to remove a JID from its roster
+        
+        @param jid: a jid to remove, this must be a bare jid
+        @type jid: str or unicode
+        
+        """
         c = RemoveJIDFromRosterCommand(jid)
         self.commands.put_nowait(c)
         return True
--- a/jabberbot/xmppbot.py	Tue Jun 12 02:34:50 2007 +0200
+++ b/jabberbot/xmppbot.py	Tue Jun 12 13:29:04 2007 +0200
@@ -39,12 +39,21 @@
         self.messages = []
         
     def add_resource(self, resource, show, priority):
-        """Adds information about a connected resource"""
+        """Adds information about a connected resource
+        
+        @param resource: resource name
+        @param show: a show presence property, as defined in XMPP
+        @param priority: priority of the given resource
+        
+        """
         self.resources[resource] = {'show': show, 'priority': priority}
     
     def remove_resource(self, resource):
-        """Removes information about a connected resource"""
+        """Removes information about a connected resource
         
+        @param resource: resource name
+        
+        """
         if self.resources.has_key(resource):
             del self.resources[resource]
         else:
@@ -54,8 +63,8 @@
         """Checks if contact is DoNotDisturb
         
         The contact is DND if its resource with the highest priority is DND
-        """
         
+        """      
         # Priority can't be lower than -128
         max_prio = -129
         max_prio_show = u"dnd"
@@ -74,6 +83,7 @@
         @param resource: resource to alter
         @param show: new value of the show property
         @raise ValueError: no resource with given name has been found
+        
         """
         if self.resources.has_key(resource):
             self.resources[resource]['show'] = show
@@ -94,12 +104,12 @@
     """A simple XMPP bot"""
        
     def __init__(self, config, from_commands, to_commands):
-        """A constructor.
+        """A constructor
         
         @param from_commands: a Queue object used to send commands to other (xmlrpc) threads
         @param to_commands: a Queue object used to receive commands from other threads
+        
         """
-        
         Thread.__init__(self)
         
         self.from_commands = from_commands
@@ -148,8 +158,9 @@
     def poll_commands(self):
         """Checks for new commands in the input queue and executes them
         
-        @return: True if any command has been executed, False otherwise."""
+        @return: True if any command has been executed, False otherwise.
         
+        """
         try:
             command = self.to_commands.get_nowait()
             self.handle_command(command)
@@ -158,8 +169,13 @@
             return False
         
     def handle_command(self, command, ignore_dnd=False):
-        """Excecutes commands from other components"""
+        """Excecutes commands from other components
         
+        @param command: a command to execute
+        @type command: any class defined in commands.py (FIXME?)
+        @param ignore_dnd: if command results in user interaction, should DnD be ignored?
+        
+        """
         # Handle normal notifications
         if isinstance(command, NotificationCommand):
             jid = JID(node_or_jid=command.jid)
@@ -215,14 +231,19 @@
         
         @param jid: JID to send the message to
         @param text: message's body
-        @param type: message type, as defined in RFC"""
+        @param type: message type, as defined in RFC
         
+        """
         message = Message(to_jid=jid, body=text, stanza_type=msg_type)
         self.get_stream().send(message)
     
     def handle_message(self, message):
-        """Handles incoming messages"""
+        """Handles incoming messages
         
+        @param message: a message stanza to parse
+        @type message: pyxmpp.message.Message
+        
+        """    
         if self.config.verbose:
             msg = "Message from %s." % (message.get_from_jid().as_utf8(),)
             self.log(msg)
@@ -246,6 +267,11 @@
             self.send_message(sender, response)
             
     def handle_internal_command(self, command):
+        """Handles internal commands, that can be completed by the XMPP bot itself
+        
+        @param command: list representing a command
+        
+        """
         if command[0] == "ping":
             return "pong"
         elif command[0] == "help":
@@ -254,9 +280,17 @@
             else:
                 return self.help_on(command[1])
         else:
+            # For unknown command return a generic help message
             return self.reply_help()
         
     def help_on(self, command):
+        """Returns a help message on a given topic
+        
+        @param command: a command to describe in a help message
+        @type command: str or unicode
+        @return: a help message
+        
+        """
         if command == "help":
             return u"""The "help" command prints a short, helpful message about a given topic or function.\n\nUsage: help [topic_or_function]"""
         
@@ -271,6 +305,12 @@
         
         
     def handle_xmlrpc_command(self, command):
+        """Creates a command object, and puts it the command queuq
+        
+        @param command: a valid name of available xmlrpc command
+        @type command: str
+        
+        """
         command_class = self.xmlrpc_commands[command[0]]
         
         try:
@@ -297,8 +337,11 @@
         self.get_stream().send(response)
         
     def handle_unavailable_presence(self, stanza):
-        """Handles unavailable presence stanzas"""
+        """Handles unavailable presence stanzas
         
+        @type stanza: pyxmpp.presence.Presence
+        
+        """
         if self.config.verbose:
             self.log("Handling unavailable presence.")
         
@@ -336,7 +379,11 @@
         return True
     
     def handle_available_presence(self, presence):
-        """Handles available presence stanzas"""
+        """Handles available presence stanzas
+        
+        @type presence: pyxmpp.presence.Presence
+        
+        """
         if self.config.verbose:
             self.log("Handling available presence.")
         
@@ -376,15 +423,22 @@
         return True
     
     def send_queued_messages(self, contact, ignore_dnd=False):
-        """Sends messages queued for the contact"""
+        """Sends messages queued for the contact
+        
+        @param contact: a contact whose queued messages are to be sent
+        @type contact: jabberbot.xmppbot.Contact
+        @param ignore_dnd: should contact's DnD status be ignored?
+        
+        """
         for command in contact.messages:
             self.handle_command(command, ignore_dnd)
                     
     def reply_help(self):
         """Constructs a generic help message
         
-        It's sent in response to an uknown message or the "help" command."""
+        It's sent in response to an uknown message or the "help" command.
         
+        """
         help = u"""Hello there! I'm a MoinMoin Notification Bot. Available commands:\n\n%s\n%s"""
         internal = ", ".join(self.internal_commands)
         xmlrpc = ", ".join(self.xmlrpc_commands.keys())