diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/differences.rst | 10 | ||||
| -rw-r--r-- | docs/using_asyncio.rst | 40 |
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) |