Changes in [105:5d8f1609aaf3:155:8b2ed9549399]

Files:

• debian/control (modified) (1 diff)
• wokkel/iwokkel.py (modified) (2 diffs)
• wokkel/muc.py (added)
• wokkel/test/helpers.py (modified) (2 diffs)
• wokkel/test/test_muc.py (added)
• wokkel/xmppim.py (modified) (5 diffs)

debian/control

@@ -11 +11 @@
 Architecture: all
 XB-Python-Version: ${python:Versions}
-Depends: ${python:Depends}, ${misc:Depends}, python-twisted, python-twisted-words (>= 8.0.0), python-twisted-names
+Depends: ${python:Depends}, ${misc:Depends}, python-twisted, python-twisted-words (>= 8.0.0), python-twisted-names, python-dateutil
 Description: A set of enhancements to Twisted Words' Jabber/XMPP
  It serves as a testing ground for new features and enhancements which will

wokkel/iwokkel.py

@@ -1 @@
-# Copyright (c) Ralph Meijer.
+# Copyright (c) Ralph Meijer
 # See LICENSE for details.
 
@@ -770 +770 @@
 
 
-    def affiliationsGet(request):
-        """
-        Called when a affiliations retrieval request (owner) has been received.
-
-        @param request: The publish-subscribe request.
-        @type request: L{wokkel.pubsub.PubSubRequest}
-        @return: A deferred that fires with a C{dict} of affiliations with the
-            entity as key (L{JID}) and the affiliation state as value
-            (C{unicode}).  The affiliation can be C{u'owner'}, C{u'publisher'},
-            or C{u'outcast'}.
-        @rtype: L{defer.Deferred}
-
-        @note: Affiliations are always on the bare JID. An implementation of
-        this method MUST NOT return JIDs with a resource part.
-        """
-
-
-    def affiliationsSet(request):
-        """
-        Called when a affiliations modify request has been received.
-
-        @param request: The publish-subscribe request.
-        @type request: L{wokkel.pubsub.PubSubRequest}
-        @return: A deferred that fires with C{None} when the affiliation
-            changes were succesfully processed..
-        @rtype: L{defer.Deferred}
-
-        @note: Affiliations are always on the bare JID. The JIDs in
-        L{wokkel.pubsub.PubSubRequest.affiliations} are already stripped of
-        any resource.
-        """
+
+class IMUCClient(Interface):
+    """
+    Multi-User Chat Client
+
+    A client interface to XEP-045 : http://xmpp.org/extensions/xep-0045.html
+
+    """
+
+    def receivedSubject(room, user, subject):
+        """
+        A subject is received when you join a room and when the subject is changed. This
+        method is triggered by one of those two events.
+
+        @param room: The room the subject was accepted for.
+        @type room: L{muc.Room}
+
+        @param user: The user that set the subject.
+        @type  user: L{muc.User}
+
+        @param subject: The subject of the given room.
+        @type subject: C{unicode}
+        """
+
+
+    def receivedHistory(room, user, message):
+        """
+        Past messages from a chat room has been received. This occurs when you join a room.
+        """
+
+
+    def configure(roomJID, options):
+        """
+        Configure a room.
+
+        @param roomJID: The room to configure.
+        @type roomJID: L{jid.JID}
+
+        @param options: A mapping of field names to values, or C{None} to cancel.
+        @type options: C{dict}
+        """
+
+
+    def getConfiguration(roomJID):
+        """
+        Grab the configuration from the room.
+
+        This sends an iq request to the room.
+
+        @param roomJID: The bare JID of the room.
+        @type roomJID: L{jid.JID}
+
+        @return: A deferred that fires with the room's configuration form as
+            a L{data_form.Form} or C{None} if there are no configuration
+            options available.
+        """
+
+
+    def join(roomJID, nick, historyOptions=None, password=None):
+        """
+        Join a MUC room by sending presence to it.
+
+        @param roomJID: The JID of the room the entity is joining.
+        @type roomJID: L{jid.JID}
+
+        @param nick: The nick name for the entitity joining the room.
+        @type nick: C{unicode}
+
+        @param historyOptions: Options for conversation history sent by the
+            room upon joining.
+        @type historyOptions: L{HistoryOptions}
+
+        @param password: Optional password for the room.
+        @type password: C{unicode}
+
+        @return: A deferred that fires when the entity is in the room or an
+                 error has occurred.
+        """
+
+
+    def nick(roomJID, nick):
+        """
+        Change an entity's nick name in a MUC room.
+
+        See: http://xmpp.org/extensions/xep-0045.html#changenick
+
+        @param roomJID: The JID of the room, i.e. without a resource.
+        @type roomJID: L{jid.JID}
+
+        @param nick: The new nick name within the room.
+        @type nick: C{unicode}
+        """
+
+
+    def leave(roomJID):
+        """
+        Leave a MUC room.
+
+        See: http://xmpp.org/extensions/xep-0045.html#exit
+
+        @param roomJID: The Room JID of the room to leave.
+        @type roomJID: L{jid.JID}
+        """
+
+
+    def userJoinedRoom(room, user):
+        """
+        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 joined.
+        @type  room: L{muc.Room}
+
+        @param user: The user that joined the room.
+        @type  user: L{muc.User}
+        """
+
+
+    def groupChat(roomJID, body):
+        """
+        Send a groupchat message.
+        """
+
+
+    def chat(occupantJID, body):
+        """
+        Send a private chat message to a user in a MUC room.
+
+        See: http://xmpp.org/extensions/xep-0045.html#privatemessage
+
+        @param occupantJID: The Room JID of the other user.
+        @type occupantJID: L{jid.JID}
+        """
+
+
+    def register(roomJID, options):
+        """
+        Send a request to register for a room.
+
+        @param roomJID: The bare JID of the room.
+        @type roomJID: L{jid.JID}
+
+        @param options: A mapping of field names to values, or C{None} to
+            cancel.
+        @type options: C{dict}
+        """
+
+
+    def subject(roomJID, subject):
+        """
+        Change the subject of a MUC room.
+
+        See: http://xmpp.org/extensions/xep-0045.html#subject-mod
+
+        @param roomJID: The bare JID of the room.
+        @type roomJID: L{jid.JID}
+
+        @param subject: The subject you want to set.
+        @type subject: C{unicode}
+        """
+
+
+    def voice(roomJID):
+        """
+        Request voice for a moderated room.
+
+        @param roomJID: The room jabber/xmpp entity id.
+        @type roomJID: L{jid.JID}
+        """
+
+
+    def history(roomJID, messages):
+        """
+        Send history to create a MUC based on a one on one chat.
+
+        See: http://xmpp.org/extensions/xep-0045.html#continue
+
+        @param roomJID: The room jabber/xmpp entity id.
+        @type roomJID: L{jid.JID}
+
+        @param messages: The history to send to the room as an ordered list of
+                         message, represented by a dictionary with the keys
+                         C{'stanza'}, holding the original stanza a
+                         L{domish.Element}, and C{'timestamp'} with the
+                         timestamp.
+        @type messages: L{list} of L{domish.Element}
+        """
+
+
+    def ban(roomJID, entity, reason=None, sender=None):
+        """
+        Ban a user from a MUC room.
+
+        @param roomJID: The bare JID of the room.
+        @type roomJID: L{jid.JID}
+
+        @param entity: The bare JID of the entity to be banned.
+        @type entity: L{jid.JID}
+
+        @param reason: The reason for banning the entity.
+        @type reason: C{unicode}
+
+        @param sender: The entity sending the request.
+        @type sender: L{jid.JID}
+        """
+
+
+    def kick(roomJID, nick, reason=None, sender=None):
+        """
+        Kick a user from a MUC room.
+
+        @param roomJID: The bare JID of the room.
+        @type roomJID: L{jid.JID}
+
+        @param nick: The occupant to be banned.
+        @type nick: L{jid.JID} or C{unicode}
+
+        @param reason: The reason given for the kick.
+        @type reason: C{unicode}
+
+        @param sender: The entity sending the request.
+        @type sender: L{jid.JID}
+        """

wokkel/test/helpers.py

@@ -6 +6 @@
 """
 
-from twisted.internet import defer
+from twisted.internet import defer, task
 from twisted.words.xish import xpath
 from twisted.words.xish.utility import EventDispatcher
 
 from wokkel.generic import parseXml
+from wokkel.subprotocols import StreamManager
 
 class XmlStreamStub(object):
@@ -93 +94 @@
 
         return d
+
+
+class TestableStreamManager(StreamManager):
+    """
+    Stream manager for testing subprotocol handlers.
+    """
+
+    def __init__(self, reactor=None):
+        class DummyFactory(object):
+            def addBootstrap(self, event, fn):
+                pass
+
+        factory = DummyFactory()
+        StreamManager.__init__(self, factory, reactor)
+        self.stub = XmlStreamStub()
+        self._connected(self.stub.xmlstream)
+        self._authd(self.stub.xmlstream)

wokkel/xmppim.py

@@ -297 +297 @@
 
 
+    def __get_status(self):
+        if None in self.statuses:
+            return self.statuses[None]
+        elif self.statuses:
+            for status in self.status.itervalues():
+                return status
+        else:
+            return None
+
+    status = property(__get_status)
+
+
     def _childParser_show(self, element):
         show = unicode(element)
@@ -368 +380 @@
 
 
-class PresenceProtocol(XMPPHandler):
-    """
-    XMPP Presence protocol.
+class BasePresenceProtocol(XMPPHandler):
+    """
+    XMPP Presence base protocol handler.
+
+    This class is the base for protocol handlers that receive presence
+    stanzas. Listening to all incoming presence stanzas, it extracts the
+    stanza's type and looks up a matching stanza parser and calls the
+    associated method. The method's name is the type + C{Received}. E.g.
+    C{availableReceived}. See L{PresenceProtocol} for a complete example.
 
     @cvar presenceTypeParserMap: Maps presence stanza types to their respective
@@ -376 +394 @@
     @type presenceTypeParserMap: C{dict}
     """
+
+    presenceTypeParserMap = {}
+
+    def connectionInitialized(self):
+        self.xmlstream.addObserver("/presence", self._onPresence)
+
+
+
+    def _onPresence(self, element):
+        """
+        Called when a presence stanza has been received.
+        """
+        stanza = Stanza.fromElement(element)
+
+        presenceType = stanza.stanzaType or 'available'
+
+        try:
+            parser = self.presenceTypeParserMap[presenceType]
+        except KeyError:
+            return
+
+        presence = parser.fromElement(element)
+
+        try:
+            handler = getattr(self, '%sReceived' % presenceType)
+        except AttributeError:
+            return
+        else:
+            handler(presence)
+
+
+
+class PresenceProtocol(BasePresenceProtocol):
 
     presenceTypeParserMap = {
@@ -386 +437 @@
                 'unsubscribed': SubscriptionPresence,
                 'probe': ProbePresence,
-        }
-
-    def connectionInitialized(self):
-        self.xmlstream.addObserver("/presence", self._onPresence)
-
-
-    def _onPresence(self, element):
-        stanza = Stanza.fromElement(element)
-
-        presenceType = stanza.stanzaType or 'available'
-
-        try:
-            parser = self.presenceTypeParserMap[presenceType]
-        except KeyError:
-            return
-
-        presence = parser.fromElement(element)
-
-        try:
-            handler = getattr(self, '%sReceived' % presenceType)
-        except AttributeError:
-            return
-        else:
-            handler(presence)
+                }
 
 
@@ -700 +728 @@
         """
 
+
+
+class Message(Stanza):
+    """
+    A message stanza.
+    """
+
+    stanzaKind = 'message'
+
+    childParsers = {
+            (None, 'body'): '_childParser_body',
+            (None, 'subject'): '_childParser_subject',
+            }
+
+    def __init__(self, recipient=None, sender=None, body=None, subject=None):
+        Stanza.__init__(self, recipient, sender)
+        self.body = body
+        self.subject = subject
+
+
+    def _childParser_body(self, element):
+        self.body = unicode(element)
+
+
+    def _childParser_subject(self, element):
+        self.subject = unicode(element)
+
+
+    def toElement(self):
+        element = Stanza.toElement(self)
+
+        if self.body:
+            element.addElement('body', content=self.body)
+        if self.subject:
+            element.addElement('subject', content=self.subject)
+
+        return element
+
+
+
 class MessageProtocol(XMPPHandler):
     """