Avoid using telethon.sync in the examples

readthedocs/basic/quick-start.rst

@@ -8,15 +8,16 @@ use these if possible.
 
 .. code-block:: python
 
-    from telethon.sync import TelegramClient
+    from telethon import TelegramClient
 
     # Remember to use your own values from my.telegram.org!
     api_id = 12345
     api_hash = '0123456789abcdef0123456789abcdef'
+    client = TelegramClient('anon', api_id, api_hash)
 
-    with TelegramClient('anon', api_id, api_hash) as client:
+    async def main():
         # Getting information about yourself
-        me = client.get_me()
+        me = await client.get_me()
 
         # "me" is an User object. You can pretty-print
         # any Telegram object with the "stringify" method:
@@ -30,20 +31,20 @@ use these if possible.
         print(me.phone)
 
         # You can print all the dialogs/conversations that you are part of:
-        for dialog in client.iter_dialogs():
+        async for dialog in client.iter_dialogs():
             print(dialog.name, 'has ID', dialog.id)
 
         # You can send messages to yourself...
-        client.send_message('me', 'Hello, myself!')
+        await client.send_message('me', 'Hello, myself!')
         # ...to some chat ID
-        client.send_message(-100123456, 'Hello, group!')
+        await client.send_message(-100123456, 'Hello, group!')
         # ...to your contacts
-        client.send_message('+34600123123', 'Hello, friend!')
+        await client.send_message('+34600123123', 'Hello, friend!')
         # ...or even to any username
-        client.send_message('TelethonChat', 'Hello, Telethon!')
+        await client.send_message('TelethonChat', 'Hello, Telethon!')
 
         # You can, of course, use markdown in your messages:
-        message = client.send_message(
+        message = await client.send_message(
             'me',
             'This message has **bold**, `code`, __italics__ and '
             'a [nice website](https://lonamiwebs.github.io)!',
@@ -54,20 +55,23 @@ use these if possible.
         print(message.raw_text)
 
         # You can reply to messages directly if you have a message object
-        message.reply('Cool!')
+        await message.reply('Cool!')
 
         # Or send files, songs, documents, albums...
-        client.send_file('me', '/home/me/Pictures/holidays.jpg')
+        await client.send_file('me', '/home/me/Pictures/holidays.jpg')
 
         # You can print the message history of any chat:
-        for message in client.iter_messages('me'):
+        async for message in client.iter_messages('me'):
             print(message.id, message.text)
 
             # You can download media from messages, too!
             # The method will return the path where the file was saved.
             if message.photo:
-                path = message.download_media()
-                print('File saved to', path)
+                path = await message.download_media()
+                print('File saved to', path)  # printed after download is done
+
+    with client:
+        client.loop.run_until_complete(main())
 
 
 Here, we show how to sign in, get information about yourself, send
@@ -77,3 +81,31 @@ files.
 You should make sure that you understand what the code shown here
 does, take note on how methods are called and used and so on before
 proceeding. We will see all the available methods later on.
+
+.. important::
+
+    Note that Telethon is an asynchronous library, and as such, you should
+    get used to it and learn a bit of basic `asyncio`. This will help a lot.
+    As a quick start, this means you generally want to write all your code
+    inside some ``async def`` like so:
+
+    .. code-block:: python
+
+        client = ...
+
+        async def do_something(me):
+            ...
+
+        async def main():
+            # Most of your code should go here.
+            # You can of course make and use your own async def (do_something).
+            # They only need to be async if they need to await things.
+            me = await client.get_me()
+            await do_something(me)
+
+        with client:
+            client.loop.run_until_complete(main())
+
+    After you understand this, you may use the ``telethon.sync`` hack if you
+    want do so (see :ref:`compatibility-and-convenience`), but note you may
+    run into other issues (iPython, Anaconda, etc. have some issues with it).

readthedocs/basic/signing-in.rst

@@ -49,7 +49,7 @@ We can finally write some code to log into our account!
 
 .. code-block:: python
 
-    from telethon.sync import TelegramClient
+    from telethon import TelegramClient
 
     # Use your own values from my.telegram.org
     api_id = 12345
@@ -57,7 +57,7 @@ We can finally write some code to log into our account!
 
     # The first parameter is the .session file name (absolute paths allowed)
     with TelegramClient('anon', api_id, api_hash) as client:
-        client.send_message('me', 'Hello, myself!')
+        client.loop.run_until_complete(client.send_message('me', 'Hello, myself!'))
 
 
 In the first line, we import the class name so we can create an instance
@@ -68,6 +68,16 @@ At last, we create a new `TelegramClient <telethon.client.telegramclient.Telegra
 instance and call it ``client``. We can now use the client variable
 for anything that we want, such as sending a message to ourselves.
 
+.. note::
+
+    Since Telethon is an asynchronous library, you need to ``await``
+    coroutine functions to have them run (or otherwise, run the loop
+    until they are complete). In this tiny example, we don't bother
+    making an ``async def main()``.
+
+    See :ref:`mastering-asyncio` to find out more.
+
+
 Using a ``with`` block is the preferred way to use the library. It will
 automatically `start() <telethon.client.auth.AuthMethods.start>` the client,
 logging or signing up if necessary.