Docs revamp. Part 5
This commit is contained in:
Dan
parent
b6ea451ee5
commit
518220431e
@ -59,6 +59,7 @@ ground up in Python and C. It enables you to easily create custom apps for both
|
||||
- **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.
|
||||
|
||||
|
||||
@ -14,29 +14,15 @@ Welcome to Pyrogram
|
||||
|
||||
<br>
|
||||
<a href="https://github.com/pyrogram/pyrogram">
|
||||
GitHub
|
||||
Source Code
|
||||
</a>
|
||||
•
|
||||
<a href="https://t.me/Pyrogram">
|
||||
Community
|
||||
</a>
|
||||
|
||||
•
|
||||
<a href="https://github.com/pyrogram/pyrogram/releases">
|
||||
Releases
|
||||
</a>
|
||||
•
|
||||
<a href="https://pypi.org/project/Pyrogram">
|
||||
PyPI
|
||||
</a>
|
||||
<br>
|
||||
<a href="compiler/api/source/main_api.tl">
|
||||
<img src="https://img.shields.io/badge/schema-layer%2097-eda738.svg?longCache=true&colorA=262b30"
|
||||
alt="Schema Layer">
|
||||
</a>
|
||||
<a href="https://github.com/pyrogram/tgcrypto">
|
||||
<img src="https://img.shields.io/badge/tgcrypto-v1.1.1-eda738.svg?longCache=true&colorA=262b30"
|
||||
alt="TgCrypto Version">
|
||||
<a href="https://t.me/Pyrogram">
|
||||
Community
|
||||
</a>
|
||||
</p>
|
||||
|
||||
@ -59,7 +45,7 @@ C. It enables you to easily create custom apps for both user and bot identities
|
||||
`MTProto API`_.
|
||||
|
||||
.. _Telegram: https://telegram.org
|
||||
.. _MTProto API: https://core.telegram.org/api#telegram-api
|
||||
.. _MTProto API: topics/faq#what-can-mtproto-do-more-than-the-bot-api
|
||||
|
||||
How the Documentation is Organized
|
||||
----------------------------------
|
||||
@ -68,11 +54,11 @@ Contents are organized into self-contained topics and can be all accessed from t
|
||||
order using the Next button at the end of each page. Here below you can, instead, find a list of the most relevant
|
||||
pages for a quick access.
|
||||
|
||||
Getting Started
|
||||
^^^^^^^^^^^^^^^
|
||||
First Steps
|
||||
^^^^^^^^^^^
|
||||
|
||||
- `Quick Start`_ - Overview to get you started as fast as possible.
|
||||
- `Calling Methods`_ - How to use Pyrogram's API.
|
||||
- `Quick Start`_ - Overview to get you started quickly.
|
||||
- `Calling Methods`_ - How to call Pyrogram's methods.
|
||||
- `Handling Updates`_ - How to handle Telegram updates.
|
||||
- `Error Handling`_ - How to handle API errors correctly.
|
||||
|
||||
@ -83,7 +69,8 @@ Getting Started
|
||||
|
||||
API Reference
|
||||
^^^^^^^^^^^^^
|
||||
- `Client Class`_ - Details about the Client class.
|
||||
|
||||
- `Client Class`_ - Reference details about the Client class.
|
||||
- `Available Methods`_ - A list of available high-level methods.
|
||||
- `Available Types`_ - A list of available high-level types.
|
||||
- `Bound Methods`_ - A list of convenient bound methods.
|
||||
|
||||
@ -2,7 +2,7 @@ Authorization
|
||||
=============
|
||||
|
||||
Once a `project is set up`_, you will still have to follow a few steps before you can actually use Pyrogram to make
|
||||
API calls. This section provides all the information you need in order to authorize yourself as user or a bot.
|
||||
API calls. This section provides all the information you need in order to authorize yourself as user or bot.
|
||||
|
||||
User Authorization
|
||||
------------------
|
||||
@ -51,7 +51,7 @@ the `Bot Father`_. Bot tokens replace the users' phone numbers only — you stil
|
||||
|
||||
The authorization process is automatically managed. All you need to do is choose a ``session_name`` (can be anything,
|
||||
usually your bot username) and pass your bot token using the ``bot_token`` parameter. The session file will be named
|
||||
after the session name, which will be ``pyrogrambot.session`` for the example below.
|
||||
after the session name, which will be ``my_bot.session`` for the example below.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
|
||||
@ -55,7 +55,7 @@ Use this command to install (note "asyncio.zip" in the link):
|
||||
$ pip3 install -U https://github.com/pyrogram/pyrogram/archive/asyncio.zip
|
||||
|
||||
|
||||
Pyrogram API remains the same and features are kept up to date from the non-async, default develop branch, but you
|
||||
Pyrogram's API remains the same and features are kept up to date from the non-async, default develop branch, but you
|
||||
are obviously required Python asyncio knowledge in order to take full advantage of it.
|
||||
|
||||
|
||||
@ -87,7 +87,7 @@ If no error shows up you are good to go.
|
||||
|
||||
>>> import pyrogram
|
||||
>>> pyrogram.__version__
|
||||
'0.12.0'
|
||||
'0.13.0'
|
||||
|
||||
.. _TgCrypto: ../topics/tgcrypto
|
||||
.. _`Github repo`: http://github.com/pyrogram/pyrogram
|
||||
|
||||
@ -1,7 +1,8 @@
|
||||
Quick Start
|
||||
===========
|
||||
|
||||
The next few steps serve as a quick start for all new Pyrogrammers that want to get something done as fast as possible!
|
||||
The next few steps serve as a quick start for all new Pyrogrammers that want to get something done as fast as possible.
|
||||
Let's go!
|
||||
|
||||
Get Pyrogram Real Fast
|
||||
----------------------
|
||||
|
||||
@ -11,8 +11,9 @@ to control the behaviour of your application. Pyrogram errors all live inside th
|
||||
RPCError
|
||||
--------
|
||||
|
||||
The father of all errors is named ``RPCError``. This error exists in form of a Python exception and is able to catch all
|
||||
Telegram API related errors.
|
||||
The father of all errors is named ``RPCError``. This error exists in form of a Python exception which is directly
|
||||
subclass-ed from Python's main ``Exception`` and is able to catch all Telegram API related errors. This error is raised
|
||||
every time a method call against Telegram's API was unsuccessful.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -27,7 +28,7 @@ Error Categories
|
||||
----------------
|
||||
|
||||
The ``RPCError`` packs together all the possible errors Telegram could raise, but to make things tidier, Pyrogram
|
||||
provides categories of errors, which are named after the common HTTP errors:
|
||||
provides categories of errors, which are named after the common HTTP errors and subclass-ed from the RPCError:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -41,6 +42,32 @@ provides categories of errors, which are named after the common HTTP errors:
|
||||
- `420 - Flood <../api/errors#flood>`_
|
||||
- `500 - InternalServerError <../api/errors#internalservererror>`_
|
||||
|
||||
Single Errors
|
||||
-------------
|
||||
|
||||
For a fine-grained control over every single error, Pyrogram does also expose errors that deal each with a specific
|
||||
issue. For example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram.errors import FloodWait
|
||||
|
||||
These errors subclass directly from the category of errors they belong to, which in turn subclass from the father
|
||||
RPCError, thus building a class of error hierarchy such as this:
|
||||
|
||||
- RPCError
|
||||
- BadRequest
|
||||
- ``MessageEmpty``
|
||||
- ``UsernameOccupied``
|
||||
- ``...``
|
||||
- InternalServerError
|
||||
- ``RpcCallFail``
|
||||
- ``InterDcCallError``
|
||||
- ``...``
|
||||
- ``...``
|
||||
|
||||
.. _Errors: api/errors
|
||||
|
||||
Unknown Errors
|
||||
--------------
|
||||
|
||||
|
||||
@ -36,7 +36,7 @@ Now instantiate a new Client object, "my_account" is a session name of your choi
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
To actually make use of any method, the client has to be started:
|
||||
To actually make use of any method, the client has to be started first:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
|
||||
@ -9,11 +9,11 @@ Defining Updates
|
||||
|
||||
First, let's define what are these updates. As hinted already, updates are simply events that happen in your Telegram
|
||||
account (incoming messages, new members join, bot button presses, etc...), which are meant to notify you about a new
|
||||
specific state that changed. These updates are handled by registering one or more callback functions in your app using
|
||||
`Handlers <../api/handlers>`_.
|
||||
specific state that has changed. These updates are handled by registering one or more callback functions in your app
|
||||
using `Handlers <../api/handlers>`_.
|
||||
|
||||
Each handler deals with a specific event and once a matching update arrives from Telegram, your registered callback
|
||||
function will be called and its body executed.
|
||||
function will be called back by the framework and its body executed.
|
||||
|
||||
Registering an Handler
|
||||
----------------------
|
||||
@ -63,8 +63,8 @@ above must only handle updates that are in form of a :obj:`Message <pyrogram.Mes
|
||||
my_handler = MessageHandler(my_function)
|
||||
|
||||
Third: the method :meth:`add_handler() <pyrogram.Client.add_handler>`. This method is used to actually register the
|
||||
handler and let Pyrogram know it needs to be taken into consideration when new updates arrive and the dispatching phase
|
||||
begins.
|
||||
handler and let Pyrogram know it needs to be taken into consideration when new updates arrive and the internal
|
||||
dispatching phase begins.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -109,4 +109,4 @@ to do so is by decorating your callback function with the :meth:`on_message() <p
|
||||
``my_function[0].callback``, that is, the *callback* field of the *handler* object which is the first element in the
|
||||
tuple, accessed by bracket notation *[0]*.
|
||||
|
||||
.. _API methods: usage.html
|
||||
.. _API methods: invoking
|
||||
@ -3,9 +3,14 @@ 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?
|
||||
-----------------
|
||||
@ -41,6 +46,7 @@ Why Pyrogram?
|
||||
- **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.
|
||||
|
||||
@ -51,23 +57,41 @@ Why Pyrogram?
|
||||
What can MTProto do more than the Bot API?
|
||||
------------------------------------------
|
||||
|
||||
- Authorize both user and bot identities.
|
||||
- Upload & download any file, up to 1500 MB each.
|
||||
- Has less overhead due to direct connections to the actual Telegram servers.
|
||||
- Run multiple sessions at once, up to 10 per account (either bot or user).
|
||||
- Get information about any public chat by usernames, even if not a member.
|
||||
- Obtain information about any message existing in a chat using message ids.
|
||||
- retrieve the whole chat members list of either public or private chats.
|
||||
- Receive extra updates, such as the one about a user name change.
|
||||
- More meaningful errors in case something went wrong.
|
||||
- Get API version updates, and thus new features, sooner.
|
||||
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 a backend application that
|
||||
implements the MTProto protocol -- just like Pyrogram -- and uses its own API key, which is always required, but hidden
|
||||
to the public.
|
||||
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
|
||||
@ -76,9 +100,7 @@ Using MTProto is the only way to communicate with the actual Telegram servers, a
|
||||
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.
|
||||
|
||||
Why is the main API (MTProto) superiod
|
||||
|
||||
I started a client but nothing happens!
|
||||
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
|
||||
@ -93,6 +115,15 @@ in a bunch of seconds:
|
||||
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
|
||||
@ -114,7 +145,16 @@ things:
|
||||
|
||||
**Note:** If you really believe this should not happen, kindly open a `Bug Report`_.
|
||||
|
||||
.. _Bug Report: https://github.com/pyrogram/pyrogram/issues/new?labels=bug&template=bug_report.md
|
||||
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!
|
||||
----------------------------------------
|
||||
@ -150,4 +190,7 @@ 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.
|
||||
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
|
||||
|
||||
@ -2,7 +2,12 @@ Pyrogram Glossary
|
||||
-----------------
|
||||
|
||||
This page contains a list of common words with brief explanations related to Pyrogram and, to some extent, Telegram in
|
||||
general.
|
||||
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::
|
||||
|
||||
@ -14,6 +19,18 @@ general.
|
||||
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.
|
||||
|
||||
@ -50,4 +67,6 @@ general.
|
||||
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
|
||||
.. _handling updates: ../start/updates
|
||||
|
||||
.. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md
|
||||
|
||||
@ -8,16 +8,16 @@ Briefly explaining, sessions are simply new logins in your account. They can be
|
||||
app (or by invoking `GetAuthorizations <../telegram/functions/account/GetAuthorizations.html>`_ with Pyrogram). They
|
||||
store some useful information such as the client who's using them and from which country and IP address.
|
||||
|
||||
.. figure:: https://i.imgur.com/lzGPCdZ.png
|
||||
:width: 70%
|
||||
.. figure:: https://i.imgur.com/YaqtMLO.png
|
||||
:width: 90%
|
||||
:align: center
|
||||
|
||||
**A Pyrogram session running on Linux, Python 3.6.**
|
||||
**A Pyrogram session running on Linux, Python 3.7.**
|
||||
|
||||
That's how a session looks like on the Android app, showing the three main pieces of information.
|
||||
|
||||
- ``app_version``: **Pyrogram 🔥 0.7.5**
|
||||
- ``device_model``: **CPython 3.6.5**
|
||||
- ``app_version``: **Pyrogram 0.13.0**
|
||||
- ``device_model``: **CPython 3.7.2**
|
||||
- ``system_version``: **Linux 4.15.0-23-generic**
|
||||
|
||||
Set Custom Values
|
||||
|
||||
@ -26,9 +26,7 @@ if sys.version_info[:3] in [(3, 5, 0), (3, 5, 1), (3, 5, 2)]:
|
||||
|
||||
__version__ = "0.13.0.develop"
|
||||
__license__ = "GNU Lesser General Public License v3 or later (LGPLv3+)"
|
||||
__copyright__ = "Copyright (C) 2017-2019 Dan Tès <https://github.com/delivrance>".replace(
|
||||
"\xe8", "e" if sys.getfilesystemencoding() != "utf-8" else "\xe8"
|
||||
)
|
||||
__copyright__ = "Copyright (C) 2017-2019 Dan <https://github.com/delivrance>"
|
||||
|
||||
from .errors import RPCError
|
||||
from .client import *
|
||||
|
||||
@ -78,7 +78,7 @@ class Client(Methods, BaseClient):
|
||||
This is an alternative way to pass it if you don't want to use the *config.ini* file.
|
||||
|
||||
app_version (``str``, *optional*):
|
||||
Application version. Defaults to "Pyrogram :fire: vX.Y.Z"
|
||||
Application version. Defaults to "Pyrogram X.Y.Z"
|
||||
This is an alternative way to set it if you don't want to use the *config.ini* file.
|
||||
|
||||
device_model (``str``, *optional*):
|
||||
|
||||
@ -31,7 +31,7 @@ class BaseClient:
|
||||
class StopTransmission(StopIteration):
|
||||
pass
|
||||
|
||||
APP_VERSION = "Pyrogram \U0001f525 {}".format(__version__)
|
||||
APP_VERSION = "Pyrogram {}".format(__version__)
|
||||
|
||||
DEVICE_MODEL = "{} {}".format(
|
||||
platform.python_implementation(),
|
||||
|
||||
Loading…
Reference in New Issue
Block a user