hydrogram · alissonlauffer · Jan 16, 2024 · Nov 8, 2023 · Dec 2, 2023 · Dec 2, 2023
diff --git a/compiler/docs/compiler.py b/compiler/docs/compiler.py
@@ -581,13 +581,19 @@ def get_title_list(s: str) -> list:
             Chat.mark_unread
             Chat.set_protected_content
             Chat.unpin_all_messages
+            Chat.ask
+            Chat.listen
+            Chat.stop_listening
         """,
         "user": """
         User
             User.archive
             User.unarchive
             User.block
             User.unblock
+            User.ask
+            User.listen
+            User.stop_listening
         """,
         "callback_query": """
         Callback Query

diff --git a/hydrogram/client.py b/hydrogram/client.py
@@ -51,7 +51,7 @@
 from hydrogram.methods import Methods
 from hydrogram.session import Auth, Session
 from hydrogram.storage import BaseStorage, SQLiteStorage
-from hydrogram.types import TermsOfService, User
+from hydrogram.types import ListenerTypes, TermsOfService, User
 from hydrogram.utils import ainput
 
 from .dispatcher import Dispatcher
@@ -310,6 +310,7 @@ def __init__(
         self.last_update_time = datetime.now()
 
         self.loop = asyncio.get_event_loop()
+        self.listeners = {listener_type: [] for listener_type in ListenerTypes}
 
     def __enter__(self):
         return self.start()

diff --git a/hydrogram/errors/__init__.py b/hydrogram/errors/__init__.py
@@ -493,6 +493,7 @@
     service_unavailable_503,
     unauthorized_401,
 )
+from .pyromod import ListenerStopped, ListenerTimeout
 from .rpc_error import UnknownError
 
 
@@ -955,6 +956,8 @@ def __init__(self, msg: Optional[str] = None):
     "TypesEmpty",
     "Unauthorized",
     "UnknownError",
+    "ListenerStopped",
+    "ListenerTimeout",
     "UnknownMethod",
     "UntilDateInvalid",
     "UploadNoVolume",

diff --git a/hydrogram/errors/pyromod/__init__.py b/hydrogram/errors/pyromod/__init__.py
@@ -0,0 +1,23 @@
+#  Hydrogram - Telegram MTProto API Client Library for Python
+#  Copyright (C) 2020-present Cezar H. <https://github.com/usernein>
+#  Copyright (C) 2023-present Amano LLC <https://amanoteam.com>
+#
+#  This file is part of Hydrogram.
+#
+#  Hydrogram 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.
+#
+#  Hydrogram 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 Hydrogram.  If not, see <http://www.gnu.org/licenses/>.
+
+from .listener_stopped import ListenerStopped
+from .listener_timeout import ListenerTimeout
+
+__all__ = ["ListenerStopped", "ListenerTimeout"]
diff --git a/hydrogram/errors/pyromod/listener_stopped.py b/hydrogram/errors/pyromod/listener_stopped.py
@@ -0,0 +1,22 @@
+#  Hydrogram - Telegram MTProto API Client Library for Python
+#  Copyright (C) 2020-present Cezar H. <https://github.com/usernein>
+#  Copyright (C) 2023-present Amano LLC <https://amanoteam.com>
+#
+#  This file is part of Hydrogram.
+#
+#  Hydrogram 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.
+#
+#  Hydrogram 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 Hydrogram.  If not, see <http://www.gnu.org/licenses/>.
+
+
+class ListenerStopped(Exception):  # noqa: N818
+    pass
diff --git a/hydrogram/errors/pyromod/listener_timeout.py b/hydrogram/errors/pyromod/listener_timeout.py
@@ -0,0 +1,22 @@
+#  Hydrogram - Telegram MTProto API Client Library for Python
+#  Copyright (C) 2020-present Cezar H. <https://github.com/usernein>
+#  Copyright (C) 2023-present Amano LLC <https://amanoteam.com>
+#
+#  This file is part of Hydrogram.
+#
+#  Hydrogram 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.
+#
+#  Hydrogram 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 Hydrogram.  If not, see <http://www.gnu.org/licenses/>.
+
+
+class ListenerTimeout(Exception):  # noqa: N818
+    pass
diff --git a/hydrogram/handlers/callback_query_handler.py b/hydrogram/handlers/callback_query_handler.py
@@ -17,7 +17,12 @@
 #  You should have received a copy of the GNU Lesser General Public License
 #  along with Hydrogram.  If not, see <http://www.gnu.org/licenses/>.
 
-from typing import Callable
+from asyncio import iscoroutinefunction
+from typing import Callable, Optional
+
+import hydrogram
+from hydrogram.types import CallbackQuery, Identifier, Listener, ListenerTypes
+from hydrogram.utils import PyromodConfig
 
 from .handler import Handler
 
@@ -47,4 +52,169 @@ class CallbackQueryHandler(Handler):
     """
 
     def __init__(self, callback: Callable, filters=None):
-        super().__init__(callback, filters)
+        self.original_callback = callback
+        super().__init__(self.resolve_future_or_callback, filters)
+
+    def compose_data_identifier(self, query: CallbackQuery) -> Identifier:
+        """
+        Composes an Identifier object from a CallbackQuery object.
+
+        Parameters:
+            query (:obj:`~hydrogram.types.CallbackQuery`):
+                The CallbackQuery object to compose of.
+
+        Returns:
+            :obj:`~hydrogram.types.Identifier`: An Identifier object.
+        """
+        from_user = query.from_user
+        from_user_id = from_user.id if from_user else None
+        from_user_username = from_user.username if from_user else None
+
+        chat_id = None
+        message_id = None
+
+        if query.message:
+            message_id = getattr(query.message, "id", getattr(query.message, "message_id", None))
+
+            if query.message.chat:
+                chat_id = [query.message.chat.id, query.message.chat.username]
+
+        return Identifier(
+            message_id=message_id,
+            chat_id=chat_id,
+            from_user_id=[from_user_id, from_user_username],
+            inline_message_id=query.inline_message_id,
+        )
+
+    async def check_if_has_matching_listener(
+        self, client: "hydrogram.Client", query: CallbackQuery
+    ) -> tuple[bool, Optional[Listener]]:
+        """
+        Checks if the CallbackQuery object has a matching listener.
+
+        Parameters:
+            client (:obj:`~hydrogram.Client`):
+                The Client object to check with.
+
+            query (:obj:`~hydrogram.types.CallbackQuery`):
+                The CallbackQuery object to check with.
+
+        Returns:
+            A tuple of whether the CallbackQuery object has a matching listener and its filters does match with the
+            CallbackQuery and the matching listener;
+        """
+        data = self.compose_data_identifier(query)
+
+        listener = client.get_listener_matching_with_data(data, ListenerTypes.CALLBACK_QUERY)
+
+        listener_does_match = False
+
+        if listener:
+            filters = listener.filters
+            if callable(filters):
+                if iscoroutinefunction(filters.__call__):
+                    listener_does_match = await filters(client, query)
+                else:
+                    listener_does_match = await client.loop.run_in_executor(
+                        None, filters, client, query
+                    )
+            else:
+                listener_does_match = True
+
+        return listener_does_match, listener
+
+    async def check(self, client: "hydrogram.Client", query: CallbackQuery) -> bool:
+        """
+        Checks if the CallbackQuery object has a matching listener or handler.
+
+        Parameters:
+            client (:obj:`~hydrogram.Client`):
+                The Client object to check with.
+
+            query (:obj:`~hydrogram.types.CallbackQuery`):
+                The CallbackQuery object to check with.
+
+        Returns:
+            ``bool``: A boolean indicating whether the CallbackQuery object has a matching listener or the handler filter matches.
+        """
+        listener_does_match, listener = await self.check_if_has_matching_listener(client, query)
+
+        if callable(self.filters):
+            if iscoroutinefunction(self.filters.__call__):
+                handler_does_match = await self.filters(client, query)
+            else:
+                handler_does_match = await client.loop.run_in_executor(
+                    None, self.filters, client, query
+                )
+        else:
+            handler_does_match = True
+
+        data = self.compose_data_identifier(query)
+
+        if PyromodConfig.unallowed_click_alert:
+            # matches with the current query but from any user
+            permissive_identifier = Identifier(
+                chat_id=data.chat_id,
+                message_id=data.message_id,
+                inline_message_id=data.inline_message_id,
+                from_user_id=None,
+            )
+
+            matches = permissive_identifier.matches(data)
+
+            if (
+                listener
+                and (matches and not listener_does_match)
+                and listener.unallowed_click_alert
+            ):
+                alert = (
+                    listener.unallowed_click_alert
+                    if isinstance(listener.unallowed_click_alert, str)
+                    else PyromodConfig.unallowed_click_alert_text
+                )
+                await query.answer(alert)
+                return False
+
+        # let handler get the chance to handle if listener
+        # exists but its filters doesn't match
+        return listener_does_match or handler_does_match
+
+    async def resolve_future_or_callback(
+        self, client: "hydrogram.Client", query: CallbackQuery, *args
+    ) -> None:
+        """
+        Resolves the future or calls the callback of the listener. Will call the original handler if no listener.
+
+        Parameters:
+            client (:obj:`~hydrogram.Client`):
+                The Client object to resolve or call with.
+
+            query (:obj:`~hydrogram.types.CallbackQuery`):
+                The CallbackQuery object to resolve or call with.
+
+            args:
+                The arguments to call the callback with.
+
+        Returns:
+            ``None``
+        """
+        listener_does_match, listener = await self.check_if_has_matching_listener(client, query)
+
+        if listener and listener_does_match:
+            client.remove_listener(listener)
+
+            if listener.future and not listener.future.done():
+                listener.future.set_result(query)
+
+                raise hydrogram.StopPropagation
+            if listener.callback:
+                if iscoroutinefunction(listener.callback):
+                    await listener.callback(client, query, *args)
+                else:
+                    listener.callback(client, query, *args)
+
+                raise hydrogram.StopPropagation
+
+            raise ValueError("Listener must have either a future or a callback")
+
+        await self.original_callback(client, query, *args)