mir/pyrogram
2
0
Fork 0
mirror of https://github.com/pyrogram/pyrogram synced 2025-08-28 12:57:52 +00:00
Code Issues Releases Wiki Activity

Docs revamp. Part 6

Browse Source
This commit is contained in:
Dan 2019-05-18 03:21:02 +02:00
parent 518220431e
commit 578dab171c
8 changed files with 174 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
docs/source/intro/start.rst → docs/source/intro/quickstart.rst
View File

73
docs/source/topics/faq.rst → docs/source/meta/faq.rst
View File

@ -20,17 +20,17 @@ C. It enables you to easily create custom applications for both user and bot ide
`MTProto API`_ with the Python programming language.
.. _Telegram: https://telegram.org
.. _MTProto API: https://core.telegram.org/api#telegram-api
.. _MTProto API: ../topics/mtproto-vs-botapi#what-is-the-mtproto-api
What does the name mean?
------------------------
Where does the name come from?
------------------------------
The word "Pyrogram" is composed by **pyro**, which comes from the Greek word *πῦρ (pyr)*, meaning fire, and **gram**,
The name "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?
-----------------------
How old is Pyrogram?
--------------------
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`_.
@ -51,40 +51,15 @@ Why Pyrogram?
- **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
.. _Smart Plugin: ../topics/smart-plugins
.. _advanced action: ../topics/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:
For a detailed answer, please refer to the `MTProto vs. Bot API`_ page.
- **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.
.. _MTProto vs. Bot API: ../topics/mtproto-vs-botapi
Why do I need an API key for bots?
----------------------------------
@ -126,7 +101,7 @@ fails or not:
|bug report|
.. _you need a proxy: proxy
.. _you need a proxy: ../topics/proxy
I keep getting PEER_ID_INVALID error!
-------------------------------------------
@ -150,12 +125,27 @@ 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**.
File ids are personal and 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``.
Can I use Bot API's file_ids in Pyrogram?
-----------------------------------------
Definitely! All file ids you might have taken from the Bot API are 100% compatible and re-usable in Pyrogram...
...at least for now.
Telegram is slowly changing some server's internals and it's doing it in such a way that file ids are going to break
inevitably. Not only this, but it seems that the new, hypothetical, file ids could also possibly expire at anytime, thus
losing the *persistence* feature.
This change will most likely affect the official `Bot API <../topics/mtproto-vs-botapi#what-is-the-bot-api>`_ too
(unless Telegram implements some workarounds server-side to keep backwards compatibility, which Pyrogram could in turn
make use of) and we can expect a proper notice from Telegram.
My account has been deactivated/limited!
----------------------------------------
@ -184,13 +174,14 @@ 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+.
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.
.. _GNU Lesser General Public License v3 or later (LGPLv3+): https://github.com/pyrogram/pyrogram/blob/develop/COPYING.lesser
.. _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

19
docs/source/topics/glossary.rst → docs/source/meta/glossary.rst
View File

@ -1,5 +1,5 @@
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.
@ -18,6 +18,7 @@ general. Some words may as well link to dedicated articles in case the topic is
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.
`More on API keys <../intro/setup#api-keys>`_.
DC
Also known as *data center*, is a place where lots of computer systems are housed and used together in order to
@ -29,18 +30,21 @@ general. Some words may as well link to dedicated articles in case the topic is
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.
know something went wrong. `More on RPCError <../start/errors>`_.
MTProto
The name of the custom-made, open encryption protocol by Telegram, implemented in Pyrogram.
The name of the custom-made, open and encrypted protocol by Telegram, implemented in Pyrogram.
`More on MTProto <mtproto-vs-botapi>`_.
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.
using MTProto as application layer protocol and execute any method Telegram provides from its public TL-schema.
`More on MTProto API <mtproto-vs-botapi#what-is-the-mtproto-api>`_.
Bot API
The `Telegram Bot API`_ that is able to only connect normal bots to Telegram using HTTP as application layer
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.
`More on Bot API <mtproto-vs-botapi#what-is-the-bot-api>`_.
Pyrogrammer
A developer that uses Pyrogram to build Telegram applications.
@ -61,12 +65,13 @@ general. Some words may as well link to dedicated articles in case the topic is
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.
`More on Handlers <../start/updates>`_
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`_.
Decorators in Pyrogram are used to automatically register callback functions for handling updates.
`More on Decorators <../start/updates#using-decorators>`_
.. _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

69
docs/source/meta/powered-by.rst Normal file
View File

@ -0,0 +1,69 @@
Powered by Pyrogram
===================
This is a collection of remarkable projects made with Pyrogram.
.. A collection of Pyrojects :^)
.. tip::
If you'd like to propose a project that's worth being listed here, feel free to open a `Feature Request`_.
Projects Showcase
-----------------
`YTAudioBot <https://t.me/ytaudio>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| **A YouTube audio downloader on Telegram, serving over 200k MAU.**
| --- by `Dan <https://t.me/haskell>`_
- Main: https://t.me/ytaudiobot
- Mirror: https://t.me/ytaudio_bot
- Website: https://ytaudiobot.ml
-----
`Pyrogram Assistant <https://github.com/pyrogram/assistant>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| **The assistant bot that helps people with Pyrogram directly on Telegram**
| --- by `Dan <https://t.me/haskell>`_
- Bot: https://t.me/pyrogrambot
- Source Code: https://github.com/pyrogram/assistant
-----
`PyroBot <https://git.colinshark.de/PyroBot/PyroBot>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| **A Telegram userbot based on Pyrogram**
| --- by `Colin <https://t.me/ColinShark>`_
- Source Code: https://git.colinshark.de/PyroBot/PyroBot
-----
`TgIntegration <https://github.com/JosXa/tgintegration>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| **Integration Test Library for Telegram Messenger Bots in Python**
| --- by `JosXa <https://t.me/JosXa>`_
- Source Code: https://github.com/JosXa/tgintegration
-----
`BotListBot <https://t.me/botlistt>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| **A bot which partly uses Pyrogram to check if other bots are still alive**
| --- by `JosXa <https://t.me/JosXa>`_
- Source Code: https://github.com/JosXa/BotListBot
-----
.. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md

0
docs/source/topics/releases.rst → docs/source/meta/releases.rst
View File

2
docs/source/meta/support-pyrogram.rst Normal file
View File

@ -0,0 +1,2 @@
Support Pyrogram Development
============================

2
docs/source/intro/auth.rst → docs/source/start/auth.rst
View File

@ -64,6 +64,6 @@ after the session name, which will be ``my_bot.session`` for the example below.
app.run()
.. _project is set up: setup.html
.. _project is set up: ../intro/setup
.. _Country Code: https://en.wikipedia.org/wiki/List_of_country_calling_codes
.. _Bot Father: https://t.me/botfather

58
docs/source/topics/mtproto-vs-botapi.rst Normal file
View 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.