summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/differences.rst10
-rw-r--r--docs/using_asyncio.rst40
2 files changed, 36 insertions, 14 deletions
diff --git a/docs/differences.rst b/docs/differences.rst
index e6e26d2c..f6e005b5 100644
--- a/docs/differences.rst
+++ b/docs/differences.rst
@@ -32,12 +32,12 @@ Differences from SleekXMPP
handlers, which will be also handled in the event loop.
The :class:`~.slixmpp.stanza.Iq` object’s :meth:`~.slixmpp.stanza.Iq.send`
- method now takes a *coroutine* parameter which, if set to ``True``,
- will return a coroutine which will (asyncio-)block until the reply
- is received.
+ method now **always** return a :class:`~.asyncio.Future` which result will be set
+ to the IQ reply when it is received, or to ``None`` if the IQ is not of
+ type ``get`` or ``set``.
- Many plugins (WIP) calls which retrieve information also accept this
- ``coroutine`` parameter.
+ Many plugins (WIP) calls which retrieve information also return the same
+ future.
**Architectural differences**
slixmpp does not have an event queue anymore, and instead processes
diff --git a/docs/using_asyncio.rst b/docs/using_asyncio.rst
index 7f63d29d..c84148e8 100644
--- a/docs/using_asyncio.rst
+++ b/docs/using_asyncio.rst
@@ -7,23 +7,46 @@ Using asyncio
Block on IQ sending
~~~~~~~~~~~~~~~~~~~
-:meth:`.Iq.send` now accepts a ``coroutine`` parameter which, if ``True``,
-will return a coroutine waiting for the IQ reply to be received.
+:meth:`.Iq.send` now returns a :class:`~.Future` so you can easily block with:
.. code-block:: python
- result = yield from iq.send(coroutine=True)
+ result = yield from iq.send()
+
+.. warning::
+
+ If the reply is an IQ with an ``error`` type, this will raise an
+ :class:`.IqError`, and if it timeouts, it will raise an
+ :class:`.IqTimeout`. Don't forget to catch it.
+
+You can still use callbacks instead.
XEP plugin integration
~~~~~~~~~~~~~~~~~~~~~~
-Many XEP plugins have been modified to accept this ``coroutine`` parameter as
-well, so you can do things like:
+The same changes from the SleekXMPP API apply, so you can do:
+
+.. code-block:: python
+
+ iq_info = yield from self.xmpp['xep_0030'].get_info(jid)
+
+But the following will only return a Future:
.. code-block:: python
- iq_info = yield from self.xmpp['xep_0030'].get_info(jid, coroutine=True)
+ iq_info = self.xmpp['xep_0030'].get_info(jid)
+
+
+Callbacks, Event Handlers, and Stream Handlers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+IQ callbacks and :term:`Event Handlers <event handler>` can be coroutine
+functions; in this case, they will be scheduled in the event loop using
+:meth:`.asyncio.async` and not ran immediately.
+A :class:`.CoroutineCallback` class has been added as well for
+:term:`Stream Handlers <stream handler>`, which will use
+:meth:`.asyncio.async` to schedule the callback.
Running the event loop
~~~~~~~~~~~~~~~~~~~~~~
@@ -52,7 +75,7 @@ callbacks while everything is not ready.
client = slixmpp.ClientXMPP('jid@example', 'password')
client.connected_event = asyncio.Event()
- callback = lambda event: client.connected_event.set()
+ callback = lambda _: client.connected_event.set()
client.add_event_handler('session_start', callback)
client.connect()
loop.run_until_complete(event.wait())
@@ -112,8 +135,7 @@ JID indicating its findings.
def on_message(self, event):
# You should probably handle IqError and IqTimeout exceptions here
# but this is an example.
- version = yield from self['xep_0092'].get_version(message['from'],
- coroutine=True)
+ version = yield from self['xep_0092'].get_version(message['from'])
text = "%s sent me a message, he runs %s" % (message['from'],
version['software_version']['name'])
self.send_message(mto='master@example.tld', mbody=text)