Changeset 127:1610e7a3b777 for wokkel


Ignore:
Timestamp:
Oct 21, 2008, 9:25:35 PM (12 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@123
Message:

some docstrings, clean up in keeping params consitent and tests

Location:
wokkel
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • wokkel/muc.py

    r126 r127  
    266266    """
    267267
    268     def __init__(self, xs, method='get', affiliation='none', a_jid=None, reason=None):
     268    def __init__(self, xs, method='get', affiliation='none', a_jid=None, reason=None, nick=None):
    269269        AdminRequest.__init__(self, xs, method)
    270270
    271         i = self.query.addElement('item')
    272 
    273         i['affiliation'] = affiliation
     271        self.affiliation = affiliation
     272        if a_jid is not None or nick is not None:
     273            i = self.query.addElement('item')
     274            i['affiliation'] = affiliation
     275
    274276        if a_jid:
    275277            i['jid'] = a_jid.full()
    276            
     278
     279        if nick:
     280            i['nick'] = nick
     281
    277282        if reason:
    278283            i.addElement('reason', None, reason)
    279284
     285    def items(self, jid_list=None):
     286        """ Set or Get the items list for this affiliation request.
     287        """
     288        if jid_list:
     289            for j in jid_list:
     290                i = self.query.addElement('item')
     291                i['affiliation'] = self.affiliation
     292                if isinstance(j, jid.JID):
     293                    i['jid'] = j.full()
     294                else:
     295                    i['nick'] = j
     296
     297        return self.query.elements()
    280298           
     299           
     300
    281301class RoleRequest(AdminRequest):
    282     def __init__(self, xs, method='get', role='none', a_jid=None, reason=None):
     302    def __init__(self, xs, method='get', role='none', a_jid=None, reason=None, nick=None):
    283303        AdminRequest.__init__(self, xs, method)
    284304        i = self.query.addElement('item')
     
    287307        if a_jid:
    288308            i['jid'] = a_jid.full()
    289            
     309        if nick:
     310            i['nick'] = nick
     311
    290312        if reason:
    291313            i.addElement('reason', None, reason)
    292314       
    293315class GroupChat(domish.Element):
    294     """
     316    """A message stanza of type groupchat. Used to send a message to a MUC room that will be
     317    broadcasted to people in the room.
     318
    295319    """
    296320    def __init__(self, to, body=None, subject=None, frm=None):
    297         """To needs to be a string
     321        """
    298322        """
    299323        domish.Element.__init__(self, (None, 'message'))
     
    312336
    313337class PrivateChat(domish.Element):
    314     """
     338    """A chat message.
    315339    """
    316340    def __init__(self, to, body=None, frm=None):
    317         """To needs to be a string
     341        """ Initialize the L{PrivateChat}
     342
     343        @param to: The xmpp entity you are sending this chat to.
     344        @type  to: L{unicode} or L{jid.JID}
     345
     346        @param body: The message you are sending.
     347        @type  body: L{unicode}
     348
     349        @param frm: The entity that is sending the message.
     350        @param frm: L{unicode}
     351
    318352        """
    319353        domish.Element.__init__(self, (None, 'message'))
    320354        self['type'] = 'chat'
    321         self['to']   = to
     355        if isinstance(to, jid.JID):
     356            self['to'] = to.userhost()
     357        else:
     358            self['to'] = to
    322359        if frm:
    323360            self['from'] = frm
     
    339376
    340377class HistoryMessage(GroupChat):
    341     """
     378    """ A history message for MUC groupchat history.
    342379    """
    343380    def __init__(self, to, stamp, body=None, subject=None, frm=None, h_frm=None):
     
    374411
    375412    def toElement(self):
     413        """Returns a L{domish.Element} representing the xml for the history options.
     414        """
    376415        h = domish.Element((None, 'history'))
    377416        for key in self.attributes:
     
    402441class Room(object):
    403442    """
    404     A Multi User Chat Room
     443    A Multi User Chat Room. An in memory object representing a MUC room.
    405444    """
    406445
    407446   
    408447    def __init__(self, name, server, nick, state=None):
    409         """
     448        """ Initialize the room.
     449       
     450        @ivar name: The name of the MUC room.
     451        @type name: L{unicode}
     452
     453        @ivar server: The server where the MUC room is located.
     454        @type server: L{unicode}
     455
     456        @ivar nick: The nick name for the client in this room.
     457        @type nick: L{unicode}
     458
     459        @ivar state: The status code of the room.
     460        @type state: L{int}
     461
     462        @ivar entity_id: The jid of the room. Generated from name, server, and nick.
     463        @type entity_id: L{jid.JID}
     464
    410465        """
    411466        self.state  = state
     
    420475
    421476    def entityId(self):
    422         """
     477        """ Creates the L{jid.JID} for the room. If name, server, or nick change then this method
     478        should be called.
     479
    423480        """
    424481        self.entity_id = jid.internJID(self.name+'@'+self.server+'/'+self.nick)
     
    427484
    428485    def addUser(self, user):
    429         """
     486        """Add a user to the room roster.
     487
     488        @param user: The user object that is being added to the room.
     489        @type  user: L{User}
     490
    430491        """
    431492        self.roster[user.nick.lower()] = user
    432493
    433494    def inRoster(self, user):
    434         """
     495        """ Check if a user is in the MUC room.
     496
     497        @param user: The user object to check.
     498        @type  user: L{User}
     499
    435500        """
    436501
     
    438503
    439504    def getUser(self, nick):
    440         """
     505        """ Get a user from the room's roster.
     506
     507        @param nick: The nick for the user in the MUC room.
     508        @type  nick: L{unicode}
     509
    441510        """
    442511        return self.roster.get(nick.lower())
    443512
    444513    def removeUser(self, user):
     514        """ Remove a user from the MUC room's roster.
     515       
     516        @param user: The user object to check.
     517        @type  user: L{User}
     518       
     519        """
    445520        if self.inRoster(user):
    446521            del self.roster[user.nick.lower()]
     
    495570
    496571class PasswordPresence(BasicPresence):
    497     """
     572    """ This behaves like an object providing L{domish.IElement}.
    498573    """
    499574    def __init__(self, to, password):
     
    504579
    505580class MessageVoice(GroupChat):
    506     """
     581    """  This behaves like an object providing L{domish.IElement}.
    507582    """
    508583    def __init__(self, to=None, frm=None):
     
    9261001   
    9271002    def _changeUserStatus(self, r, room_jid, status, show):
     1003        # change the user status in a room.
     1004
    9281005        # check if user is in roster
    9291006        user = r.getUser(room_jid.resource)
     
    11021179        self.xmlstream.send(p)
    11031180   
    1104     def register(self, to, fields=[]):
    1105         """
     1181    def register(self, room_jid, fields=[]):
     1182        """ Send a request to register for a room.
     1183
     1184        @param room_jid: The room entity id.
     1185        @type  room_jid: L{jid.JID}
     1186
     1187        @param fields: The fields you need to register.
     1188        @type  fields: L{list} of L{dataform.Field}
     1189
    11061190        """
    11071191        iq = RegisterRequest(self.xmlstream, method='set', fields=fields)
    1108         iq['to'] = to
     1192        iq['to'] = room_jid.userhost()
    11091193        return iq.send()
    11101194
    11111195
    11121196    def _getAffiliationList(self, room_jid, affiliation):
     1197        # send a request for an affiliation list in a room.
    11131198        iq = AffiliationRequest(self.xmlstream,
    11141199                                method='get',
     
    11981283
    11991284    def getRegisterForm(self, room):
    1200         """
     1285        """ Grab the registration form for a MUC room.
    12011286
    12021287        @param room: The room jabber/xmpp entity id for the requested registration form.
     
    12141299        @type  room_jid: L{jid.JID}
    12151300       
     1301        @ivar reason: The reason we are destroying the room.
     1302        @type reason: L{unicode}
     1303
    12161304        """
    12171305        def destroyed(iq):
     
    12271315        return iq.send().addCallback(destroyed)
    12281316
    1229     def subject(self, to, subject):
    1230         """
    1231         """
    1232         msg = GroupChat(to, subject=subject)
     1317    def subject(self, room_jid, subject):
     1318        """ Change the subject of a MUC room.
     1319
     1320        See: http://xmpp.org/extensions/xep-0045.html#subject-mod
     1321
     1322        @param room_jid: The room jabber/xmpp entity id.
     1323        @type  room_jid: L{jid.JID}
     1324
     1325        @param subject: The subject you want to set.
     1326        @type  subject: L{unicode}
     1327
     1328        """
     1329        msg = GroupChat(room_jid, subject=subject)
    12331330        self.xmlstream.send(msg)
    12341331
    1235     def voice(self, to):
    1236         """
    1237         """
    1238         msg = MessageVoice(to=to)
     1332    def voice(self, room_jid):
     1333        """ Request voice for a moderated room.
     1334
     1335        @param room_jid: The room jabber/xmpp entity id.
     1336        @type  room_jid: L{jid.JID}
     1337
     1338        """
     1339        msg = MessageVoice(to=room_jid)
    12391340        self.xmlstream.send(msg)
    12401341
    12411342
    12421343
    1243     def history(self, to, message_list):
    1244         """
     1344    def history(self, room_jid, message_list):
     1345        """ Send history to create a MUC based on a one on one chat.
     1346       
     1347        See: http://xmpp.org/extensions/xep-0045.html#continue
     1348
     1349        @param room_jid: The room jabber/xmpp entity id.
     1350        @type  room_jid: L{jid.JID}
     1351
     1352        @param message_list: A list of history to send to the room.
     1353        @type  message_list: L{list} of L{domish.Element}
     1354
    12451355        """
    12461356       
     
    12491359            mto = m['to']
    12501360            frm = m.getAttribute('from', None)
    1251             m['to'] = to
     1361            m['to'] = room_jid.userhost()
    12521362
    12531363            d = m.addElement('delay', NS_DELAY)
     
    12571367            self.xmlstream.send(m)
    12581368
    1259     def _setAffiliation(self, frm, room_jid, affiliation, reason=None, a_jid=None):
     1369    def _setAffiliation(self, frm, room_jid, affiliation, reason=None, a_jid=None, nick=None):
     1370        # Send an affiliation request to change an entities affiliation to a MUC room.
    12601371        iq = AffiliationRequest(self.xmlstream,
    12611372                                method='set',
    12621373                                affiliation=affiliation,
    12631374                                a_jid=a_jid,
     1375                                nick=nick,
    12641376                                reason=reason)
    12651377        iq['to'] = room_jid.userhost() # this is a room jid, only send to room
     
    12671379        return iq.send()
    12681380
    1269     def _setRole(self, frm, room_jid, a_jid=None, reason=None, role='none'):
     1381    def _setRole(self, frm, room_jid, a_jid=None, reason=None, role='none', nick=None):
     1382        # send a role request
    12701383        iq = RoleRequest(self.xmlstream,
    12711384                         method='set',
    12721385                         a_jid=a_jid,
    12731386                         role=role,
     1387                         nick=nick,
    12741388                         reason=reason)
    12751389       
     
    12851399        return r
    12861400
    1287     def grantVoice(self, frm, room_jid, voice_jid=None, reason=None):
    1288         return self._setRole(frm, room_jid, role='participant', a_jid=voice_jid, reason=reason)
    1289 
    1290     def grantVisitor(self, frm, room_jid, reason=None):
    1291         return self._setRole(frm, room_jid, role='visitor', reason=reason)
    1292 
    1293     def grantModerator(self, frm, room_jid, reason=None):
    1294         return self._setRole(frm, room_jid, role='moderator', reason=reason)
    1295 
    1296     def ban(self, to, ban_jid, frm, reason=None):
    1297         return self._setAffiliation(frm, to, 'outcast', a_jid=ban_jid, reason=reason)
    1298 
    1299     def kick(self, to, kick_jid, frm, reason=None):       
    1300         return self._setAffiliation(frm, to, 'none', a_jid=kick_jid, reason=reason)
    1301        
     1401    def modifyAffiliationList(self, frm, room_jid, jid_list, affiliation):
     1402        """Modify an affiliation list.
     1403
     1404        @param frm: The entity sending the request.
     1405        @type  frm: L{jid.JID}
     1406
     1407        @param room_jid: The room jabber/xmpp entity id.
     1408        @type  room_jid: L{jid.JID}
     1409
     1410        @param jid_list: The list of jabber ids to change in a room. This can be a nick or a full jid.
     1411        @type  jid_list: L{list} of L{unicode} for nicks. L{list} of L{jid.JID} for jids.
     1412
     1413        @param affiliation: The affilation to change.
     1414        @type  affiliation: L{unicode}
     1415
     1416
     1417        """
     1418        iq = AffiliationRequest(self.xmlstream,
     1419                                method='set',
     1420                                affiliation=affiliation,
     1421                                )
     1422        iq.items(jid_list)
     1423        iq['to'] = room_jid.userhost() # this is a room jid, only send to room
     1424        iq['from'] = frm.full()
     1425        return iq.send()
     1426
     1427    def grantVoice(self, frm, room_jid, voice_jid=None, reason=None, nick=None):
     1428        """ Grant voice to an entity.
     1429       
     1430        @param frm: The entity sending the request.
     1431        @type  frm: L{jid.JID}
     1432
     1433        @param room_jid: The room jabber/xmpp entity id.
     1434        @type  room_jid: L{jid.JID}
     1435       
     1436        @param reason: The reason for granting voice to the entity.
     1437        @type  reason: L{unicode}
     1438
     1439        @param nick: The nick name for the client in this room.
     1440        @type  nick: L{unicode}
     1441
     1442        """
     1443        return self._setRole(frm, room_jid, role='participant', a_jid=voice_jid, nick=nick, reason=reason)
     1444
     1445    def grantVisitor(self, frm, room_jid, reason=None, nick=None):
     1446        """ Change a participant to a visitor. This will disallow the entity to send messages to a moderated room.
     1447        @param frm: The entity sending the request.
     1448        @type  frm: L{jid.JID}
     1449
     1450        @param room_jid: The room jabber/xmpp entity id.
     1451        @type  room_jid: L{jid.JID}
     1452       
     1453        @param reason: The reason for granting voice to the entity.
     1454        @type  reason: L{unicode}
     1455
     1456        @param nick: The nick name for the client in this room.
     1457        @type  nick: L{unicode}
     1458
     1459        """
     1460        return self._setRole(frm, room_jid, role='visitor', reason=reason, nick=nick)
     1461
     1462    def grantModerator(self, frm, room_jid, reason=None, nick=None):
     1463        """Grant moderator priviledges to a MUC room.
     1464
     1465        @param frm: The entity sending the request.
     1466        @type  frm: L{jid.JID}
     1467
     1468        @param room_jid: The room jabber/xmpp entity id.
     1469        @type  room_jid: L{jid.JID}
     1470
     1471        """
     1472        return self._setRole(frm, room_jid, role='moderator', reason=reason, nick=nick)
     1473
     1474    def ban(self, room_jid, ban_jid, frm, reason=None, nick=None):
     1475        """Ban a user from a MUC room.
     1476
     1477        @param room_jid: The room jabber/xmpp entity id.
     1478        @type  room_jid: L{jid.JID}
     1479
     1480        @param ban_jid: The room jabber/xmpp entity id.
     1481        @type  ban_jid: L{jid.JID}
     1482
     1483        @param frm: The entity sending the request.
     1484        @type  frm: L{jid.JID}
     1485
     1486        @param reason: The reason for banning the entity.
     1487        @type  reason: L{unicode}
     1488
     1489        @param nick: The nick name for the client in this room.
     1490        @type  nick: L{unicode}
     1491
     1492        """
     1493        return self._setAffiliation(frm, room_jid, 'outcast', nick=nick, a_jid=ban_jid, reason=reason)
     1494
     1495    def kick(self, room_jid, kick_jid, frm, reason=None, nick=None):       
     1496        """Kick a user from a MUC room.
     1497
     1498        @param room_jid: The room jabber/xmpp entity id.
     1499        @type  room_jid: L{jid.JID}
     1500
     1501        @param kick_jid: The room jabber/xmpp entity id.
     1502        @type  kick_jid: L{jid.JID}
     1503
     1504        @param frm: The entity sending the request.
     1505        @type  frm: L{jid.JID}
     1506
     1507        @param reason: The reason given for the kick.
     1508        @type  reason: L{unicode}
     1509
     1510        @param nick: The nick for the user in the MUC room.
     1511        @type  nick: L{unicode}
     1512
     1513        """
     1514        return self._setAffiliation(frm, room_jid, 'none', a_jid=kick_jid, nick=nick, reason=reason)
     1515       
  • wokkel/test/test_muc.py

    r126 r127  
    361361        archive.append(msg)
    362362
    363         self.protocol.history(self.room_jid.userhost(), archive)
     363        self.protocol.history(self.room_jid, archive)
    364364
    365365
     
    405405            self.failUnless(iq['type']=='result', 'We did not get a result')
    406406       
    407         d = self.protocol.register(self.room_jid.userhost())
     407        d = self.protocol.register(self.room_jid)
    408408        d.addCallback(cb)
    409409
     
    445445        iq = self.stub.output[-1]
    446446        self.failUnless(xpath.matches("/iq/query[@xmlns='%s']/x"% (muc.NS_MUC_OWNER,), iq), 'Bad configure request')
     447       
     448        response = toResponse(iq, 'result')
     449        self.stub.send(response)
     450        return d
     451
     452
     453    def test_roomDestroy(self):
     454        """ Destroy a room.
     455        """
     456
     457        def cb(destroyed):
     458            self.failUnless(destroyed==True, 'Room not destroyed.')
     459                   
     460        d = self.protocol.destroy(self.room_jid)
     461        d.addCallback(cb)
     462
     463        iq = self.stub.output[-1]
     464        self.failUnless(xpath.matches("/iq/query[@xmlns='%s']/destroy"% (muc.NS_MUC_OWNER,), iq), 'Bad configure request')
    447465       
    448466        response = toResponse(iq, 'result')
Note: See TracChangeset for help on using the changeset viewer.