pep/slixmpp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

XEP-0059: docs and typing

Browse source 
Also:
 - fix a typo in the plugin description (wrong number)
 - add iq_options to make retrieval more flexible
This commit is contained in:
mathieui 2021-03-07 19:47:00 +01:00
parent ae31f78b63
commit 27cf97458b
1 changed files with 107 additions and 63 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

170
slixmpp/plugins/xep_0059/rsm.py
View file

@ -5,9 +5,16 @@
# See the file LICENSE for copying permission. # See the file LICENSE for copying permission.
import logging import logging
import slixmpp from collections.abc import AsyncIterator
from slixmpp import Iq from typing import (
from slixmpp.plugins import BasePlugin, register_plugin Any,
Callable,
Dict,
Optional,
)
from slixmpp.stanza import Iq
from slixmpp.plugins import BasePlugin
from slixmpp.xmlstream import register_stanza_plugin from slixmpp.xmlstream import register_stanza_plugin
from slixmpp.plugins.xep_0059 import stanza, Set from slixmpp.plugins.xep_0059 import stanza, Set
from slixmpp.exceptions import XMPPError from slixmpp.exceptions import XMPPError
@ -16,41 +23,73 @@ from slixmpp.exceptions import XMPPError
log = logging.getLogger(__name__) log = logging.getLogger(__name__)
class ResultIterator: class ResultIterator(AsyncIterator):
""" """
An iterator for Result Set Management An iterator for Result Set Management
Example:
.. code-block:: python
q = Iq()
q['to'] = 'pubsub.example.com'
q['disco_items']['node'] = 'blog'
async for i in ResultIterator(q, 'disco_items', '10'):
print(i['disco_items']['items'])
""" """
#: Template for the RSM query
query: Iq
#: Substanza of the query to send, e.g. "disco_items"
interface: str
#: Stanza interface on the query results providing the retrieved
#: elements (used to count them)
results: str
#: From which item id to start
start: Optional[str]
#: Amount of elements to retrieve for each page
amount: int
#: If True, page backwards through the results
reverse: bool
#: Callback to run before sending the stanza
pre_cb: Optional[Callable[[Iq], None]]
#: Callback to run after receiving the reply
post_cb: Optional[Callable[[Iq], None]]
#: Optional dict of Iq options (timeout, etc…) for Iq.send()
iq_options: Dict[str, Any]
def __init__(self, query, interface, results='substanzas', amount=10, def __init__(self, query: Iq, interface: str, results: str = 'substanzas',
start=None, reverse=False, recv_interface=None, amount: int = 10,
pre_cb=None, post_cb=None): start: Optional[str] = None, reverse: bool = False,
recv_interface: Optional[str] = None,
pre_cb: Optional[Callable[[Iq], None]] = None,
post_cb: Optional[Callable[[Iq], None]] = None,
iq_options: Optional[Dict[str, Any]] = None):
""" """
Arguments: :param query: The template query
query -- The template query :param interface: The substanza of the query to send, for example
interface -- The substanza of the query to send, for example disco_items disco_items
recv_interface -- The substanza of the query to receive, for example disco_items :param recv_interface: The substanza of the query to receive, for
results -- The query stanza's interface which provides a example disco_items
:param results: The query stanza's interface which provides a
countable list of query results. countable list of query results.
amount -- The max amounts of items to request per iteration :param amount: The max amounts of items to request per iteration
start -- From which item id to start :param start: From which item id to start
reverse -- If True, page backwards through the results :param reverse: If True, page backwards through the results
pre_cb -- Callback to run before sending the stanza :param pre_cb: Callback to run before sending the stanza
post_cb -- Callback to run after receiving the reply :param post_cb: Callback to run after receiving the reply
:param iq_options: Optional dict of parameters for Iq.send
Example:
q = Iq()
q['to'] = 'pubsub.example.com'
q['disco_items']['node'] = 'blog'
for i in ResultIterator(q, 'disco_items', '10'):
print i['disco_items']['items']
""" """
self.query = query self.query = query
self.amount = amount self.amount = amount
self.start = start self.start = start
if iq_options is None:
self.iq_options = {}
else:
self.iq_options = iq_options
self.interface = interface self.interface = interface
if recv_interface: if recv_interface is not None:
self.recv_interface = recv_interface self.recv_interface = recv_interface
else: else:
self.recv_interface = interface self.recv_interface = interface
@ -63,10 +102,10 @@ class ResultIterator:
def __aiter__(self): def __aiter__(self):
return self return self
async def __anext__(self): async def __anext__(self) -> Iq:
return await self.next() return await self.next()
async def next(self): async def next(self) -> Iq:
""" """
Return the next page of results from a query. Return the next page of results from a query.
@ -76,20 +115,19 @@ class ResultIterator:
""" """
if self._stop: if self._stop:
raise StopAsyncIteration raise StopAsyncIteration
if self.query[self.interface]['rsm']['before'] is None:
self.query[self.interface]['rsm']['before'] = self.reverse
self.query['id'] = self.query.stream.new_id() self.query['id'] = self.query.stream.new_id()
self.query[self.interface]['rsm']['max'] = str(self.amount) self.query[self.interface]['rsm']['max'] = str(self.amount)
if self.start and self.reverse: if self.start:
self.query[self.interface]['rsm']['before'] = self.start if self.reverse:
elif self.start: self.query[self.interface]['rsm']['before'] = self.start
self.query[self.interface]['rsm']['after'] = self.start else:
self.query[self.interface]['rsm']['after'] = self.start
try: try:
if self.pre_cb: if self.pre_cb:
self.pre_cb(self.query) self.pre_cb(self.query)
r = await self.query.send() r = await self.query.send(**self.iq_options)
if not r[self.recv_interface]['rsm']['first'] and \ if not r[self.recv_interface]['rsm']['first'] and \
not r[self.recv_interface]['rsm']['last']: not r[self.recv_interface]['rsm']['last']:
@ -118,7 +156,7 @@ class ResultIterator:
class XEP_0059(BasePlugin): class XEP_0059(BasePlugin):
""" """
XEP-0050: Result Set Management XEP-0059: Result Set Management
""" """
name = 'xep_0059' name = 'xep_0059'
@ -139,34 +177,40 @@ class XEP_0059(BasePlugin):
def session_bind(self, jid): def session_bind(self, jid):
self.xmpp['xep_0030'].add_feature(Set.namespace) self.xmpp['xep_0030'].add_feature(Set.namespace)
def iterate(self, stanza, interface, results='substanzas', amount=10, reverse=False, def iterate(self, stanza: Iq, interface: str, results: str = 'substanzas',
recv_interface=None, pre_cb=None, post_cb=None): amount: int = 10, reverse: bool = False,
recv_interface: Optional[str] = None,
pre_cb: Optional[Callable[[Iq], None]] = None,
post_cb: Optional[Callable[[Iq], None]] = None,
iq_options: Optional[Dict[str, Any]] = None
) -> ResultIterator:
""" """
Create a new result set iterator for a given stanza query. Create a new result set iterator for a given stanza query.
Arguments: :param stanza: A stanza object to serve as a template for
stanza -- A stanza object to serve as a template for queries made each iteration. For example, a
queries made each iteration. For example, a basic disco#items query.
basic disco#items query. :param interface: The name of the substanza to which the
interface -- The name of the substanza to which the result set management stanza should be
result set management stanza should be appended in the query stanza. For example,
appended in the query stanza. For example, for disco#items queries the interface
for disco#items queries the interface 'disco_items' should be used.
'disco_items' should be used. :param recv_interface: The name of the substanza from which the
recv_interface -- The name of the substanza from which the result set management stanza should be
result set management stanza should be read in the result stanza. If unspecified,
read in the result stanza. If unspecified, it will be set to the same value as the
it will be set to the same value as the ``interface`` parameter.
``interface`` parameter. :param pre_cb: Callback to run before sending each stanza e.g.
pre_cb -- Callback to run before sending each stanza e.g. setting the MAM queryid and starting a stanza
setting the MAM queryid and starting a stanza collector.
collector. :param post_cb: Callback to run after receiving each stanza e.g.
post_cb -- Callback to run after receiving each stanza e.g. stopping a MAM stanza collector in order to
stopping a MAM stanza collector in order to gather results.
gather results. :param results: The name of the interface containing the
results -- The name of the interface containing the query results (typically just 'substanzas').
query results (typically just 'substanzas'). :param iq_options: Optional dict of parameters for Iq.send
""" """
return ResultIterator(stanza, interface, results, amount, reverse=reverse, return ResultIterator(stanza, interface, results, amount,
recv_interface=recv_interface, pre_cb=pre_cb, reverse=reverse, recv_interface=recv_interface,
post_cb=post_cb) pre_cb=pre_cb, post_cb=post_cb,
iq_options=iq_options)