Document the magic sync module

readthedocs/extra/advanced-usage/accessing-the-full-api.rst

@@ -26,6 +26,15 @@ can go through a sorted list of everything you can do.
     can also do ``from telethon.tl import types, functions``. Both work.
 
 
+.. important::
+
+    All the examples in this documentation assume that you have
+    ``from telethon import sync`` or ``import telethon.sync``
+    for the sake of simplicity and that you understand what
+    it does (see :ref:`asyncio-magic` for more). Simply add
+    either line at the beginning of your project and it will work.
+
+
 You should also refer to the documentation to see what the objects
 (constructors) Telegram returns look like. Every constructor inherits
 from a common type, and that's the reason for this distinction.
@@ -69,9 +78,9 @@ Or we call `client.get_input_entity
 
 .. code-block:: python
 
-    import asyncio
-    loop = asyncio.get_event_loop()
-    peer = loop.run_until_complete(client.get_input_entity('someone'))
+    import telethon.sync
+    peer = client.get_input_entity('someone')
+
 
 When you're going to invoke an API method, most require you to pass an
 :tl:`InputUser`, :tl:`InputChat`, or so on, this is why using
@@ -83,7 +92,7 @@ instead:
 
 .. code-block:: python
 
-    entity = loop.run_until_complete(client.get_entity('someone'))
+    entity = client.get_entity('someone')
 
 In the later case, when you use the entity, the library will cast it to
 its "input" version for you. If you already have the complete user and
@@ -112,9 +121,7 @@ request we do:
 
 .. code-block:: python
 
-    result = loop.run_until_complete(
-        client(SendMessageRequest(peer, 'Hello there!'))
-    )
+    result = client(SendMessageRequest(peer, 'Hello there!'))
     # __call__ is an alias for client.invoke(request). Both will work
 
 Message sent! Of course, this is only an example. There are over 250
@@ -123,21 +130,18 @@ as you wish. Remember to use the right types! To sum up:
 
 .. code-block:: python
 
-    result = loop.run_until_complete(client(SendMessageRequest(
+    result = client(SendMessageRequest(
         client.get_input_entity('username'), 'Hello there!'
-    )))
+    ))
 
 
 This can further be simplified to:
 
 .. code-block:: python
 
-    async def main():
-        result = await client(SendMessageRequest('username', 'Hello there!'))
-        # Or even
-        result = await client(SendMessageRequest(PeerChannel(id), 'Hello there!'))
-
-    loop.run_until_complete(main())
+    result = client(SendMessageRequest('username', 'Hello there!'))
+    # Or even
+    result = client(SendMessageRequest(PeerChannel(id), 'Hello there!'))
 
 .. note::
 

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

@@ -38,7 +38,8 @@ so the code above and the following are equivalent:
     async def main():
         await client.disconnected
 
-    asyncio.get_event_loop().run_until_complete(main())
+    loop = asyncio.get_event_loop()
+    loop.run_until_complete(main())
 
 
 You could also run `client.disconnected
@@ -48,3 +49,17 @@ until it completed.
 But if you don't want to ``await``, then you should know what you want
 to be doing instead! What matters is that you shouldn't let your script
 die. If you don't care about updates, you don't need any of this.
+
+Notice that unlike `client.disconnected
+<telethon.client.telegrambaseclient.TelegramBaseClient.disconnected>`,
+`client.run_until_disconnected
+<telethon.client.updates.UpdateMethods.run_until_disconnected>` will
+handle ``KeyboardInterrupt`` with you. This method is special and can
+also be ran while the loop is running, so you can do this:
+
+.. code-block:: python
+
+    async def main():
+        await client.run_until_disconnected()
+
+    loop.run_until_complete(main())