mirror of
https://github.com/pyrogram/pyrogram
synced 2025-09-05 00:35:10 +00:00
Docs revamp. Part 6
This commit is contained in:
Dan
@@ -1,196 +0,0 @@
|
||||
Pyrogram FAQ
|
||||
============
|
||||
|
||||
This FAQ page provides answers to common questions about Pyrogram and, to some extent, Telegram in general.
|
||||
|
||||
.. tip::
|
||||
|
||||
If you think something interesting could be added here, feel free to propose it by opening a `Feature Request`_.
|
||||
|
||||
.. contents:: Contents
|
||||
:backlinks: none
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
What is Pyrogram?
|
||||
-----------------
|
||||
|
||||
**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and
|
||||
C. It enables you to easily create custom applications for both user and bot identities (bot API alternative) via the
|
||||
`MTProto API`_ with the Python programming language.
|
||||
|
||||
.. _Telegram: https://telegram.org
|
||||
.. _MTProto API: https://core.telegram.org/api#telegram-api
|
||||
|
||||
What does the name mean?
|
||||
------------------------
|
||||
|
||||
The word "Pyrogram" is composed by **pyro**, which comes from the Greek word *πῦρ (pyr)*, meaning fire, and **gram**,
|
||||
from *Telegram*. The word *pyro* itself is built from *Python*, **py** for short, and the suffix **ro** to come up with
|
||||
the word *fire*, which also inspired the project logo.
|
||||
|
||||
How old is the project?
|
||||
-----------------------
|
||||
|
||||
Pyrogram was first released on December 12, 2017. The actual work on the framework began roughly three months prior the
|
||||
initial public release on `GitHub`_.
|
||||
|
||||
.. _GitHub: https://github.com/pyrogram/pyrogram
|
||||
|
||||
Why Pyrogram?
|
||||
-------------
|
||||
|
||||
- **Easy**: You can install Pyrogram with pip and start building your applications right away.
|
||||
- **Elegant**: Low-level details are abstracted and re-presented in a much nicer and easier way.
|
||||
- **Fast**: Crypto parts are boosted up by TgCrypto_, a high-performance library written in pure C.
|
||||
- **Documented**: Pyrogram API methods, types and public interfaces are well documented.
|
||||
- **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted.
|
||||
- **Updated**, to make use of the latest Telegram API version and features.
|
||||
- **Bot API-like**: Similar to the Bot API in its simplicity, but much more powerful and detailed.
|
||||
- **Pluggable**: The `Smart Plugin`_ system allows to write components with minimal boilerplate code.
|
||||
- **Comprehensive**: Execute any `advanced action`_ an official client is able to do, and even more.
|
||||
|
||||
.. _TgCrypto: https://github.com/pyrogram/tgcrypto
|
||||
.. _Smart Plugin: smart-plugins
|
||||
.. _advanced action: advanced-usage
|
||||
|
||||
What can MTProto do more than the Bot API?
|
||||
------------------------------------------
|
||||
|
||||
Here you can find a list of all the known advantages in using MTProto-based libraries (Pyrogram) instead of the official
|
||||
HTTP Bot API:
|
||||
|
||||
- **Authorize both user and bot identities**: The Bot API only allows bot accounts.
|
||||
|
||||
- **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).
|
||||
|
||||
- **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.
|
||||
|
||||
- **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.
|
||||
|
||||
- **Get information about any public chat by usernames, even if not a member**: The Bot API simply doesn't support this.
|
||||
|
||||
- **Obtain information about any message existing in a chat using their ids**: The Bot API simply doesn't support this.
|
||||
|
||||
- **Retrieve the whole chat members list of either public or private chats**: The Bot API simply doesn't support this.
|
||||
|
||||
- **Receive extra updates, such as the one about a user name change**: The Bot API simply doesn't support this.
|
||||
|
||||
- **Has more meaningful errors in case something went wrong**: The Bot API reports less detailed errors.
|
||||
|
||||
- **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.
|
||||
|
||||
- **Get API version updates, and thus new features, sooner**: The Bot API is simply slower in implementing new features.
|
||||
|
||||
Why do I need an API key for bots?
|
||||
----------------------------------
|
||||
|
||||
Requests against the official bot API endpoint are made via JSON/HTTP, but are handled by an intermediate server
|
||||
application that implements the MTProto protocol -- just like Pyrogram -- and uses its own API key, which is always
|
||||
required, but hidden to the public.
|
||||
|
||||
.. figure:: https://i.imgur.com/C108qkX.png
|
||||
:align: center
|
||||
|
||||
Using MTProto is the only way to communicate with the actual Telegram servers, and the main API requires developers to
|
||||
identify applications by means of a unique key; the bot token identifies a bot as a user and replaces the user's phone
|
||||
number only.
|
||||
|
||||
I started a client and nothing happens!
|
||||
---------------------------------------
|
||||
|
||||
If you are connecting from Russia, China or Iran `you need a proxy`_, because Telegram could be partially or
|
||||
totally blocked in those countries.
|
||||
|
||||
Another possible cause might be network issues, either yours or Telegram's. To confirm this, add the following code on
|
||||
the top of your script and run it again. You should see some error mentioning a socket timeout or an unreachable network
|
||||
in a bunch of seconds:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import logging
|
||||
logging.basicConfig(level=logging.INFO)
|
||||
|
||||
Another way to confirm you aren't able to connect to Telegram is by pinging these IP addresses and see whether ping
|
||||
fails or not:
|
||||
|
||||
- DC1: ``149.154.175.50``
|
||||
- DC2: ``149.154.167.51``
|
||||
- DC3: ``149.154.175.100``
|
||||
- DC4: ``149.154.167.91``
|
||||
- DC5: ``91.108.56.149``
|
||||
|
||||
|bug report|
|
||||
|
||||
.. _you need a proxy: proxy
|
||||
|
||||
I keep getting PEER_ID_INVALID error!
|
||||
-------------------------------------------
|
||||
|
||||
The error in question is **[400 PEER_ID_INVALID]: The id/access_hash combination is invalid**, and could mean several
|
||||
things:
|
||||
|
||||
- The chat id you tried to use is simply wrong, double check it.
|
||||
- The chat id refers to a group or channel you are not a member of.
|
||||
- The chat id refers to a user you have't seen yet (from contacts, groups in common, forwarded messages or private
|
||||
chats).
|
||||
|
||||
|bug report|
|
||||
|
||||
.. |bug report| replace::
|
||||
|
||||
**Note:** If you really believe this should not happen, kindly open a `Bug Report`_.
|
||||
|
||||
Can I use the same file_id across different accounts?
|
||||
-----------------------------------------------------
|
||||
|
||||
No, Telegram doesn't allow this.
|
||||
|
||||
File ids are bound to a specific user/bot, and an attempt in using a foreign file id will result in errors such as
|
||||
**[400 MEDIA_EMPTY]: The media is invalid**.
|
||||
|
||||
The only exception are stickers' file ids; you can use them across different accounts without any problem, like this
|
||||
one: ``CAADBAADyg4AAvLQYAEYD4F7vcZ43AI``.
|
||||
|
||||
My account has been deactivated/limited!
|
||||
----------------------------------------
|
||||
|
||||
First of all, you should understand that Telegram wants to be a safe place for people to stay in, and to pursue this
|
||||
goal there are automatic protection systems running to prevent flood and spam, as well as a moderation team of humans
|
||||
who reviews reports.
|
||||
|
||||
**Pyrogram is a tool at your commands; it only does what you tell it to do, the rest is up to you.**
|
||||
|
||||
Having said that, here's how a list of what Telegram definitely doesn't like:
|
||||
|
||||
- Flood, abusing the API.
|
||||
- Spam, sending unsolicited messages or adding people to unwanted groups and channels.
|
||||
- Virtual/VoIP and cheap real numbers, because they are relatively easy to get and likely used for spam/flood.
|
||||
|
||||
However, you might be right, and your account was deactivated/limited without any reason. This could happen because of
|
||||
mistakes by either the automatic systems or a moderator. In such cases you can kindly email Telegram at
|
||||
recover@telegram.org, contact `@smstelegram`_ on Twitter or use `this form`_.
|
||||
|
||||
.. _@smstelegram: https://twitter.com/smstelegram
|
||||
.. _this form: https://telegram.org/support
|
||||
|
||||
About the License
|
||||
-----------------
|
||||
|
||||
.. image:: https://www.gnu.org/graphics/lgplv3-with-text-154x68.png
|
||||
:align: left
|
||||
|
||||
Pyrogram is free software and is currently licensed under the terms of the GNU Lesser General Public License v3 or later
|
||||
(LGPLv3+). In short: you may use, redistribute and/or modify it provided that modifications are described and licensed
|
||||
for free under LGPLv3+.
|
||||
|
||||
In other words: you can use and integrate Pyrogram into your own code --- either open source, under the same or a
|
||||
different licence or even proprietary --- without being required to release the source code of your own applications.
|
||||
However, any modifications to the library itself are required to be published for free under the same LGPLv3+ license.
|
||||
|
||||
.. _Bug Report: https://github.com/pyrogram/pyrogram/issues/new?labels=bug&template=bug_report.md
|
||||
.. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md
|
||||
@@ -1,72 +0,0 @@
|
||||
Pyrogram Glossary
|
||||
-----------------
|
||||
|
||||
This page contains a list of common words with brief explanations related to Pyrogram and, to some extent, Telegram in
|
||||
general. Some words may as well link to dedicated articles in case the topic is covered in a more detailed fashion.
|
||||
|
||||
.. tip::
|
||||
|
||||
If you think something interesting could be added here, feel free to propose it by opening a `Feature Request`_.
|
||||
|
||||
|
||||
.. glossary::
|
||||
|
||||
API
|
||||
Application Programming Interface: a set of methods, protocols and tools that make it easier to develop programs
|
||||
by providing useful building blocks to the developer.
|
||||
|
||||
API key
|
||||
A secret code used to authenticate and/or authorize a specific application to Telegram in order for it to
|
||||
control how the API is being used, for example, to prevent abuses of the API.
|
||||
|
||||
DC
|
||||
Also known as *data center*, is a place where lots of computer systems are housed and used together in order to
|
||||
achieve high quality and availability for services.
|
||||
|
||||
RPC
|
||||
Acronym for Remote Procedure call, that is, a function which gets executed at some remote place (i.e. Telegram
|
||||
server) and not in your local.
|
||||
|
||||
RPCError
|
||||
An error caused by an RPC which must be returned in place of the successful result in order to let the caller
|
||||
know something went wrong.
|
||||
|
||||
MTProto
|
||||
The name of the custom-made, open encryption protocol by Telegram, implemented in Pyrogram.
|
||||
|
||||
MTProto API
|
||||
The Telegram main API Pyrogram makes use of, which is able to connect both users and normal bots to Telegram
|
||||
using MTProto as application layer protocol and execute any method Telegram provides from its public schema.
|
||||
|
||||
Bot API
|
||||
The `Telegram Bot API`_ that is able to only connect normal bots to Telegram using HTTP as application layer
|
||||
protocol and allows to execute a subset of the main Telegram API.
|
||||
|
||||
Pyrogrammer
|
||||
A developer that uses Pyrogram to build Telegram applications.
|
||||
|
||||
Userbot
|
||||
Also known as *user bot* or *ubot* for short, is a user logged in by third-party Telegram libraries --- such as
|
||||
Pyrogram --- to automate some behaviours, like sending messages or reacting to text commands or any other event.
|
||||
|
||||
Session
|
||||
Also known as *login session*, is a strictly personal piece of information created and held by both parties
|
||||
(client and server) which is used to grant permission into a single account without having to start a new
|
||||
authorization process from scratch.
|
||||
|
||||
Callback
|
||||
Also known as *callback function*, is a user-defined generic function that *can be* registered to and then
|
||||
called-back by the framework when specific events occurs.
|
||||
|
||||
Handler
|
||||
An object that wraps around a callback function that is *actually meant* to be registered into the framework,
|
||||
which will then be able to handle a specific kind of events, such as a new incoming message, for example.
|
||||
|
||||
Decorator
|
||||
Also known as *function decorator*, in Python, is a callable object that is used to modify another function.
|
||||
Decorators in Pyrogram are used to automatically register callback functions for `handling updates`_.
|
||||
|
||||
.. _Telegram Bot API: https://core.telegram.org/bots/api
|
||||
.. _handling updates: ../start/updates
|
||||
|
||||
.. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md
|
||||
58
docs/source/topics/mtproto-vs-botapi.rst
Normal file
58
docs/source/topics/mtproto-vs-botapi.rst
Normal file
@@ -0,0 +1,58 @@
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: https://i.imgur.com/C108qkX.png
|
||||
:align: center
|
||||
|
||||
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
|
||||
HTTP Bot API. Using Pyrogram you can:
|
||||
|
||||
- **Authorize both user and bot identities**: The Bot API only allows bot accounts.
|
||||
|
||||
- **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).
|
||||
|
||||
- **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.
|
||||
|
||||
- **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.
|
||||
|
||||
- **Get information about any public chat by usernames, even if not a member**: The Bot API simply doesn't support this.
|
||||
|
||||
- **Obtain information about any message existing in a chat using their ids**: The Bot API simply doesn't support this.
|
||||
|
||||
- **Retrieve the whole chat members list of either public or private chats**: The Bot API simply doesn't support this.
|
||||
|
||||
- **Receive extra updates, such as the one about a user name change**: The Bot API simply doesn't support this.
|
||||
|
||||
- **Has more meaningful errors in case something went wrong**: The Bot API reports less detailed errors.
|
||||
|
||||
- **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.
|
||||
|
||||
- **Get API version updates, and thus new features, sooner**: The Bot API is simply slower in implementing new features.
|
||||
@@ -1,13 +0,0 @@
|
||||
Release Notes
|
||||
=============
|
||||
|
||||
Release notes for Pyrogram releases will describe what's new in each version, and will also make you aware of any
|
||||
backwards-incompatible changes made in that version.
|
||||
|
||||
When upgrading to a new version of Pyrogram, you will need to check all the breaking changes in order to find
|
||||
incompatible code in your application, but also to take advantage of new features and improvements.
|
||||
|
||||
.. note::
|
||||
|
||||
Currently, all Pyrogram release notes live inside the GitHub repository web page:
|
||||
https://github.com/pyrogram/pyrogram/releases.
|
||||
Reference in New Issue
Block a user