Merge develop -> asyncio

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at dan@pyrogram.org. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

.github/CONTRIBUTING.md

@@ -0,0 +1 @@
+# How to Contribute

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug Report
+about: Create a bug report affecting the library
+labels: "bug"
+---
+
+<!-- WARNING: Ignoring this template will lead to the issue being closed as incomplete -->
+
+## Checklist
+- [ ] I am sure the error is coming from Pyrogram's code and not elsewhere.
+- [ ] I have searched in the issue tracker for similar bug reports, including closed ones.
+- [ ] I ran `pip3 install -U https://github.com/pyrogram/pyrogram/archive/develop.zip` and reproduced the issue using the latest development version.
+
+## Description
+A clear and concise description of the problem.
+
+## Steps to Reproduce
+[A minimal, complete and verifiable example](https://stackoverflow.com/help/mcve).
+
+## Traceback
+The full traceback (if applicable).

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,14 @@
+---
+name: Feature Request
+about: Suggest ideas, new features or enhancements
+labels: "enhancement"
+---
+
+<!-- WARNING: Ignoring this template will lead to the issue being closed as incomplete -->
+
+## Checklist
+- [ ] I believe the idea is awesome and would benefit the library.
+- [ ] I have searched in the issue tracker for similar requests, including closed ones.
+
+## Description
+A detailed description of the request.

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,15 @@
+---
+name: Ask Question
+about: Ask a Pyrogram related question
+title: For Q&A purposes, please read this template body
+labels: "question"
+---
+
+<!-- WARNING: Ignoring this template will lead to the issue being closed as incomplete -->
+
+# Important
+This place is for issues about Pyrogram, it's **not a forum**.
+
+If you'd like to post a question, please move to https://stackoverflow.com or join the Telegram community by following the description in https://t.me/pyrogram.
+
+Thanks.

MANIFEST.in

@@ -1,5 +1,5 @@
 ## Include
-include COPYING COPYING.lesser NOTICE requirements.txt
+include README.md COPYING COPYING.lesser NOTICE requirements.txt
 recursive-include compiler *.py *.tl *.tsv *.txt
 recursive-include pyrogram mime.types
 

README.md

@@ -0,0 +1,85 @@
+<p align="center">
+    <a href="https://github.com/pyrogram/pyrogram">
+        <img src="https://i.imgur.com/BOgY9ai.png" alt="Pyrogram">
+    </a>
+    <br>
+    <b>Telegram MTProto API Framework for Python</b>
+    <br>
+    <a href="https://docs.pyrogram.org">
+        Documentation
+    </a>
+    •
+    <a href="https://github.com/pyrogram/pyrogram/releases">
+        Releases
+    </a>
+    •
+    <a href="https://t.me/Pyrogram">
+        Community
+    </a>
+</p>
+
+## Pyrogram
+
+``` python
+from pyrogram import Client, Filters
+
+app = Client("my_account")
+
+
+@app.on_message(Filters.private)
+def hello(client, message):
+    message.reply("Hello {}".format(message.from_user.first_name))
+
+
+app.run()
+```
+
+**Pyrogram** is an elegant, easy-to-use [Telegram](https://telegram.org/) client library and framework written from the
+ground up in Python and C. It enables you to easily create custom apps for both user and bot identities (bot API alternative) via the [MTProto API](https://core.telegram.org/api#telegram-api).
+
+> [Pyrogram in fully-asynchronous mode is also available »](https://github.com/pyrogram/pyrogram/issues/181)
+>
+> [Working PoC of Telegram voice calls using Pyrogram »](https://github.com/bakatrouble/pytgvoip)
+
+### Features
+
+- **Easy**: You can install Pyrogram with pip and start building your applications right away.
+- **Elegant**: Low-level details are abstracted and re-presented in a much nicer and easier way.
+- **Fast**: Crypto parts are boosted up by [TgCrypto](https://github.com/pyrogram/tgcrypto), a high-performance library
+  written in pure C.
+- **Documented**: Pyrogram API methods, types and public interfaces are well documented.
+- **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted.
+- **Updated**, to make use of the latest Telegram API version and features.
+- **Bot API-like**: Similar to the Bot API in its simplicity, but much more powerful and detailed.
+- **Pluggable**: The Smart Plugin system allows to write components with minimal boilerplate code.
+- **Comprehensive**: Execute any advanced action an official client is able to do, and even more.
+
+### Requirements
+
+- Python 3.4 or higher.
+- A [Telegram API key](https://docs.pyrogram.org/intro/setup#api-keys).
+
+### Installing
+
+``` bash
+pip3 install pyrogram
+```
+
+### Resources
+
+- The Docs contain lots of resources to help you getting started with Pyrogram: https://docs.pyrogram.org.
+- Reading [Examples in this repository](https://github.com/pyrogram/pyrogram/tree/master/examples) is also a good way
+  for learning how Pyrogram works.
+- Seeking extra help? Don't be shy, come join and ask our [Community](https://t.me/PyrogramChat)!
+- For other requests you can send an [Email](mailto:dan@pyrogram.org) or a [Message](https://t.me/haskell).
+
+### Contributing
+
+Pyrogram is brand new, and **you are welcome to try it and help make it even better** by either submitting pull
+requests or reporting issues/bugs as well as suggesting best practices, ideas, enhancements on both code
+and documentation. Any help is appreciated!
+
+### Copyright & License
+
+- Copyright (C) 2017-2019 Dan Tès <<https://github.com/delivrance>>
+- Licensed under the terms of the [GNU Lesser General Public License v3 or later (LGPLv3+)](COPYING.lesser)

README.rst

@@ -1,131 +0,0 @@
-|header|
-
-Pyrogram
-========
-
-.. code-block:: python
-
-    from pyrogram import Client, Filters
-
-    app = Client("my_account")
-
-
-    @app.on_message(Filters.private)
-    def hello(client, message):
-        message.reply("Hello {}".format(message.from_user.first_name))
-
-
-    app.run()
-
-**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and C.
-It enables you to easily create custom apps using both user and bot identities (bot API alternative) via the `MTProto API`_.
-
-    `Pyrogram in fully-asynchronous mode is also available » <https://github.com/pyrogram/pyrogram/issues/181>`_
-    
-    `Working PoC of Telegram voice calls using Pyrogram » <https://github.com/bakatrouble/pytgvoip>`_
-
-Features
---------
-
--   **Easy**: You can install Pyrogram with pip and start building your applications right away.
--   **Elegant**: Low-level details are abstracted and re-presented in a much nicer and easier way.
--   **Fast**: Crypto parts are boosted up by TgCrypto_, a high-performance library written in pure C.
--   **Documented**: Pyrogram API methods, types and public interfaces are well documented.
--   **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted.
--   **Updated**, to the latest Telegram API version, currently Layer 97 on top of `MTProto 2.0`_.
--   **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.
-
-Requirements
-------------
-
--   Python 3.4 or higher.
--   A `Telegram API key`_.
-
-Installing
-----------
-
-.. code:: shell
-
-    pip3 install pyrogram
-
-Resources
----------
-
--   The Docs contain lots of resources to help you getting started with Pyrogram: https://docs.pyrogram.ml.
--   Reading `Examples in this repository`_ is also a good way for learning how Pyrogram works.
--   Seeking extra help? Don't be shy, come join and ask our Community_!
--   For other requests you can send an Email_ or a Message_.
-
-Contributing
-------------
-
-Pyrogram is brand new, and **you are welcome to try it and help make it even better** by either submitting pull
-requests or reporting issues/bugs as well as suggesting best practices, ideas, enhancements on both code
-and documentation. Any help is appreciated!
-
-Copyright & License
--------------------
-
--   Copyright (C) 2017-2019 Dan Tès <https://github.com/delivrance>
--   Licensed under the terms of the `GNU Lesser General Public License v3 or later (LGPLv3+)`_
-
-.. _`Telegram`: https://telegram.org/
-.. _`MTProto API`: https://core.telegram.org/api#telegram-api
-.. _`Telegram API key`: https://docs.pyrogram.ml/start/ProjectSetup#api-keys
-.. _`Community`: https://t.me/PyrogramChat
-.. _`Examples in this repository`: https://github.com/pyrogram/pyrogram/tree/master/examples
-.. _`GitHub`: https://github.com/pyrogram/pyrogram/issues
-.. _`Email`: admin@pyrogram.ml
-.. _`Message`: https://t.me/haskell
-.. _TgCrypto: https://github.com/pyrogram/tgcrypto
-.. _`MTProto 2.0`: https://core.telegram.org/mtproto
-.. _`GNU Lesser General Public License v3 or later (LGPLv3+)`: COPYING.lesser
-
-.. |header| raw:: html
-
-    <h1 align="center">
-        <a href="https://github.com/pyrogram/pyrogram">
-            <div><img src="https://raw.githubusercontent.com/pyrogram/logos/master/logos/pyrogram_logo2.png" alt="Pyrogram Logo"></div>
-        </a>
-    </h1>
-
-    <p align="center">
-        <b>Telegram MTProto API Framework for Python</b>
-
-        <br>
-        <a href="https://docs.pyrogram.ml">
-            Documentation
-        </a>
-        •
-        <a href="https://github.com/pyrogram/pyrogram/releases">
-            Changelog
-        </a>
-        •
-        <a href="https://t.me/PyrogramChat">
-            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>
-
-.. |logo| image:: https://raw.githubusercontent.com/pyrogram/logos/master/logos/pyrogram_logo2.png
-    :target: https://pyrogram.ml
-    :alt: Pyrogram
-
-.. |description| replace:: **Telegram MTProto API Framework for Python**
-
-.. |schema| image:: https://img.shields.io/badge/schema-layer%2097-eda738.svg?longCache=true&colorA=262b30
-    :target: compiler/api/source/main_api.tl
-    :alt: Schema Layer
-
-.. |tgcrypto| image:: https://img.shields.io/badge/tgcrypto-v1.1.1-eda738.svg?longCache=true&colorA=262b30
-    :target: https://github.com/pyrogram/tgcrypto
-    :alt: TgCrypto Version

compiler/api/compiler.py

@@ -328,15 +328,15 @@ def start():
                 )
 
         if docstring_args:
-            docstring_args = "Args:\n        " + "\n        ".join(docstring_args)
+            docstring_args = "Parameters:\n        " + "\n        ".join(docstring_args)
         else:
             docstring_args = "No parameters required."
 
         docstring_args = "Attributes:\n        ID: ``{}``\n\n    ".format(c.id) + docstring_args
 
         if c.section == "functions":
-            docstring_args += "\n\n    Raises:\n        :obj:`RPCError <pyrogram.RPCError>`"
             docstring_args += "\n\n    Returns:\n        " + get_docstring_arg_type(c.return_type)
+
         else:
             references = get_references(".".join(filter(None, [c.namespace, c.name])))
 
@@ -462,7 +462,7 @@ def start():
                             ["{0}={0}".format(i[0]) for i in sorted_args if i != ("flags", "#")]
                         ),
                         slots=", ".join(['"{}"'.format(i[0]) for i in sorted_args if i != ("flags", "#")]),
-                        qualname="{}{}".format("{}.".format(c.namespace) if c.namespace else "", c.name)
+                        qualname="{}.{}{}".format(c.section, "{}.".format(c.namespace) if c.namespace else "", c.name)
                     )
                 )
 

compiler/docs/compiler.py

@@ -21,7 +21,7 @@ import os
 import shutil
 
 HOME = "compiler/docs"
-DESTINATION = "docs/source"
+DESTINATION = "docs/source/telegram"
 
 FUNCTIONS_PATH = "pyrogram/api/functions"
 TYPES_PATH = "pyrogram/api/types"
@@ -129,6 +129,6 @@ if "__main__" == __name__:
     FUNCTIONS_PATH = "../../pyrogram/api/functions"
     TYPES_PATH = "../../pyrogram/api/types"
     HOME = "."
-    DESTINATION = "../../docs/source"
+    DESTINATION = "../../docs/source/telegram"
 
     start()

compiler/docs/template/page.txt

@@ -1,5 +1,5 @@
 {title}
 {title_markup}
 
-.. autoclass:: {full_class_path}
+.. autoclass:: {full_class_path}()
     :members:

compiler/error/source/400_BAD_REQUEST.tsv

@@ -97,3 +97,5 @@ CHAT_NOT_MODIFIED	The chat settings were not modified
 RESULTS_TOO_MUCH	The result contains too many items
 RESULT_ID_DUPLICATE	The result contains items with duplicated identifiers
 ACCESS_TOKEN_INVALID	The bot access token is invalid
+INVITE_HASH_EXPIRED	The chat invite link is no longer valid
+USER_BANNED_IN_CHANNEL	You are limited, check @SpamBot for details

compiler/error/source/403_FORBIDDEN.tsv

@@ -3,3 +3,5 @@ CHAT_WRITE_FORBIDDEN	You don't have rights to send messages in this chat
 RIGHT_FORBIDDEN	One or more admin rights can't be applied to this kind of chat (channel/supergroup)
 CHAT_ADMIN_INVITE_REQUIRED	You don't have rights to invite other users
 MESSAGE_DELETE_FORBIDDEN	You don't have rights to delete messages in this chat
+CHAT_SEND_MEDIA_FORBIDDEN	You can't send media messages in this chat
+MESSAGE_AUTHOR_REQUIRED	You are not the author of this message

compiler/error/source/500_INTERNAL_SERVER_ERROR.tsv

@@ -6,3 +6,6 @@ PERSISTENT_TIMESTAMP_OUTDATED	Telegram is having internal problems. Please try a
 HISTORY_GET_FAILED	Telegram is having internal problems. Please try again later
 REG_ID_GENERATE_FAILED	Telegram is having internal problems. Please try again later
 RANDOM_ID_DUPLICATE	Telegram is having internal problems. Please try again later
+WORKER_BUSY_TOO_LONG_RETRY	Telegram is having internal problems. Please try again later
+INTERDC_X_CALL_ERROR	Telegram is having internal problems. Please try again later
+INTERDC_X_CALL_RICH_ERROR	Telegram is having internal problems. Please try again later

docs/robots.txt

@@ -0,0 +1,3 @@
+User-agent: *
+Allow: /
+Sitemap: https://docs.pyrogram.org/sitemap.xml

docs/sitemap.py

@@ -18,17 +18,16 @@
 
 import datetime
 import os
-import re
 
-canonical = "https://docs.pyrogram.ml"
+canonical = "https://docs.pyrogram.org/"
 
 dirs = {
-    "start": ("weekly", 0.9),
+    ".": ("weekly", 1.0),
-    "resources": ("weekly", 0.8),
+    "intro": ("weekly", 0.8),
-    "pyrogram": ("weekly", 0.8),
+    "start": ("weekly", 0.8),
-    "functions": ("monthly", 0.7),
+    "api": ("weekly", 0.6),
-    "types": ("monthly", 0.7),
+    "topics": ("weekly", 0.6),
-    "errors": ("weekly", 0.6)
+    "telegram": ("weekly", 0.4)
 }
 
 
@@ -37,10 +36,10 @@ def now():
 
 
 with open("sitemap.xml", "w") as f:
-    f.write("<?xml version=\"1.0\" encoding=\"utf-8\"?>\n")
+    f.write('<?xml version="1.0" encoding="utf-8"?>\n')
-    f.write("<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n")
+    f.write('<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n')
 
-    urls = [(canonical, now(), "weekly", 1.0)]
+    urls = []
 
 
     def search(path):
@@ -48,14 +47,27 @@ with open("sitemap.xml", "w") as f:
             for j in os.listdir(path):
                 search("{}/{}".format(path, j))
         except NotADirectoryError:
-            d = path.split("/")[0]
+            if not path.endswith(".rst"):
-            path = "{}/{}".format(canonical, path.split(".")[0])
+                return
-            path = re.sub("^(.+)/index$", "\g<1>", path)
+
-            urls.append((path, now(), dirs[d][0], dirs[d][1]))
+            path = path.split("/")[1:]
+
+            if path[0].endswith(".rst"):
+                folder = "."
+            else:
+                folder = path[0]
+
+            path = "{}{}".format(canonical, "/".join(path))[:-len(".rst")]
+
+            if path.endswith("index"):
+                path = path[:-len("index")]
+
+            urls.append((path, now(), *dirs[folder]))
 
 
-    for i in dirs.keys():
+    search("source")
-        search(i)
+
+    urls.sort(key=lambda x: x[3], reverse=True)
 
     for i in urls:
         f.write("    <url>\n")

docs/source/api/bound-methods.rst

@@ -0,0 +1,102 @@
+Bound Methods
+=============
+
+Some Pyrogram types define what are called bound methods. Bound methods are functions attached to a class which are
+accessed via an instance of that class. They make it even easier to call specific methods by automatically inferring
+some of the required arguments.
+
+.. code-block:: python
+    :emphasize-lines: 8
+
+    from pyrogram import Client
+
+    app = Client("my_account")
+
+
+    @app.on_message()
+    def hello(client, message)
+        message.reply("hi")
+
+
+    app.run()
+
+.. currentmodule:: pyrogram
+
+- Message_
+- CallbackQuery_
+- InlineQuery_
+
+.. _Message:
+
+Message
+-------
+
+- :meth:`Message.click()`
+- :meth:`Message.delete()`
+- :meth:`Message.download()`
+- :meth:`Message.edit()`
+- :meth:`Message.edit_caption()`
+- :meth:`Message.edit_media()`
+- :meth:`Message.edit_reply_markup()`
+- :meth:`Message.forward()`
+- :meth:`Message.pin()`
+- :meth:`Message.reply()`
+- :meth:`Message.reply_animation()`
+- :meth:`Message.reply_audio()`
+- :meth:`Message.reply_cached_media()`
+- :meth:`Message.reply_chat_action()`
+- :meth:`Message.reply_contact()`
+- :meth:`Message.reply_document()`
+- :meth:`Message.reply_game()`
+- :meth:`Message.reply_inline_bot_result()`
+- :meth:`Message.reply_location()`
+- :meth:`Message.reply_media_group()`
+- :meth:`Message.reply_photo()`
+- :meth:`Message.reply_poll()`
+- :meth:`Message.reply_sticker()`
+- :meth:`Message.reply_venue()`
+- :meth:`Message.reply_video()`
+- :meth:`Message.reply_video_note()`
+- :meth:`Message.reply_voice()`
+
+.. automethod:: Message.click()
+.. automethod:: Message.delete()
+.. automethod:: Message.download()
+.. automethod:: Message.edit()
+.. automethod:: Message.edit_caption()
+.. automethod:: Message.edit_media()
+.. automethod:: Message.edit_reply_markup()
+.. automethod:: Message.forward()
+.. automethod:: Message.pin()
+.. automethod:: Message.reply()
+.. automethod:: Message.reply_animation()
+.. automethod:: Message.reply_audio()
+.. automethod:: Message.reply_cached_media()
+.. automethod:: Message.reply_chat_action()
+.. automethod:: Message.reply_contact()
+.. automethod:: Message.reply_document()
+.. automethod:: Message.reply_game()
+.. automethod:: Message.reply_inline_bot_result()
+.. automethod:: Message.reply_location()
+.. automethod:: Message.reply_media_group()
+.. automethod:: Message.reply_photo()
+.. automethod:: Message.reply_poll()
+.. automethod:: Message.reply_sticker()
+.. automethod:: Message.reply_venue()
+.. automethod:: Message.reply_video()
+.. automethod:: Message.reply_video_note()
+.. automethod:: Message.reply_voice()
+
+.. _CallbackQuery:
+
+CallbackQuery
+-------------
+
+.. automethod:: CallbackQuery.answer()
+
+.. _InlineQuery:
+
+InlineQuery
+-----------
+
+.. automethod:: InlineQuery.answer()

docs/source/api/client.rst

@@ -0,0 +1,16 @@
+Pyrogram Client
+===============
+
+This is the Client class. It exposes high-level methods for an easy access to the API.
+
+.. code-block:: python
+    :emphasize-lines: 1-3
+
+    from pyrogram import Client
+
+    app = Client("my_account")
+
+    with app:
+        app.send_message("me", "Hi!")
+
+.. autoclass:: pyrogram.Client()

docs/source/api/decorators.rst

@@ -0,0 +1,48 @@
+Decorators
+==========
+
+While still being methods bound to the :obj:`Client <pyrogram.Client>` class, decorators are of a special kind and thus deserve a
+dedicated page.
+
+Decorators are able to register callback functions for handling updates in a much easier and cleaner way compared to
+`Handlers <Handlers.html>`_; they do so by instantiating the correct handler and calling
+:meth:`add_handler() <pyrogram.Client.add_handler>`, automatically. All you need to do is adding the decorators on top
+of your functions.
+
+.. code-block:: python
+    :emphasize-lines: 6
+
+    from pyrogram import Client
+
+    app = Client("my_account")
+
+
+    @app.on_message()
+    def log(client, message):
+        print(message)
+
+
+    app.run()
+
+.. currentmodule:: pyrogram.Client
+
+.. autosummary::
+    :nosignatures:
+
+    on_message
+    on_callback_query
+    on_inline_query
+    on_deleted_messages
+    on_user_status
+    on_poll
+    on_disconnect
+    on_raw_update
+
+.. automethod:: pyrogram.Client.on_message()
+.. automethod:: pyrogram.Client.on_callback_query()
+.. 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/api/errors.rst

@@ -0,0 +1,72 @@
+RPC Errors
+==========
+
+All Pyrogram API errors live inside the ``errors`` sub-package: ``pyrogram.errors``.
+The errors ids listed here are shown as *UPPER_SNAKE_CASE*, but the actual exception names to import from Pyrogram
+follow the usual *PascalCase* convention.
+
+.. code-block:: python
+    :emphasize-lines: 1, 5
+
+    from pyrogram.errors import FloodWait
+
+    try:
+        ...
+    except FloodWait as e:
+        ...
+
+303 - SeeOther
+--------------
+
+.. csv-table::
+    :file: ../../../compiler/error/source/303_SEE_OTHER.tsv
+    :delim: tab
+    :header-rows: 1
+
+400 - BadRequest
+----------------
+
+.. csv-table::
+    :file: ../../../compiler/error/source/400_BAD_REQUEST.tsv
+    :delim: tab
+    :header-rows: 1
+
+401 - Unauthorized
+------------------
+
+.. csv-table::
+    :file: ../../../compiler/error/source/401_UNAUTHORIZED.tsv
+    :delim: tab
+    :header-rows: 1
+
+403 - Forbidden
+---------------
+
+.. csv-table::
+    :file: ../../../compiler/error/source/403_FORBIDDEN.tsv
+    :delim: tab
+    :header-rows: 1
+
+406 - NotAcceptable
+-------------------
+
+.. csv-table::
+    :file: ../../../compiler/error/source/406_NOT_ACCEPTABLE.tsv
+    :delim: tab
+    :header-rows: 1
+
+420 - Flood
+-----------
+
+.. csv-table::
+    :file: ../../../compiler/error/source/420_FLOOD.tsv
+    :delim: tab
+    :header-rows: 1
+
+500 - InternalServerError
+-------------------------
+
+.. csv-table::
+    :file: ../../../compiler/error/source/500_INTERNAL_SERVER_ERROR.tsv
+    :delim: tab
+    :header-rows: 1

docs/source/api/filters.rst

@@ -1,5 +1,5 @@
-Filters
+Update Filters
-=======
+==============
 
 .. autoclass:: pyrogram.Filters
     :members:

docs/source/api/handlers.rst

@@ -0,0 +1,47 @@
+Update Handlers
+===============
+
+Handlers are used to instruct Pyrogram about which kind of updates you'd like to handle with your callback functions.
+
+For a much more convenient way of registering callback functions have a look at `Decorators <Decorators.html>`_ instead.
+In case you decided to manually create a handler, use :meth:`add_handler() <pyrogram.Client.add_handler>` to register
+it.
+
+.. code-block:: python
+    :emphasize-lines: 1, 10
+
+    from pyrogram import Client, MessageHandler
+
+    app = Client("my_account")
+
+
+    def dump(client, message):
+        print(message)
+
+
+    app.add_handler(MessageHandler(dump))
+
+    app.run()
+
+.. currentmodule:: pyrogram
+
+.. autosummary::
+    :nosignatures:
+
+    MessageHandler
+    DeletedMessagesHandler
+    CallbackQueryHandler
+    InlineQueryHandler
+    UserStatusHandler
+    PollHandler
+    DisconnectHandler
+    RawUpdateHandler
+
+.. autoclass:: MessageHandler()
+.. autoclass:: DeletedMessagesHandler()
+.. autoclass:: CallbackQueryHandler()
+.. autoclass:: InlineQueryHandler()
+.. autoclass:: UserStatusHandler()
+.. autoclass:: PollHandler()
+.. autoclass:: DisconnectHandler()
+.. autoclass:: RawUpdateHandler()

docs/source/api/methods.rst

@@ -0,0 +1,265 @@
+Available Methods
+=================
+
+All Pyrogram methods listed here are bound to a :obj:`Client <pyrogram.Client>` instance.
+
+.. code-block:: python
+    :emphasize-lines: 6
+
+    from pyrogram import Client
+
+    app = Client("my_account")
+
+    with app:
+        app.send_message("haskell", "hi")
+
+.. currentmodule:: pyrogram.Client
+
+Utilities
+---------
+
+.. autosummary::
+    :nosignatures:
+
+    start
+    stop
+    restart
+    idle
+    run
+    add_handler
+    remove_handler
+    send
+    resolve_peer
+    save_file
+    stop_transmission
+
+Messages
+--------
+
+.. autosummary::
+    :nosignatures:
+
+    send_message
+    forward_messages
+    send_photo
+    send_audio
+    send_document
+    send_sticker
+    send_video
+    send_animation
+    send_voice
+    send_video_note
+    send_media_group
+    send_location
+    send_venue
+    send_contact
+    send_cached_media
+    send_chat_action
+    edit_message_text
+    edit_message_caption
+    edit_message_reply_markup
+    edit_message_media
+    delete_messages
+    get_messages
+    get_history
+    get_history_count
+    iter_history
+    send_poll
+    vote_poll
+    stop_poll
+    retract_vote
+    download_media
+
+Chats
+-----
+
+.. autosummary::
+    :nosignatures:
+
+    join_chat
+    leave_chat
+    kick_chat_member
+    unban_chat_member
+    restrict_chat_member
+    promote_chat_member
+    export_chat_invite_link
+    set_chat_photo
+    delete_chat_photo
+    set_chat_title
+    set_chat_description
+    pin_chat_message
+    unpin_chat_message
+    get_chat
+    get_chat_member
+    get_chat_members
+    get_chat_members_count
+    iter_chat_members
+    get_dialogs
+    iter_dialogs
+    get_dialogs_count
+    restrict_chat
+    update_chat_username
+
+Users
+-----
+
+.. autosummary::
+    :nosignatures:
+
+    get_me
+    get_users
+    get_user_profile_photos
+    get_user_profile_photos_count
+    set_user_profile_photo
+    delete_user_profile_photos
+    update_username
+
+Contacts
+--------
+
+.. autosummary::
+    :nosignatures:
+
+    add_contacts
+    get_contacts
+    get_contacts_count
+    delete_contacts
+
+Password
+--------
+
+.. autosummary::
+    :nosignatures:
+
+    enable_cloud_password
+    change_cloud_password
+    remove_cloud_password
+
+Bots
+----
+
+.. autosummary::
+    :nosignatures:
+
+    get_inline_bot_results
+    send_inline_bot_result
+    answer_callback_query
+    answer_inline_query
+    request_callback_answer
+    send_game
+    set_game_score
+    get_game_high_scores
+
+..  Utilities
+    ---------
+
+.. automethod:: pyrogram.Client.start()
+.. automethod:: pyrogram.Client.stop()
+.. automethod:: pyrogram.Client.restart()
+.. automethod:: pyrogram.Client.idle()
+.. automethod:: pyrogram.Client.run()
+.. automethod:: pyrogram.Client.add_handler()
+.. automethod:: pyrogram.Client.remove_handler()
+.. automethod:: pyrogram.Client.send()
+.. automethod:: pyrogram.Client.resolve_peer()
+.. automethod:: pyrogram.Client.save_file()
+.. automethod:: pyrogram.Client.stop_transmission()
+
+..  Messages
+    --------
+
+.. automethod:: pyrogram.Client.send_message()
+.. automethod:: pyrogram.Client.forward_messages()
+.. automethod:: pyrogram.Client.send_photo()
+.. automethod:: pyrogram.Client.send_audio()
+.. automethod:: pyrogram.Client.send_document()
+.. automethod:: pyrogram.Client.send_sticker()
+.. automethod:: pyrogram.Client.send_video()
+.. automethod:: pyrogram.Client.send_animation()
+.. automethod:: pyrogram.Client.send_voice()
+.. automethod:: pyrogram.Client.send_video_note()
+.. automethod:: pyrogram.Client.send_media_group()
+.. automethod:: pyrogram.Client.send_location()
+.. automethod:: pyrogram.Client.send_venue()
+.. automethod:: pyrogram.Client.send_contact()
+.. automethod:: pyrogram.Client.send_cached_media()
+.. automethod:: pyrogram.Client.send_chat_action()
+.. automethod:: pyrogram.Client.edit_message_text()
+.. automethod:: pyrogram.Client.edit_message_caption()
+.. automethod:: pyrogram.Client.edit_message_reply_markup()
+.. automethod:: pyrogram.Client.edit_message_media()
+.. automethod:: pyrogram.Client.delete_messages()
+.. automethod:: pyrogram.Client.get_messages()
+.. automethod:: pyrogram.Client.get_history()
+.. automethod:: pyrogram.Client.get_history_count()
+.. automethod:: pyrogram.Client.iter_history()
+.. automethod:: pyrogram.Client.send_poll()
+.. automethod:: pyrogram.Client.vote_poll()
+.. automethod:: pyrogram.Client.stop_poll()
+.. automethod:: pyrogram.Client.retract_vote()
+.. automethod:: pyrogram.Client.download_media()
+
+..  Chats
+    -----
+
+.. automethod:: pyrogram.Client.join_chat()
+.. automethod:: pyrogram.Client.leave_chat()
+.. automethod:: pyrogram.Client.kick_chat_member()
+.. automethod:: pyrogram.Client.unban_chat_member()
+.. automethod:: pyrogram.Client.restrict_chat_member()
+.. automethod:: pyrogram.Client.promote_chat_member()
+.. automethod:: pyrogram.Client.export_chat_invite_link()
+.. automethod:: pyrogram.Client.set_chat_photo()
+.. automethod:: pyrogram.Client.delete_chat_photo()
+.. automethod:: pyrogram.Client.set_chat_title()
+.. automethod:: pyrogram.Client.set_chat_description()
+.. automethod:: pyrogram.Client.pin_chat_message()
+.. automethod:: pyrogram.Client.unpin_chat_message()
+.. automethod:: pyrogram.Client.get_chat()
+.. automethod:: pyrogram.Client.get_chat_member()
+.. automethod:: pyrogram.Client.get_chat_members()
+.. automethod:: pyrogram.Client.get_chat_members_count()
+.. automethod:: pyrogram.Client.iter_chat_members()
+.. automethod:: pyrogram.Client.get_dialogs()
+.. automethod:: pyrogram.Client.iter_dialogs()
+.. automethod:: pyrogram.Client.get_dialogs_count()
+.. automethod:: pyrogram.Client.restrict_chat()
+.. automethod:: pyrogram.Client.update_chat_username()
+
+..  Users
+    -----
+
+.. automethod:: pyrogram.Client.get_me()
+.. automethod:: pyrogram.Client.get_users()
+.. automethod:: pyrogram.Client.get_user_profile_photos()
+.. automethod:: pyrogram.Client.get_user_profile_photos_count()
+.. automethod:: pyrogram.Client.set_user_profile_photo()
+.. automethod:: pyrogram.Client.delete_user_profile_photos()
+.. automethod:: pyrogram.Client.update_username()
+
+..  Contacts
+    --------
+
+.. automethod:: pyrogram.Client.add_contacts()
+.. automethod:: pyrogram.Client.get_contacts()
+.. automethod:: pyrogram.Client.get_contacts_count()
+.. automethod:: pyrogram.Client.delete_contacts()
+
+..  Password
+    --------
+
+.. automethod:: pyrogram.Client.enable_cloud_password()
+.. automethod:: pyrogram.Client.change_cloud_password()
+.. automethod:: pyrogram.Client.remove_cloud_password()
+
+..  Bots
+    ----
+
+.. automethod:: pyrogram.Client.get_inline_bot_results()
+.. automethod:: pyrogram.Client.send_inline_bot_result()
+.. automethod:: pyrogram.Client.answer_callback_query()
+.. automethod:: pyrogram.Client.answer_inline_query()
+.. automethod:: pyrogram.Client.request_callback_answer()
+.. automethod:: pyrogram.Client.send_game()
+.. automethod:: pyrogram.Client.set_game_score()
+.. automethod:: pyrogram.Client.get_game_high_scores()

docs/source/api/types.rst

@@ -0,0 +1,184 @@
+Available Types
+===============
+
+All Pyrogram types listed here are accessible through the main package directly.
+
+.. code-block:: python
+    :emphasize-lines: 1
+
+    from pyrogram import User, Message, ...
+
+.. note::
+
+    **Optional** fields may not exist when irrelevant -- i.e.: they will contain the value of ``None`` and aren't shown
+    when, for example, using ``print()``.
+
+.. currentmodule:: pyrogram
+
+Users & Chats
+-------------
+
+.. autosummary::
+    :nosignatures:
+
+    User
+    UserStatus
+    Chat
+    ChatPreview
+    ChatPhoto
+    ChatMember
+    ChatMembers
+    ChatPermissions
+    Dialog
+    Dialogs
+
+Messages & Media
+----------------
+
+.. autosummary::
+    :nosignatures:
+
+    Message
+    Messages
+    MessageEntity
+    Photo
+    PhotoSize
+    UserProfilePhotos
+    Audio
+    Document
+    Animation
+    Video
+    Voice
+    VideoNote
+    Contact
+    Location
+    Venue
+    Sticker
+    Game
+    Poll
+    PollOption
+
+Keyboards
+---------
+
+.. autosummary::
+    :nosignatures:
+
+    ReplyKeyboardMarkup
+    KeyboardButton
+    ReplyKeyboardRemove
+    InlineKeyboardMarkup
+    InlineKeyboardButton
+    ForceReply
+    CallbackQuery
+    GameHighScore
+    GameHighScores
+    CallbackGame
+
+Input Media
+-----------
+
+.. autosummary::
+    :nosignatures:
+
+    InputMedia
+    InputMediaPhoto
+    InputMediaVideo
+    InputMediaAudio
+    InputMediaAnimation
+    InputMediaDocument
+    InputPhoneContact
+
+Inline Mode
+------------
+
+.. autosummary::
+    :nosignatures:
+
+    InlineQuery
+    InlineQueryResult
+    InlineQueryResultArticle
+
+InputMessageContent
+-------------------
+
+.. autosummary::
+    :nosignatures:
+
+    InputMessageContent
+    InputTextMessageContent
+
+..  User & Chats
+    ------------
+
+.. autoclass:: User()
+.. autoclass:: UserStatus()
+.. autoclass:: Chat()
+.. autoclass:: ChatPreview()
+.. autoclass:: ChatPhoto()
+.. autoclass:: ChatMember()
+.. autoclass:: ChatMembers()
+.. autoclass:: ChatPermissions()
+.. autoclass:: Dialog()
+.. autoclass:: Dialogs()
+
+..  Messages & Media
+    ----------------
+
+.. autoclass:: Message()
+.. autoclass:: Messages()
+.. autoclass:: MessageEntity()
+.. autoclass:: Photo()
+.. autoclass:: PhotoSize()
+.. autoclass:: UserProfilePhotos()
+.. autoclass:: Audio()
+.. autoclass:: Document()
+.. autoclass:: Animation()
+.. autoclass:: Video()
+.. autoclass:: Voice()
+.. autoclass:: VideoNote()
+.. autoclass:: Contact()
+.. autoclass:: Location()
+.. autoclass:: Venue()
+.. autoclass:: Sticker()
+.. autoclass:: Game()
+.. autoclass:: Poll()
+.. autoclass:: PollOption()
+
+..  Keyboards
+    ---------
+
+.. autoclass:: ReplyKeyboardMarkup()
+.. autoclass:: KeyboardButton()
+.. autoclass:: ReplyKeyboardRemove()
+.. autoclass:: InlineKeyboardMarkup()
+.. autoclass:: InlineKeyboardButton()
+.. autoclass:: ForceReply()
+.. autoclass:: CallbackQuery()
+.. autoclass:: GameHighScore()
+.. autoclass:: GameHighScores()
+.. autoclass:: CallbackGame()
+
+..  Input Media
+    -----------
+
+.. autoclass:: InputMedia()
+.. autoclass:: InputMediaPhoto()
+.. autoclass:: InputMediaVideo()
+.. autoclass:: InputMediaAudio()
+.. autoclass:: InputMediaAnimation()
+.. autoclass:: InputMediaDocument()
+.. autoclass:: InputPhoneContact()
+
+..  Inline Mode
+    -----------
+
+.. autoclass:: InlineQuery()
+.. autoclass:: InlineQueryResult()
+.. autoclass:: InlineQueryResultArticle()
+
+..  InputMessageContent
+    -------------------
+
+.. autoclass:: InputMessageContent()
+.. autoclass:: InputTextMessageContent()

docs/source/conf.py

@@ -1,198 +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"
 ]
 
-# Don't show source files on docs
+master_doc = "index"
-html_show_sourcelink = True
+source_suffix = ".rst"
+autodoc_member_order = "bysource"
 
-# Order by source, not alphabetically
+version = __version__
-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
+version_rst = ".. |version| replace:: {}".format(version)
 
-# The language for content autogenerated by Sphinx. Refer to documentation
+templates_path = ["_templates"]
-# 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
+napoleon_use_rtype = False
-# 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"
-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.ml/",
+    "canonical_url": "https://docs.pyrogram.org/",
-    'collapse_navigation': False,
+    "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/errors/BadRequest.rst

@@ -1,7 +0,0 @@
-400 - Bad Request
-=================
-
-.. module:: pyrogram.errors.BadRequest
-
-.. automodule:: pyrogram.errors.exceptions.bad_request_400
-    :members:

docs/source/errors/Flood.rst

@@ -1,7 +0,0 @@
-420 - Flood
-===========
-
-.. module:: pyrogram.errors.Flood
-
-.. automodule:: pyrogram.errors.exceptions.flood_420
-    :members:

docs/source/errors/Forbidden.rst

@@ -1,7 +0,0 @@
-403 - Forbidden
-===============
-
-.. module:: pyrogram.errors.Forbidden
-
-.. automodule:: pyrogram.errors.exceptions.forbidden_403
-    :members:

docs/source/errors/InternalServerError.rst

@@ -1,7 +0,0 @@
-500 - Internal Server Error
-===========================
-
-.. module:: pyrogram.errors.InternalServerError
-
-.. automodule:: pyrogram.errors.exceptions.internal_server_error_500
-    :members:

docs/source/errors/NotAcceptable.rst

@@ -1,7 +0,0 @@
-406 - Not Acceptable
-====================
-
-.. module:: pyrogram.errors.NotAcceptable
-
-.. automodule:: pyrogram.errors.exceptions.not_acceptable_406
-    :members:

docs/source/errors/SeeOther.rst

@@ -1,7 +0,0 @@
-303 - See Other
-===============
-
-.. module:: pyrogram.errors.SeeOther
-
-.. automodule:: pyrogram.errors.exceptions.see_other_303
-    :members:

docs/source/errors/Unauthorized.rst

@@ -1,7 +0,0 @@
-401 - Unauthorized
-==================
-
-.. module:: pyrogram.errors.Unauthorized
-
-.. automodule:: pyrogram.errors.exceptions.unauthorized_401
-    :members:

docs/source/errors/UnknownError.rst

@@ -1,7 +0,0 @@
-520 - Unknown Error
-===================
-
-.. module:: pyrogram.errors.UnknownError
-
-.. autoexception:: pyrogram.errors.rpc_error.UnknownError
-    :members:

docs/source/faq.rst

@@ -0,0 +1,201 @@
+Pyrogram FAQ
+============
+
+This FAQ page provides answers to common questions about Pyrogram and, to some extent, Telegram in general.
+
+.. tip::
+
+    If you think something interesting could be added here, feel free to propose it by opening a `Feature Request`_.
+
+.. contents:: Contents
+    :backlinks: none
+    :local:
+    :depth: 1
+
+What is Pyrogram?
+-----------------
+
+**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and
+C. It enables you to easily create custom applications for both user and bot identities (bot API alternative) via the
+`MTProto API`_ with the Python programming language.
+
+.. _Telegram: https://telegram.org
+.. _MTProto API: topics/mtproto-vs-botapi#what-is-the-mtproto-api
+
+Where does the name come from?
+------------------------------
+
+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 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`_.
+
+.. _GitHub: https://github.com/pyrogram/pyrogram
+
+Why Pyrogram?
+-------------
+
+- **Easy**: You can install Pyrogram with pip and start building your applications right away.
+- **Elegant**: Low-level details are abstracted and re-presented in a much nicer and easier way.
+- **Fast**: Crypto parts are boosted up by TgCrypto_, a high-performance library written in pure C.
+- **Documented**: Pyrogram API methods, types and public interfaces are well documented.
+- **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted.
+- **Updated**, to make use of the latest Telegram API version and features.
+- **Bot API-like**: Similar to the Bot API in its simplicity, but much more powerful and detailed.
+- **Pluggable**: The `Smart Plugin`_ system allows to write components with minimal boilerplate code.
+- **Comprehensive**: Execute any `advanced action`_ an official client is able to do, and even more.
+
+.. _TgCrypto: https://github.com/pyrogram/tgcrypto
+.. _Smart Plugin: topics/smart-plugins
+.. _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
+
+Why do I need an API key for bots?
+----------------------------------
+
+Requests against the official bot API endpoint are made via JSON/HTTP, but are handled by an intermediate server
+application that implements the MTProto protocol -- just like Pyrogram -- and uses its own API key, which is always
+required, but hidden to the public.
+
+.. figure:: https://i.imgur.com/C108qkX.png
+    :align: center
+
+Using MTProto is the only way to communicate with the actual Telegram servers, and the main API requires developers to
+identify applications by means of a unique key; the bot token identifies a bot as a user and replaces the user's phone
+number only.
+
+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!
+---------------------------------------
+
+If you are connecting from Russia, China or Iran `you need a proxy`_, because Telegram could be partially or
+totally blocked in those countries.
+
+Another possible cause might be network issues, either yours or Telegram's. To confirm this, add the following code on
+the top of your script and run it again. You should see some error mentioning a socket timeout or an unreachable network
+in a bunch of seconds:
+
+.. code-block:: python
+
+    import logging
+    logging.basicConfig(level=logging.INFO)
+
+Another way to confirm you aren't able to connect to Telegram is by pinging these IP addresses and see whether ping
+fails or not:
+
+- DC1: ``149.154.175.50``
+- DC2: ``149.154.167.51``
+- DC3: ``149.154.175.100``
+- DC4: ``149.154.167.91``
+- DC5: ``91.108.56.149``
+
+.. _you need a proxy: topics/proxy
+
+I keep getting PEER_ID_INVALID error!
+-------------------------------------------
+
+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)``.
+
+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 review reports.
+
+.. 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 a list of what Telegram definitely doesn't like:
+
+- Flood, abusing the API.
+- Spam, sending unsolicited messages or adding people to unwanted groups and channels.
+- Virtual/VoIP and cheap real numbers, because they are relatively easy to get and likely used for spam/flood.
+
+However, you might be right, and your account was deactivated/limited without any reason. This could happen because of
+mistakes by either the automatic systems or a moderator. In such cases you can kindly email Telegram at
+recover@telegram.org, contact `@smstelegram`_ on Twitter or use `this form`_.
+
+.. _@smstelegram: https://twitter.com/smstelegram
+.. _this form: https://telegram.org/support
+
+About the License
+-----------------
+
+.. image:: https://www.gnu.org/graphics/lgplv3-with-text-154x68.png
+    :align: left
+
+Pyrogram is free software and is currently licensed under the terms of the
+`GNU Lesser General Public License v3 or later (LGPLv3+)`_. In short: you may use, redistribute and/or modify it
+provided that modifications are described and licensed for free under LGPLv3+.
+
+In other words: you can use and integrate Pyrogram into your own code --- either open source, under the same or
+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
+.. _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

docs/source/glossary.rst

@@ -0,0 +1,75 @@
+Pyrogram Glossary
+=================
+
+This page contains a list of common words with brief explanations related to Pyrogram and, to some extent, Telegram in
+general. Some words may as well link to dedicated articles in case the topic is covered in a more detailed fashion.
+
+.. tip::
+
+    If you think something interesting could be added here, feel free to propose it by opening a `Feature Request`_.
+
+
+.. glossary::
+
+    API
+        Application Programming Interface: a set of methods, protocols and tools that make it easier to develop programs
+        by providing useful building blocks to the developer.
+
+    API key
+        A secret code used to authenticate and/or authorize a specific application to Telegram in order for it to
+        control how the API is being used, for example, to prevent abuses of the API.
+        `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
+        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 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>`_.
+
+    MTProto
+        The name of the custom-made, open and encrypted protocol by Telegram, implemented in Pyrogram.
+        `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 <topics/mtproto-vs-botapi#what-is-the-mtproto-api>`_.
+
+    Bot API
+        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 sub-set of the main Telegram API.
+        `More on Bot API <topics/mtproto-vs-botapi#what-is-the-bot-api>`_.
+
+    Pyrogrammer
+        A developer that uses Pyrogram to build Telegram applications.
+
+    Userbot
+        Also known as *user bot* or *ubot* for short, is a user logged in by third-party Telegram libraries --- such as
+        Pyrogram --- to automate some behaviours, like sending messages or reacting to text commands or any other event.
+
+    Session
+        Also known as *login session*, is a strictly personal piece of information created and held by both parties
+        (client and server) which is used to grant permission into a single account without having to start a new
+        authorization process from scratch.
+
+    Callback
+        Also known as *callback function*, is a user-defined generic function that *can be* registered to and then
+        called-back by the framework when specific events occurs.
+
+    Handler
+        An object that wraps around a callback function that is *actually meant* to be registered into the framework,
+        which will then be able to handle a specific kind of events, such as a new incoming message, for example.
+        `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>`_.
+
+.. _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.ml">
+        <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>
 
@@ -13,26 +13,17 @@ Welcome to Pyrogram
         <b>Telegram MTProto API Framework for Python</b>
 
         <br>
-        <a href="https://docs.pyrogram.ml">
+        <a href="https://github.com/pyrogram/pyrogram">
-            Documentation
+            Source Code
         </a>
         •
         <a href="https://github.com/pyrogram/pyrogram/releases">
-            Changelog
+            Releases
         </a>
         •
-        <a href="https://t.me/PyrogramChat">
+        <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>
 
 .. code-block:: python
@@ -49,73 +40,133 @@ Welcome to Pyrogram
 
     app.run()
 
-Welcome to Pyrogram's Documentation! Here you can find resources for learning how to use the framework.
+**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and
-Contents are organized into self-contained topics and can be accessed from the sidebar, or by following them in order
+C. It enables you to easily create custom apps for both user and bot identities (bot API alternative) via the
-using the Next button at the end of each page. But first, here's a brief overview of what is this all about.
+`MTProto API`_.
 
-About
+.. _Telegram: https://telegram.org
------
+.. _MTProto API: topics/mtproto-vs-botapi#what-is-the-mtproto-api
 
-**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and C.
+How the Documentation is Organized
-It enables you to easily create custom apps using both user and bot identities (bot API alternative) via the `MTProto API`_.
+----------------------------------
 
-Features
+Contents are organized into self-contained topics and can be all accessed from the sidebar, or by following them in
---------
+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.
 
--   **Easy**: You can install Pyrogram with pip and start building your applications right away.
+First Steps
--   **Elegant**: Low-level details are abstracted and re-presented in a much nicer and easier way.
+-----------
--   **Fast**: Crypto parts are boosted up by TgCrypto_, a high-performance library written in pure C.
--   **Documented**: Pyrogram API methods, types and public interfaces are well documented.
--   **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted.
--   **Updated**, to the latest Telegram API version, currently Layer 97 on top of `MTProto 2.0`_.
--   **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.
 
-To get started, press the Next button.
+.. hlist::
+    :columns: 2
+
+    - `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
+.. _Handling Updates: start/updates
+.. _Error Handling: start/errors
+
+API Reference
+-------------
+
+.. hlist::
+    :columns: 2
+
+    - `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
+----
+
+.. hlist::
+    :columns: 2
+
+    - `Pyrogram FAQ`_: Answers to common Pyrogram questions.
+    - `Pyrogram Glossary`_: List of words with brief explanations.
+    - `Release Notes`_: Release notes for Pyrogram releases.
+    - `Powered by Pyrogram`_: Collection of Pyrogram Projects.
+    - `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:
-    :caption: Quick Start
+    :caption: Introduction
 
-    start/Installation
+    intro/quickstart
-    start/Setup
+    intro/install
-    start/Usage
+    intro/setup
 
 .. toctree::
     :hidden:
-    :caption: Resources
+    :caption: Getting Started
 
-    resources/UpdateHandling
+    start/auth
-    resources/UsingFilters
+    start/invoking
-    resources/MoreOnUpdates
+    start/updates
-    resources/ConfigurationFile
+    start/errors
-    resources/SmartPlugins
-    resources/AutoAuthorization
-    resources/CustomizeSessions
-    resources/TgCrypto
-    resources/TextFormatting
-    resources/SOCKS5Proxy
-    resources/BotsInteraction
-    resources/ErrorHandling
-    resources/TestServers
-    resources/AdvancedUsage
-    resources/VoiceCalls
-    resources/Changelog
 
 .. toctree::
     :hidden:
-    :caption: Main Package
+    :caption: API Reference
 
-    pyrogram/index
+    api/client
+    api/methods
+    api/types
+    api/bound-methods
+    api/handlers
+    api/decorators
+    api/filters
+    api/errors
+
+.. toctree::
+    :hidden:
+    :caption: Topic Guides
+
+    topics/filters
+    topics/more-on-updates
+    topics/config-file
+    topics/smart-plugins
+    topics/auto-auth
+    topics/session-settings
+    topics/tgcrypto
+    topics/text-formatting
+    topics/serialize
+    topics/proxy
+    topics/bots-interaction
+    topics/mtproto-vs-botapi
+    topics/test-servers
+    topics/advanced-usage
+    topics/voice-calls
+
+.. toctree::
+    :hidden:
+    :caption: Meta
+
+    faq
+    glossary
+    releases
+    powered-by
+    support-pyrogram
 
 .. toctree::
     :hidden:
     :caption: Telegram API
 
-    functions/index
+    telegram/functions/index
-    types/index
+    telegram/types/index
-
-.. _`Telegram`: https://telegram.org
-.. _TgCrypto: https://docs.pyrogram.ml/resources/TgCrypto
-.. _`MTProto API`: https://core.telegram.org/api#telegram-api
-.. _`MTProto 2.0`: https://core.telegram.org/mtproto

docs/source/intro/install.rst

@@ -1,8 +1,8 @@
-Installation
+Install Guide
-============
+=============
 
 Being a Python library, **Pyrogram** requires Python to be installed in your system.
-We recommend using the latest version of Python 3 and pip.
+We recommend using the latest versions of both Python 3 and pip.
 
 - Get **Python 3** from https://www.python.org/downloads/ (or with your package manager)
 - Get **pip** by following the instructions at https://pip.pypa.io/en/latest/installing/.
@@ -29,12 +29,12 @@ Install Pyrogram
 Bleeding Edge
 -------------
 
-Things are constantly evolving in Pyrogram, although new releases are published only when enough changes are added,
+Pyrogram is always evolving, although new releases on PyPI are published only when enough changes are added, but this
-but this doesn't mean you can't try new features right now!
+doesn't mean you can't try new features right now!
 
-In case you would like to try out the latest Pyrogram features and additions, the `GitHub repo`_ is always kept updated
+In case you'd like to try out the latest Pyrogram features, the `GitHub repo`_ is always kept updated with new changes;
-with new changes; you can install the development version straight from the ``develop`` branch using this command
+you can install the development version straight from the ``develop`` branch using this command (note "develop.zip" in
-(note "develop.zip" in the link):
+the link):
 
 .. code-block:: text
 
@@ -44,7 +44,8 @@ Asynchronous
 ------------
 
 Pyrogram heavily depends on IO-bound network code (it's a cloud-based messaging framework after all), and here's
-where asyncio shines the most by providing extra performance while running on a single OS-level thread only.
+where asyncio shines the most by providing extra performance and efficiency while running on a single OS-level thread
+only.
 
 **A fully asynchronous variant of Pyrogram is therefore available** (Python 3.5.3+ required).
 Use this command to install (note "asyncio.zip" in the link):
@@ -54,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.
 
 
@@ -82,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.12.0'
+    '|version|'
 
-.. _TgCrypto: https://docs.pyrogram.ml/resources/TgCrypto
+.. _TgCrypto: ../topics/tgcrypto
 .. _`Github repo`: http://github.com/pyrogram/pyrogram

docs/source/intro/quickstart.rst

@@ -0,0 +1,49 @@
+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.
+Let's go!
+
+Get Pyrogram Real Fast
+----------------------
+
+1. Install Pyrogram with ``pip3 install -U pyrogram``.
+
+2. Get your own Telegram API key from https://my.telegram.org/apps.
+
+3.  Open your best text editor and paste the following:
+
+    .. code-block:: python
+
+        from pyrogram import Client
+
+        api_id = 12345
+        api_hash = "0123456789abcdef0123456789abcdef"
+
+        with Client("my_account", api_id, api_hash) as app:
+            app.send_message("me", "Greetings from **Pyrogram**!")
+
+4. Replace *api_id* and *api_hash* values with your own.
+
+5. Save the file as ``pyro.py``.
+
+6. Run the script with ``python3 pyro.py``
+
+7. Follow the instructions on your terminal to login.
+
+8. Watch Pyrogram send a message to yourself.
+
+9. Join our `community`_.
+
+10. Say, "hi!".
+
+Enjoy the API
+-------------
+
+That was just a quick overview that barely scratched the surface!
+In the next few pages of the introduction, we'll take a much more in-depth look of what we have just done above.
+
+Feeling eager to continue? You can take a shortcut to `Calling Methods`_ and come back later to learn some more details.
+
+.. _community: //t.me/Pyrogram
+.. _Calling Methods: ../start/invoking

docs/source/intro/setup.rst

@@ -0,0 +1,61 @@
+Project Setup
+=============
+
+We have just `installed Pyrogram`_. In this page we'll discuss what you need to do in order to set up a project with
+the library. Let's see how it's done.
+
+API Keys
+--------
+
+The very first step requires you to obtain a valid Telegram API key (API id/hash pair):
+
+#. Visit https://my.telegram.org/apps and log in with your Telegram Account.
+#. Fill out the form to register a new Telegram application.
+#. Done! The API key consists of two parts: **api_id** and **api_hash**.
+
+.. important::
+
+     The API key is personal and must be kept secret.
+
+.. note::
+
+    The API key is unique for each user, but defines a token for a Telegram *application* you are going to build. This
+    means that you are able to authorize multiple users (and bots too) to access the Telegram database through the
+    MTProto API by a single API key.
+
+Configuration
+-------------
+
+Having the API key from the `previous step <#api-keys>`_  in handy, we can now begin to configure a Pyrogram project.
+There are two ways to do so, and you can choose what fits better for you:
+
+-   First option (recommended): create a new ``config.ini`` file at the root of your working directory, copy-paste the
+    following and replace the **api_id** and **api_hash** values with your own. This is the preferred method because
+    allows you to keep your credentials out of your code without having to deal with how to load them:
+
+    .. code-block:: ini
+
+        [pyrogram]
+        api_id = 12345
+        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
+    credentials from the environment variables and directly pass the values into Pyrogram):
+
+    .. code-block:: python
+
+        from pyrogram import Client
+
+        app = Client(
+            "my_account",
+            api_id=12345,
+            api_hash="0123456789abcdef0123456789abcdef"
+        )
+
+.. note::
+
+    To keep code snippets clean and concise, from now on it is assumed you are making use of the ``config.ini`` file,
+    thus, the *api_id* and *api_hash* parameters usage won't be shown anymore.
+
+.. _installed Pyrogram: install.html

docs/source/powered-by.rst

@@ -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/botlist>`_
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+| **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
+

docs/source/pyrogram/ChatAction.rst

@@ -1,5 +0,0 @@
-ChatAction
-==========
-
-.. autoclass:: pyrogram.ChatAction
-    :members:

docs/source/pyrogram/Client.rst

@@ -1,162 +0,0 @@
-Client
-======
-
-.. currentmodule:: pyrogram.Client
-
-.. autoclass:: pyrogram.Client
-
-Utilities
----------
-
-.. autosummary::
-    :nosignatures:
-
-    start
-    stop
-    restart
-    idle
-    run
-    add_handler
-    remove_handler
-    send
-    resolve_peer
-    save_file
-    stop_transmission
-
-Decorators
-----------
-
-.. autosummary::
-    :nosignatures:
-
-    on_message
-    on_callback_query
-    on_inline_query
-    on_deleted_messages
-    on_user_status
-    on_disconnect
-    on_raw_update
-
-Messages
---------
-
-.. autosummary::
-    :nosignatures:
-
-    send_message
-    forward_messages
-    send_photo
-    send_audio
-    send_document
-    send_sticker
-    send_video
-    send_animation
-    send_voice
-    send_video_note
-    send_media_group
-    send_location
-    send_venue
-    send_contact
-    send_cached_media
-    send_chat_action
-    edit_message_text
-    edit_message_caption
-    edit_message_reply_markup
-    edit_message_media
-    delete_messages
-    get_messages
-    get_history
-    get_history_count
-    iter_history
-    send_poll
-    vote_poll
-    stop_poll
-    retract_vote
-    download_media
-
-Chats
------
-
-.. autosummary::
-    :nosignatures:
-
-    join_chat
-    leave_chat
-    kick_chat_member
-    unban_chat_member
-    restrict_chat_member
-    promote_chat_member
-    export_chat_invite_link
-    set_chat_photo
-    delete_chat_photo
-    set_chat_title
-    set_chat_description
-    pin_chat_message
-    unpin_chat_message
-    get_chat
-    get_chat_preview
-    get_chat_member
-    get_chat_members
-    get_chat_members_count
-    iter_chat_members
-    get_dialogs
-    iter_dialogs
-    get_dialogs_count
-    restrict_chat
-    update_chat_username
-
-Users
------
-
-.. autosummary::
-    :nosignatures:
-
-    get_me
-    get_users
-    get_user_profile_photos
-    get_user_profile_photos_count
-    set_user_profile_photo
-    delete_user_profile_photos
-    update_username
-
-Contacts
---------
-
-.. autosummary::
-    :nosignatures:
-
-    add_contacts
-    get_contacts
-    get_contacts_count
-    delete_contacts
-
-Password
---------
-
-.. autosummary::
-    :nosignatures:
-
-    enable_cloud_password
-    change_cloud_password
-    remove_cloud_password
-
-Bots
-----
-
-.. autosummary::
-    :nosignatures:
-
-    get_inline_bot_results
-    send_inline_bot_result
-    answer_callback_query
-    answer_inline_query
-    request_callback_answer
-    send_game
-    set_game_score
-    get_game_high_scores
-    answer_inline_query
-
-
-.. autoclass:: pyrogram.Client
-    :inherited-members:
-    :members:

docs/source/pyrogram/Handlers.rst

@@ -1,37 +0,0 @@
-Handlers
-========
-
-.. currentmodule:: pyrogram
-
-.. autosummary::
-    :nosignatures:
-
-    MessageHandler
-    DeletedMessagesHandler
-    CallbackQueryHandler
-    InlineQueryHandler
-    UserStatusHandler
-    DisconnectHandler
-    RawUpdateHandler
-
-.. autoclass:: MessageHandler
-    :members:
-
-.. autoclass:: DeletedMessagesHandler
-    :members:
-
-.. autoclass:: CallbackQueryHandler
-    :members:
-
-.. autoclass:: InlineQueryHandler
-    :members:
-
-.. autoclass:: UserStatusHandler
-    :members:
-
-.. autoclass:: DisconnectHandler
-    :members:
-
-.. autoclass:: RawUpdateHandler
-    :members:
-

docs/source/pyrogram/ParseMode.rst

@@ -1,6 +0,0 @@
-ParseMode
-=========
-
-.. autoclass:: pyrogram.ParseMode
-    :members:
-    :undoc-members:

docs/source/pyrogram/RPCError.rst

@@ -1,15 +0,0 @@
-RPCError
-========
-
-.. autoexception:: pyrogram.RPCError
-    :members:
-
-.. toctree::
-    ../errors/SeeOther
-    ../errors/BadRequest
-    ../errors/Unauthorized
-    ../errors/Forbidden
-    ../errors/NotAcceptable
-    ../errors/Flood
-    ../errors/InternalServerError
-    ../errors/UnknownError

docs/source/pyrogram/Types.rst

@@ -1,263 +0,0 @@
-Types
-=====
-
-.. currentmodule:: pyrogram
-
-Users & Chats
--------------
-
-.. autosummary::
-    :nosignatures:
-
-    User
-    UserStatus
-    Chat
-    ChatPreview
-    ChatPhoto
-    ChatMember
-    ChatMembers
-    ChatPermissions
-    Dialog
-    Dialogs
-
-Messages & Media
-----------------
-
-.. autosummary::
-    :nosignatures:
-
-    Message
-    Messages
-    MessageEntity
-    Photo
-    PhotoSize
-    UserProfilePhotos
-    Audio
-    Document
-    Animation
-    Video
-    Voice
-    VideoNote
-    Contact
-    Location
-    Venue
-    Sticker
-    Poll
-    PollOption
-
-Bots
-----
-
-.. autosummary::
-    :nosignatures:
-
-    ReplyKeyboardMarkup
-    KeyboardButton
-    ReplyKeyboardRemove
-    InlineKeyboardMarkup
-    InlineKeyboardButton
-    ForceReply
-    CallbackQuery
-    Game
-
-Input Media
------------
-
-.. autosummary::
-    :nosignatures:
-
-    InputMedia
-    InputMediaPhoto
-    InputMediaVideo
-    InputMediaAudio
-    InputMediaAnimation
-    InputMediaDocument
-    InputPhoneContact
-
-Inline Mode
-------------
-
-.. autosummary::
-    :nosignatures:
-
-    InlineQuery
-    InlineQueryResult
-    InlineQueryResultArticle
-
-InputMessageContent
--------------------
-
-.. autosummary::
-    :nosignatures:
-
-    InputMessageContent
-    InputTextMessageContent
-
-..  User & Chats
-    ------------
-
-.. autoclass:: User
-    :members:
-
-.. autoclass:: UserStatus
-    :members:
-
-.. autoclass:: Chat
-    :members:
-
-.. autoclass:: ChatPreview
-    :members:
-
-.. autoclass:: ChatPhoto
-    :members:
-
-.. autoclass:: ChatMember
-    :members:
-
-.. autoclass:: ChatMembers
-    :members:
-
-.. autoclass:: ChatPermissions
-    :members:
-
-.. autoclass:: Dialog
-    :members:
-
-.. autoclass:: Dialogs
-    :members:
-
-..  Messages & Media
-    ----------------
-
-.. autoclass:: Message
-    :members:
-
-.. autoclass:: Messages
-    :members:
-
-.. autoclass:: MessageEntity
-    :members:
-
-.. autoclass:: Photo
-    :members:
-
-.. autoclass:: PhotoSize
-    :members:
-
-.. autoclass:: UserProfilePhotos
-    :members:
-
-.. autoclass:: Audio
-    :members:
-
-.. autoclass:: Document
-    :members:
-
-.. autoclass:: Animation
-    :members:
-
-.. autoclass:: Video
-    :members:
-
-.. autoclass:: Voice
-    :members:
-
-.. autoclass:: VideoNote
-    :members:
-
-.. autoclass:: Contact
-    :members:
-
-.. autoclass:: Location
-    :members:
-
-.. autoclass:: Venue
-    :members:
-
-.. autoclass:: Sticker
-    :members:
-
-.. autoclass:: Poll
-    :members:
-
-.. autoclass:: PollOption
-    :members:
-
-..  Bots
-    ----
-
-.. autoclass:: ReplyKeyboardMarkup
-    :members:
-
-.. autoclass:: KeyboardButton
-    :members:
-
-.. autoclass:: ReplyKeyboardRemove
-    :members:
-
-.. autoclass:: InlineKeyboardMarkup
-    :members:
-
-.. autoclass:: InlineKeyboardButton
-    :members:
-
-.. autoclass:: ForceReply
-    :members:
-
-.. autoclass:: CallbackQuery
-    :members:
-
-.. autoclass:: Game
-    :members:
-
-.. autoclass:: GameHighScore
-    :members:
-
-.. autoclass:: GameHighScores
-    :members:
-
-..  Input Media
-    -----------
-
-.. autoclass:: InputMedia
-    :members:
-
-.. autoclass:: InputMediaPhoto
-    :members:
-
-.. autoclass:: InputMediaVideo
-    :members:
-
-.. autoclass:: InputMediaAudio
-    :members:
-
-.. autoclass:: InputMediaAnimation
-    :members:
-
-.. autoclass:: InputMediaDocument
-    :members:
-
-.. autoclass:: InputPhoneContact
-    :members:
-
-
-..  Inline Mode
-    -----------
-
-.. autoclass:: InlineQuery
-    :members:
-
-.. autoclass:: InlineQueryResult
-    :members:
-
-.. autoclass:: InlineQueryResultArticle
-    :members:
-
-..  InputMessageContent
-    -------------------
-
-.. autoclass:: InputMessageContent
-    :members:
-
-.. autoclass:: InputTextMessageContent
-    :members:

docs/source/pyrogram/index.rst

@@ -1,20 +0,0 @@
-Pyrogram
-========
-
-In this section you can find a detailed description of the Pyrogram package and its API.
-
-:class:`Client <pyrogram.Client>` is the main class. It exposes easy-to-use methods that are named
-after the well established `Telegram Bot API`_ methods, thus offering a familiar look to Bot developers.
-
-.. toctree::
-    :maxdepth: 1
-
-    Client
-    Types
-    Handlers
-    Filters
-    ChatAction
-    ParseMode
-    RPCError
-
-.. _Telegram Bot API: https://core.telegram.org/bots/api#available-methods

docs/source/releases.rst

@@ -0,0 +1,13 @@
+Release Notes
+=============
+
+Release notes for Pyrogram releases will describe what's new in each version, and will also make you aware of any
+backwards-incompatible changes made in that version.
+
+When upgrading to a new version of Pyrogram, you will need to check all the breaking changes in order to find
+incompatible code in your application, but also to take advantage of new features and improvements.
+
+.. note::
+
+    Currently, all Pyrogram release notes live inside the GitHub repository web page:
+    https://github.com/pyrogram/pyrogram/releases.

docs/source/resources/Changelog.rst

@@ -1,11 +0,0 @@
-Changelog
-=========
-
-Currently, all Pyrogram release notes live inside the GitHub repository web page:
-https://github.com/pyrogram/pyrogram/releases
-
-(You will be automatically redirected in 10 seconds.)
-
-.. raw:: html
-
-    <meta http-equiv="refresh" content="10; URL=https://github.com/pyrogram/pyrogram/releases"/>

docs/source/resources/ErrorHandling.rst

@@ -1,59 +0,0 @@
-Error Handling
-==============
-
-Errors are inevitable when working with the API, and they must be correctly handled with ``try..except`` blocks.
-
-There are many errors that Telegram could return, but they all fall in one of these categories
-(which are in turn children of the :obj:`RPCError <pyrogram.RPCError>` superclass):
-
--   :obj:`303 - See Other <pyrogram.errors.SeeOther>`
--   :obj:`400 - Bad Request <pyrogram.errors.BadRequest>`
--   :obj:`401 - Unauthorized <pyrogram.errors.Unauthorized>`
--   :obj:`403 - Forbidden <pyrogram.errors.Forbidden>`
--   :obj:`406 - Not Acceptable <pyrogram.errors.NotAcceptable>`
--   :obj:`420 - Flood <pyrogram.errors.Flood>`
--   :obj:`500 - Internal Server Error <pyrogram.errors.InternalServerError>`
-
-As stated above, there are really many (too many) errors, and in case Pyrogram does not know anything yet about a
-specific one, it raises a special :obj:`520 Unknown Error <pyrogram.errors.UnknownError>` exception and logs it
-in the ``unknown_errors.txt`` file. Users are invited to report these unknown errors; in later versions of Pyrogram
-some kind of automatic error reporting module might be implemented.
-
-Examples
---------
-
-.. code-block:: python
-
-    from pyrogram.errors import (
-        BadRequest, Flood, InternalServerError,
-        SeeOther, Unauthorized, UnknownError
-    )
-
-    try:
-        ...
-    except BadRequest:
-        pass
-    except Flood:
-        pass
-    except InternalServerError:
-        pass
-    except SeeOther:
-        pass
-    except Unauthorized:
-        pass
-    except UnknownError:
-        pass
-
-Exception objects may also contain some informative values.
-E.g.: :obj:`FloodWait <pyrogram.errors.exceptions.flood_420.FloodWait>` holds the amount of seconds you have to wait
-before you can try again. The value is always stored in the ``x`` field of the returned exception object:
-
-.. code-block:: python
-
-    import time
-    from pyrogram.errors import FloodWait
-
-    try:
-        ...
-    except FloodWait as e:
-        time.sleep(e.x)

docs/source/resources/UpdateHandling.rst

@@ -1,72 +0,0 @@
-Update Handling
-===============
-
-Let's now dive right into the core of the framework.
-
-Updates are events that happen in your Telegram account (incoming messages, new channel posts, new members join, ...)
-and are handled by registering one or more callback functions in your app using `Handlers <../pyrogram/Handlers.html>`_.
-
-Each handler deals with a specific event and once a matching update arrives from Telegram, your registered callback
-function will be called.
-
-Registering an Handler
-----------------------
-
-To explain how handlers work let's have a look at the most used one, the
-:obj:`MessageHandler <pyrogram.MessageHandler>`, which will be in charge for handling :obj:`Message <pyrogram.Message>`
-updates coming from all around your chats. Every other handler shares the same setup logic; you should not have troubles
-settings them up once you learn from this section.
-
-Using add_handler()
--------------------
-
-The :meth:`add_handler() <pyrogram.Client.add_handler>` method takes any handler instance that wraps around your defined
-callback function and registers it in your Client. Here's a full example that prints out the content of a message as
-soon as it arrives:
-
-.. code-block:: python
-
-    from pyrogram import Client, MessageHandler
-
-
-    def my_function(client, message):
-        print(message)
-
-
-    app = Client("my_account")
-
-    my_handler = MessageHandler(my_function)
-    app.add_handler(my_handler)
-
-    app.run()
-
-Using Decorators
-----------------
-
-A much nicer way to register a MessageHandler is by decorating your callback function with the
-:meth:`on_message() <pyrogram.Client.on_message>` decorator, which will still make use of add_handler() under the hood.
-
-.. code-block:: python
-
-    from pyrogram import Client
-
-    app = Client("my_account")
-
-
-    @app.on_message()
-    def my_handler(client, message):
-        print(message)
-
-
-    app.run()
-
-
-.. note::
-
-    Due to how these decorators work in Pyrogram, they will wrap your defined callback function in a tuple consisting of
-    ``(handler, group)``; this will be the value held by your function identifier (e.g.: *my_function* from the example
-    above).
-
-    In case, for some reason, you want to get your own function back after it has been decorated, you need to access
-    ``my_function[0].callback``, that is, the *callback* field of the *handler* object which is the first element in the
-    tuple.

docs/source/start/Setup.rst

@@ -1,120 +0,0 @@
-Setup
-=====
-
-Once you successfully `installed Pyrogram`_, you will still have to follow a few steps before you can actually use
-the library to make API calls. This section provides all the information you need in order to set up a project
-with Pyrogram.
-
-API Keys
---------
-
-The very first step requires you to obtain a valid Telegram API key (API id/hash pair).
-If you already have one you can skip this step, otherwise:
-
-#. Visit https://my.telegram.org/apps and log in with your Telegram Account.
-#. Fill out the form to register a new Telegram application.
-#. Done. The API key consists of two parts: **App api_id** and **App api_hash**.
-
-.. important::
-
-     This API key is personal and must be kept secret.
-
-Configuration
--------------
-
-The API key obtained in the `previous step <#api-keys>`_ defines a token for your application allowing you to access
-the Telegram database using the MTProto API — **it is therefore required for all authorizations of both users and bots**.
-
-Having it handy, it's time to configure your Pyrogram project. There are two ways to do so, and you can choose what
-fits better for you:
-
--   Create a new ``config.ini`` file at the root of your working directory, copy-paste the following and replace the
-    **api_id** and **api_hash** values with your own. This is the preferred method because allows you to keep your
-    credentials out of your code without having to deal with how to load them:
-
-    .. code-block:: ini
-
-        [pyrogram]
-        api_id = 12345
-        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:
-
-    .. code-block:: python
-
-        from pyrogram import Client
-
-        app = Client(
-            "my_account",
-            api_id=12345,
-            api_hash="0123456789abcdef0123456789abcdef"
-        )
-
-.. note::
-
-    From now on, the code snippets assume you are using the ``config.ini`` file, thus they won't show the *api_id* and
-    *api_hash* parameters usage to keep them as clean as possible.
-
-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
-: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:
-
-.. code-block:: python
-
-    from pyrogram import Client
-
-    app = Client("my_account")
-    app.run()
-
-This starts an interactive shell asking you to input your **phone number** (including your `Country Code`_)
-and the **phone code** you will receive:
-
-.. code-block:: text
-
-    Enter phone number: +39**********
-    Is "+39**********" correct? (y/n): y
-    Enter phone code: 32768
-    Logged in successfully as Dan
-
-After successfully authorizing yourself, a new file called ``my_account.session`` will be created allowing Pyrogram
-executing API calls with your identity. This file will be loaded again when you restart your app, and as long as you
-keep the session alive, Pyrogram won't ask you again to enter your phone number.
-
-.. important::
-
-    Your ``*.session`` files are personal and must be kept secret.
-
-.. note::
-
-    The code above does nothing except asking for credentials and keeping the client online, hit ``CTRL+C`` now to stop
-    your application and keep reading.
-
-Bot Authorization
------------------
-
-Bots are a special kind of users that are authorized via their tokens (instead of phone numbers), which are created by
-BotFather_. Bot tokens replace the users' phone numbers only — you still need to
-`configure a Telegram API key <#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
-after the session name, which will be ``pyrogrambot.session`` for the example below.
-
-.. code-block:: python
-
-    from pyrogram import Client
-
-    app = Client(
-        "pyrogrambot",
-        bot_token="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
-    )
-    app.run()
-
-.. _installed Pyrogram: Installation.html
-.. _`Country Code`: https://en.wikipedia.org/wiki/List_of_country_calling_codes
-.. _BotFather: https://t.me/botfather

docs/source/start/Usage.rst

@@ -1,51 +0,0 @@
-Usage
-=====
-
-Having your `project set up`_ and your account authorized_, it's time to start playing with the API. Let's start!
-
-High-level API
---------------
-
-The easiest and recommended way to interact with Telegram is via the high-level Pyrogram methods_ and types_, which are
-named after the `Telegram Bot API`_.
-
-Here's a simple example:
-
-.. code-block:: python
-
-    from pyrogram import Client
-
-    app = Client("my_account")
-
-    app.start()
-
-    print(app.get_me())
-    app.send_message("me", "Hi there! I'm using **Pyrogram**")
-    app.send_location("me", 51.500729, -0.124583)
-    app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")
-
-    app.stop()
-
-You can also use Pyrogram in a context manager with the ``with`` statement. The Client will automatically
-:meth:`start <pyrogram.Client.start>` and :meth:`stop <pyrogram.Client.stop>` gracefully, even in case of unhandled
-exceptions in your code:
-
-.. code-block:: python
-
-    from pyrogram import Client
-
-    app = Client("my_account")
-
-    with app:
-        print(app.get_me())
-        app.send_message("me", "Hi there! I'm using **Pyrogram**")
-        app.send_location("me", 51.500729, -0.124583)
-        app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")
-
-More examples on `GitHub <https://github.com/pyrogram/pyrogram/tree/develop/examples>`_.
-
-.. _project set up: Setup.html
-.. _authorized: Setup.html#user-authorization
-.. _Telegram Bot API: https://core.telegram.org/bots/api
-.. _methods: ../pyrogram/Client.html#messages
-.. _types: ../pyrogram/Types.html

docs/source/start/auth.rst

@@ -0,0 +1,69 @@
+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 bot.
+
+User Authorization
+------------------
+
+In order to use the API, Telegram requires that users be authorized via their phone numbers.
+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:
+
+.. code-block:: python
+
+    from pyrogram import Client
+
+    app = Client("my_account")
+    app.run()
+
+This starts an interactive shell asking you to input your **phone number** (including your `Country Code`_) and the
+**phone code** you will receive in your devices that are already authorized or via SMS:
+
+.. code-block:: text
+
+    Enter phone number: +39**********
+    Is "+39**********" correct? (y/n): y
+    Enter phone code: 32768
+    Logged in successfully as Dan
+
+After successfully authorizing yourself, a new file called ``my_account.session`` will be created allowing Pyrogram to
+execute API calls with your identity. This file will be loaded again when you restart your app, and as long as you
+keep the session alive, Pyrogram won't ask you again to enter your phone number.
+
+.. important::
+
+    Your ``*.session`` files are personal and must be kept secret.
+
+.. note::
+
+    The code above does nothing except asking for credentials and keeping the client online, hit ``CTRL+C`` now to stop
+    your application and keep reading.
+
+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 <../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
+after the session name, which will be ``my_bot.session`` for the example below.
+
+.. code-block:: python
+
+    from pyrogram import Client
+
+    app = Client(
+        "my_bot",
+        bot_token="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
+    )
+
+    app.run()
+
+.. _project is set up: ../intro/setup
+.. _Country Code: https://en.wikipedia.org/wiki/List_of_country_calling_codes
+.. _Bot Father: https://t.me/botfather

docs/source/start/errors.rst

@@ -0,0 +1,91 @@
+Error Handling
+==============
+
+Errors are inevitable when working with the API, and they must be correctly handled with ``try..except`` blocks in order
+to control the behaviour of your application. Pyrogram errors all live inside the ``errors`` package:
+
+.. code-block:: python
+
+    from pyrogram import errors
+
+RPCError
+--------
+
+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
+
+    from pyrogram.errors import RPCError
+
+.. warning::
+
+    It must be noted that catching this error is bad practice, especially when no feedback is given (i.e. by
+    logging/printing the full error traceback), because it makes it impossible to understand what went wrong.
+
+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 and subclass-ed from the RPCError:
+
+.. code-block:: python
+
+    from pyrogram.errors import BadRequest, Forbidden, ...
+
+-   `303 - SeeOther <../api/errors#seeother>`_
+-   `400 - BadRequest <../api/errors#badrequest>`_
+-   `401 - Unauthorized  <../api/errors#unauthorized>`_
+-   `403 - Forbidden <../api/errors#forbidden>`_
+-   `406 - NotAcceptable <../api/errors#notacceptable>`_
+-   `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
+--------------
+
+In case Pyrogram does not know anything yet about a specific error, it raises a special ``520 - UnknownError`` exception
+and logs it in the ``unknown_errors.txt`` file. Users are invited to report these unknown errors.
+
+Errors with Values
+------------------
+
+Exception objects may also contain some informative values. For example, ``FloodWait`` holds the amount of seconds you
+have to wait before you can try again. The value is always stored in the ``x`` field of the returned exception object:
+
+.. code-block:: python
+
+    import time
+    from pyrogram.errors import FloodWait
+
+    try:
+        ...
+    except FloodWait as e:
+        time.sleep(e.x)  # Wait before trying again

docs/source/start/invoking.rst

@@ -0,0 +1,84 @@
+Calling Methods
+===============
+
+At this point, we have successfully `installed Pyrogram`_ and authorized_ our account; we are now aiming towards the
+core of the library. It's time to start playing with the API!
+
+Basic Usage
+-----------
+
+Making API method calls with Pyrogram is very simple. Here's an example we are going to examine:
+
+.. code-block:: python
+
+    from pyrogram import Client
+
+    app = Client("my_account")
+
+    app.start()
+
+    print(app.get_me())
+    app.send_message("me", "Hi, it's me!")
+    app.send_location("me", 51.500729, -0.124583)
+    app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")
+
+    app.stop()
+
+Let's begin by importing the Client class from the Pyrogram package:
+
+.. code-block:: python
+
+    from pyrogram import Client
+
+Now instantiate a new Client object, "my_account" is a session name of your choice:
+
+.. code-block:: python
+
+    app = Client("my_account")
+
+To actually make use of any method, the client has to be started first:
+
+.. code-block:: python
+
+    app.start()
+
+Now, you can call any method you like:
+
+.. code-block:: python
+
+    print(app.get_me())  # Print information about yourself
+
+    # Send messages to yourself:
+    app.send_message("me", "Hi!")  # Text message
+    app.send_location("me", 51.500729, -0.124583)  # Location
+    app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")  # Sticker
+
+Finally, when done, simply stop the client:
+
+.. code-block:: python
+
+    app.stop()
+
+Context Manager
+---------------
+
+You can also use Pyrogram's Client in a context manager with the ``with`` statement. The client will automatically
+:meth:`start() <pyrogram.Client.start>` and :meth:`stop() <pyrogram.Client.stop>` gracefully, even in case of unhandled
+exceptions in your code. The example above can be therefore rewritten in a much nicer way:
+
+.. code-block:: python
+
+    from pyrogram import Client
+
+    app = Client("my_account")
+
+    with app:
+        print(app.get_me())
+        app.send_message("me", "Hi there! I'm using **Pyrogram**")
+        app.send_location("me", 51.500729, -0.124583)
+        app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")
+
+More examples can be found on `GitHub <https://github.com/pyrogram/pyrogram/tree/develop/examples>`_.
+
+.. _installed Pyrogram: ../intro/install.html
+.. _authorized: ../intro/setup.html

docs/source/start/updates.rst

@@ -0,0 +1,112 @@
+Handling Updates
+================
+
+Calling `API methods`_ sequentially is cool, but how to react when, for example, a new message arrives? This page deals
+with updates and how to handle such events in Pyrogram. Let's have a look at how they work.
+
+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 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 back by the framework and its body executed.
+
+Registering a Handler
+---------------------
+
+To explain how handlers work let's have a look at the most used one, the
+:obj:`MessageHandler <pyrogram.MessageHandler>`, which will be in charge for handling :obj:`Message <pyrogram.Message>`
+updates coming from all around your chats. Every other handler shares the same setup logic; you should not have troubles
+settings them up once you learn from this section.
+
+Using add_handler()
+-------------------
+
+The :meth:`add_handler() <pyrogram.Client.add_handler>` method takes any handler instance that wraps around your defined
+callback function and registers it in your Client. Here's a full example that prints out the content of a message as
+soon as it arrives:
+
+.. code-block:: python
+
+    from pyrogram import Client, MessageHandler
+
+
+    def my_function(client, message):
+        print(message)
+
+
+    app = Client("my_account")
+
+    my_handler = MessageHandler(my_function)
+    app.add_handler(my_handler)
+
+    app.run()
+
+Let's examine these four new pieces. First one: a callback function we defined which accepts two arguments -
+*(client, message)*. This will be the function that gets executed every time a new message arrives and Pyrogram will
+call that function by passing the client instance and the new message instance as argument.
+
+.. code-block:: python
+
+    def my_function(client, message):
+        print(message)
+
+Second one: the :obj:`MessageHandler <pyrogram.MessageHandler>`. This object tells Pyrogram the function we defined
+above must only handle updates that are in form of a :obj:`Message <pyrogram.Message>`:
+
+.. code-block:: python
+
+    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 internal
+dispatching phase begins.
+
+.. code-block:: python
+
+    app.add_handler(my_handler)
+
+Last one, the :meth:`run() <pyrogram.Client.run>` method. What this does is simply call
+:meth:`start() <pyrogram.Client.start>` and a special method :meth:`idle() <pyrogram.Client.idle>` that keeps your main
+scripts alive until you press ``CTRL+C``; the client will be automatically stopped after that.
+
+.. code-block:: python
+
+    app.run()
+
+Using Decorators
+----------------
+
+All of the above will become quite verbose, especially in case you have lots of handlers to register. A much nicer way
+to do so is by decorating your callback function with the :meth:`on_message() <pyrogram.Client.on_message>` decorator.
+
+.. code-block:: python
+
+    from pyrogram import Client
+
+    app = Client("my_account")
+
+
+    @app.on_message()
+    def my_handler(client, message):
+        print(message)
+
+
+    app.run()
+
+
+.. note::
+
+    Due to how these decorators work in Pyrogram, they will wrap your defined callback function in a tuple consisting of
+    ``(handler, group)``; this will be the value held by your function identifier (e.g.: *my_function* from the example
+    above).
+
+    In case, for some reason, you want to get your own function back after it has been decorated, you need to access
+    ``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: invoking

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/advanced-usage.rst

@@ -101,9 +101,9 @@ sending messages with IDs only thanks to cached access hashes.
 There are three different InputPeer types, one for each kind of Telegram entity.
 Whenever an InputPeer is needed you must pass one of these:
 
-    - `InputPeerUser <https://docs.pyrogram.ml/types/InputPeerUser>`_ - Users
+    - :obj:`InputPeerUser <../telegram/types/InputPeerUser>` - Users
-    - `InputPeerChat <https://docs.pyrogram.ml/types/InputPeerChat>`_ -  Basic Chats
+    - :obj:`InputPeerChat <../telegram/types/InputPeerChat>` -  Basic Chats
-    - `InputPeerChannel <https://docs.pyrogram.ml/types/InputPeerChannel>`_ - Either Channels or Supergroups
+    - :obj:`InputPeerChannel <../telegram/types/InputPeerChannel>` - Either Channels or Supergroups
 
 But you don't necessarily have to manually instantiate each object because, luckily for you, Pyrogram already provides
 :meth:`resolve_peer() <pyrogram.Client.resolve_peer>` as a convenience utility method that returns the correct InputPeer
@@ -125,12 +125,9 @@ For example, given the ID *123456789*, here's how Pyrogram can tell entities apa
 So, every time you take a raw ID, make sure to translate it into the correct ID when you want to use it with an
 high-level method.
 
-
+.. _methods: ../api/methods
-
+.. _types: ../api/types
-
+.. _plenty of them: ../api/methods
-.. _methods: ../pyrogram/Client.html#messages
+.. _raw functions: ../telegram/functions
-.. _types: ../pyrogram/Types.html
+.. _raw types: ../telegram/types
-.. _plenty of them: ../pyrogram/Client.html#messages
+.. _Community: https://t.me/Pyrogram
-.. _raw functions: ../pyrogram/functions
-.. _raw types: ../pyrogram/types
-.. _Community: https://t.me/PyrogramChat

docs/source/topics/config-file.rst

@@ -54,7 +54,7 @@ The ``[pyrogram]`` section contains your Telegram API credentials: *api_id* and
     api_id = 12345
     api_hash = 0123456789abcdef0123456789abcdef
 
-`More info about API Key. <../start/Setup.html#configuration>`_
+`More info about API Key. <../intro/setup#api-keys>`_
 
 Proxy
 ^^^^^
@@ -70,7 +70,7 @@ The ``[proxy]`` section contains settings about your SOCKS5 proxy.
     username = <your_username>
     password = <your_password>
 
-`More info about SOCKS5 Proxy. <SOCKS5Proxy.html>`_
+`More info about SOCKS5 Proxy. <proxy>`_
 
 Plugins
 ^^^^^^^
@@ -87,4 +87,4 @@ The ``[plugins]`` section contains settings about Smart Plugins.
     exclude =
         module fn2
 
-`More info about Smart Plugins. <SmartPlugins.html>`_
+`More info about Smart Plugins. <smart-plugins>`_

docs/source/topics/filters.rst

@@ -7,6 +7,9 @@ but there's much more than that to come.
 Here we'll discuss about :class:`Filters <pyrogram.Filters>`. Filters enable a fine-grain control over what kind of
 updates are allowed or not to be passed in your callback functions, based on their inner details.
 
+Single Filters
+--------------
+
 Let's start right away with a simple example:
 
 -   This example will show you how to **only** handle messages containing an :obj:`Audio <pyrogram.Audio>` object and

docs/source/topics/more-on-updates.rst

@@ -151,9 +151,9 @@ Continue Propagation
 
 As opposed to `stopping the update propagation <#stop-propagation>`_ and also as an alternative to the
 `handler groups <#handler-groups>`_, you can signal the internal dispatcher to continue the update propagation within
-**the same group** regardless of the next handler's filters. This allows you to register multiple handlers with
+**the same group** despite having conflicting filters in the next registered handler. This allows you to register
-overlapping filters in the same group; to let the dispatcher process the next handler you can do *one* of the following
+multiple handlers with overlapping filters in the same group; to let the dispatcher process the next handler you can do
-in each handler you want to grant permission to continue:
+*one* of the following in each handler you want to grant permission to continue:
 
 - Call the update's bound-method ``.continue_propagation()`` (preferred way).
 - Manually ``raise ContinuePropagation`` exception (more suitable for raw updates only).
@@ -218,5 +218,5 @@ The output of both (equivalent) examples will be:
     1
     2
 
-.. _`update handlers`: UpdateHandling.html
+.. _`update handlers`: ../start/updates
-.. _`filters`: UsingFilters.html
+.. _`filters`: filters

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

@@ -0,0 +1,110 @@
+MTProto vs. Bot API
+===================
+
+Pyrogram is a framework that acts as a fully-fledged Telegram client based on MTProto, and this very feature makes it
+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
+itself --- it's the only protocol used to exchange information between a client and the actual Telegram servers.
+
+The MTProto **API** on the other hand, is what people, for convenience, call the main Telegram API as a whole. This API
+is able to authorize both users and bots and is built on top of the MTProto encryption protocol by means of
+`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 using a sub-set of the main MTProto API. 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
+
+.. _Bot API: https://core.telegram.org/bots/api
+
+Advantages of the MTProto API
+-----------------------------
+
+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:
+
+.. hlist::
+    :columns: 1
+
+    - :guilabel:`+` **Authorize both user and bot identities**
+    - :guilabel:`--` The Bot API only allows bot accounts
+
+.. hlist::
+    :columns: 1
+
+    - :guilabel:`+` **Upload & download any file, up to 1500 MB each (~1.5 GB)**
+    - :guilabel:`--` The Bot API allows uploads and downloads of files only up to 50 MB / 20 MB in size (respectively).
+
+.. hlist::
+    :columns: 1
+
+    - :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.
+
+.. hlist::
+    :columns: 1
+
+    - :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.
+
+.. hlist::
+    :columns: 1
+
+    - :guilabel:`+` **Has much more detailed types and powerful methods**
+    - :guilabel:`--` The Bot API types often miss some useful information about Telegram entities and some of the
+      methods are limited as well.
+
+.. 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

@@ -1,24 +1,23 @@
-Customize Sessions
+Session Settings
-==================
+================
 
 As you may probably know, Telegram allows users (and bots) having more than one session (authorizations) registered
 in the system at the same time.
 
 Briefly explaining, sessions are simply new logins in your account. They can be reviewed in the settings of an official
-app (or by invoking `GetAuthorizations <../functions/account/GetAuthorizations.html>`_ with Pyrogram). They store some
+app (or by invoking `GetAuthorizations <../telegram/functions/account/GetAuthorizations.html>`_ with Pyrogram). They
-useful information such as the client who's using them and from which country and IP address.
+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
-.. figure:: https://i.imgur.com/lzGPCdZ.png
+    :width: 600
-    :width: 70%
     :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**
+-   ``app_version``: **Pyrogram 0.13.0**
--   ``device_model``: **CPython 3.6.5**
+-   ``device_model``: **CPython 3.7.2**
 -   ``system_version``: **Linux 4.15.0-23-generic**
 
 Set Custom Values

docs/source/topics/smart-plugins.rst

@@ -65,7 +65,7 @@ after importing your modules, like this:
         app.run()
 
 This is already nice and doesn't add *too much* boilerplate code, but things can get boring still; you have to
-manually ``import``, manually :meth:`add_handler <pyrogram.Client.add_handler>` and manually instantiate each
+manually ``import``, manually :meth:`add_handler() <pyrogram.Client.add_handler>` and manually instantiate each
 :obj:`MessageHandler <pyrogram.MessageHandler>` object because **you can't use those cool decorators** for your
 functions. So, what if you could? Smart Plugins solve this issue by taking care of handlers registration automatically.
 
@@ -156,7 +156,7 @@ found inside each module will be, instead, loaded in the order they are defined,
 .. note::
 
     Remember: there can be at most one handler, within a group, dealing with a specific update. Plugins with overlapping
-    filters included a second time will not work. Learn more at `More on Updates <MoreOnUpdates.html>`_.
+    filters included a second time will not work. Learn more at `More on Updates <more-on-updates>`_.
 
 This default loading behaviour is usually enough, but sometimes you want to have more control on what to include (or
 exclude) and in which exact order to load plugins. The way to do this is to make use of ``include`` and ``exclude``

docs/source/topics/text-formatting.rst

@@ -11,7 +11,7 @@ Beside bold, italic, and pre-formatted code, **Pyrogram does also support inline
 Markdown Style
 --------------
 
-To use this mode, pass :obj:`MARKDOWN <pyrogram.ParseMode.MARKDOWN>` or "markdown" in the *parse_mode* field when using
+To use this mode, pass "markdown" in the *parse_mode* field when using
 :obj:`send_message() <pyrogram.Client.send_message>`. Use the following syntax in your message:
 
 .. code-block:: text
@@ -20,7 +20,7 @@ To use this mode, pass :obj:`MARKDOWN <pyrogram.ParseMode.MARKDOWN>` or "markdow
 
     __italic text__
 
-    [inline URL](https://docs.pyrogram.ml/)
+    [inline URL](https://docs.pyrogram.org/)
 
     [inline mention of a user](tg://user?id=23122162)
 
@@ -34,8 +34,8 @@ To use this mode, pass :obj:`MARKDOWN <pyrogram.ParseMode.MARKDOWN>` or "markdow
 HTML Style
 ----------
 
-To use this mode, pass :obj:`HTML <pyrogram.ParseMode.HTML>` or "html" in the *parse_mode* field when using
+To use this mode, pass "html" in the *parse_mode* field when using :obj:`send_message() <pyrogram.Client.send_message>`.
-:obj:`send_message() <pyrogram.Client.send_message>`. The following tags are currently supported:
+The following tags are currently supported:
 
 .. code-block:: text
 
@@ -43,7 +43,7 @@ To use this mode, pass :obj:`HTML <pyrogram.ParseMode.HTML>` or "html" in the *p
 
     <i>italic</i>, <em>italic</em>
 
-    <a href="http://docs.pyrogram.ml/">inline URL</a>
+    <a href="http://docs.pyrogram.org/">inline URL</a>
 
     <a href="tg://user?id=23122162">inline mention of a user</a>
 
@@ -66,7 +66,7 @@ Examples
                 "**bold**, "
                 "__italic__, "
                 "[mention](tg://user?id=23122162), "
-                "[URL](https://docs.pyrogram.ml), "
+                "[URL](https://docs.pyrogram.org), "
                 "`code`, "
                 "```"
                 "for i in range(10):\n"
@@ -84,7 +84,7 @@ Examples
                 "<b>bold</b>, "
                 "<i>italic</i>, "
                 "<a href=\"tg://user?id=23122162\">mention</a>, "
-                "<a href=\"https://pyrogram.ml/\">URL</a>, "
+                "<a href=\"https://pyrogram.org/\">URL</a>, "
                 "<code>code</code>, "
                 "<pre>"
                 "for i in range(10):\n"

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.

examples/README.md

@@ -12,12 +12,12 @@ Example | Description
 ---: | :---
 [**hello_world**](hello_world.py) | Demonstration of basic API usage
 [**echobot**](echobot.py) | Echo every private text message
-[**welcome**](welcome.py) | The Welcome Bot in [@PyrogramChat](https://t.me/pyrogramchat)
+[**welcomebot**](welcomebot.py) | The Welcome Bot in [@PyrogramChat](https://t.me/pyrogramchat)
-[**history**](history.py) | Get the full message history of a chat
+[**get_history**](get_history.py) | Get the full message history of a chat
-[**chat_members**](chat_members.py) | Get all the members of a chat
+[**get_chat_members**](get_chat_members.py) | Get all the members of a chat
-[**dialogs**](dialogs.py) | Get all of your dialog chats
+[**get_dialogs**](get_dialogs.py) | Get all of your dialog chats
-[**using_inline_bots**](using_inline_bots.py) | Query an inline bot (as user) and send a result to a chat
+[**callback_queries**](callback_queries.py) | Handle callback queries (as bot) coming from inline button presses
-[**keyboards**](keyboards.py) | Send normal and inline keyboards using regular bots
+[**inline_queries**](inline_queries.py) | Handle inline queries (as bot) and answer with results
-[**callback_queries**](callback_queries.py) | Handle queries coming from inline button presses
+[**use_inline_bots**](use_inline_bots.py) | Query an inline bot (as user) and send a result to a chat
-[**inline_queries**](inline_queries.py) | Handle inline queries
+[**bot_keyboards**](bot_keyboards.py) | Send normal and inline keyboards using regular bots
 [**raw_updates**](raw_updates.py) | Handle raw updates (old, should be avoided)

examples/bot_keyboards.py

@@ -1,4 +1,4 @@
-"""This example will show you how to send normal and inline keyboards.
+"""This example will show you how to send normal and inline keyboards (as bot).
 
 You must log-in as a regular bot in order to send keyboards (use the token from @BotFather).
 Any attempt in sending keyboards with a user account will be simply ignored by the server.
@@ -39,7 +39,7 @@ with app:
                     ),
                     InlineKeyboardButton(  # Opens a web URL
                         "URL",
-                        url="https://docs.pyrogram.ml"
+                        url="https://docs.pyrogram.org"
                     ),
                 ],
                 [  # Second row

examples/get_dialogs.py

@@ -1,4 +1,4 @@
-"""This example shows how to get the full dialogs list of a user."""
+"""This example shows how to get the full dialogs list (as user)."""
 
 from pyrogram import Client
 

examples/inline_queries.py

@@ -22,12 +22,12 @@ def answer(client, inline_query):
                 input_message_content=InputTextMessageContent(
                     "Here's how to install **Pyrogram**"
                 ),
-                url="https://docs.pyrogram.ml/start/Installation",
+                url="https://docs.pyrogram.org/intro/install",
                 description="How to install Pyrogram",
                 thumb_url="https://i.imgur.com/JyxrStE.png",
                 reply_markup=InlineKeyboardMarkup(
                     [
-                        [InlineKeyboardButton("Open website", url="https://docs.pyrogram.ml/start/Installation")]
+                        [InlineKeyboardButton("Open website", url="https://docs.pyrogram.org/intro/install")]
                     ]
                 )
             ),
@@ -37,12 +37,12 @@ def answer(client, inline_query):
                 input_message_content=InputTextMessageContent(
                     "Here's how to use **Pyrogram**"
                 ),
-                url="https://docs.pyrogram.ml/start/Usage",
+                url="https://docs.pyrogram.org/start/invoking",
                 description="How to use Pyrogram",
                 thumb_url="https://i.imgur.com/JyxrStE.png",
                 reply_markup=InlineKeyboardMarkup(
                     [
-                        [InlineKeyboardButton("Open website", url="https://docs.pyrogram.ml/start/Usage")]
+                        [InlineKeyboardButton("Open website", url="https://docs.pyrogram.org/start/invoking")]
                     ]
                 )
             )

examples/use_inline_bots.py

@@ -0,0 +1,13 @@
+"""This example shows how to query an inline bot (as user)"""
+
+from pyrogram import Client
+
+# Create a new Client
+app = Client("my_account")
+
+with app:
+    # Get bot results for "Fuzz Universe" from the inline bot @vid
+    bot_results = app.get_inline_bot_results("vid", "Fuzz Universe")
+
+    # Send the first result (bot_results.results[0]) to your own chat (Saved Messages)
+    app.send_inline_bot_result("me", bot_results.query_id, bot_results.results[0].id)

examples/using_inline_bots.py

@@ -1,17 +0,0 @@
-"""This example shows how to query an inline bot"""
-
-from pyrogram import Client
-
-# Create a new Client
-app = Client("my_account")
-
-# Start the Client
-app.start()
-
-# Get bot results for "Fuzz Universe" from the inline bot @vid
-bot_results = app.get_inline_bot_results("vid", "Fuzz Universe")
-# Send the first result (bot_results.results[0]) to your own chat (Saved Messages)
-app.send_inline_bot_result("me", bot_results.query_id, bot_results.results[0].id)
-
-# Stop the client
-app.stop()

examples/welcomebot.py

@@ -8,7 +8,7 @@ from pyrogram import Client, Emoji, Filters
 
 TARGET = "PyrogramChat"  # Target chat. Can also be a list of multiple chat ids/usernames
 MENTION = "[{}](tg://user?id={})"  # User mention markup
-MESSAGE = "{} Welcome to [Pyrogram](https://docs.pyrogram.ml/)'s group chat {}!"  # Welcome message
+MESSAGE = "{} Welcome to [Pyrogram](https://docs.pyrogram.org/)'s group chat {}!"  # Welcome message
 
 app = Client("my_account")
 

pyrogram/__init__.py

@@ -26,9 +26,7 @@ if sys.version_info[:3] in [(3, 5, 0), (3, 5, 1), (3, 5, 2)]:
 
 __version__ = "0.13.0.async"
 __license__ = "GNU Lesser General Public License v3 or later (LGPLv3+)"
-__copyright__ = "Copyright (C) 2017-2019 Dan Tès <https://github.com/delivrance>".replace(
+__copyright__ = "Copyright (C) 2017-2019 Dan <https://github.com/delivrance>"
-    "\xe8", "e" if sys.getfilesystemencoding() != "utf-8" else "\xe8"
-)
 
 try:
     import uvloop

pyrogram/api/core/object.py

@@ -30,43 +30,51 @@ class Object:
     QUALNAME = "Base"
 
     @staticmethod
-    def read(b: BytesIO, *args):
+    def read(b: BytesIO, *args):  # TODO: Rename b -> data
         return Object.all[int.from_bytes(b.read(4), "little")].read(b, *args)
 
     def write(self, *args) -> bytes:
         pass
 
+    def __eq__(self, other: "Object") -> bool:
+        for attr in self.__slots__:
+            try:
+                if getattr(self, attr) != getattr(other, attr):
+                    return False
+            except AttributeError:
+                return False
+
+        return True
+
     def __str__(self) -> str:
+        def default(obj: Object):
+            try:
+                return OrderedDict(
+                    [("_", obj.QUALNAME)]
+                    + [(attr, getattr(obj, attr))
+                       for attr in obj.__slots__
+                       if getattr(obj, attr) is not None]
+                )
+            except AttributeError:
+                if isinstance(obj, datetime):
+                    return obj.strftime("%d-%b-%Y %H:%M:%S")
+                else:
+                    return repr(obj)
+
         return dumps(self, indent=4, default=default, ensure_ascii=False)
 
+    def __repr__(self) -> str:
+        return "pyrogram.api.{}({})".format(
+            self.QUALNAME,
+            ", ".join(
+                "{}={}".format(attr, repr(getattr(self, attr)))
+                for attr in self.__slots__
+                if getattr(self, attr) is not None
+            )
+        )
+
     def __len__(self) -> int:
         return len(self.write())
 
     def __getitem__(self, item):
         return getattr(self, item)
-
-
-def remove_none(obj):
-    if isinstance(obj, (list, tuple, set)):
-        return type(obj)(remove_none(x) for x in obj if x is not None)
-    elif isinstance(obj, dict):
-        return type(obj)((remove_none(k), remove_none(v)) for k, v in obj.items() if k is not None and v is not None)
-    else:
-        return obj
-
-
-def default(o: "Object"):
-    try:
-        content = {i: getattr(o, i) for i in o.__slots__}
-
-        return remove_none(
-            OrderedDict(
-                [("_", o.QUALNAME)]
-                + [i for i in content.items()]
-            )
-        )
-    except AttributeError:
-        if isinstance(o, datetime):
-            return o.strftime("%d-%b-%Y %H:%M:%S")
-        else:
-            return repr(o)

pyrogram/client/__init__.py

@@ -17,9 +17,9 @@
 # along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
 
 from .client import Client
-from .ext import BaseClient, ChatAction, Emoji, ParseMode
+from .ext import BaseClient, Emoji
 from .filters import Filters
 
 __all__ = [
-    "Client", "BaseClient", "ChatAction", "Emoji", "ParseMode", "Filters",
+    "Client", "BaseClient", "Emoji", "Filters",
 ]

pyrogram/client/client.py

@@ -61,27 +61,23 @@ log = logging.getLogger(__name__)
 
 
 class Client(Methods, BaseClient):
-    """This class represents a Client, the main mean for interacting with Telegram.
+    """Pyrogram Client, the main means for interacting with Telegram.
-    It exposes bot-like methods for an easy access to the API as well as a simple way to
-    invoke every single Telegram API method available.
 
-    Args:
+    Parameters:
         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*):
-            Application version. Defaults to "Pyrogram \U0001f525 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*):
@@ -107,10 +103,14 @@ 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.
 
+        bot_token (``str``, *optional*):
+            Pass your Bot API token to create a bot session, e.g.: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
+            Only applicable for new sessions.
+
         phone_number (``str`` | ``callable``, *optional*):
             Pass your phone number as string (with your Country Code prefix included) to avoid entering it manually.
             Or pass a callback function which accepts no arguments and must return the correct phone number as string
@@ -144,10 +144,6 @@ class Client(Methods, BaseClient):
             a new Telegram account in case the phone number you passed is not registered yet.
             Only applicable for new sessions.
 
-        bot_token (``str``, *optional*):
-            Pass your Bot API token to create a bot session, e.g.: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
-            Only applicable for new sessions.
-
         last_name (``str``, *optional*):
             Same purpose as *first_name*; pass a Last Name to avoid entering it manually. It can
             be an empty string: "". Only applicable for new sessions.
@@ -173,7 +169,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.
@@ -194,12 +190,12 @@ class Client(Methods, BaseClient):
         ipv6: bool = False,
         proxy: dict = None,
         test_mode: bool = False,
+        bot_token: str = None,
         phone_number: str = None,
         phone_code: Union[str, callable] = None,
         password: str = None,
         recovery_code: callable = None,
         force_sms: bool = False,
-        bot_token: str = None,
         first_name: str = None,
         last_name: str = None,
         workers: int = BaseClient.WORKERS,
@@ -222,12 +218,12 @@ class Client(Methods, BaseClient):
         # TODO: Make code consistent, use underscore for private/protected fields
         self._proxy = proxy
         self.test_mode = test_mode
+        self.bot_token = bot_token
         self.phone_number = phone_number
         self.phone_code = phone_code
         self.password = password
         self.recovery_code = recovery_code
         self.force_sms = force_sms
-        self.bot_token = bot_token
         self.first_name = first_name
         self.last_name = last_name
         self.workers = workers
@@ -268,12 +264,11 @@ class Client(Methods, BaseClient):
         self._proxy.update(value)
 
     async def start(self):
-        """Use this method to start the Client after creating it.
+        """Start the Client.
-        Requires no parameters.
 
         Raises:
-            :class:`RPCError <pyrogram.RPCError>` in case of a Telegram RPC error.
+            RPCError: In case of a Telegram RPC error.
-            ``ConnectionError`` in case you try to start an already started Client.
+            ConnectionError: In case you try to start an already started Client.
         """
         if self.is_started:
             raise ConnectionError("Client has already been started")
@@ -285,7 +280,7 @@ class Client(Methods, BaseClient):
             log.warning('\nWARNING: You are using a bot token as session name!\n'
                         'This usage will be deprecated soon. Please use a session file name to load '
                         'an existing session and the bot_token argument to create new sessions.\n'
-                        'More info: https://docs.pyrogram.ml/start/Setup#bot-authorization\n')
+                        'More info: https://docs.pyrogram.org/intro/auth#bot-authorization\n')
 
         self.load_config()
         await self.load_session()
@@ -351,11 +346,10 @@ class Client(Methods, BaseClient):
         return self
 
     async def stop(self):
-        """Use this method to manually stop the Client.
+        """Stop the Client.
-        Requires no parameters.
 
         Raises:
-            ``ConnectionError`` in case you try to stop an already stopped Client.
+            ConnectionError: In case you try to stop an already stopped Client.
         """
         if not self.is_started:
             raise ConnectionError("Client is already stopped")
@@ -391,25 +385,34 @@ class Client(Methods, BaseClient):
         return self
 
     async def restart(self):
-        """Use this method to restart the Client.
+        """Restart the Client.
-        Requires no parameters.
 
         Raises:
-            ``ConnectionError`` in case you try to restart a stopped Client.
+            ConnectionError: In case you try to restart a stopped Client.
         """
         await self.stop()
         await self.start()
 
     async def idle(self, stop_signals: tuple = (SIGINT, SIGTERM, SIGABRT)):
-        """Blocks the program execution until one of the signals are received,
+        """Block the main script execution until a signal (e.g.: from CTRL+C) is received.
-        then gently stop the Client by closing the underlying connection.
+        Once the signal is received, the client will automatically stop and the main script will continue its execution.
 
-        Args:
+        This is used after starting one or more clients and is useful for event-driven applications only, that are,
+        applications which react upon incoming Telegram updates through handlers, rather than executing a set of methods
+        sequentially.
+
+        The way Pyrogram works, will keep your handlers in a pool of workers, which are executed concurrently outside
+        the main script; calling idle() will ensure the client(s) will be kept alive by not letting the main script to
+        end, until you decide to quit.
+
+        Parameters:
             stop_signals (``tuple``, *optional*):
                 Iterable containing signals the signal handler will listen to.
                 Defaults to (SIGINT, SIGTERM, SIGABRT).
         """
 
+        # TODO: Maybe make this method static and don't automatically stop
+
         def signal_handler(*args):
             log.info("Stop signal received ({}). Exiting...".format(args[0]))
             self.is_idle = False
@@ -425,16 +428,18 @@ class Client(Methods, BaseClient):
         await self.stop()
 
     def run(self, coroutine=None):
-        """Use this method to automatically start and idle a Client.
+        """Start the Client and automatically idle the main script.
-        If a coroutine is passed as argument this method will start the client, run the coroutine
+
-        until is complete and then stop the client automatically.
+        This is a convenience method that literally just calls :meth:`start` and :meth:`idle`. It makes running a client
+        less verbose, but is not suitable in case you want to run more than one client in a single main script,
+        since :meth:`idle` will block.
 
         Args:
             coroutine: (``Coroutine``, *optional*):
                 Pass a coroutine to run it until is complete.
 
         Raises:
-            :class:`RPCError <pyrogram.RPCError>` in case of a Telegram RPC error.
+            RPCError: In case of a Telegram RPC error.
         """
         run = asyncio.get_event_loop().run_until_complete
 
@@ -452,13 +457,13 @@ class Client(Methods, BaseClient):
         return coroutine
 
     def add_handler(self, handler: Handler, group: int = 0):
-        """Use this method to register an update handler.
+        """Register an update handler.
 
         You can register multiple handlers, but at most one handler within a group
         will be used for a single update. To handle the same update more than once, register
         your handler using a different group id (lower group id == higher priority).
 
-        Args:
+        Parameters:
             handler (``Handler``):
                 The handler to be registered.
 
@@ -466,7 +471,7 @@ class Client(Methods, BaseClient):
                 The group identifier, defaults to 0.
 
         Returns:
-            A tuple of (handler, group)
+            ``tuple``: A tuple consisting of (handler, group).
         """
         if isinstance(handler, DisconnectHandler):
             self.disconnect_handler = handler.callback
@@ -476,13 +481,13 @@ class Client(Methods, BaseClient):
         return handler, group
 
     def remove_handler(self, handler: Handler, group: int = 0):
-        """Removes a previously-added update handler.
+        """Remove a previously-registered update handler.
 
         Make sure to provide the right group that the handler was added in. You can use
         the return value of the :meth:`add_handler` method, a tuple of (handler, group), and
         pass it directly.
 
-        Args:
+        Parameters:
             handler (``Handler``):
                 The handler to be removed.
 
@@ -495,7 +500,7 @@ class Client(Methods, BaseClient):
             self.dispatcher.remove_handler(handler, group)
 
     def stop_transmission(self):
-        """Use this method to stop downloading or uploading a file.
+        """Stop downloading or uploading a file.
         Must be called inside a progress callback function.
         """
         raise Client.StopTransmission
@@ -763,9 +768,16 @@ class Client(Methods, BaseClient):
 
         print("Logged in successfully as {}".format(r.user.first_name))
 
-    def fetch_peers(self, entities: List[Union[types.User,
+    def fetch_peers(
+        self,
+        entities: List[
+            Union[
+                types.User,
                 types.Chat, types.ChatForbidden,
-                                               types.Channel, types.ChannelForbidden]]):
+                types.Channel, types.ChannelForbidden
+            ]
+        ]
+    ):
         for entity in entities:
             if isinstance(entity, types.User):
                 user_id = entity.id
@@ -1027,14 +1039,20 @@ class Client(Methods, BaseClient):
                    data: Object,
                    retries: int = Session.MAX_RETRIES,
                    timeout: float = Session.WAIT_TIMEOUT):
-        """Use this method to send Raw Function queries.
+        """Send raw Telegram queries.
 
-        This method makes possible to manually call every single Telegram API method in a low-level manner.
+        This method makes it possible to manually call every single Telegram API method in a low-level manner.
         Available functions are listed in the :obj:`functions <pyrogram.api.functions>` package and may accept compound
         data types from :obj:`types <pyrogram.api.types>` as well as bare types such as ``int``, ``str``, etc...
 
-        Args:
+        .. note::
-            data (``Object``):
+
+            This is a utility method intended to be used **only** when working with raw
+            :obj:`functions <pyrogram.api.functions>` (i.e: a Telegram API method you wish to use which is not
+            available yet in the Client class as an easy-to-use method).
+
+        Parameters:
+            data (``RawFunction``):
                 The API Schema function filled with proper arguments.
 
             retries (``int``):
@@ -1043,8 +1061,11 @@ class Client(Methods, BaseClient):
             timeout (``float``):
                 Timeout in seconds.
 
+        Returns:
+            ``RawType``: The raw type response generated by the query.
+
         Raises:
-            :class:`RPCError <pyrogram.RPCError>` in case of a Telegram RPC error.
+            RPCError: In case of a Telegram RPC error.
         """
         if not self.is_started:
             raise ConnectionError("Client has not been started")
@@ -1075,7 +1096,7 @@ class Client(Methods, BaseClient):
             else:
                 raise AttributeError(
                     "No API Key found. "
-                    "More info: https://docs.pyrogram.ml/start/ProjectSetup#configuration"
+                    "More info: https://docs.pyrogram.org/intro/setup#configuration"
                 )
 
         for option in ["app_version", "device_model", "system_version", "lang_code"]:
@@ -1325,23 +1346,26 @@ class Client(Methods, BaseClient):
 
     async def resolve_peer(self,
                            peer_id: Union[int, str]):
-        """Use this method to get the InputPeer of a known peer_id.
+        """Get the InputPeer of a known peer id.
+        Useful whenever an InputPeer type is required.
 
-        This is a utility method intended to be used **only** when working with Raw Functions (i.e: a Telegram API
+        .. note::
-        method you wish to use which is not available yet in the Client class as an easy-to-use method), whenever an
-        InputPeer type is required.
 
-        Args:
+            This is a utility method intended to be used **only** when working with raw
+            :obj:`functions <pyrogram.api.functions>` (i.e: a Telegram API method you wish to use which is not
+            available yet in the Client class as an easy-to-use method).
+
+        Parameters:
             peer_id (``int`` | ``str``):
                 The peer id you want to extract the InputPeer from.
                 Can be a direct id (int), a username (str) or a phone number (str).
 
         Returns:
-            On success, the resolved peer id is returned in form of an InputPeer object.
+            ``InputPeer``: On success, the resolved peer id is returned in form of an InputPeer object.
 
         Raises:
-            :class:`RPCError <pyrogram.RPCError>` in case of a Telegram RPC error.
+            RPCError: In case of a Telegram RPC error.
-            ``KeyError`` in case the peer doesn't exist in the internal database.
+            KeyError: In case the peer doesn't exist in the internal database.
         """
         try:
             return self.peers_by_id[peer_id]
@@ -1399,14 +1423,18 @@ class Client(Methods, BaseClient):
                         file_id: int = None,
                         file_part: int = 0,
                         progress: callable = None,
-                        progress_args: tuple = ()):
+                        progress_args: tuple = ()
-        """Use this method to upload a file onto Telegram servers, without actually sending the message to anyone.
+    ):
+        """Upload a file onto Telegram servers, without actually sending the message to anyone.
+        Useful whenever an InputFile type is required.
 
-        This is a utility method intended to be used **only** when working with Raw Functions (i.e: a Telegram API
+        .. note::
-        method you wish to use which is not available yet in the Client class as an easy-to-use method), whenever an
-        InputFile type is required.
 
-        Args:
+            This is a utility method intended to be used **only** when working with raw
+            :obj:`functions <pyrogram.api.functions>` (i.e: a Telegram API method you wish to use which is not
+            available yet in the Client class as an easy-to-use method).
+
+        Parameters:
             path (``str``):
                 The path of the file you want to upload that exists on your local machine.
 
@@ -1426,7 +1454,7 @@ class Client(Methods, BaseClient):
                 a chat_id and a message_id in order to edit a message with the updated progress.
 
         Other Parameters:
-            client (:obj:`Client <pyrogram.Client>`):
+            client (:obj:`Client`):
                 The Client itself, useful when you want to call other API methods inside the callback function.
 
             current (``int``):
@@ -1440,10 +1468,10 @@ class Client(Methods, BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            On success, the uploaded file is returned in form of an InputFile object.
+            ``InputFile``: On success, the uploaded file is returned in form of an InputFile object.
 
         Raises:
-            :class:`RPCError <pyrogram.RPCError>` in case of a Telegram RPC error.
+            RPCError: In case of a Telegram RPC error.
         """
 
         async def worker(session):

pyrogram/client/ext/__init__.py

@@ -17,8 +17,6 @@
 # along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
 
 from .base_client import BaseClient
-from .chat_action import ChatAction
 from .dispatcher import Dispatcher
 from .emoji import Emoji
-from .parse_mode import ParseMode
 from .syncer import Syncer

pyrogram/client/ext/base_client.py

@@ -30,7 +30,7 @@ class BaseClient:
     class StopTransmission(StopAsyncIteration):
         pass
 
-    APP_VERSION = "Pyrogram \U0001f525 {}".format(__version__)
+    APP_VERSION = "Pyrogram {}".format(__version__)
 
     DEVICE_MODEL = "{} {}".format(
         platform.python_implementation(),

pyrogram/client/ext/chat_action.py

@@ -1,77 +0,0 @@
-# Pyrogram - Telegram MTProto API Client Library for Python
-# Copyright (C) 2017-2019 Dan Tès <https://github.com/delivrance>
-#
-# This file is part of Pyrogram.
-#
-# Pyrogram is free software: you can redistribute it and/or modify
-# 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.
-#
-# Pyrogram is distributed in the hope that it will be useful,
-# 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.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
-
-from enum import Enum
-
-from pyrogram.api import types
-
-
-class ChatAction(Enum):
-    """This enumeration provides a convenient access to all Chat Actions available.
-    Chat Actions are intended to be used with
-    :meth:`send_chat_action() <pyrogram.Client.send_chat_action>`.
-    """
-
-    CANCEL = types.SendMessageCancelAction
-    """Cancels any chat action currently displayed."""
-
-    TYPING = types.SendMessageTypingAction
-    """User is typing a text message."""
-
-    PLAYING = types.SendMessageGamePlayAction
-    """User is playing a game."""
-
-    CHOOSE_CONTACT = types.SendMessageChooseContactAction
-    """User is choosing a contact to share."""
-
-    UPLOAD_PHOTO = types.SendMessageUploadPhotoAction
-    """User is uploading a photo."""
-
-    RECORD_VIDEO = types.SendMessageRecordVideoAction
-    """User is recording a video."""
-
-    UPLOAD_VIDEO = types.SendMessageUploadVideoAction
-    """User is uploading a video."""
-
-    RECORD_AUDIO = types.SendMessageRecordAudioAction
-    """User is recording an audio message."""
-
-    UPLOAD_AUDIO = types.SendMessageUploadAudioAction
-    """User is uploading an audio message."""
-
-    UPLOAD_DOCUMENT = types.SendMessageUploadDocumentAction
-    """User is uploading a generic document."""
-
-    FIND_LOCATION = types.SendMessageGeoLocationAction
-    """User is searching for a location on the map."""
-
-    RECORD_VIDEO_NOTE = types.SendMessageRecordRoundAction
-    """User is recording a round video note."""
-
-    UPLOAD_VIDEO_NOTE = types.SendMessageUploadRoundAction
-    """User is uploading a round video note."""
-
-    @staticmethod
-    def from_string(action: str) -> "ChatAction":
-        for a in ChatAction:
-            if a.name.lower() == action.lower():
-                return a
-
-        raise ValueError("Invalid ChatAction: '{}'. Possible types are {}".format(
-            action, [x.name.lower() for x in ChatAction]
-        ))

pyrogram/client/ext/parse_mode.py

@@ -1,29 +0,0 @@
-# Pyrogram - Telegram MTProto API Client Library for Python
-# Copyright (C) 2017-2019 Dan Tès <https://github.com/delivrance>
-#
-# This file is part of Pyrogram.
-#
-# Pyrogram is free software: you can redistribute it and/or modify
-# 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.
-#
-# Pyrogram is distributed in the hope that it will be useful,
-# 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.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
-
-
-class ParseMode:
-    """This class provides a convenient access to Parse Modes.
-    Parse Modes are intended to be used with any method that accepts the optional argument **parse_mode**.
-    """
-
-    HTML = "html"
-    """Set the parse mode to HTML style"""
-
-    MARKDOWN = "markdown"
-    """Set the parse mode to Markdown style"""

pyrogram/client/filters/filters.py

@@ -19,15 +19,15 @@
 import re
 
 from .filter import Filter
-from ..types.bots import InlineKeyboardMarkup, ReplyKeyboardMarkup
+from ..types.keyboards import InlineKeyboardMarkup, ReplyKeyboardMarkup
 
 
 def create(name: str, func: callable, **kwargs) -> type:
-    """Use this method to create a Filter.
+    """Create a Filter.
 
     Custom filters give you extra control over which updates are allowed or not to be processed by your handlers.
 
-    Args:
+    Parameters:
         name (``str``):
             Your filter's name. Can be anything you like.
 
@@ -35,9 +35,9 @@ def create(name: str, func: callable, **kwargs) -> type:
             A function that accepts two arguments *(filter, update)* and returns a Boolean: True if the update should be
             handled, False otherwise.
             The "update" argument type will vary depending on which `Handler <Handlers.html>`_ is coming from.
-            For example, in a :obj:`MessageHandler <pyrogram.MessageHandler>` the update type will be
+            For example, in a :obj:`MessageHandler` the update type will be
-            a :obj:`Message <pyrogram.Message>`; in a :obj:`CallbackQueryHandler <pyrogram.CallbackQueryHandler>` the
+            a :obj:`Message`; in a :obj:`CallbackQueryHandler` the
-            update type will be a :obj:`CallbackQuery <pyrogram.CallbackQuery>`. Your function body can then access the
+            update type will be a :obj:`CallbackQuery`. Your function body can then access the
             incoming update and decide whether to allow it or not.
 
         **kwargs (``any``, *optional*):
@@ -54,7 +54,7 @@ def create(name: str, func: callable, **kwargs) -> type:
 class Filters:
     """This class provides access to all library-defined Filters available in Pyrogram.
 
-    The Filters listed here are intended to be used with the :obj:`MessageHandler <pyrogram.MessageHandler>` only.
+    The Filters listed here are intended to be used with the :obj:`MessageHandler` only.
     At the moment, if you want to filter updates coming from different `Handlers <Handlers.html>`_ you have to create
     your own filters with :meth:`Filters.create` and use them in the same way.
     """
@@ -89,49 +89,49 @@ class Filters:
     """Filter edited messages."""
 
     audio = create("Audio", lambda _, m: bool(m.audio))
-    """Filter messages that contain :obj:`Audio <pyrogram.Audio>` objects."""
+    """Filter messages that contain :obj:`Audio` objects."""
 
     document = create("Document", lambda _, m: bool(m.document))
-    """Filter messages that contain :obj:`Document <pyrogram.Document>` objects."""
+    """Filter messages that contain :obj:`Document` objects."""
 
     photo = create("Photo", lambda _, m: bool(m.photo))
-    """Filter messages that contain :obj:`Photo <pyrogram.PhotoSize>` objects."""
+    """Filter messages that contain :obj:`Photo` objects."""
 
     sticker = create("Sticker", lambda _, m: bool(m.sticker))
-    """Filter messages that contain :obj:`Sticker <pyrogram.Sticker>` objects."""
+    """Filter messages that contain :obj:`Sticker` objects."""
 
     animation = create("Animation", lambda _, m: bool(m.animation))
-    """Filter messages that contain :obj:`Animation <pyrogram.Animation>` objects."""
+    """Filter messages that contain :obj:`Animation` objects."""
 
     game = create("Game", lambda _, m: bool(m.game))
-    """Filter messages that contain :obj:`Game <pyrogram.Game>` objects."""
+    """Filter messages that contain :obj:`Game` objects."""
 
     video = create("Video", lambda _, m: bool(m.video))
-    """Filter messages that contain :obj:`Video <pyrogram.Video>` objects."""
+    """Filter messages that contain :obj:`Video` objects."""
 
     media_group = create("MediaGroup", lambda _, m: bool(m.media_group_id))
     """Filter messages containing photos or videos being part of an album."""
 
     voice = create("Voice", lambda _, m: bool(m.voice))
-    """Filter messages that contain :obj:`Voice <pyrogram.Voice>` note objects."""
+    """Filter messages that contain :obj:`Voice` note objects."""
 
     video_note = create("VideoNote", lambda _, m: bool(m.video_note))
-    """Filter messages that contain :obj:`VideoNote <pyrogram.VideoNote>` objects."""
+    """Filter messages that contain :obj:`VideoNote` objects."""
 
     contact = create("Contact", lambda _, m: bool(m.contact))
-    """Filter messages that contain :obj:`Contact <pyrogram.Contact>` objects."""
+    """Filter messages that contain :obj:`Contact` objects."""
 
     location = create("Location", lambda _, m: bool(m.location))
-    """Filter messages that contain :obj:`Location <pyrogram.Location>` objects."""
+    """Filter messages that contain :obj:`Location` objects."""
 
     venue = create("Venue", lambda _, m: bool(m.venue))
-    """Filter messages that contain :obj:`Venue <pyrogram.Venue>` objects."""
+    """Filter messages that contain :obj:`Venue` objects."""
 
     web_page = create("WebPage", lambda _, m: m.web_page)
     """Filter messages sent with a webpage preview."""
 
     poll = create("Poll", lambda _, m: m.poll)
-    """Filter messages that contain :obj:`Poll <pyrogram.Poll>` objects."""
+    """Filter messages that contain :obj:`Poll` objects."""
 
     private = create("Private", lambda _, m: bool(m.chat and m.chat.type == "private"))
     """Filter messages sent in private chats."""
@@ -191,35 +191,19 @@ class Filters:
     """Filter messages sent via inline bots"""
 
     service = create("Service", lambda _, m: bool(m.service))
-    """Filter service messages. A service message contains any of the following fields set
+    """Filter service messages.
     
-    - left_chat_member
+    A service message contains any of the following fields set: *left_chat_member*,
-    - new_chat_title
+    *new_chat_title*, *new_chat_photo*, *delete_chat_photo*, *group_chat_created*, *supergroup_chat_created*,
-    - new_chat_photo
+    *channel_chat_created*, *migrate_to_chat_id*, *migrate_from_chat_id*, *pinned_message*, *game_score*.
-    - delete_chat_photo
+    """
-    - group_chat_created
-    - supergroup_chat_created
-    - channel_chat_created
-    - migrate_to_chat_id
-    - migrate_from_chat_id
-    - pinned_message
-    - game_score"""
 
     media = create("Media", lambda _, m: bool(m.media))
-    """Filter media messages. A media message contains any of the following fields set
+    """Filter media messages.
     
-    - audio
+    A media message contains any of the following fields set: *audio*, *document*, *photo*, *sticker*, *video*,
-    - document
+    *animation*, *voice*, *video_note*, *contact*, *location*, *venue*, *poll*.
-    - photo
+    """
-    - sticker
-    - video
-    - animation
-    - voice
-    - video_note
-    - contact
-    - location
-    - venue
-    - poll"""
 
     @staticmethod
     def command(
@@ -230,12 +214,12 @@ class Filters:
     ):
         """Filter commands, i.e.: text messages starting with "/" or any other custom prefix.
 
-        Args:
+        Parameters:
             commands (``str`` | ``list``):
                 The command or list of commands as string the filter should look for.
                 Examples: "start", ["start", "help", "settings"]. When a message text containing
                 a command arrives, the command itself and its arguments will be stored in the *command*
-                field of the :class:`Message <pyrogram.Message>`.
+                field of the :class:`Message`.
 
             prefix (``str`` | ``list``, *optional*):
                 A prefix or a list of prefixes as string the filter should look for.
@@ -275,11 +259,11 @@ class Filters:
     def regex(pattern, flags: int = 0):
         """Filter messages that match a given RegEx pattern.
 
-        Args:
+        Parameters:
             pattern (``str``):
                 The RegEx pattern as string, it will be applied to the text of a message. When a pattern matches,
                 all the `Match Objects <https://docs.python.org/3/library/re.html#match-objects>`_
-                are stored in the *matches* field of the :class:`Message <pyrogram.Message>` itself.
+                are stored in the *matches* field of the :class:`Message` itself.
 
             flags (``int``, *optional*):
                 RegEx flags.
@@ -298,7 +282,7 @@ class Filters:
         You can use `set bound methods <https://docs.python.org/3/library/stdtypes.html#set>`_ to manipulate the
         users container.
 
-        Args:
+        Parameters:
             users (``int`` | ``str`` | ``list``):
                 Pass one or more user ids/usernames to filter users.
                 For you yourself, "me" or "self" can be used as well. 
@@ -329,7 +313,7 @@ class Filters:
         You can use `set bound methods <https://docs.python.org/3/library/stdtypes.html#set>`_ to manipulate the
         chats container.
 
-        Args:
+        Parameters:
             chats (``int`` | ``str`` | ``list``):
                 Pass one or more chat ids/usernames to filter chats.
                 For your personal cloud (Saved Messages) you can simply use "me" or "self".

pyrogram/client/handlers/callback_query_handler.py

@@ -26,17 +26,17 @@ class CallbackQueryHandler(Handler):
     For a nicer way to register this handler, have a look at the
     :meth:`on_callback_query() <pyrogram.Client.on_callback_query>` decorator.
 
-    Args:
+    Parameters:
         callback (``callable``):
             Pass a function that will be called when a new CallbackQuery arrives. It takes *(client, callback_query)*
             as positional arguments (look at the section below for a detailed description).
 
-        filters (:obj:`Filters <pyrogram.Filters>`):
+        filters (:obj:`Filters`):
             Pass one or more filters to allow only a subset of callback queries to be passed
             in your callback function.
 
     Other parameters:
-        client (:obj:`Client <pyrogram.Client>`):
+        client (:obj:`Client`):
             The Client itself, useful when you want to call other API methods inside the message handler.
 
         callback_query (:obj:`CallbackQuery <pyrogram.CallbackQuery>`):

pyrogram/client/handlers/deleted_messages_handler.py

@@ -27,20 +27,20 @@ class DeletedMessagesHandler(Handler):
     For a nicer way to register this handler, have a look at the
     :meth:`on_deleted_messages() <pyrogram.Client.on_deleted_messages>` decorator.
 
-    Args:
+    Parameters:
         callback (``callable``):
             Pass a function that will be called when one or more Messages have been deleted.
             It takes *(client, messages)* as positional arguments (look at the section below for a detailed description).
 
-        filters (:obj:`Filters <pyrogram.Filters>`):
+        filters (:obj:`Filters`):
             Pass one or more filters to allow only a subset of messages to be passed
             in your callback function.
 
     Other parameters:
-        client (:obj:`Client <pyrogram.Client>`):
+        client (:obj:`Client`):
             The Client itself, useful when you want to call other API methods inside the message handler.
 
-        messages (:obj:`Messages <pyrogram.Messages>`):
+        messages (:obj:`Messages`):
             The deleted messages.
     """
 

pyrogram/client/handlers/disconnect_handler.py

@@ -26,13 +26,13 @@ class DisconnectHandler(Handler):
     For a nicer way to register this handler, have a look at the
     :meth:`on_disconnect() <pyrogram.Client.on_disconnect>` decorator.
 
-    Args:
+    Parameters:
         callback (``callable``):
             Pass a function that will be called when a disconnection occurs. It takes *(client)*
             as positional argument (look at the section below for a detailed description).
 
     Other parameters:
-        client (:obj:`Client <pyrogram.Client>`):
+        client (:obj:`Client`):
             The Client itself. Useful, for example, when you want to change the proxy before a new connection
             is established.
     """

pyrogram/client/handlers/inline_query_handler.py

@@ -26,20 +26,20 @@ class InlineQueryHandler(Handler):
     For a nicer way to register this handler, have a look at the
     :meth:`on_inline_query() <pyrogram.Client.on_inline_query>` decorator.
 
-    Args:
+    Parameters:
         callback (``callable``):
             Pass a function that will be called when a new InlineQuery arrives. It takes *(client, inline_query)*
             as positional arguments (look at the section below for a detailed description).
 
-        filters (:obj:`Filters <pyrogram.Filters>`):
+        filters (:obj:`Filters`):
             Pass one or more filters to allow only a subset of inline queries to be passed
             in your callback function.
 
     Other parameters:
-        client (:obj:`Client <pyrogram.Client>`):
+        client (:obj:`Client`):
             The Client itself, useful when you want to call other API methods inside the inline query handler.
 
-        inline_query (:obj:`InlineQuery <pyrogram.InlineQuery>`):
+        inline_query (:obj:`InlineQuery`):
             The received inline query.
     """
 

pyrogram/client/handlers/message_handler.py

@@ -27,20 +27,20 @@ class MessageHandler(Handler):
     For a nicer way to register this handler, have a look at the
     :meth:`on_message() <pyrogram.Client.on_message>` decorator.
 
-    Args:
+    Parameters:
         callback (``callable``):
             Pass a function that will be called when a new Message arrives. It takes *(client, message)*
             as positional arguments (look at the section below for a detailed description).
 
-        filters (:obj:`Filters <pyrogram.Filters>`):
+        filters (:obj:`Filters`):
             Pass one or more filters to allow only a subset of messages to be passed
             in your callback function.
 
     Other parameters:
-        client (:obj:`Client <pyrogram.Client>`):
+        client (:obj:`Client`):
             The Client itself, useful when you want to call other API methods inside the message handler.
 
-        message (:obj:`Message <pyrogram.Message>`):
+        message (:obj:`Message`):
             The received message.
     """
 

pyrogram/client/handlers/poll_handler.py

@@ -27,7 +27,7 @@ class PollHandler(Handler):
     For a nicer way to register this handler, have a look at the
     :meth:`on_poll() <pyrogram.Client.on_poll>` decorator.
 
-    Args:
+    Parameters:
         callback (``callable``):
             Pass a function that will be called when a new poll update arrives. It takes *(client, poll)*
             as positional arguments (look at the section below for a detailed description).

pyrogram/client/handlers/raw_update_handler.py

@@ -26,14 +26,14 @@ class RawUpdateHandler(Handler):
     For a nicer way to register this handler, have a look at the
     :meth:`on_raw_update() <pyrogram.Client.on_raw_update>` decorator.
 
-    Args:
+    Parameters:
         callback (``callable``):
             A function that will be called when a new update is received from the server. It takes
             *(client, update, users, chats)* as positional arguments (look at the section below for
             a detailed description).
 
     Other Parameters:
-        client (:class:`Client <pyrogram.Client>`):
+        client (:class:`Client`):
             The Client itself, useful when you want to call other API methods inside the update handler.
 
         update (``Update``):