mirror of
https://github.com/pyrogram/pyrogram
synced 2025-09-04 08:15:08 +00:00
Docs revamp. Part 7
This commit is contained in:
Dan
@@ -1,58 +1,110 @@
|
||||
MTProto vs. Bot API
|
||||
===================
|
||||
|
||||
Being Pyrogram an MTProto-based library, this very feature makes it already superior to, what is usually called, the
|
||||
official Bot API.
|
||||
Pyrogram is a framework that acts as a fully-fledged Telegram client based on MTProto, and this very feature makes it
|
||||
already superior to, what is usually called, the official Bot API, in many respects. This page will therefore show you
|
||||
why Pyrogram might be a better choice for your project by comparing the two APIs, but first, let's make it clear what
|
||||
actually is the MTProto and the Bot API.
|
||||
|
||||
What is the MTProto API?
|
||||
------------------------
|
||||
|
||||
MTProto, took alone, is the name of the custom-made, open and encrypted communication protocol created by Telegram
|
||||
itself --- it's the only protocol used to exchange information between a client application and the actual Telegram
|
||||
servers.
|
||||
`MTProto`_, took alone, is the name of the custom-made, open and encrypted communication protocol created by Telegram
|
||||
itself --- it's the only protocol used to exchange information between a client and the actual Telegram servers.
|
||||
|
||||
The MTProto **API** however, is what people, for convenience, call the main Telegram API as a whole. This API is able
|
||||
to authorize both users and bots and happens to be built on top of the MTProto encryption protocol by means of binary
|
||||
data serialized in a specific way, as described by the TL language, hence the correlation.
|
||||
The MTProto **API** on the other hand, is what people, for convenience, call the main Telegram API as a whole. This API
|
||||
is able to authorize both users and bots and is built on top of the MTProto encryption protocol by means of
|
||||
`binary data serialized`_ in a specific way, as described by the `TL language`_, and delivered using UDP, TCP or even
|
||||
HTTP as transport-layer protocol.
|
||||
|
||||
.. _MTProto: https://core.telegram.org/mtproto
|
||||
.. _binary data serialized: https://core.telegram.org/mtproto/serialize
|
||||
.. _TL language: https://core.telegram.org/mtproto/TL
|
||||
|
||||
What is the Bot API?
|
||||
--------------------
|
||||
|
||||
The Bot API is an HTTP(S) interface for building normal bots. Bots are special accounts that are authorized via tokens
|
||||
instead of phone numbers. The Bot API is built yet again on top of the main Telegram API, but runs on an intermediate
|
||||
server application that in turn communicates with the actual Telegram servers using MTProto.
|
||||
The `Bot API`_ is an HTTP(S) interface for building normal bots using a sub-set of the main MTProto API. Bots are special
|
||||
accounts that are authorized via tokens instead of phone numbers. The Bot API is built yet again on top of the main
|
||||
Telegram API, but runs on an intermediate server application that in turn communicates with the actual Telegram servers
|
||||
using MTProto.
|
||||
|
||||
.. figure:: https://i.imgur.com/C108qkX.png
|
||||
:align: center
|
||||
|
||||
.. _Bot API: https://core.telegram.org/bots/api
|
||||
|
||||
Advantages of the MTProto API
|
||||
-----------------------------
|
||||
|
||||
Here is a list of all the known advantages in using MTProto-based libraries (such as Pyrogram) instead of the official
|
||||
Here is a list of all the advantages in using MTProto-based libraries -- such as Pyrogram -- instead of the official
|
||||
HTTP Bot API. Using Pyrogram you can:
|
||||
|
||||
- **Authorize both user and bot identities**: The Bot API only allows bot accounts.
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- **Upload & download any file, up to 1500 MB each (~1.5 GB)**: The Bot API allows uploads and downloads of files only
|
||||
up to 50 MB / 20 MB in size (respectively).
|
||||
- :guilabel:`+` **Authorize both user and bot identities**
|
||||
- :guilabel:`--` The Bot API only allows bot accounts
|
||||
|
||||
- **Has less overhead due to direct connections to Telegram**: The Bot API uses an intermediate server to handle HTTP
|
||||
requests before they are sent to the actual Telegram servers.
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- **Run multiple sessions at once, up to 10 per account (either bot or user)**: The Bot API intermediate server will
|
||||
terminate any other session in case you try to use the same bot again in a parallel connection.
|
||||
- :guilabel:`+` **Upload & download any file, up to 1500 MB each (~1.5 GB)**
|
||||
- :guilabel:`--` The Bot API allows uploads and downloads of files only up to 50 MB / 20 MB in size (respectively).
|
||||
|
||||
- **Get information about any public chat by usernames, even if not a member**: The Bot API simply doesn't support this.
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- **Obtain information about any message existing in a chat using their ids**: The Bot API simply doesn't support this.
|
||||
- :guilabel:`+` **Has less overhead due to direct connections to Telegram**
|
||||
- :guilabel:`--` The Bot API uses an intermediate server to handle HTTP requests before they are sent to the actual
|
||||
Telegram servers.
|
||||
|
||||
- **Retrieve the whole chat members list of either public or private chats**: The Bot API simply doesn't support this.
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- **Receive extra updates, such as the one about a user name change**: The Bot API simply doesn't support this.
|
||||
- :guilabel:`+` **Run multiple sessions at once, up to 10 per account (either bot or user)**
|
||||
- :guilabel:`--` The Bot API intermediate server will terminate any other session in case you try to use the same
|
||||
bot again in a parallel connection.
|
||||
|
||||
- **Has more meaningful errors in case something went wrong**: The Bot API reports less detailed errors.
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- **Has much more detailed types and powerful methods**: The Bot API types often miss some useful information about
|
||||
Telegram's type and some of the methods are limited as well.
|
||||
- :guilabel:`+` **Has much more detailed types and powerful methods**
|
||||
- :guilabel:`--` The Bot API types often miss some useful information about Telegram entities and some of the
|
||||
methods are limited as well.
|
||||
|
||||
- **Get API version updates, and thus new features, sooner**: The Bot API is simply slower in implementing new features.
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- :guilabel:`+` **Get information about any public chat by usernames, even if not a member**
|
||||
- :guilabel:`--` The Bot API simply doesn't support this
|
||||
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- :guilabel:`+` **Obtain information about any message existing in a chat using their ids**
|
||||
- :guilabel:`--` The Bot API simply doesn't support this
|
||||
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- :guilabel:`+` **Retrieve the whole chat members list of either public or private chats**
|
||||
- :guilabel:`--` The Bot API simply doesn't support this
|
||||
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- :guilabel:`+` **Receive extra updates, such as the one about a user name change**
|
||||
- :guilabel:`--` The Bot API simply doesn't support this
|
||||
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- :guilabel:`+` **Has more meaningful errors in case something went wrong**
|
||||
- :guilabel:`--` The Bot API reports less detailed errors
|
||||
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- :guilabel:`+` **Get API version updates, and thus new features, sooner**
|
||||
- :guilabel:`--` The Bot API is simply slower in implementing new features
|
||||
|
||||
55
docs/source/topics/serialize.rst
Normal file
55
docs/source/topics/serialize.rst
Normal file
@@ -0,0 +1,55 @@
|
||||
Object Serialization
|
||||
====================
|
||||
|
||||
Serializing means converting a Pyrogram object, which exists as Python class instance, to a text string that can be
|
||||
easily shared and stored anywhere. Pyrogram provides two formats for serializing its objects: one good looking for
|
||||
humans and another more compact for machines that is able to recover the original structures.
|
||||
|
||||
For Humans - str(obj)
|
||||
---------------------
|
||||
|
||||
If you want a nicely formatted, human readable JSON representation of any object in the API -- namely, any object from
|
||||
`Pyrogram types`_, `raw functions`_ and `raw types`_ -- you can use use ``str(obj)``.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
...
|
||||
|
||||
with app:
|
||||
r = app.get_chat("haskell")
|
||||
|
||||
print(str(r))
|
||||
|
||||
.. tip::
|
||||
|
||||
When using ``print()`` you don't actually need to use ``str()`` on the object because it is called automatically, we
|
||||
have done that above just to show you how to explicitly convert a Pyrogram object to JSON.
|
||||
|
||||
.. _Pyrogram types: ../api/types
|
||||
.. _raw functions: ../telegram/functions
|
||||
.. _raw types: ../telegram/types
|
||||
|
||||
For Machines - repr(obj)
|
||||
------------------------
|
||||
|
||||
If you want to share or store objects for future references in a more compact way, you can use ``repr(obj)``. While
|
||||
still pretty much readable, this format is not intended for humans. The advantage of this format is that once you
|
||||
serialize your object, you can use ``eval()`` to get back the original structure; just make sure to ``import pyrogram``,
|
||||
as the process requires the package to be in scope.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import pyrogram
|
||||
|
||||
...
|
||||
|
||||
with app:
|
||||
r = app.get_chat("haskell")
|
||||
|
||||
print(repr(r))
|
||||
print(eval(repr(r)) == r) # True
|
||||
|
||||
.. note::
|
||||
|
||||
Type definitions are subject to changes between versions. You should make sure to store and load objects using the
|
||||
same Pyrogram version.
|
||||
@@ -9,7 +9,7 @@ app (or by invoking `GetAuthorizations <../telegram/functions/account/GetAuthori
|
||||
store some useful information such as the client who's using them and from which country and IP address.
|
||||
|
||||
.. figure:: https://i.imgur.com/YaqtMLO.png
|
||||
:width: 90%
|
||||
:width: 600
|
||||
:align: center
|
||||
|
||||
**A Pyrogram session running on Linux, Python 3.7.**
|
||||
|
||||
@@ -2,7 +2,7 @@ Fast Crypto
|
||||
===========
|
||||
|
||||
Pyrogram's speed can be *dramatically* boosted up by TgCrypto_, a high-performance, easy-to-install Telegram Crypto
|
||||
Library specifically written in C for Pyrogram [#f1]_ as a Python extension.
|
||||
Library specifically written in C for Pyrogram [1]_ as a Python extension.
|
||||
|
||||
TgCrypto is a replacement for the much slower PyAES and implements the crypto algorithms Telegram requires, namely
|
||||
**AES-IGE 256 bit** (used in MTProto v2.0) and **AES-CTR 256 bit** (used for CDN encrypted files).
|
||||
@@ -28,5 +28,5 @@ what you should do next:
|
||||
|
||||
.. _TgCrypto: https://github.com/pyrogram/tgcrypto
|
||||
|
||||
.. [#f1] Although TgCrypto is intended for Pyrogram, it is shipped as a standalone package and can thus be used for
|
||||
.. [1] Although TgCrypto is intended for Pyrogram, it is shipped as a standalone package and can thus be used for
|
||||
other Python projects too.
|
||||
|
||||
Reference in New Issue
Block a user