Add a friendlier introduction to events

readthedocs/extra/advanced-usage/update-modes.rst

@@ -0,0 +1,144 @@
+.. _update-modes:
+
+============
+Update Modes
+============
+
+
+The library can run in four distinguishable modes:
+
+- With no extra threads at all.
+- With an extra thread that receives everything as soon as possible (default).
+- With several worker threads that run your update handlers.
+- A mix of the above.
+
+Since this section is about updates, we'll describe the simplest way to
+work with them.
+
+
+Using multiple workers
+**********************
+
+When you create your client, simply pass a number to the
+``update_workers`` parameter:
+
+    ``client = TelegramClient('session', api_id, api_hash, update_workers=2)``
+
+You can set any amount of workers you want. The more you put, the more
+update handlers that can be called "at the same time". One or two should
+suffice most of the time, since setting more will not make things run
+faster most of the times (actually, it could slow things down).
+
+The next thing you want to do is to add a method that will be called when
+an `Update`__ arrives:
+
+    .. code-block:: python
+
+        def callback(update):
+            print('I received', update)
+
+        client.add_update_handler(callback)
+        # do more work here, or simply sleep!
+
+That's it! This is the old way to listen for raw updates, with no further
+processing. If this feels annoying for you, remember that you can always
+use :ref:`working-with-updates` but maybe use this for some other cases.
+
+Now let's do something more interesting. Every time an user talks to use,
+let's reply to them with the same text reversed:
+
+    .. code-block:: python
+
+        from telethon.tl.types import UpdateShortMessage, PeerUser
+
+        def replier(update):
+            if isinstance(update, UpdateShortMessage) and not update.out:
+                client.send_message(PeerUser(update.user_id), update.message[::-1])
+
+
+        client.add_update_handler(replier)
+        input('Press enter to stop this!')
+        client.disconnect()
+
+We only ask you one thing: don't keep this running for too long, or your
+contacts will go mad.
+
+
+Spawning no worker at all
+*************************
+
+All the workers do is loop forever and poll updates from a queue that is
+filled from the ``ReadThread``, responsible for reading every item off
+the network. If you only need a worker and the ``MainThread`` would be
+doing no other job, this is the preferred way. You can easily do the same
+as the workers like so:
+
+    .. code-block:: python
+
+        while True:
+            try:
+                update = client.updates.poll()
+                if not update:
+                    continue
+
+                print('I received', update)
+            except KeyboardInterrupt:
+                break
+
+        client.disconnect()
+
+Note that ``poll`` accepts a ``timeout=`` parameter, and it will return
+``None`` if other thread got the update before you could or if the timeout
+expired, so it's important to check ``if not update``.
+
+This can coexist with the rest of ``N`` workers, or you can set it to ``0``
+additional workers:
+
+    ``client = TelegramClient('session', api_id, api_hash, update_workers=0)``
+
+You **must** set it to ``0`` (or other number), as it defaults to ``None``
+and there is a different. ``None`` workers means updates won't be processed
+*at all*, so you must set it to some value (``0`` or greater) if you want
+``client.updates.poll()`` to work.
+
+
+Using the main thread instead the ``ReadThread``
+************************************************
+
+If you have no work to do on the ``MainThread`` and you were planning to have
+a ``while True: sleep(1)``, don't do that. Instead, don't spawn the secondary
+``ReadThread`` at all like so:
+
+    .. code-block:: python
+
+        client = TelegramClient(
+            ...
+            spawn_read_thread=False
+        )
+
+And then ``.idle()`` from the ``MainThread``:
+
+    ``client.idle()``
+
+You can stop it with :kbd:`Control+C`, and you can configure the signals
+to be used in a similar fashion to `Python Telegram Bot`__.
+
+As a complete example:
+
+    .. code-block:: python
+
+        def callback(update):
+            print('I received', update)
+
+        client = TelegramClient('session', api_id, api_hash,
+                                update_workers=1, spawn_read_thread=False)
+
+        client.connect()
+        client.add_update_handler(callback)
+        client.idle()  # ends with Ctrl+C
+
+
+This is the preferred way to use if you're simply going to listen for updates.
+
+__ https://lonamiwebs.github.io/Telethon/types/update.html
+__ https://github.com/python-telegram-bot/python-telegram-bot/blob/4b3315db6feebafb94edcaa803df52bb49999ced/telegram/ext/updater.py#L460