mirror of
https://github.com/LonamiWebs/Telethon.git
synced 2024-11-27 20:03:46 +03:00
186 lines
5.8 KiB
ReStructuredText
186 lines
5.8 KiB
ReStructuredText
.. _asyncio-crash-course:
|
|
|
|
===========================
|
|
A Crash Course into asyncio
|
|
===========================
|
|
|
|
|
|
Why asyncio?
|
|
************
|
|
|
|
Python's `asyncio <https://docs.python.org/3/library/asyncio.html>`_ is the
|
|
standard way to run asynchronous code from within Python. Since Python 3.5,
|
|
using ``async def`` and ``await`` became possible, and Python 3.6 further
|
|
improves what you can do with asynchronous code, although it's not the only
|
|
way (other projects like `Trio <https://github.com/python-trio>`_ also exist).
|
|
|
|
Telegram is a service where all API calls are executed in an asynchronous
|
|
way. You send your request, and eventually, Telegram will process it and
|
|
respond to it. It feels natural to make a library that also behaves this
|
|
way: you send a request, and you can ``await`` for its result.
|
|
|
|
Now that we know that Telegram's API follows an asynchronous model, you
|
|
should understand the benefits of developing a library that does the same,
|
|
it greatly simplifies the internal code and eases working with the API.
|
|
|
|
Using ``asyncio`` keeps a cleaner library that will be easier to understand,
|
|
develop, and that will be faster than using threads, which are harder to get
|
|
right and can cause issues. It also enables to use the powerful ``asyncio``
|
|
system such as futures, timeouts, cancellation, etc. in a natural way.
|
|
|
|
If you're still not convinced or you're just not ready for using ``asyncio``,
|
|
the library offers a synchronous interface without the need for all the
|
|
``async`` and ``await`` you would otherwise see. `Follow this link
|
|
<https://github.com/LonamiWebs/Telethon/tree/sync>`_ to find out more.
|
|
|
|
|
|
How do I get started?
|
|
*********************
|
|
|
|
To get started with ``asyncio``, all you need is to setup your main
|
|
``async def`` like so:
|
|
|
|
.. code-block:: python
|
|
|
|
import asyncio
|
|
|
|
async def main():
|
|
pass # Your code goes here
|
|
|
|
if __name__ == '__main__':
|
|
loop = asyncio.get_event_loop()
|
|
loop.run_until_complete(main())
|
|
|
|
|
|
Inside ``async def main():``, you can use the ``await`` keyword. Most
|
|
methods in the :ref:`TelegramClient <telethon-client>` are ``async def``.
|
|
You must ``await`` all ``async def``, also known as a *coroutines*:
|
|
|
|
.. code-block:: python
|
|
|
|
async def main():
|
|
client = TelegramClient(...)
|
|
|
|
# client.start() is a coroutine (async def), it needs an await
|
|
await client.start()
|
|
|
|
# Sending a message also interacts with the API, and needs an await
|
|
await client.send_message('me', 'Hello myself!')
|
|
|
|
|
|
If you don't know anything else about ``asyncio``, this will be enough
|
|
to get you started. Once you're ready to learn more about it, you will
|
|
be able to use that power and everything you've learnt with Telethon.
|
|
Just remember that if you use ``await``, you need to be inside of an
|
|
``async def``.
|
|
|
|
Another way to use ``async def`` is to use ``loop.run_until_complete(f())``,
|
|
but the loop must not be running before.
|
|
|
|
If you want to handle updates (and don't let the script die), you must
|
|
`await client.disconnected <telethon.client.telegrambaseclient.TelegramBaseClient.disconnected>`
|
|
which is a property that you can wait on until you call
|
|
`await client.disconnect() <telethon.client.telegrambaseclient.TelegramBaseClient.disconnect>`:
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
client = TelegramClient(...)
|
|
|
|
@client.on(events.NewMessage)
|
|
async def handler(event):
|
|
print(event)
|
|
|
|
async def main():
|
|
await client.start()
|
|
await client.disconnected
|
|
|
|
if __name__ == '__main__':
|
|
loop = asyncio.get_event_loop()
|
|
loop.run_until_complete(main())
|
|
|
|
This is the same as using the ``run_until_disconnected()`` method:
|
|
|
|
.. code-block:: python
|
|
|
|
client = TelegramClient(...)
|
|
|
|
@client.on(events.NewMessage)
|
|
async def handler(event):
|
|
print(event)
|
|
|
|
if __name__ == '__main__':
|
|
loop = asyncio.get_event_loop()
|
|
loop.run_until_complete(client.start())
|
|
client.run_until_disconnected()
|
|
|
|
|
|
Which methods should I use and when?
|
|
************************************
|
|
|
|
Something to note is that you must always get an event loop if you
|
|
want to be able to make any API calls. This is done as follows:
|
|
|
|
.. code-block:: python
|
|
|
|
import asyncio
|
|
loop = asyncio.get_event_loop()
|
|
|
|
The loop must be running, or things will never get sent.
|
|
Normally, you use ``run_until_complete``:
|
|
|
|
.. code-block:: python
|
|
|
|
async def coroutine():
|
|
await asyncio.sleep(1)
|
|
|
|
loop.run_until_complete(coroutine())
|
|
|
|
Note that ``asyncio.sleep`` is in itself a coroutine, so this will
|
|
work too:
|
|
|
|
.. code-block:: python
|
|
|
|
loop.run_until_complete(asyncio.sleep(1))
|
|
|
|
Generally, you make an ``async def main()`` if you need to ``await``
|
|
a lot of things, instead of typing ``run_until_complete`` all the time:
|
|
|
|
.. code-block:: python
|
|
|
|
async def main():
|
|
message = await client.send_message('me', 'Hi')
|
|
await asyncio.sleep(1)
|
|
await message.delete()
|
|
|
|
loop.run_until_complete(main())
|
|
|
|
# vs
|
|
|
|
message = loop.run_until_complete(client.send_message('me', 'Hi'))
|
|
loop.run_until_complete(asyncio.sleep(1))
|
|
loop.run_until_complete(message.delete())
|
|
|
|
You can see that the first version has more lines, but you had to type
|
|
a lot less. You can also rename the run method to something shorter:
|
|
|
|
.. code-block:: python
|
|
|
|
# Note no parenthesis (), we're not running it, just copying the method
|
|
rc = loop.run_until_complete
|
|
message = rc(client.send_message('me', 'Hi'))
|
|
rc(asyncio.sleep(1))
|
|
rc(message.delete())
|
|
|
|
The documentation will use all these three styles so you can get used
|
|
to them. Which one to use is up to you, but generally you should work
|
|
inside an ``async def main()`` and just run the loop there.
|
|
|
|
|
|
More resources to learn asyncio
|
|
*******************************
|
|
|
|
If you would like to learn a bit more about why ``asyncio`` is something
|
|
you should learn, `check out my blog post
|
|
<https://lonamiwebs.github.io/blog/asyncio/>`_ that goes into more detail.
|