Docs revamp. Part 5

delivrance · delivrance · commit 518220431ecf · 2019-05-18T01:45:01.000+02:00
diff --git a/README.md b/README.md
@@ -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.
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -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.
diff --git a/docs/source/intro/auth.rst b/docs/source/intro/auth.rst
@@ -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
 
diff --git a/docs/source/intro/install.rst b/docs/source/intro/install.rst
@@ -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
diff --git a/docs/source/intro/start.rst b/docs/source/intro/start.rst
@@ -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
 ----------------------
diff --git a/docs/source/start/errors.rst b/docs/source/start/errors.rst
@@ -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
 --------------
 
diff --git a/docs/source/start/invoking.rst b/docs/source/start/invoking.rst
@@ -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
 
diff --git a/docs/source/start/updates.rst b/docs/source/start/updates.rst
@@ -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
diff --git a/docs/source/topics/faq.rst b/docs/source/topics/faq.rst
@@ -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
diff --git a/docs/source/topics/glossary.rst b/docs/source/topics/glossary.rst
@@ -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
diff --git a/docs/source/topics/session-settings.rst b/docs/source/topics/session-settings.rst
diff --git a/pyrogram/__init__.py b/pyrogram/__init__.py
diff --git a/pyrogram/client/client.py b/pyrogram/client/client.py
diff --git a/pyrogram/client/ext/base_client.py b/pyrogram/client/ext/base_client.py
