Changeset 125:edb21c02197b for wokkel

Timestamp:

Oct 21, 2008, 12:32:00 AM (14 years ago)

Author:

Christopher Zorn <tofu@…>

Branch:

wokkel-muc-client-support-24

Convert:

svn:b33ecbfc-034c-dc11-8662-000475d9059e/branches/wokkel-muc-client-support-24@121

Message:

docstrings, tests and bug fixes

Location:

wokkel

Files:

• muc.py (modified) (18 diffs)
• test/test_muc.py (modified) (3 diffs)

wokkel/muc.py

@@ -282 +282 @@
     def __init__(self, xs, method='get', role='none', a_jid=None, reason=None):
         AdminRequest.__init__(self, xs, method)
-
         i = self.query.addElement('item')
 
@@ -291 +290 @@
         if reason:
             i.addElement('reason', None, reason)
-
+        
 class GroupChat(domish.Element):
     """
@@ -660 +659 @@
 
     def _onGroupChat(self, msg):
-        """
+        """ A group chat message has been received from a MUC room. 
+        
+        There are a few event methods that may get called here. receviedGroupChat and receivedHistory
         """
         if not msg.hasAttribute('from'):
@@ -686 +687 @@
 
     def _onSubject(self, msg):
-        """
+        """A subject has been sent from a MUC room.
         """
         if not msg.hasAttribute('from'):
@@ -702 +703 @@
 
     def _makeTimeStamp(self, stamp=None):
+        # create a timestamp
         if stamp is None:
             stamp = datetime.datetime.now()
@@ -754 +756 @@
 
     def userJoinedRoom(self, room, user):
-        """User has joined a room
+        """User has joined a MUC room. 
+
+        This method will need to be modified inorder for clients to
+        do something when this event occurs.
+
+        @param room: The room the user has joined.
+        @type  room: L{Room}
+
+        @param user: The user that joined the MUC room.
+        @type  user: L{User}
+
         """
         pass
 
     def userLeftRoom(self, room, user):
-        """User has left a room
+        """User has left a room.
+        
+        This method will need to be modified inorder for clients to
+        do something when this event occurs.
+
+        @param room: The room the user has joined.
+        @type  room: L{Room}
+
+        @param user: The user that joined the MUC room.
+        @type  user: L{User}
+
         """
         pass
@@ -766 +788 @@
     def userUpdatedStatus(self, room, user, show, status):
         """User Presence has been received
+        
+        This method will need to be modified inorder for clients to
+        do something when this event occurs.
+        
         """
         pass
@@ -772 +798 @@
     def receivedSubject(self, room, subject):
         """
+        This method will need to be modified inorder for clients to
+        do something when this event occurs.
+
         """
         pass
@@ -778 +807 @@
     def receivedHistory(self, room, user, message, history, frm=None):
         """
+        This method will need to be modified inorder for clients to
+        do something when this event occurs.
         """
         pass
@@ -790 +821 @@
     def sendDeferred(self,  obj, timeout):
         """ Send data or a domish element, adding a deferred with a timeout.
+        
+        @param obj: The object to send over the wire.
+        @type  obj: L{domish.Element} or L{unicode}
+
+        @param timeout: The number of seconds to wait before the deferred is timed out.
+        @type  timeout: L{int}
+
+        The deferred object L{defer.Deferred} is returned.
         """
         d = defer.Deferred()
@@ -817 +856 @@
 
     def disco(self, entity, type='info'):
-        """Send disco queries to a XMPP entity
+        """Send disco queries to a XMPP entity.
+
+        @param entity: The server or entity where we want discovery information from.
+        @type  entity: L{jid.JID}
+
+        @param type: The optional disco type.
+        @type  type: L{unicode}
+
         """
 
@@ -831 +877 @@
         @param room_jid: The room jabber/xmpp entity id for the requested configuration form.
         @type  room_jid: L{jid.JID}
+
+        @param fields: The fields we want to modify.
+        @type  fields: A L{list} or L{dataform.Field}
 
         """
@@ -977 +1026 @@
 
     def _sendMessage(self, msg, children=None):
-
+        # send a message
         if children:
             for c in children:
@@ -991 +1040 @@
         self._sendMessage(msg, children=children)
 
-    def chat(self, to, message, children=None):
-        msg = PrivateChat(to, body=message)
+    def chat(self, room_jid, message, children=None):
+        """Send a private chat message to a user in a MUC room.
+        
+        See: http://xmpp.org/extensions/xep-0045.html#privatemessage
+
+        @param room_jid: The room entity id.
+        @type  room_jid: L{jid.JID}
+
+        """
+
+        msg = PrivateChat(room_jid, body=message)
 
         self._sendMessage(msg, children=children)
         
-    def invite(self, to, reason=None, full_jid=None):
-        """
-        """
-        msg = InviteMessage(to, reason=reason, full_jid=full_jid)
+    def invite(self, room_jid, reason=None, full_jid=None):
+        """Invite a xmpp entity to a MUC room.
+
+        See: http://xmpp.org/extensions/xep-0045.html#invite
+
+        @param room_jid: The room entity id.
+        @type  room_jid: L{jid.JID}
+        
+        @param reason: The reason for the invite.
+        @type  reason: L{unicode}
+
+        @param full_jid: The xmpp user's entity id.
+        @type  full_jid: L{jid.JID}
+
+        """
+        msg = InviteMessage(room_jid, reason=reason, full_jid=full_jid)
         self._sendMessage(msg)
 
 
-    def password(self, to, password):
-        p = PasswordPresence(to, password)
+    def password(self, room_jid, password):
+        """Send a password to a room so the entity can join.
+        
+        See: http://xmpp.org/extensions/xep-0045.html#enter-pw
+
+        @param room_jid: The room entity id.
+        @type  room_jid: L{jid.JID}
+        
+        @param password: The MUC room password.
+        @type  password: L{unicode}
+        
+        """
+        p = PasswordPresence(room_jid, password)
 
         self.xmlstream.send(p)
     
     def register(self, to, fields=[]):
+        """
+        """
         iq = RegisterRequest(self.xmlstream, method='set', fields=fields)
         iq['to'] = to
@@ -1024 +1107 @@
 
     def _getRoleList(self, room_jid, role):
+        # send a role request
         iq = RoleRequest(self.xmlstream,
                                 method='get',
@@ -1033 +1117 @@
 
     def _setAffiliationList(self, affiliation, room_jid, iq):
+        # set a rooms affiliation list
         r = self._getRoom(room_jid)
         if r is not None:
@@ -1175 +1260 @@
                          role=role,
                          reason=reason)
+        
         iq['to'] = room_jid.userhost() # this is a room jid, only send to room
         iq['from'] = frm.full()
@@ -1186 +1272 @@
         return r
 
-    def grantVoice(self, frm, room_jid, reason=None):
-        return self._setRole(frm, room_jid, role='participant', reason=reason)
+    def grantVoice(self, frm, room_jid, voice_jid=None, reason=None):
+        return self._setRole(frm, room_jid, role='participant', a_jid=voice_jid, reason=reason)
 
     def grantVisitor(self, frm, room_jid, reason=None):

wokkel/test/test_muc.py

@@ -74 +74 @@
     def test_userJoinedRoom(self):
         """The client receives presence from an entity joining the room.
+
+        This tests the class L{muc.UserPresence} and the userJoinedRoom event method.
+
+        The test sends the user presence and tests if the event method is called.
+
         """
         p = muc.UserPresence()
@@ -184 +189 @@
         self.stub.send(response)
         return d        
+
+
+    def test_joinRoomBadJid(self):
+        """Client joining a room and getting a forbidden error.
+        """
+
+        def cb(error):
+            
+            self.failUnless(error.value.mucCondition=='jid-malformed','Wrong muc condition')
+
+            
+            
+        d = self.protocol.join(self.test_srv, self.test_room, self.test_nick)
+        d.addBoth(cb)
+
+        prs = self.stub.output[-1]
+        self.failUnless(prs.name=='presence', "Need to be presence")
+        self.failUnless(getattr(prs, 'x', None), 'No muc x element')
+        # send back user presence, they joined
+        
+        response = muc.PresenceError(error=muc.MUCError('modify',
+                                                        'jid-malformed'
+                                                        ),
+                                     frm=self.room_jid.full())
+        self.stub.send(response)
+        return d        
+
+
 
     def test_partRoom(self):
@@ -442 +475 @@
         return d
 
-        
+    def test_grantVoice(self):
+        """Test granting voice to a user.
+
+        """
+        give_voice = JID('ban@jabber.org/TroubleMakger')
+        def cb(give_voice):
+            self.failUnless(give_voice, 'Did not give voice user')
+
+            
+        d = self.protocol.grantVoice(self.user_jid, self.room_jid, give_voice)
+        d.addCallback(cb)
+
+        iq = self.stub.output[-1]
+        
+        self.failUnless(xpath.matches("/iq[@type='set' and @to='%s']/query/item[@role='participant']" % (self.room_jid.userhost(),), iq), 'Wrong voice stanza')
+
+        response = toResponse(iq, 'result')
+
+        self.stub.send(response)
+
+        return d
+
+