Merge branch 'doc-update' into 'master'

Add documentation on how to replace proces()

See merge request poezio/slixmpp!186
This commit is contained in:
mathieui 2022-02-27 20:48:48 +01:00
commit 001e0c7060
4 changed files with 60 additions and 2 deletions

View file

@ -9,6 +9,7 @@ Tutorials, FAQs, and How To Guides
internal_api internal_api
features features
sasl sasl
remove_process
handlersmatchers handlersmatchers
guide_xep_0030 guide_xep_0030
xmpp_tdg xmpp_tdg

View file

@ -0,0 +1,55 @@
.. _remove-process:
How to remove xmpp.process()
============================
Starting from slixmpp 1.8.0, running ``process()`` on an
XMLStream/ClientXMPP/ComponentXMPP instance is deprecated, and starting from
1.9.0, it will be removed.
Why
---
This has been the usual way of running an application using SleekXMPP/slixmpp
for ages, but it has come at a price: people do not understand how they
should run their application without it, or how to integrate their slixmpp
code with the rest of their asyncio application.
In essence, ``process()`` is only a very thin wrapper around asyncio loop
functions:
.. code-block:: python
if timeout is None:
if forever:
self.loop.run_forever()
else:
self.loop.run_until_complete(self.disconnected)
else:
tasks: List[Future] = [asyncio.sleep(timeout)]
if not forever:
tasks.append(self.disconnected)
self.loop.run_until_complete(asyncio.wait(tasks))
How
---
Hence it can be replaced according to what you want your application to do:
- To run forever, ``loop.run_forever()`` will work just fine
- To run until disconnected, ``loop.run_until_complete(xmpp.disconnected)``
will be enough (XMLStream.disconnected is an future which result is set when
the stream gets disconnected.
- To run for a scheduled time (and still abort when disconnected):
.. code-block:: python
tasks = [asyncio.sleep(timeout)]
tasks.append(xmpp.disconnected)
loop.run_until_complete(asyncio.wait(tasks))
There is no magic at play here and anything is possible if a more flexible
execution scheme is expected.

View file

@ -193,7 +193,7 @@ implementation should work correctly.
.. tip:: .. tip::
To see how to implement in-band registration as a Slixmpp plugin, To see how to implement in-band registration as a Slixmpp plugin,
see the tutorial :ref:`tutorial-create-plugin`. see the tutorial :ref:`create-plugin`.
`View full source (5) <http://github.com/legastero/xmpp-tdg/blob/master/code/CheshiR/RegistrableComponent.py>`_ | `View full source (5) <http://github.com/legastero/xmpp-tdg/blob/master/code/CheshiR/RegistrableComponent.py>`_ |
`View original code (5) <http://github.com/remko/xmpp-tdg/blob/master/code/CheshiR/RegistrableComponent.py>`_ `View original code (5) <http://github.com/remko/xmpp-tdg/blob/master/code/CheshiR/RegistrableComponent.py>`_

View file

@ -149,6 +149,8 @@ class XEP_0313(BasePlugin):
""" """
Iterate over each message of MAM query. Iterate over each message of MAM query.
.. versionadded:: 1.8.0
:param jid: Entity holding the MAM records :param jid: Entity holding the MAM records
:param start: MAM query start time :param start: MAM query start time
:param end: MAM query end time :param end: MAM query end time
@ -239,7 +241,7 @@ class XEP_0313(BasePlugin):
async def get_fields(self, jid: Optional[JID] = None, **iqkwargs) -> Form: async def get_fields(self, jid: Optional[JID] = None, **iqkwargs) -> Form:
"""Get MAM query fields. """Get MAM query fields.
.. versionaddedd:: 1.8.0 .. versionadded:: 1.8.0
:param jid: JID to retrieve the policy from. :param jid: JID to retrieve the policy from.
:return: The Form of allowed options :return: The Form of allowed options