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 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/howto') 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) `_ -- 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 (limited to 'docs/howto') 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