Docs revamp. Part 7

README.md

@@ -16,15 +16,6 @@
     <a href="https://t.me/Pyrogram">
         Community
     </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>
 </p>
 
 ## Pyrogram

docs/source/api/client.rst

@@ -1,7 +1,7 @@
 Pyrogram Client
 ===============
 
-This class exposes high-level methods for an easy access to the API.
+This is the Client class. It exposes high-level methods for an easy access to the API.
 
 .. code-block:: python
     :emphasize-lines: 1-3

docs/source/api/decorators.rst

@@ -34,6 +34,7 @@ of your functions.
     on_inline_query
     on_deleted_messages
     on_user_status
+    on_poll
     on_disconnect
     on_raw_update
 
@@ -42,5 +43,6 @@ of your functions.
 .. automethod:: pyrogram.Client.on_inline_query()
 .. automethod:: pyrogram.Client.on_deleted_messages()
 .. automethod:: pyrogram.Client.on_user_status()
+.. automethod:: pyrogram.Client.on_poll()
 .. automethod:: pyrogram.Client.on_disconnect()
 .. automethod:: pyrogram.Client.on_raw_update()

docs/source/conf.py

@@ -1,200 +1,68 @@
-#!/usr/bin/env python3
+# Pyrogram - Telegram MTProto API Client Library for Python
-# -*- coding: utf-8 -*-
+# Copyright (C) 2017-2019 Dan Tès <https://github.com/delivrance>
 #
-# Pyrogram documentation build configuration file, created by
+# This file is part of Pyrogram.
-# sphinx-quickstart on Fri Dec 29 11:35:55 2017.
 #
-# This file is execfile()d with the current directory set to its
+# Pyrogram is free software: you can redistribute it and/or modify
-# containing dir.
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
 #
-# Note that not all possible configuration values are present in this
+# Pyrogram is distributed in the hope that it will be useful,
-# autogenerated file.
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
 #
-# All configuration values have a default; values that are commented out
+# You should have received a copy of the GNU Lesser General Public License
-# serve to show the default.
+# along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath("../.."))
 
-# Import after sys.path.insert() to avoid issues
 from pyrogram import __version__
 
 from pygments.styles.friendly import FriendlyStyle
 
 FriendlyStyle.background_color = "#f3f2f1"
 
-# -- General configuration ------------------------------------------------
+project = "Pyrogram"
+copyright = "2017-2019, Dan"
+author = "Dan"
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
-    'sphinx.ext.autodoc',
+    "sphinx.ext.autodoc",
-    'sphinx.ext.napoleon',
+    "sphinx.ext.napoleon",
-    'sphinx.ext.autosummary'
+    "sphinx.ext.autosummary"
 ]
 
+master_doc = "index"
+source_suffix = ".rst"
+autodoc_member_order = "bysource"
+
+version = __version__
+release = version
+version_rst = ".. |version| replace:: {}".format(version)
+
+templates_path = ["_templates"]
+
 napoleon_use_rtype = False
 
-# Don't show source files on docs
+pygments_style = "friendly"
-html_show_sourcelink = True
-
-# Order by source, not alphabetically
-autodoc_member_order = 'bysource'
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = 'Pyrogram'
-copyright = '2017-2019, Dan Tès'
-author = 'Dan Tès'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = "version " + __version__
-# The full version, including alpha/beta/rc tags.
-release = version
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = []
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'friendly'
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
-# -- Options for HTML output ----------------------------------------------
 
 html_title = "Pyrogram Documentation"
-
+html_theme = "sphinx_rtd_theme"
-# Overridden by template
+html_static_path = ["_static"]
+html_show_sourcelink = True
 html_show_copyright = False
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = 'sphinx_rtd_theme'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
 html_theme_options = {
-    'canonical_url': "https://docs.pyrogram.org/",
+    "canonical_url": "https://docs.pyrogram.org/",
-    'collapse_navigation': True,
+    "collapse_navigation": True,
-    'sticky_navigation': False,
+    "sticky_navigation": False,
-    'logo_only': True,
+    "logo_only": True,
-    'display_version': True
+    "display_version": True
 }
 
-# The name of an image file (relative to this directory) to place at the top
+html_logo = "_images/pyrogram.png"
-# of the sidebar.
+html_favicon = "_images/favicon.ico"
-html_logo = '_images/logo.png'
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-html_favicon = '_images/favicon.ico'
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
-
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# This is required for the alabaster theme
-# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
-    '**': [
-        'relations.html',  # needs 'show_related': True theme option to display
-        'searchbox.html',
-    ]
-}
-
-# -- Options for HTMLHelp output ------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'Pyrogramdoc'
-
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, 'Pyrogram.tex', 'Pyrogram Documentation',
-     'Dan Tès', 'manual'),
-]
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'pyrogram', 'Pyrogram Documentation',
-     [author], 1)
-]
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (master_doc, 'Pyrogram', 'Pyrogram Documentation',
-     author, 'Pyrogram', 'One line description of project.',
-     'Miscellaneous'),
-]

docs/source/faq.rst

@@ -20,7 +20,7 @@ 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: ../topics/mtproto-vs-botapi#what-is-the-mtproto-api
+.. _MTProto API: topics/mtproto-vs-botapi#what-is-the-mtproto-api
 
 Where does the name come from?
 ------------------------------
@@ -51,15 +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: ../topics/smart-plugins
+.. _Smart Plugin: topics/smart-plugins
-.. _advanced action: ../topics/advanced-usage
+.. _advanced action: topics/advanced-usage
 
 What can MTProto do more than the Bot API?
 ------------------------------------------
 
 For a detailed answer, please refer to the `MTProto vs. Bot API`_ page.
 
-.. _MTProto vs. Bot API: ../topics/mtproto-vs-botapi
+.. _MTProto vs. Bot API: topics/mtproto-vs-botapi
 
 Why do I need an API key for bots?
 ----------------------------------
@@ -75,6 +75,53 @@ 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.
 
+Can I use the same file_id across different accounts?
+-----------------------------------------------------
+
+No, Telegram doesn't allow this.
+
+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 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.
+
+Can I use multiple clients at once on the same account?
+-------------------------------------------------------
+
+Yes, you can. Both user and bot accounts are able to run multiple sessions in parallel (up to 10 per account). However,
+you must pay attention and not use the *same* exact session in more than one client at the same time. In other words:
+
+- Avoid copying your session file: even if you rename the file, the copied sessions will still point to a specific one
+  stored in the server.
+
+- Make sure that only one instance of your script runs, using your session file.
+
+If you -- even accidentally -- fail to do so, all the previous session copies will immediately stop receiving updates
+and eventually the server will start throwing the error ``[406 AUTH_KEY_DUPLICATED]``, inviting you to login again.
+
+Why is that so? Because the server has recognized two identical sessions are running in two different locations, and
+concludes it could possibly be due to a cloned/stolen device. Having the session ended in such occasions will protect
+the user's privacy.
+
+So, the only correct way to run multiple clients on the same account is authorizing your account (either user or bot)
+from the beginning every time, and use one separate session for each parallel client you are going to use.
+
 I started a client and nothing happens!
 ---------------------------------------
 
@@ -99,63 +146,30 @@ fails or not:
 - DC4: ``149.154.167.91``
 - DC5: ``91.108.56.149``
 
-|bug report|
+.. _you need a proxy: topics/proxy
-
-.. _you need a proxy: ../topics/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
+The error in question is ``[400 PEER_ID_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).
-
+- The chat id argument you passed is in form of a string; you have to convert it into an integer with ``int(chat_id)``.
-|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 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!
 ----------------------------------------
 
 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.
+who review reports.
 
-**Pyrogram is a tool at your commands; it only does what you tell it to do, the rest is up to you.**
+.. centered:: 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:
+Having said that, here's 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.
@@ -178,8 +192,8 @@ 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
+In other words: you can use and integrate Pyrogram into your own code --- either open source, under the same or
-different licence or even proprietary --- without being required to release the source code of your own applications.
+different license, 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

docs/source/glossary.rst

@@ -18,7 +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>`_.
+        `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
@@ -26,25 +26,25 @@ general. Some words may as well link to dedicated articles in case the topic is
 
     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.
+        server) and not in your local machine.
 
     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. `More on RPCError <../start/errors>`_.
+        know something went wrong. `More on RPCError <start/errors>`_.
 
     MTProto
         The name of the custom-made, open and encrypted protocol by Telegram, implemented in Pyrogram.
-        `More on MTProto <mtproto-vs-botapi>`_.
+        `More on MTProto <topics/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 TL-schema.
-        `More on MTProto API <mtproto-vs-botapi#what-is-the-mtproto-api>`_.
+        `More on MTProto API <topics/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 only to Telegram using HTTP as application layer
-        protocol and allows to execute a subset of the main Telegram API.
+        protocol and allows to execute a sub-set of the main Telegram API.
-        `More on Bot API <mtproto-vs-botapi#what-is-the-bot-api>`_.
+        `More on Bot API <topics/mtproto-vs-botapi#what-is-the-bot-api>`_.
 
     Pyrogrammer
         A developer that uses Pyrogram to build Telegram applications.
@@ -65,13 +65,11 @@ 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>`_
+        `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.
-        `More on Decorators <../start/updates#using-decorators>`_
+        `More on Decorators <start/updates#using-decorators>`_.
-
-.. _handling updates: ../start/updates
 
 .. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md

docs/source/index.rst

@@ -4,8 +4,8 @@ Welcome to Pyrogram
 .. raw:: html
 
     <div align="center">
-        <a href="https://docs.pyrogram.org">
+        <a href="/">
-            <div><img src="_static/logo.png" alt="Pyrogram Logo"></div>
+            <div><img src="_static/pyrogram.png" alt="Pyrogram Logo" width="420"></div>
         </a>
     </div>
 
@@ -55,12 +55,15 @@ order using the Next button at the end of each page. Here below you can, instead
 pages for a quick access.
 
 First Steps
-^^^^^^^^^^^
+-----------
 
-- `Quick Start`_ - Overview to get you started quickly.
+.. hlist::
-- `Calling Methods`_ - How to call Pyrogram's methods.
+    :columns: 2
-- `Handling Updates`_ - How to handle Telegram updates.
+
-- `Error Handling`_ - How to handle API errors correctly.
+    - `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.
 
 .. _Quick Start: intro/quickstart
 .. _Calling Methods: start/invoking
@@ -68,32 +71,38 @@ First Steps
 .. _Error Handling: start/errors
 
 API Reference
-^^^^^^^^^^^^^
+-------------
 
-- `Client Class`_ - Reference details about the Client class.
+.. hlist::
-- `Available Methods`_ - A list of available high-level methods.
+    :columns: 2
-- `Available Types`_ - A list of available high-level types.
-- `Bound Methods`_ - A list of convenient bound methods.
 
-.. _Client Class: api/client
+    - `Pyrogram Client`_: Reference details about the Client class.
+    - `Available Methods`_: List of available high-level methods.
+    - `Available Types`_: List of available high-level types.
+    - `Bound Methods`_: List of convenient bound methods.
+
+.. _Pyrogram Client: ./api/client
 .. _Available Methods: api/methods
 .. _Available Types: api/types
 .. _Bound Methods: api/bound-methods
 
 Meta
-^^^^
+----
 
-- `Pyrogram FAQ`_ - Answers to common Pyrogram questions.
+.. hlist::
-- `Pyrogram Glossary`_ - A list of words with brief explanations.
+    :columns: 2
-- `Release Notes`_ - Release notes for Pyrogram releases.
-- `Powered by Pyrogram`_ - A collection of Pyrogram Projects.
-- `Support Pyrogram Development`_ - Ways to show your appreciation.
 
-.. _Pyrogram FAQ: meta/faq
+    - `Pyrogram FAQ`_: Answers to common Pyrogram questions.
-.. _Pyrogram Glossary: meta/glossary
+    - `Pyrogram Glossary`_: List of words with brief explanations.
-.. _Release Notes: meta/releases
+    - `Release Notes`_: Release notes for Pyrogram releases.
-.. _Powered by Pyrogram: meta/powered-by
+    - `Powered by Pyrogram`_: Collection of Pyrogram Projects.
-.. _Support Pyrogram Development: meta/support-pyrogram
+    - `Support Pyrogram`_: Ways to show your appreciation.
+
+.. _Pyrogram FAQ: faq
+.. _Pyrogram Glossary: glossary
+.. _Release Notes: releases
+.. _Powered by Pyrogram: powered-by
+.. _Support Pyrogram: support-pyrogram
 
 .. toctree::
     :hidden:
@@ -137,6 +146,7 @@ Meta
     topics/session-settings
     topics/tgcrypto
     topics/text-formatting
+    topics/serialize
     topics/proxy
     topics/bots-interaction
     topics/mtproto-vs-botapi
@@ -148,11 +158,11 @@ Meta
     :hidden:
     :caption: Meta
 
-    meta/faq
+    faq
-    meta/glossary
+    glossary
-    meta/releases
+    releases
-    meta/powered-by
+    powered-by
-    meta/support-pyrogram
+    support-pyrogram
 
 .. toctree::
     :hidden:

docs/source/intro/install.rst

@@ -83,11 +83,11 @@ Verifying
 To verify that Pyrogram is correctly installed, open a Python shell and import it.
 If no error shows up you are good to go.
 
-.. code-block:: python
+.. parsed-literal::
 
     >>> import pyrogram
     >>> pyrogram.__version__
-    '0.13.0'
+    '|version|'
 
 .. _TgCrypto: ../topics/tgcrypto
 .. _`Github repo`: http://github.com/pyrogram/pyrogram

docs/source/intro/setup.rst

@@ -40,7 +40,7 @@ There are two ways to do so, and you can choose what fits better for you:
         api_hash = 0123456789abcdef0123456789abcdef
 
 -   Alternatively, you can pass your API key to Pyrogram by simply using the *api_id* and *api_hash* parameters of the
-    Client class. This way you can have full control on how to store and load your credentials (e.g.:, you can load the
+    Client class. This way you can have full control on how to store and load your credentials (e.g., you can load the
     credentials from the environment variables and directly pass the values into Pyrogram):
 
     .. code-block:: python

docs/source/meta/support-pyrogram.rst

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

docs/source/powered-by.rst

@@ -55,8 +55,8 @@ Projects Showcase
 
 -----
 
-`BotListBot <https://t.me/botlistt>`_
+`BotListBot <https://t.me/botlist>`_
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 | **A bot which partly uses Pyrogram to check if other bots are still alive**
 | --- by `JosXa <https://t.me/JosXa>`_

docs/source/start/auth.rst

@@ -8,7 +8,7 @@ User Authorization
 ------------------
 
 In order to use the API, Telegram requires that users be authorized via their phone numbers.
-Pyrogram automatically manages this access, all you need to do is create an instance of the
+Pyrogram automatically manages this process, all you need to do is create an instance of the
 :class:`Client <pyrogram.Client>` class by passing to it a ``session_name`` of your choice (e.g.: "my_account") and call
 the :meth:`run() <pyrogram.Client.run>` method:
 
@@ -47,7 +47,7 @@ Bot Authorization
 
 Bots are a special kind of users that are authorized via their tokens (instead of phone numbers), which are created by
 the `Bot Father`_. Bot tokens replace the users' phone numbers only — you still need to
-`configure a Telegram API key <setup.html#configuration>`_ with Pyrogram, even when using bots.
+`configure a Telegram API key <../intro/setup#configuration>`_ with Pyrogram, even when using bots.
 
 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

docs/source/support-pyrogram.rst

@@ -0,0 +1,26 @@
+Support Pyrogram
+================
+
+Pyrogram is free and open source software, and thus supported by your love! If you like the project and have found it to
+be useful, give Pyrogram a `Star on GitHub`_. Your appreciation means a lot and helps staying motivated.
+
+.. raw:: html
+
+    <a class="github-button" href="https://github.com/pyrogram/pyrogram" data-size="large" data-show-count="true" aria-label="Star pyrogram/pyrogram on GitHub">Star</a>
+    <br><br>
+
+Donate
+------
+
+If you'd also like to donate in order to support Pyrogram -- or any of my `other works`_ -- you can use the PayPal
+button below. Thank you.
+
+.. image:: https://i.imgur.com/fasFTzK.png
+    :target: https://paypal.me/delivrance
+    :width: 128
+
+--- `Dan`_
+
+.. _Star on GitHub: https://github.com/pyrogram/pyrogram
+.. _other works: https://github.com/delivrance
+.. _Dan: https://t.me/haskell

docs/source/topics/mtproto-vs-botapi.rst

@@ -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
+Pyrogram is a framework that acts as a fully-fledged Telegram client based on MTProto, and this very feature makes it
-official Bot API.
+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
+`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
+itself --- it's the only protocol used to exchange information between a client and the actual Telegram servers.
-servers.
 
-The MTProto **API** however, is what people, for convenience, call the main Telegram API as a whole. This API is able
+The MTProto **API** on the other hand, is what people, for convenience, call the main Telegram API as a whole. This API
-to authorize both users and bots and happens to be built on top of the MTProto encryption protocol by means of binary
+is able to authorize both users and bots and is built on top of the MTProto encryption protocol by means of
-data serialized in a specific way, as described by the TL language, hence the correlation.
+`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
+The `Bot API`_ is an HTTP(S) interface for building normal bots using a sub-set of the main MTProto API. Bots are special
-instead of phone numbers. The Bot API is built yet again on top of the main Telegram API, but runs on an intermediate
+accounts that are authorized via tokens instead of phone numbers. The Bot API is built yet again on top of the main
-server application that in turn communicates with the actual Telegram servers using MTProto.
+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
+    - :guilabel:`+` **Authorize both user and bot identities**
-  up to 50 MB / 20 MB in size (respectively).
+    - :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
+.. hlist::
-  requests before they are sent to the actual Telegram servers.
+    :columns: 1
 
-- **Run multiple sessions at once, up to 10 per account (either bot or user)**: The Bot API intermediate server will
+    - :guilabel:`+` **Upload & download any file, up to 1500 MB each (~1.5 GB)**
-  terminate any other session in case you try to use the same bot again in a parallel connection.
+    - :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
+    - :guilabel:`+` **Has much more detailed types and powerful methods**
-  Telegram's type and some of the methods are limited as well.
+    - :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

docs/source/topics/serialize.rst

@@ -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.

docs/source/topics/session-settings.rst

@@ -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.**

docs/source/topics/tgcrypto.rst

@@ -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.

pyrogram/client/client.py

@@ -66,15 +66,13 @@ class Client(Methods, BaseClient):
         session_name (``str``):
             Name to uniquely identify a session of either a User or a Bot, e.g.: "my_account". This name will be used
             to save a file to disk that stores details needed for reconnecting without asking again for credentials.
-            Note for bots: You can pass a bot token here, but this usage will be deprecated in next releases.
-            Use *bot_token* instead.
 
         api_id (``int``, *optional*):
             The *api_id* part of your Telegram API Key, as integer. E.g.: 12345
             This is an alternative way to pass it if you don't want to use the *config.ini* file.
 
         api_hash (``str``, *optional*):
-            The *api_hash* part of your Telegram API Key, as string. E.g.: "0123456789abcdef0123456789abcdef"
+            The *api_hash* part of your Telegram API Key, as string. E.g.: "0123456789abcdef0123456789abcdef".
             This is an alternative way to pass it if you don't want to use the *config.ini* file.
 
         app_version (``str``, *optional*):
@@ -104,7 +102,7 @@ class Client(Methods, BaseClient):
             This is an alternative way to setup a proxy if you don't want to use the *config.ini* file.
 
         test_mode (``bool``, *optional*):
-            Enable or disable log-in to testing servers. Defaults to False.
+            Enable or disable login to the test servers. Defaults to False.
             Only applicable for new sessions and will be ignored in case previously
             created sessions are loaded.
 
@@ -170,7 +168,7 @@ class Client(Methods, BaseClient):
             Defaults to False (updates enabled and always received).
 
         takeout (``bool``, *optional*):
-            Pass True to let the client use a takeout session instead of a normal one, implies no_updates.
+            Pass True to let the client use a takeout session instead of a normal one, implies *no_updates=True*.
             Useful for exporting your Telegram data. Methods invoked inside a takeout session (such as get_history,
             download_media, ...) are less prone to throw FloodWait exceptions.
             Only available for users, bots will ignore this parameter.

pyrogram/client/types/messages_and_media/message.py

@@ -2928,7 +2928,7 @@ class Message(PyrogramType, Update):
             True on success.
 
         Raises:
-            :class:`RPCError <pyrogram.RPCError>`
+            RPCError: In case of a Telegram RPC error.
         """
         return self._client.pin_chat_message(
             chat_id=self.chat.id,

setup.py

@@ -122,6 +122,7 @@ class Generate(Command):
 if len(argv) > 1 and argv[1] in ["bdist_wheel", "install", "develop"]:
     api_compiler.start()
     error_compiler.start()
+    docs_compiler.start()
 
 setup(
     name="Pyrogram",