handlers: fix typing and docs (#143)

pyrogram/pyrogram#701

Co-authored-by: Adek Maulana <[email protected]>

Author: SpEcHiDe

docs/source/releases/changes-in-this-fork.rst

@@ -26,6 +26,7 @@ Changes in this Fork
 | Scheme layer used: 198 |
 +------------------------+
 
+- PR from upstream: `701 <https://github.com/pyrogram/pyrogram/pull/701>`_
 - View `new and changed <https://telegramplayground.github.io/TG-APIs/TL/diff/tdlib.html?from=196&to=198>`__ `raw API methods <https://telegramplayground.github.io/TG-APIs/TL/diff/tdesktop.html?from=196&to=198>`__.
 
 +------------------------+

pyrogram/handlers/business_bot_connection_handler.py

@@ -16,10 +16,20 @@
 #  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 typing import Callable
+from typing import Any, Callable
 
+import pyrogram
+from pyrogram.filters import Filter
 from .handler import Handler
 
+CallbackFunc: Callable = Callable[
+    [
+        "pyrogram.Client",
+        pyrogram.types.BusinessConnection
+    ],
+    Any
+]
+
 
 class BusinessBotConnectionHandler(Handler):
     """The Bot Business Connection handler class. Used to handle new bot business connection.
@@ -47,5 +57,5 @@ class BusinessBotConnectionHandler(Handler):
 
     """
 
-    def __init__(self, callback: Callable, filters=None):
+    def __init__(self, callback: CallbackFunc, filters: Filter = None):
         super().__init__(callback, filters)

pyrogram/handlers/callback_query_handler.py

@@ -16,10 +16,21 @@
 #  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 typing import Callable
 
+from typing import Any, Callable
+
+import pyrogram
+from pyrogram.filters import Filter
 from .handler import Handler
 
+CallbackFunc: Callable = Callable[
+    [
+        "pyrogram.Client",
+        pyrogram.types.CallbackQuery
+    ],
+    Any
+]
+
 
 class CallbackQueryHandler(Handler):
     """The CallbackQuery handler class. Used to handle callback queries coming from inline buttons.
@@ -33,17 +44,17 @@ class CallbackQueryHandler(Handler):
             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`):
+        filters (:obj:`Filter`):
             Pass one or more filters to allow only a subset of callback queries to be passed
             in your callback function.
 
     Other parameters:
         client (:obj:`~pyrogram.Client`):
-            The Client itself, useful when you want to call other API methods inside the message handler.
+            The Client itself, useful when you want to call other API methods inside the callback query handler.
 
         callback_query (:obj:`~pyrogram.types.CallbackQuery`):
             The received callback query.
     """
 
-    def __init__(self, callback: Callable, filters=None):
+    def __init__(self, callback: CallbackFunc, filters: Filter = None):
         super().__init__(callback, filters)

pyrogram/handlers/chat_join_request_handler.py

@@ -16,10 +16,20 @@
 #  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 typing import Callable
+from typing import Any, Callable
 
+import pyrogram
+from pyrogram.filters import Filter
 from .handler import Handler
 
+CallbackFunc: Callable = Callable[
+    [
+        "pyrogram.Client",
+        pyrogram.types.ChatJoinRequest
+    ],
+    Any
+]
+
 
 class ChatJoinRequestHandler(Handler):
     """The ChatJoinRequest handler class. Used to handle join chat requests.
@@ -43,7 +53,8 @@ class ChatJoinRequestHandler(Handler):
 
         chat_join_request (:obj:`~pyrogram.types.ChatJoinRequest`):
             The received chat join request.
+
     """
 
-    def __init__(self, callback: Callable, filters=None):
+    def __init__(self, callback: CallbackFunc, filters: Filter = None):
         super().__init__(callback, filters)

pyrogram/handlers/chat_member_updated_handler.py

@@ -16,10 +16,20 @@
 #  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 typing import Callable
+from typing import Any, Callable
 
+import pyrogram
+from pyrogram.filters import Filter
 from .handler import Handler
 
+CallbackFunc: Callable = Callable[
+    [
+        "pyrogram.Client",
+        pyrogram.types.ChatMemberUpdated
+    ],
+    Any
+]
+
 
 class ChatMemberUpdatedHandler(Handler):
     """The ChatMemberUpdated handler class. Used to handle changes in the status of a chat member.
@@ -34,16 +44,18 @@ class ChatMemberUpdatedHandler(Handler):
             *(client, chat_member_updated)* as positional arguments (look at the section below for a detailed
             description).
 
-        filters (:obj:`Filters`):
+        filters (:obj:`Filter`):
             Pass one or more filters to allow only a subset of updates to be passed in your callback function.
 
     Other parameters:
         client (:obj:`~pyrogram.Client`):
-            The Client itself, useful when you want to call other API methods inside the handler.
+            The Client itself, useful when you want to call other API methods inside the chat member updated
+            handler.
 
         chat_member_updated (:obj:`~pyrogram.types.ChatMemberUpdated`):
             The received chat member update.
+
     """
 
-    def __init__(self, callback: Callable, filters=None):
+    def __init__(self, callback: CallbackFunc, filters: Filter = None):
         super().__init__(callback, filters)

pyrogram/handlers/chosen_inline_result_handler.py

@@ -16,10 +16,20 @@
 #  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 typing import Callable
+from typing import Any, Callable
 
+import pyrogram
+from pyrogram.filters import Filter
 from .handler import Handler
 
+CallbackFunc: Callable = Callable[
+    [
+        "pyrogram.Client",
+        pyrogram.types.ChosenInlineResult
+    ],
+    Any
+]
+
 
 class ChosenInlineResultHandler(Handler):
     """The ChosenInlineResultHandler handler class. Used to handle chosen inline results coming from inline queries.
@@ -38,17 +48,19 @@ class ChosenInlineResultHandler(Handler):
             It takes *(client, chosen_inline_result)* as positional arguments (look at the section below for a
             detailed description).
 
-        filters (:obj:`Filters`):
+        filters (:obj:`Filter`):
             Pass one or more filters to allow only a subset of chosen inline results to be passed
             in your callback function.
 
     Other parameters:
         client (:obj:`~pyrogram.Client`):
-            The Client itself, useful when you want to call other API methods inside the message handler.
+            The Client itself, useful when you want to call other API methods inside the choose inline result
+            handler.
 
         chosen_inline_result (:obj:`~pyrogram.types.ChosenInlineResult`):
             The received chosen inline result.
+
     """
 
-    def __init__(self, callback: Callable, filters=None):
+    def __init__(self, callback: CallbackFunc, filters: Filter = None):
         super().__init__(callback, filters)

pyrogram/handlers/deleted_messages_handler.py

@@ -16,13 +16,21 @@
 #  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 typing import Callable
+from typing import Any, Callable
 
 import pyrogram
 from pyrogram.filters import Filter
 from pyrogram.types import Message
 from .handler import Handler
 
+CallbackFunc: Callable = Callable[
+    [
+        "pyrogram.Client",
+        list[Message]
+    ],
+    Any
+]
+
 
 class DeletedMessagesHandler(Handler):
     """The deleted messages handler class. Used to handle deleted messages coming from any chat
@@ -36,19 +44,20 @@ class DeletedMessagesHandler(Handler):
             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`):
+        filters (:obj:`Filter`):
             Pass one or more filters to allow only a subset of messages to be passed
             in your callback function.
 
     Other parameters:
         client (:obj:`~pyrogram.Client`):
-            The Client itself, useful when you want to call other API methods inside the message handler.
+            The Client itself, useful when you want to call other API methods inside the deleted message handler.
 
         messages (List of :obj:`~pyrogram.types.Message`):
             The deleted messages, as list.
+
     """
 
-    def __init__(self, callback: Callable, filters: Filter = None):
+    def __init__(self, callback: CallbackFunc, filters: Filter = None):
         super().__init__(callback, filters)
 
     async def check(self, client: "pyrogram.Client", messages: list[Message]):

pyrogram/handlers/disconnect_handler.py

@@ -16,10 +16,13 @@
 #  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 typing import Callable
+from typing import Any, Callable
 
+import pyrogram
 from .handler import Handler
 
+CallbackFunc: Callable = Callable[["pyrogram.Client"], Any]
+
 
 class DisconnectHandler(Handler):
     """The Disconnect handler class. Used to handle disconnections. It is intended to be used with
@@ -37,7 +40,8 @@ class DisconnectHandler(Handler):
         client (:obj:`~pyrogram.Client`):
             The Client itself. Useful, for example, when you want to change the proxy before a new connection
             is established.
+
     """
 
-    def __init__(self, callback: Callable):
+    def __init__(self, callback: CallbackFunc):
         super().__init__(callback)

pyrogram/handlers/edited_message_handler.py

@@ -16,10 +16,20 @@
 #  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 typing import Callable
+from typing import Any, Callable
 
+import pyrogram
+from pyrogram.filters import Filter
 from .handler import Handler
 
+CallbackFunc: Callable = Callable[
+    [
+        "pyrogram.Client",
+        pyrogram.types.Message
+    ],
+    Any
+]
+
 
 class EditedMessageHandler(Handler):
     """The EditedMessage handler class. Used to handle edited messages.
@@ -43,7 +53,8 @@ class EditedMessageHandler(Handler):
 
         edited_message (:obj:`~pyrogram.types.Message`):
             The received edited message.
+
     """
 
-    def __init__(self, callback: Callable, filters=None):
+    def __init__(self, callback: CallbackFunc, filters: Filter = None):
         super().__init__(callback, filters)

pyrogram/handlers/handler.py

@@ -17,15 +17,17 @@
 #  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
 
 import inspect
-from typing import Callable
+from typing import Any, Callable
 
 import pyrogram
 from pyrogram.filters import Filter
 from pyrogram.types import Update
 
+CallbackFunc: Callable = Callable[..., Any]
+
 
 class Handler:
-    def __init__(self, callback: Callable, filters: Filter = None):
+    def __init__(self, callback: CallbackFunc, filters: Filter = None):
         self.callback = callback
         self.filters = filters
 

pyrogram/handlers/inline_query_handler.py

@@ -16,10 +16,20 @@
 #  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 typing import Callable
+from typing import Any, Callable
 
+import pyrogram
+from pyrogram.filters import Filter
 from .handler import Handler
 
+CallbackFunc: Callable = Callable[
+    [
+        "pyrogram.Client",
+        pyrogram.types.InlineQuery
+    ],
+    Any
+]
+
 
 class InlineQueryHandler(Handler):
     """The InlineQuery handler class. Used to handle inline queries.
@@ -33,7 +43,7 @@ class InlineQueryHandler(Handler):
             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`):
+        filters (:obj:`Filter`):
             Pass one or more filters to allow only a subset of inline queries to be passed
             in your callback function.
 
@@ -43,7 +53,8 @@ class InlineQueryHandler(Handler):
 
         inline_query (:obj:`~pyrogram.types.InlineQuery`):
             The received inline query.
+
     """
 
-    def __init__(self, callback: Callable, filters=None):
+    def __init__(self, callback: CallbackFunc, filters: Filter = None):
         super().__init__(callback, filters)