Avoid using telethon.sync in the examples

readthedocs/concepts/asyncio.rst

@@ -96,8 +96,12 @@ Instead of this:
 
 .. code-block:: python
 
+    me = client.loop.run_until_complete(client.get_me())
+    print(me.username)
+
+    # or, using asyncio's default loop (it's the same)
     import asyncio
-    loop = asyncio.get_event_loop()
+    loop = asyncio.get_event_loop()  # == client.loop
     me = loop.run_until_complete(client.get_me())
     print(me.username)
 

readthedocs/concepts/entities.rst

@@ -102,33 +102,35 @@ you're able to just do this:
 
 .. code-block:: python
 
+    # (These examples assume you are inside an "async def")
+    #
     # Dialogs are the "conversations you have open".
     # This method returns a list of Dialog, which
     # has the .entity attribute and other information.
     #
     # This part is IMPORTANT, because it feels the entity cache.
-    dialogs = client.get_dialogs()
+    dialogs = await client.get_dialogs()
 
     # All of these work and do the same.
-    lonami = client.get_entity('lonami')
-    lonami = client.get_entity('t.me/lonami')
-    lonami = client.get_entity('https://telegram.dog/lonami')
+    lonami = await client.get_entity('lonami')
+    lonami = await client.get_entity('t.me/lonami')
+    lonami = await client.get_entity('https://telegram.dog/lonami')
 
     # Other kind of entities.
-    channel = client.get_entity('telegram.me/joinchat/AAAAAEkk2WdoDrB4-Q8-gg')
-    contact = client.get_entity('+34xxxxxxxxx')
-    friend  = client.get_entity(friend_id)
+    channel = await client.get_entity('telegram.me/joinchat/AAAAAEkk2WdoDrB4-Q8-gg')
+    contact = await client.get_entity('+34xxxxxxxxx')
+    friend  = await client.get_entity(friend_id)
 
     # Getting entities through their ID (User, Chat or Channel)
-    entity = client.get_entity(some_id)
+    entity = await client.get_entity(some_id)
 
     # You can be more explicit about the type for said ID by wrapping
     # it inside a Peer instance. This is recommended but not necessary.
     from telethon.tl.types import PeerUser, PeerChat, PeerChannel
 
-    my_user    = client.get_entity(PeerUser(some_id))
-    my_chat    = client.get_entity(PeerChat(some_id))
-    my_channel = client.get_entity(PeerChannel(some_id))
+    my_user    = await client.get_entity(PeerUser(some_id))
+    my_chat    = await client.get_entity(PeerChat(some_id))
+    my_channel = await client.get_entity(PeerChannel(some_id))
 
 
 .. note::
@@ -212,7 +214,7 @@ wherever needed, so you can even do things like:
 
 .. code-block:: python
 
-    client(SendMessageRequest('username', 'hello'))
+    await client(SendMessageRequest('username', 'hello'))
 
 The library will call the ``.resolve()`` method of the request, which will
 resolve ``'username'`` with the appropriated :tl:`InputPeer`. Don't worry if
@@ -258,7 +260,7 @@ That means you can do this:
 
     message.is_private
     message.chat_id
-    message.get_chat()
+    await message.get_chat()
     # ...etc
 
 `SenderGetter <telethon.tl.custom.sendergetter.SenderGetter>` is similar:
@@ -266,7 +268,7 @@ That means you can do this:
 .. code-block:: python
 
     message.user_id
-    message.get_input_user()
+    await message.get_input_user()
     message.user
     # ...etc
 
@@ -285,22 +287,25 @@ applications"? Now do the same with the library. Use what applies:
 
 .. code-block:: python
 
-    with client:
+    # (These examples assume you are inside an "async def")
+    async with client:
         # Does it have an username? Use it!
-        entity = client.get_entity(username)
+        entity = await client.get_entity(username)
 
         # Do you have a conversation open with them? Get dialogs.
-        client.get_dialogs()
+        await client.get_dialogs()
 
         # Are they participant of some group? Get them.
-        client.get_participants('TelethonChat')
+        await client.get_participants('TelethonChat')
 
         # Is the entity the original sender of a forwarded message? Get it.
-        client.get_messages('TelethonChat', 100)
+        await client.get_messages('TelethonChat', 100)
 
         # NOW you can use the ID, anywhere!
-        entity = client.get_entity(123456)
-        client.send_message(123456, 'Hi!')
+        await client.send_message(123456, 'Hi!')
+
+        entity = await client.get_entity(123456)
+        print(entity)
 
 Once the library has "seen" the entity, you can use their **integer** ID.
 You can't use entities from IDs the library hasn't seen. You must make the

readthedocs/concepts/errors.rst

@@ -19,7 +19,8 @@ available in :ref:`telethon-errors`, but some examples are:
        from telethon import errors
 
        try:
-           print(client.get_messages(chat)[0].text)
+           messages = await client.get_messages(chat)
+           print(messages[0].text)
        except errors.FloodWaitError as e:
            print('Have to sleep', e.seconds, 'seconds')
            time.sleep(e.seconds)

readthedocs/concepts/full-api.rst

@@ -78,8 +78,17 @@ Or we call `client.get_input_entity()
 
 .. code-block:: python
 
-    import telethon.sync
-    peer = client.get_input_entity('someone')
+    import telethon
+
+    async def main():
+        peer = await client.get_input_entity('someone')
+
+    client.loop.run_until_complete(main())
+
+.. note::
+
+    Remember that ``await`` must occur inside an ``async def``.
+    Every full API example assumes you already know and do this.
 
 
 When you're going to invoke an API method, most require you to pass an
@@ -92,7 +101,7 @@ instead:
 
 .. code-block:: python
 
-    entity = client.get_entity('someone')
+    entity = await 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
@@ -120,7 +129,7 @@ request we do:
 
 .. code-block:: python
 
-    result = client(SendMessageRequest(peer, 'Hello there!'))
+    result = await client(SendMessageRequest(peer, 'Hello there!'))
 
 Message sent! Of course, this is only an example. There are over 250
 methods available as of layer 80, and you can use every single of them
@@ -128,8 +137,8 @@ as you wish. Remember to use the right types! To sum up:
 
 .. code-block:: python
 
-    result = client(SendMessageRequest(
-        client.get_input_entity('username'), 'Hello there!'
+    result = await client(SendMessageRequest(
+        await client.get_input_entity('username'), 'Hello there!'
     ))
 
 
@@ -137,9 +146,9 @@ This can further be simplified to:
 
 .. code-block:: python
 
-    result = client(SendMessageRequest('username', 'Hello there!'))
+    result = await client(SendMessageRequest('username', 'Hello there!'))
     # Or even
-    result = client(SendMessageRequest(PeerChannel(id), 'Hello there!'))
+    result = await client(SendMessageRequest(PeerChannel(id), 'Hello there!'))
 
 .. note::
 
@@ -195,7 +204,7 @@ knows all requests directly:
 
 .. code-block:: python
 
-    client([
+    await client([
         SendMessageRequest('me', 'Hello'),
         SendMessageRequest('me', ', '),
         SendMessageRequest('me', 'World'),
@@ -212,7 +221,7 @@ and still access the successful results:
     from telethon.errors import MultiError
 
     try:
-        client([
+        await client([
             SendMessageRequest('me', 'Hello'),
             SendMessageRequest('me', ''),
             SendMessageRequest('me', 'World')

readthedocs/concepts/sessions.rst

@@ -154,7 +154,7 @@ you can save it in a variable directly:
 
     string = '1aaNk8EX-YRfwoRsebUkugFvht6DUPi_Q25UOCzOAqzc...'
     with TelegramClient(StringSession(string), api_id, api_hash) as client:
-        client.send_message('me', 'Hi')
+        client.loop.run_until_complete(client.send_message('me', 'Hi'))
 
 
 These strings are really convenient for using in places like Heroku since

readthedocs/concepts/strings.rst

@@ -8,7 +8,7 @@ does a result have? Well, the easiest thing to do is printing it:
 
 .. code-block:: python
 
-    user = client.get_entity('Lonami')
+    user = await client.get_entity('Lonami')
     print(user)
 
 That will show a huge **string** similar to the following: