Merge branch 'doc-update' into 'master'

Add documentation on how to replace proces()

See merge request poezio/slixmpp!186

3 files changed, 57 insertions, 1 deletions

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.
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) <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>`_