Merge branch 'develop' into asyncio

# Conflicts:
#	pyrogram/client/client.py

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*):