Ignore:
Timestamp:
Apr 16, 2008, 4:08:15 PM (14 years ago)
Author:
Ralph Meijer <ralphm@…>
Branch:
default
Convert:
svn:b33ecbfc-034c-dc11-8662-000475d9059e/trunk@48
Message:

Add maxItems argument to PubSubClient?.items(), lot of docs and tests.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wokkel/pubsub.py

    r17 r18  
    7878
    7979
     80
    8081class SubscriptionPending(Exception):
    8182    """
    8283    Raised when the requested subscription is pending acceptance.
    8384    """
     85
    8486
    8587
     
    8991    becoming active.
    9092    """
     93
    9194
    9295
     
    104107
    105108
     109
    106110class Unsupported(PubSubError):
    107111    def __init__(self, feature, text=None):
     
    112116
    113117
     118
    114119class OptionsUnavailable(Unsupported):
    115120    def __init__(self):
    116121        Unsupported.__init__(self, 'subscription-options-unavailable')
     122
    117123
    118124
     
    136142        """
    137143
    138         domish.Element.__init__(self, (None, 'item'))
     144        domish.Element.__init__(self, (NS_PUBSUB, 'item'))
    139145        if id is not None:
    140146            self['id'] = id
     
    146152
    147153
    148 class PubSubRequest(xmlstream.IQ):
    149     """
    150     Base class for publish subscribe user requests.
    151 
    152     @cvar namespace: request namespace
    153     @cvar verb: request verb
    154     @cvar method: type attribute of the IQ request. Either C{'set'} or C{'get'}
    155     @ivar command: command element of the request. This is the direct child of
     154
     155class _PubSubRequest(xmlstream.IQ):
     156    """
     157    Publish subscribe request.
     158
     159    @ivar verb: Request verb
     160    @type verb: C{str}
     161    @ivar namespace: Request namespace.
     162    @type namespace: C{str}
     163    @ivar method: Type attribute of the IQ request. Either C{'set'} or C{'get'}
     164    @type method: C{str}
     165    @ivar command: Command element of the request. This is the direct child of
    156166                   the C{pubsub} element in the C{namespace} with the name
    157167                   C{verb}.
    158168    """
    159169
    160     namespace = NS_PUBSUB
    161     method = 'set'
    162 
    163     def __init__(self, xs):
    164         xmlstream.IQ.__init__(self, xs, self.method)
    165         self.addElement((self.namespace, 'pubsub'))
    166 
    167         self.command = self.pubsub.addElement(self.verb)
     170    def __init__(self, xs, verb, namespace=NS_PUBSUB, method='set'):
     171        xmlstream.IQ.__init__(self, xs, method)
     172        self.addElement((namespace, 'pubsub'))
     173
     174        self.command = self.pubsub.addElement(verb)
    168175
    169176    def send(self, to):
     
    181188
    182189
    183 class CreateNode(PubSubRequest):
    184     verb = 'create'
    185 
    186     def __init__(self, xs, node=None):
    187         PubSubRequest.__init__(self, xs)
    188         if node:
    189             self.command["node"] = node
    190 
    191 
    192 class DeleteNode(PubSubRequest):
    193     verb = 'delete'
    194     def __init__(self, xs, node):
    195         PubSubRequest.__init__(self, xs)
    196         self.command["node"] = node
    197 
    198 
    199 class Subscribe(PubSubRequest):
    200     verb = 'subscribe'
    201 
    202     def __init__(self, xs, node, subscriber):
    203         PubSubRequest.__init__(self, xs)
    204         self.command["node"] = node
    205         self.command["jid"] = subscriber.full()
    206 
    207 
    208 class Unsubscribe(PubSubRequest):
    209     verb = 'unsubscribe'
    210 
    211     def __init__(self, xs, node, subscriber):
    212         PubSubRequest.__init__(self, xs)
    213         self.command["node"] = node
    214         self.command["jid"] = subscriber.full()
    215 
    216 
    217 class Publish(PubSubRequest):
    218     verb = 'publish'
    219 
    220     def __init__(self, xs, node):
    221         PubSubRequest.__init__(self, xs)
    222         self.command["node"] = node
    223 
    224     def addItem(self, id=None, payload=None):
    225         item = self.command.addElement("item")
    226         item.addChild(payload)
    227 
    228         if id is not None:
    229             item["id"] = id
    230 
    231         return item
    232 
    233 class Items(PubSubRequest):
    234     verb = 'items'
    235     method = 'get'
    236 
    237     def __init__(self, xs, node):
    238         PubSubRequest.__init__(self, xs)
    239         self.command["node"] = node
    240190
    241191class PubSubClient(XMPPHandler):
     
    297247
    298248    def createNode(self, service, nodeIdentifier=None):
    299         request = CreateNode(self.xmlstream, nodeIdentifier)
     249        """
     250        Create a publish subscribe node.
     251
     252        @param service: The publish subscribe service to create the node at.
     253        @type service: L{JID}
     254        @param nodeIdentifier: Optional suggestion for the id of the node.
     255        @type nodeIdentifier: C{unicode}
     256        """
     257
     258
     259        request = _PubSubRequest(self.xmlstream, 'create')
     260        if nodeIdentifier:
     261            request.command['node'] = nodeIdentifier
    300262
    301263        def cb(iq):
     
    310272
    311273    def deleteNode(self, service, nodeIdentifier):
    312         return DeleteNode(self.xmlstream, nodeIdentifier).send(service)
     274        """
     275        Delete a publish subscribe node.
     276
     277        @param service: The publish subscribe service to delete the node from.
     278        @type service: L{JID}
     279        @param nodeIdentifier: The identifier of the node.
     280        @type nodeIdentifier: C{unicode}
     281        """
     282        request = _PubSubRequest(self.xmlstream, 'delete')
     283        request.command['node'] = nodeIdentifier
     284        return request.send(service)
    313285
    314286    def subscribe(self, service, nodeIdentifier, subscriber):
    315         request = Subscribe(self.xmlstream, nodeIdentifier, subscriber)
     287        """
     288        Subscribe to a publish subscribe node.
     289
     290        @param service: The publish subscribe service that keeps the node.
     291        @type service: L{JID}
     292        @param nodeIdentifier: The identifier of the node.
     293        @type nodeIdentifier: C{unicode}
     294        @param subscriber: The entity to subscribe to the node. This entity
     295                           will get notifications of new published items.
     296        @type subscriber: L{JID}
     297        """
     298        request = _PubSubRequest(self.xmlstream, 'subscribe')
     299        request.command['node'] = nodeIdentifier
     300        request.command['jid'] = subscriber.full()
    316301
    317302        def cb(iq):
     
    331316
    332317    def unsubscribe(self, service, nodeIdentifier, subscriber):
    333         request = Unsubscribe(self.xmlstream, nodeIdentifier, subscriber)
     318        """
     319        Unsubscribe from a publish subscribe node.
     320
     321        @param service: The publish subscribe service that keeps the node.
     322        @type service: L{JID}
     323        @param nodeIdentifier: The identifier of the node.
     324        @type nodeIdentifier: C{unicode}
     325        @param subscriber: The entity to unsubscribe from the node.
     326        @type subscriber: L{JID}
     327        """
     328        request = _PubSubRequest(self.xmlstream, 'unsubscribe')
     329        request.command['node'] = nodeIdentifier
     330        request.command['jid'] = subscriber.full()
    334331        return request.send(service)
    335332
    336     def publish(self, service, nodeIdentifier, items=[]):
    337         request = Publish(self.xmlstream, nodeIdentifier)
    338         for item in items:
    339             request.command.addChild(item)
     333    def publish(self, service, nodeIdentifier, items=None):
     334        """
     335        Publish to a publish subscribe node.
     336
     337        @param service: The publish subscribe service that keeps the node.
     338        @type service: L{JID}
     339        @param nodeIdentifier: The identifier of the node.
     340        @type nodeIdentifier: C{unicode}
     341        @param items: Optional list of L{Item}s to publish.
     342        @type items: C{list}
     343        """
     344        request = _PubSubRequest(self.xmlstream, 'publish')
     345        request.command['node'] = nodeIdentifier
     346        if items:
     347            for item in items:
     348                request.command.addChild(item)
    340349
    341350        return request.send(service)
    342351
    343     def items(self, service, nodeIdentifier):
     352    def items(self, service, nodeIdentifier, maxItems=None):
     353        """
     354        Retrieve previously published items from a publish subscribe node.
     355
     356        @param service: The publish subscribe service that keeps the node.
     357        @type service: L{JID}
     358        @param nodeIdentifier: The identifier of the node.
     359        @type nodeIdentifier: C{unicode}
     360        @param maxItems: Optional limit on the number of retrieved items.
     361        @type maxItems: C{int}
     362        """
     363        request = _PubSubRequest(self.xmlstream, 'items', method='get')
     364        request.command['node'] = nodeIdentifier
     365        if maxItems:
     366            request.command["max_items"] = str(int(maxItems))
     367
    344368        def cb(iq):
    345369            items = []
     
    349373            return items
    350374
    351         request = Items(self.xmlstream, nodeIdentifier)
    352375        return request.send(service).addCallback(cb)
     376
     377
    353378
    354379class PubSubService(XMPPHandler, IQHandlerMixin):
Note: See TracChangeset for help on using the changeset viewer.