summaryrefslogtreecommitdiff
path: root/docs/using_asyncio.rst
diff options
context:
space:
mode:
authormathieui <mathieui@mathieui.net>2015-02-28 13:34:52 +0100
committermathieui <mathieui@mathieui.net>2015-02-28 19:02:35 +0100
commitbf5d7c83af320b7af629857aab7060302abfabf5 (patch)
tree548e088aae38c780300b7f10fc7eec092db33a1a /docs/using_asyncio.rst
parentc66a4d4097a249efc029b761d6150378a54bf702 (diff)
downloadslixmpp-bf5d7c83af320b7af629857aab7060302abfabf5.tar.gz
slixmpp-bf5d7c83af320b7af629857aab7060302abfabf5.tar.bz2
slixmpp-bf5d7c83af320b7af629857aab7060302abfabf5.tar.xz
slixmpp-bf5d7c83af320b7af629857aab7060302abfabf5.zip
Change the API to make iq.send() always return a future
remove coroutine_wrapper, add a future_wrapper (which is only needed when the result stanza can be cached). Update the documentation as well.
Diffstat (limited to 'docs/using_asyncio.rst')
-rw-r--r--docs/using_asyncio.rst40
1 files changed, 31 insertions, 9 deletions
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)