From 4ebf825c43b1e3f502c5d3f8d08e3fe8e2863f96 Mon Sep 17 00:00:00 2001
From: Lonami Exo <totufals@hotmail.com>
Date: Thu, 23 May 2019 12:11:58 +0200
Subject: [PATCH] Clarify documentation on connection and receiving updates

---
 telethon/client/telegrambaseclient.py | 10 +++++++++
 telethon/client/updates.py            | 29 +++++++++++++++++++--------
 2 files changed, 31 insertions(+), 8 deletions(-)

diff --git a/telethon/client/telegrambaseclient.py b/telethon/client/telegrambaseclient.py
index e5a722ef..3fc2bcb9 100644
--- a/telethon/client/telegrambaseclient.py
+++ b/telethon/client/telegrambaseclient.py
@@ -385,6 +385,16 @@ class TelegramBaseClient(abc.ABC):
         """
         Connects to Telegram.
 
+        .. note::
+
+            Connect means connect and nothing else, and only one low-level
+            request is made to notify Telegram about which layer we will be
+            using.
+
+            Before Telegram sends you updates, you need to make a high-level
+            request, like `client.get_me() <telethon.client.users.UserMethods.get_me>`,
+            as described in https://core.telegram.org/api/updates.
+
         Example
             .. code-block:: python
 
diff --git a/telethon/client/updates.py b/telethon/client/updates.py
index 00c3f3a0..c6df1546 100644
--- a/telethon/client/updates.py
+++ b/telethon/client/updates.py
@@ -19,7 +19,9 @@ class UpdateMethods(UserMethods):
 
     async def _run_until_disconnected(self: 'TelegramClient'):
         try:
-            await self.disconnected
+            # Make a high-level request to notify that we want updates
+            await self(functions.updates.GetStateRequest())
+            return await self.disconnected
         except KeyboardInterrupt:
             pass
         finally:
@@ -29,17 +31,28 @@ class UpdateMethods(UserMethods):
         """
         Runs the event loop until the library is disconnected.
 
-        Disconnections can be manual (by calling `disconnect()
-        <telethon.client.telegrambaseclient.TelegramBaseClient.disconnect>`)
-        or not (if the library fails to reconnect automatically).
+        It also notifies Telegram that we want to receive updates
+        as described in https://core.telegram.org/api/updates.
 
-        If a disconnection error occurs (i.e. not manual disconnect),
-        said error will be raised through here, so you have a chance
-        to ``except`` it on your own code.
+        Manual disconnections can be made by calling `disconnect()
+        <telethon.client.telegrambaseclient.TelegramBaseClient.disconnect>`
+        or sending a ``KeyboardInterrupt`` (e.g. by pressing ``Ctrl+C`` on
+        the console window running the script).
+
+        If a disconnection error occurs (i.e. the library fails to reconnect
+        automatically), said error will be raised through here, so you have a
+        chance to ``except`` it on your own code.
 
         If the loop is already running, this method returns a coroutine
         that you should await on your own code.
 
+        .. note::
+
+            If you want to handle ``KeyboardInterrupt`` in your code,
+            simply run the event loop in your code too in any way, such as
+            ``loop.run_forever()`` or ``await client.disconnected`` (e.g.
+            ``loop.run_until_complete(client.disconnected)``).
+
         Example
             .. code-block:: python
 
@@ -52,7 +65,7 @@ class UpdateMethods(UserMethods):
         if self.loop.is_running():
             return self._run_until_disconnected()
         try:
-            return self.loop.run_until_complete(self.disconnected)
+            return self.loop.run_until_complete(self._run_until_disconnected())
         except KeyboardInterrupt:
             pass
         finally: