mirror of
https://github.com/LonamiWebs/Telethon.git
synced 2024-11-10 19:46:36 +03:00
Add new section for people coming from Bot API
This commit is contained in:
parent
e5f1b2afa3
commit
da5c801b4d
333
readthedocs/concepts/botapi-vs-mtproto.rst
Normal file
333
readthedocs/concepts/botapi-vs-mtproto.rst
Normal file
|
@ -0,0 +1,333 @@
|
|||
.. _botapi:
|
||||
|
||||
=======================
|
||||
HTTP Bot API vs MTProto
|
||||
=======================
|
||||
|
||||
|
||||
Telethon is more than just another viable alternative when developing bots
|
||||
for Telegram. If you haven't decided which wrapper library for bots to use
|
||||
yet, using Telethon from the beginning may save you some headaches later.
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
What is Bot API?
|
||||
================
|
||||
|
||||
The `Telegram Bot API`_, also known as HTTP Bot API and from now on referred
|
||||
to as simply "Bot API" is Telegram's official way for developers to control
|
||||
their own Telegram bots. Quoting their main page:
|
||||
|
||||
The Bot API is an HTTP-based interface created for developers keen on
|
||||
building bots for Telegram.
|
||||
|
||||
To learn how to create and set up a bot, please consult our
|
||||
`Introduction to Bots`_ and `Bot FAQ`_.
|
||||
|
||||
Bot API is simply an HTTP endpoint which translates your requests to it into
|
||||
MTProto calls through tdlib_, their bot backend.
|
||||
|
||||
|
||||
What is MTProto?
|
||||
================
|
||||
|
||||
MTProto_ is Telegram's own protocol to communicate with their API when you
|
||||
connect to their servers.
|
||||
|
||||
Telethon is an alternative MTProto-based backend written entirely in Python
|
||||
and much easier to setup and use.
|
||||
|
||||
Both official applications and third-party clients (like your own
|
||||
applications) logged in as either user or bots **can use MTProto** to
|
||||
communicate directly with Telegram's API (which is not the HTTP bot API).
|
||||
|
||||
When we talk about MTProto, we often mean "MTProto-based clients".
|
||||
|
||||
|
||||
Advantages of MTProto over Bot API
|
||||
==================================
|
||||
|
||||
MTProto clients (like Telethon) connect directly to Telegram's servers,
|
||||
which means there is no HTTP connection, no "polling" or "web hooks". This
|
||||
means **less overhead**, since the protocol used between you and the server
|
||||
is much more compact than HTTP requests with responses in wasteful JSON.
|
||||
|
||||
Since there is a direct connection to Telegram's servers, even if their
|
||||
Bot API endpoint is down, you can still have connection to Telegram directly.
|
||||
|
||||
Using a MTProto client, you are also not limited to the public API that
|
||||
they expose, and instead, **you have full control** of what your bot can do.
|
||||
Telethon offers you all the power with often **much easier usage** than any
|
||||
of the available Python Bot API wrappers.
|
||||
|
||||
If your application ever needs user features because bots cannot do certain
|
||||
things, you will be able to easily login as a user and even keep your bot
|
||||
without having to learn a new library.
|
||||
|
||||
If less overhead and full control didn't convince you to use Telethon yet,
|
||||
check out the repository `HTTP Bot API vs MTProto comparison`_ with a more
|
||||
exhaustive and up-to-date list of differences.
|
||||
|
||||
|
||||
Migrating from Bot API to Telethon
|
||||
==================================
|
||||
|
||||
It doesn't matter if you wrote your bot with requests_ and you were
|
||||
making API requests manually, or if you used a wrapper library like
|
||||
python-telegram-bot_ or pyTelegramBotAPI_. It's never too late to
|
||||
migrate to Telethon!
|
||||
|
||||
If you were using an asynchronous library like aiohttp_ or a wrapper like
|
||||
aiogram_ or dumbot_, it will be even easier, because Telethon is also an
|
||||
asynchronous library.
|
||||
|
||||
Next, we will see some examples from the most popular libraries.
|
||||
|
||||
|
||||
Migrating from python-telegram-bot
|
||||
----------------------------------
|
||||
|
||||
Let's take their `echobot2.py`_ example and shorten it a bit:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telegram.ext import Updater, CommandHandler, MessageHandler, Filters
|
||||
|
||||
def start(update, context):
|
||||
"""Send a message when the command /start is issued."""
|
||||
update.message.reply_text('Hi!')
|
||||
|
||||
def echo(update, context):
|
||||
"""Echo the user message."""
|
||||
update.message.reply_text(update.message.text)
|
||||
|
||||
def main():
|
||||
"""Start the bot."""
|
||||
updater = Updater("TOKEN")
|
||||
dp = updater.dispatcher
|
||||
dp.add_handler(CommandHandler("start", start))
|
||||
dp.add_handler(MessageHandler(Filters.text, echo))
|
||||
|
||||
updater.start_polling()
|
||||
|
||||
updater.idle()
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
|
||||
|
||||
After using Telethon:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
bot = TelegramClient('bot', 11111, 'a1b2c3d4').start(bot_token='TOKEN')
|
||||
|
||||
@bot.on(events.NewMessage(pattern='/start'))
|
||||
async def start(event):
|
||||
"""Send a message when the command /start is issued."""
|
||||
await event.respond('Hi!')
|
||||
raise events.StopPropagation
|
||||
|
||||
@bot.on(events.NewMessage)
|
||||
async def echo(event):
|
||||
"""Echo the user message."""
|
||||
await event.respond(event.text)
|
||||
|
||||
def main():
|
||||
"""Start the bot."""
|
||||
bot.run_until_disconnected()
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
|
||||
Key differences:
|
||||
|
||||
* The recommended way to do it imports less things.
|
||||
* All handlers trigger by default, so we need ``events.StopPropagation``.
|
||||
* Adding handlers, responding and running is a lot less verbose.
|
||||
* Telethon needs ``async def`` and ``await``.
|
||||
* The ``bot`` isn't hidden away by ``Updater`` or ``Dispatcher``.
|
||||
|
||||
|
||||
Migrating from pyTelegramBotAPI
|
||||
-------------------------------
|
||||
|
||||
Let's show another echobot from their README:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import telebot
|
||||
|
||||
bot = telebot.TeleBot("TOKEN")
|
||||
|
||||
@bot.message_handler(commands=['start'])
|
||||
def send_welcome(message):
|
||||
bot.reply_to(message, "Howdy, how are you doing?")
|
||||
|
||||
@bot.message_handler(func=lambda m: True)
|
||||
def echo_all(message):
|
||||
bot.reply_to(message, message.text)
|
||||
|
||||
bot.polling()
|
||||
|
||||
Now we rewrite it to use Telethon:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
bot = TelegramClient('bot', 11111, 'a1b2c3d4').start(bot_token='TOKEN')
|
||||
|
||||
@bot.on(events.NewMessage(pattern='/start'))
|
||||
async def send_welcome(event):
|
||||
await event.reply('Howdy, how are you doing?')
|
||||
|
||||
@bot.on(events.NewMessage)
|
||||
async def echo_all(event):
|
||||
await event.reply(event.text)
|
||||
|
||||
bot.run_until_disconnected()
|
||||
|
||||
Key differences:
|
||||
|
||||
* Instead of doing ``bot.reply_to(message)``, we can do ``event.reply``.
|
||||
Note that the ``event`` behaves just like their ``message``.
|
||||
* Telethon also supports ``func=lambda m: True``, but it's not necessary.
|
||||
|
||||
|
||||
Migrating from aiogram
|
||||
----------------------
|
||||
|
||||
From their GitHub:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from aiogram import Bot, Dispatcher, executor, types
|
||||
|
||||
API_TOKEN = 'BOT TOKEN HERE'
|
||||
|
||||
# Initialize bot and dispatcher
|
||||
bot = Bot(token=API_TOKEN)
|
||||
dp = Dispatcher(bot)
|
||||
|
||||
@dp.message_handler(commands=['start'])
|
||||
async def send_welcome(message: types.Message):
|
||||
"""
|
||||
This handler will be called when client send `/start` command.
|
||||
"""
|
||||
await message.reply("Hi!\nI'm EchoBot!\nPowered by aiogram.")
|
||||
|
||||
@dp.message_handler(regexp='(^cat[s]?$|puss)')
|
||||
async def cats(message: types.Message):
|
||||
with open('data/cats.jpg', 'rb') as photo:
|
||||
await bot.send_photo(message.chat.id, photo, caption='Cats is here 😺',
|
||||
reply_to_message_id=message.message_id)
|
||||
|
||||
@dp.message_handler()
|
||||
async def echo(message: types.Message):
|
||||
await bot.send_message(message.chat.id, message.text)
|
||||
|
||||
if __name__ == '__main__':
|
||||
executor.start_polling(dp, skip_updates=True)
|
||||
|
||||
|
||||
After rewrite:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
# Initialize bot and... just the bot!
|
||||
bot = TelegramClient('bot', 11111, 'a1b2c3d4').start(bot_token='TOKEN')
|
||||
|
||||
@bot.on(events.NewMessage(pattern='/start'))
|
||||
async def send_welcome(event):
|
||||
await event.reply('Howdy, how are you doing?')
|
||||
|
||||
@bot.on(events.NewMessage(pattern='(^cat[s]?$|puss)'))
|
||||
async def cats(event):
|
||||
await event.reply('Cats is here 😺', file='data/cats.jpg')
|
||||
|
||||
@bot.on(events.NewMessage)
|
||||
async def echo_all(event):
|
||||
await event.reply(event.text)
|
||||
|
||||
if __name__ == '__main__':
|
||||
bot.run_until_disconnected()
|
||||
|
||||
|
||||
Key differences:
|
||||
|
||||
* Telethon offers convenience methods to avoid retyping
|
||||
``bot.send_photo(message.chat.id, ...)`` all the time,
|
||||
and instead let you type ``event.reply``.
|
||||
* Sending files is **a lot** easier. The methods for sending
|
||||
photos, documents, audios, etc. are all the same!
|
||||
|
||||
Migrating from dumbot
|
||||
---------------------
|
||||
|
||||
Showcasing their subclassing example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from dumbot import Bot
|
||||
|
||||
class Subbot(Bot):
|
||||
async def init(self):
|
||||
self.me = await self.getMe()
|
||||
|
||||
async def on_update(self, update):
|
||||
await self.sendMessage(
|
||||
chat_id=update.message.chat.id,
|
||||
text='i am {}'.format(self.me.username)
|
||||
)
|
||||
|
||||
Subbot(token).run()
|
||||
|
||||
After rewriting:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
class Subbot(TelegramClient):
|
||||
def __init__(self, *a, **kw):
|
||||
await super().__init__(*a, **kw)
|
||||
self.add_event_handler(self.on_update, events.NewMessage)
|
||||
|
||||
async def connect():
|
||||
await super().connect()
|
||||
self.me = await self.get_me()
|
||||
|
||||
async def on_update(event):
|
||||
await event.reply('i am {}'.format(self.me.username))
|
||||
|
||||
bot = Subbot('bot', 11111, 'a1b2c3d4').start(bot_token='TOKEN')
|
||||
bot.run_until_disconnected()
|
||||
|
||||
|
||||
Key differences:
|
||||
|
||||
* Telethon method names are ``snake_case``.
|
||||
* dumbot does not offer friendly methods like ``update.reply``.
|
||||
* Telethon does not have an implicit ``on_update`` handler, so
|
||||
we need to manually register one.
|
||||
|
||||
|
||||
.. _Telegram Bot API: https://core.telegram.org/bots/api
|
||||
.. _Introduction to Bots: https://core.telegram.org/bots
|
||||
.. _Bot FAQ: https://core.telegram.org/bots/faq
|
||||
.. _tdlib: https://core.telegram.org/tdlib
|
||||
.. _MTProto: https://core.telegram.org/mtproto
|
||||
.. _HTTP Bot API vs MTProto comparison: https://github.com/telegram-mtproto/botapi-comparison
|
||||
.. _requests: https://pypi.org/project/requests/
|
||||
.. _python-telegram-bot: https://python-telegram-bot.readthedocs.io
|
||||
.. _pyTelegramBotAPI: https://github.com/eternnoir/pyTelegramBotAPI
|
||||
.. _aiohttp: https://docs.aiohttp.org/en/stable
|
||||
.. _aiogram: https://aiogram.readthedocs.io
|
||||
.. _dumbot: https://github.com/Lonami/dumbot
|
||||
.. _echobot2.py: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot2.py
|
|
@ -21,6 +21,7 @@ Telethon's Documentation
|
|||
* Looking for the method reference? See :ref:`client-ref`.
|
||||
* Did you upgrade the library? Please read :ref:`changelog`.
|
||||
* Used Telethon before v1.0? See :ref:`compatibility-and-convenience`.
|
||||
* Coming from Bot API or want to create new bots? See :ref:`botapi`.
|
||||
* Need the full API reference? https://lonamiwebs.github.io/Telethon/.
|
||||
|
||||
|
||||
|
@ -71,6 +72,7 @@ You can also use the menu on the left to quickly skip over sections.
|
|||
concepts/sessions
|
||||
concepts/full-api
|
||||
concepts/errors
|
||||
concepts/botapi-vs-mtproto
|
||||
concepts/asyncio
|
||||
|
||||
.. toctree::
|
||||
|
|
Loading…
Reference in New Issue
Block a user