From b23b805dc521edf0dcdd8d4ac6b8b43539aba536 Mon Sep 17 00:00:00 2001 From: mathieui Date: Sun, 27 Feb 2022 20:32:48 +0100 Subject: docs: Fix some wrong references --- docs/howto/xmpp_tdg.rst | 2 +- slixmpp/plugins/xep_0313/mam.py | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/howto/xmpp_tdg.rst b/docs/howto/xmpp_tdg.rst index 53194e13..d3b761d2 100644 --- a/docs/howto/xmpp_tdg.rst +++ b/docs/howto/xmpp_tdg.rst @@ -193,7 +193,7 @@ implementation should work correctly. .. tip:: 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) `_ | `View original code (5) `_ diff --git a/slixmpp/plugins/xep_0313/mam.py b/slixmpp/plugins/xep_0313/mam.py index 02efd3ce..f49ac637 100644 --- a/slixmpp/plugins/xep_0313/mam.py +++ b/slixmpp/plugins/xep_0313/mam.py @@ -149,6 +149,8 @@ class XEP_0313(BasePlugin): """ Iterate over each message of MAM query. + .. versionadded:: 1.8.0 + :param jid: Entity holding the MAM records :param start: MAM query start 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: """Get MAM query fields. - .. versionaddedd:: 1.8.0 + .. versionadded:: 1.8.0 :param jid: JID to retrieve the policy from. :return: The Form of allowed options -- cgit v1.2.3 From 5c4c867dee2d0195d94c6f01f04ae92e1e8b84c2 Mon Sep 17 00:00:00 2001 From: mathieui Date: Sun, 27 Feb 2022 20:33:26 +0100 Subject: docs: add a page on how to remove process() --- docs/howto/index.rst | 1 + docs/howto/remove_process.rst | 55 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 docs/howto/remove_process.rst diff --git a/docs/howto/index.rst b/docs/howto/index.rst index e4dee4d7..a4f0f3b0 100644 --- a/docs/howto/index.rst +++ b/docs/howto/index.rst @@ -9,6 +9,7 @@ Tutorials, FAQs, and How To Guides internal_api features sasl + remove_process handlersmatchers guide_xep_0030 xmpp_tdg diff --git a/docs/howto/remove_process.rst b/docs/howto/remove_process.rst new file mode 100644 index 00000000..26d54a62 --- /dev/null +++ b/docs/howto/remove_process.rst @@ -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. -- cgit v1.2.3