Merge branch 'develop' into asyncio

# Conflicts:
#	pyrogram/client/client.py

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = ~/PycharmProjects/pyrogram/venv/bin/sphinx-build
+SPHINXBUILD   = ~/PycharmProjects/pyrogram/venv3.6/bin/sphinx-build
 SPHINXPROJ    = Pyrogram
 SOURCEDIR     = source
 BUILDDIR      = build

docs/source/index.rst

@@ -44,12 +44,11 @@ Welcome to Pyrogram
 
     @app.on_message(Filters.private)
     def hello(client, message):
-        client.send_message(
+        message.reply_text(
-            message.chat.id, "Hello {}".format(message.from_user.first_name))
+            "Hello {}".format(message.from_user.first_name))
 
 
-    app.start()
+    app.run()
-    app.idle()
 
 Welcome to Pyrogram's Documentation! Here you can find resources for learning how to use the library.
 Contents are organized by topic and can be accessed from the sidebar, or by following them one by one using the Next

docs/source/pyrogram/Client.rst

@@ -17,6 +17,7 @@ Client
         start
         stop
         idle
+        run
         on_message
         on_callback_query
         on_raw_update

docs/source/pyrogram/handlers/DeletedMessagesHandler.rst

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

docs/source/pyrogram/handlers/index.rst

@@ -5,6 +5,7 @@ Handlers
 
 .. toctree::
     MessageHandler
+    DeletedMessagesHandler
     CallbackQueryHandler
+    DisconnectHandler
     RawUpdateHandler
-    DisconnectHandler

docs/source/resources/AutoAuthorization.rst

@@ -35,6 +35,7 @@ ask you to input the phone code manually.
 
     app.start()
     print(app.get_me())
+    app.stop()
 
 Sign Up
 -------
@@ -61,4 +62,5 @@ Telegram account in case the phone number you passed is not registered yet.
     )
 
     app.start()
-    print(app.get_me())
+    print(app.get_me())
+    app.stop()

docs/source/resources/UpdateHandling.rst

@@ -6,6 +6,7 @@ and are handled by registering one or more callback functions with an Handler. T
 from, one for each kind of update:
 
 -   `MessageHandler <../pyrogram/handlers/MessageHandler.html>`_
+-   `DeletedMessagesHandler <../pyrogram/handlers/DeletedMessagesHandler.html>`_
 -   `CallbackQueryHandler <../pyrogram/handlers/CallbackQueryHandler.html>`_
 -   `RawUpdateHandler <../pyrogram/handlers/RawUpdateHandler.html>`_
 
@@ -31,8 +32,7 @@ We shall examine the :obj:`MessageHandler <pyrogram.MessageHandler>`, which will
             print(message)
 
 
-        app.start()
+        app.run()
-        app.idle()
 
 -   If you prefer not to use decorators, there is an alternative way for registering Handlers.
     This is useful, for example, when you want to keep your callback functions in separate files.
@@ -50,8 +50,7 @@ We shall examine the :obj:`MessageHandler <pyrogram.MessageHandler>`, which will
 
         app.add_handler(MessageHandler(my_handler))
 
-        app.start()
+        app.run()
-        app.idle()
 
 Using Filters
 -------------

docs/source/start/Setup.rst

@@ -1,7 +1,7 @@
 Setup
 =====
 
-Once you successfully installed_ Pyrogram, you will have to follow a few steps before you can actually use
+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.
 
@@ -40,13 +40,13 @@ There are two ways to configure a Pyrogram application project, and you can choo
         from pyrogram import Client
 
         app = Client(
-            session_name="my_account",
+            "my_account",
             api_id=12345,
             api_hash="0123456789abcdef0123456789abcdef"
         )
 
 .. note:: The examples below assume you have created a ``config.ini`` file, thus they won't show the *api_id*
-and *api_hash* parameters usage.
+    and *api_hash* parameters usage.
 
 User Authorization
 ------------------
@@ -61,7 +61,7 @@ the :class:`Client <pyrogram.Client>` class by passing to it a ``session_name``
     from pyrogram import Client
 
     app = Client("my_account")
-    app.start()
+    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:
@@ -92,11 +92,11 @@ Instead of phone numbers, Bots are authorized via their tokens which are created
     from pyrogram import Client
 
     app = Client("123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11")
-    app.start()
+    app.run()
 
 That's all, no further action is needed. The session file will be named after the Bot user_id, which is
 ``123456.session`` for the example above.
 
-.. _installed: Installation.html
+.. _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

@@ -10,11 +10,11 @@ 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`_.
 
-.. hint:: If you can't find a method you want to use, chances are it's not implemented yet. In this case, you must use
+.. hint:: If you can't find an high-level method you want to use, chances are it's not implemented yet.
-    the `Raw Functions`_. Meanwhile, feel free to join our Community_ if you're stuck or want to propose a
+    In this case, you must use the `Raw Functions`_. Meanwhile, feel free to join our Community_ if you get stuck
-    new method!
+    or want to propose a new method!
 
-Examples:
+Examples (more on `GitHub <https://github.com/pyrogram/pyrogram/tree/develop/examples>`_):
 
 -   Get information about the authorized user:
 
@@ -39,7 +39,7 @@ Examples:
 Using Raw Functions
 -------------------
 
-If you can't find a high-level method for your needs or want complete, low-level access to the whole Telegram API,
+If you can't find a high-level method for your needs or if want complete, low-level access to the whole Telegram API,
 you have to use the raw :mod:`functions <pyrogram.api.functions>` and :mod:`types <pyrogram.api.types>` exposed by the
 ``pyrogram.api`` package and call any Telegram API method you wish using the :meth:`send() <pyrogram.Client.send>`
 method provided by the Client class.
@@ -49,15 +49,17 @@ method provided by the Client class.
     re-implemented by providing a much simpler and cleaner interface which is very similar to the Bot API.
     If you think a raw function should be wrapped and added as a high-level method, feel free to ask in our Community_!
 
-Examples:
+Examples (more on `GitHub <https://github.com/pyrogram/pyrogram/tree/develop/examples>`_):
 
 -   Update first name, last name and bio:
 
     .. code-block:: python
 
+        from pyrogram import Client
         from pyrogram.api import functions
 
-        ...
+        app = Client("my_account")
+        app.start()
 
         app.send(
             functions.account.UpdateProfile(
@@ -66,13 +68,17 @@ Examples:
             )
         )
 
+        app.stop()
+
 -   Share your Last Seen time only with your contacts:
 
     .. code-block:: python
 
+        from pyrogram import Client
         from pyrogram.api import functions, types
 
-        ...
+        app = Client("my_account")
+        app.start()
 
         app.send(
             functions.account.SetPrivacy(
@@ -81,13 +87,17 @@ Examples:
             )
         )
 
+        app.stop()
+
 -   Invite users to your channel/supergroup:
 
     .. code-block:: python
 
+        from pyrogram import Client
         from pyrogram.api import functions, types
 
-        ...
+        app = Client("my_account")
+        app.start()
 
         app.send(
             functions.channels.InviteToChannel(
@@ -100,6 +110,8 @@ Examples:
             )
         )
 
+        app.stop()
+
 .. _methods: ../pyrogram/Client.html#available-methods
 .. _plenty of them: ../pyrogram/Client.html#available-methods
 .. _types: ../pyrogram/types/index.html

examples/callback_query_handler.py

@@ -34,5 +34,4 @@ def answer(client, callback_query):
     )
 
 
-app.start()
+app.run()  # Automatically start() and idle()
-app.idle()

examples/echo_bot.py

@@ -36,5 +36,4 @@ def echo(client, message):
     )
 
 
-app.start()
+app.run()  # Automatically start() and idle()
-app.idle()

examples/get_history.py

@@ -24,12 +24,12 @@ from pyrogram.api.errors import FloodWait
 """This example shows how to retrieve the full message history of a chat"""
 
 app = Client("my_account")
-app.start()
-
 target = "me"  # "me" refers to your own chat (Saved Messages)
 messages = []  # List that will contain all the messages of the target chat
 offset_id = 0  # ID of the last message of the chunk
 
+app.start()
+
 while True:
     try:
         m = app.get_history(target, offset_id=offset_id)

examples/get_participants.py

@@ -28,13 +28,13 @@ Refer to get_participants2.py for more than 10.000 users.
 """
 
 app = Client("my_account")
-app.start()
-
 target = "pyrogramchat"  # Target channel/supergroup
 users = []  # List that will contain all the users of the target chat
 limit = 200  # Amount of users to retrieve for each API call
 offset = 0  # Offset starts at 0
 
+app.start()
+
 while True:
     try:
         participants = app.send(

examples/get_participants2.py

@@ -33,15 +33,14 @@ as some user names may not contain ascii letters at all.
 """
 
 app = Client("my_account")
-app.start()
-
 target = "pyrogramchat"  # Target channel/supergroup username or id
 users = {}  # To ensure uniqueness, users will be stored in a dictionary with user_id as key
 limit = 200  # Amount of users to retrieve for each API call (200 is the maximum)
-
 # "" + "0123456789" + "abcdefghijklmnopqrstuvwxyz" (as list)
 queries = [""] + [str(i) for i in range(10)] + list(ascii_lowercase)
 
+app.start()
+
 for q in queries:
     print("Searching for '{}'".format(q))
     offset = 0  # For each query, offset restarts from 0

examples/raw_update_handler.py

@@ -28,5 +28,4 @@ def raw(client, update, users, chats):
     print(update)
 
 
-app.start()
+app.run()  # Automatically start() and idle()
-app.idle()

examples/welcome_bot.py

@@ -49,5 +49,4 @@ def welcome(client, message):
     )
 
 
-app.start()
+app.run()  # Automatically start() and idle()
-app.idle()

pyrogram/client/client.py

@@ -265,6 +265,38 @@ class Client(Methods, BaseClient):
         self.is_started = False
         await self.session.stop()
 
+    def signal_handler(self, *args):
+        self.is_idle = False
+
+    def idle(self, stop_signals: tuple = (SIGINT, SIGTERM, SIGABRT)):
+        """Blocks the program execution until one of the signals are received,
+        then gently stop the Client by closing the underlying connection.
+
+        Args:
+            stop_signals (``tuple``, *optional*):
+                Iterable containing signals the signal handler will listen to.
+                Defaults to (SIGINT, SIGTERM, SIGABRT).
+        """
+        for s in stop_signals:
+            signal(s, self.signal_handler)
+
+        self.is_idle = True
+
+        while self.is_idle:
+            time.sleep(1)
+
+        self.stop()
+
+    def run(self):
+        """Use this method to automatically start and idle a Client.
+        Requires no parameters.
+
+        Raises:
+            :class:`Error <pyrogram.Error>`
+        """
+        self.start()
+        self.idle()
+
     def add_handler(self, handler, group: int = 0):
         """Use this method to register an update handler.
 

pyrogram/client/handlers/callback_query_handler.py

@@ -23,6 +23,9 @@ class CallbackQueryHandler(Handler):
     """The CallbackQuery handler class. Used to handle callback queries coming from inline buttons.
     It is intended to be used with :meth:`add_handler() <pyrogram.Client.add_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:
         callback (``callable``):
             Pass a function that will be called when a new CallbackQuery arrives. It takes *(client, callback_query)*

pyrogram/client/handlers/deleted_messages_handler.py

@@ -20,10 +20,13 @@ from .handler import Handler
 
 
 class DeletedMessagesHandler(Handler):
-    """The Deleted Messages handler class. Used to handle deleted messages coming from any chat
+    """The deleted Messages handler class. Used to handle deleted messages coming from any chat
     (private, group, channel). It is intended to be used with
     :meth:`add_handler() <pyrogram.Client.add_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:
         callback (``callable``):
             Pass a function that will be called when one or more Messages have been deleted.

pyrogram/client/handlers/disconnect_handler.py

@@ -23,6 +23,8 @@ class DisconnectHandler(Handler):
     """The Disconnect handler class. Used to handle disconnections. It is intended to be used with
     :meth:`add_handler() <pyrogram.Client.add_handler>`
 
+    For a nicer way to register this handler, have a look at the
+    :meth:`on_disconnect() <pyrogram.Client.on_disconnect>` decorator.
 
     Args:
         callback (``callable``):

pyrogram/client/handlers/message_handler.py

@@ -24,6 +24,9 @@ class MessageHandler(Handler):
     any chat (private, group, channel). It is intended to be used with
     :meth:`add_handler() <pyrogram.Client.add_handler>`
 
+    For a nicer way to register this handler, have a look at the
+    :meth:`on_message() <pyrogram.Client.on_message>` decorator.
+
     Args:
         callback (``callable``):
             Pass a function that will be called when a new Message arrives. It takes *(client, message)*

pyrogram/client/handlers/raw_update_handler.py

@@ -23,6 +23,9 @@ class RawUpdateHandler(Handler):
     """The Raw Update handler class. Used to handle raw updates. It is intended to be used with
     :meth:`add_handler() <pyrogram.Client.add_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:
         callback (``callable``):
             A function that will be called when a new update is received from the server. It takes

pyrogram/client/methods/decorators/on_callback_query.py

@@ -24,7 +24,7 @@ class OnCallbackQuery(BaseClient):
     def on_callback_query(self, filters=None, group: int = 0):
         """Use this decorator to automatically register a function for handling
         callback queries. This does the same thing as :meth:`add_handler` using the
-        CallbackQueryHandler.
+        :class:`CallbackQueryHandler`.
 
         Args:
             filters (:obj:`Filters <pyrogram.Filters>`):

pyrogram/client/methods/decorators/on_deleted_messages.py

@@ -24,7 +24,7 @@ class OnDeletedMessages(BaseClient):
     def on_deleted_messages(self, filters=None, group: int = 0):
         """Use this decorator to automatically register a function for handling
         deleted messages. This does the same thing as :meth:`add_handler` using the
-        DeletedMessagesHandler.
+        :class:`DeletedMessagesHandler`.
 
         Args:
             filters (:obj:`Filters <pyrogram.Filters>`):

pyrogram/client/methods/decorators/on_disconnect.py

@@ -24,7 +24,7 @@ class OnDisconnect(BaseClient):
     def on_disconnect(self):
         """Use this decorator to automatically register a function for handling
         disconnections. This does the same thing as :meth:`add_handler` using the
-        DisconnectHandler.
+        :class:`DisconnectHandler`.
         """
 
         def decorator(func):

pyrogram/client/methods/decorators/on_message.py

@@ -24,7 +24,7 @@ class OnMessage(BaseClient):
     def on_message(self, filters=None, group: int = 0):
         """Use this decorator to automatically register a function for handling
         messages. This does the same thing as :meth:`add_handler` using the
-        MessageHandler.
+        :class:`MessageHandler`.
 
         Args:
             filters (:obj:`Filters <pyrogram.Filters>`):

pyrogram/client/methods/decorators/on_raw_update.py

@@ -24,7 +24,7 @@ class OnRawUpdate(BaseClient):
     def on_raw_update(self, group: int = 0):
         """Use this decorator to automatically register a function for handling
         raw updates. This does the same thing as :meth:`add_handler` using the
-        RawUpdateHandler.
+        :class:`RawUpdateHandler`.
 
         Args:
             group (``int``, *optional*):