feat(pyromod): add bound methods and refactor listener logic

SychO3 · SychO3 · commit 2c84cd340121 · 2026-03-24T18:18:41.000+08:00
diff --git a/pyrogram/client.py b/pyrogram/client.py
@@ -444,8 +444,6 @@ def loop(self, value: asyncio.AbstractEventLoop):
 
         self.listeners = {listener_type: [] for listener_type in pyrogram.enums.ListenerTypes}
 
-        self.listeners = {listener_type: [] for listener_type in pyrogram.enums.ListenerTypes}
-
     def __enter__(self):
         return self.start()
 
diff --git a/pyrogram/enums/__init__.py b/pyrogram/enums/__init__.py
@@ -57,7 +57,7 @@
 from .suggested_post_state import SuggestedPostState
 from .upgraded_gift_origin import UpgradedGiftOrigin
 from .user_status import UserStatus
-from .listerner_types import ListenerTypes
+from .listener_types import ListenerTypes
 
 __all__ = [
     'BlockList',
diff --git a/pyrogram/enums/listener_types.py b/pyrogram/enums/listener_types.py
diff --git a/pyrogram/handlers/callback_query_handler.py b/pyrogram/handlers/callback_query_handler.py
@@ -140,18 +140,17 @@ async def check(self, client: "pyrogram.Client", query: CallbackQuery):
         else:
             handler_does_match = True
 
-        if PyromodConfig.unallowed_click_alert and listener:
+        if PyromodConfig.unallowed_click_alert and listener and not listener_does_match:
             data = self.compose_data_identifier(query)
             permissive_identifier = Identifier(
-                chat_id=data.chat_id,
-                message_id=data.message_id,
-                inline_message_id=data.inline_message_id,
+                chat_id=listener.identifier.chat_id,
+                message_id=listener.identifier.message_id,
+                inline_message_id=listener.identifier.inline_message_id,
                 from_user_id=None,
             )
 
             if (
                 permissive_identifier.matches(data)
-                and not listener_does_match
                 and listener.unallowed_click_alert
             ):
                 alert = (
@@ -188,18 +187,17 @@ async def resolve_future_or_callback(
                 try:
                     listener.future.set_result(query)
                 except asyncio.CancelledError:
-                    # Future cancelled during shutdown; stop propagation silently
                     raise pyrogram.StopPropagation
-
                 raise pyrogram.StopPropagation
+            elif listener.future and listener.future.done():
+                await self.original_callback(client, query, *args)
             elif listener.callback:
                 try:
                     await utils.invoke_callable(listener.callback, client, query, *args)
                 except asyncio.CancelledError:
                     raise pyrogram.StopPropagation
-
                 raise pyrogram.StopPropagation
             else:
-                raise ValueError("Listener must have either a future or a callback")
+                await self.original_callback(client, query, *args)
         else:
             await self.original_callback(client, query, *args)
diff --git a/pyrogram/handlers/message_handler.py b/pyrogram/handlers/message_handler.py
@@ -139,13 +139,13 @@ async def resolve_future_or_callback(self, client: "pyrogram.Client", message: M
                     listener.future.set_result(message)
                 except asyncio.CancelledError:
                     raise pyrogram.StopPropagation
-
                 raise pyrogram.StopPropagation
+            elif listener.future and listener.future.done():
+                await self.original_callback(client, message, *args)
             elif listener.callback:
                 await utils.invoke_callable(listener.callback, client, message, *args)
-
                 raise pyrogram.StopPropagation
             else:
-                raise ValueError("Listener must have either a future or a callback")
+                await self.original_callback(client, message, *args)
         else:
             await self.original_callback(client, message, *args)
diff --git a/pyrogram/methods/pyromod/__init__.py b/pyrogram/methods/pyromod/__init__.py
@@ -23,7 +23,7 @@
 from .get_many_listeners_matching_with_identifier_pattern import GetManyListenersMatchingWithIdentifierPattern
 from .listen import Listen
 from .register_next_step_handler import RegisterNextStepHandler
-from .remove_listerner import RemoveListener
+from .remove_listener import RemoveListener
 from .stop_listener import StopListener
 from .stop_listening import StopListening
 from .wait_for_callback_query import WaitForCallbackQuery
diff --git a/pyrogram/methods/pyromod/ask.py b/pyrogram/methods/pyromod/ask.py
@@ -17,10 +17,10 @@
 #  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
 
 import asyncio
-import inspect
 from typing import TYPE_CHECKING
 import pyrogram
 
+from pyrogram import utils
 from pyrogram.filters import Filter
 from pyrogram.errors import ListenerTimeout
 from pyrogram.types import Identifier, Listener
@@ -137,30 +137,19 @@ async def ask(
 
             try:
                 response = await asyncio.wait_for(future, timeout)
-            except asyncio.exceptions.TimeoutError:
+            except asyncio.TimeoutError:
                 if callable(PyromodConfig.timeout_handler):
-                    handler = PyromodConfig.timeout_handler
-
-                    if (
-                        inspect.iscoroutinefunction(handler)
-                        or inspect.iscoroutinefunction(getattr(handler, "__call__", None))
-                    ):
-                        result = handler(pattern, listener, timeout)
-                        if inspect.isawaitable(result):
-                            await result
-                    else:
-                        await self.loop.run_in_executor(
-                            None, handler, pattern, listener, timeout
-                        )
+                    await utils.invoke_callable(
+                        PyromodConfig.timeout_handler, pattern, listener, timeout,
+                        executor=self.executor, loop=self.loop
+                    )
                 elif PyromodConfig.throw_exceptions:
-                    # Remove listener before raising
                     try:
                         self.remove_listener(listener)
                     except Exception:
                         pass
                     raise ListenerTimeout(timeout)
 
-                # Cleanup listener on timeout to avoid zombie listeners
                 try:
                     self.remove_listener(listener)
                 except Exception:
diff --git a/pyrogram/methods/pyromod/get_listener_matching_with_data.py b/pyrogram/methods/pyromod/get_listener_matching_with_data.py
@@ -33,7 +33,7 @@ def get_listener_matching_with_data(
 
         Parameters:
             data (:obj:`~pyrogram.types.Identifier`):
-                The Identifier to match agains.
+                The Identifier to match against.
 
             listener_type (:obj:`~pyrogram.enums.ListenerTypes`):
                 The type of listener to get.
diff --git a/pyrogram/methods/pyromod/get_listener_matching_with_identifier_pattern.py b/pyrogram/methods/pyromod/get_listener_matching_with_identifier_pattern.py
@@ -37,7 +37,7 @@ def get_listener_matching_with_identifier_pattern(
 
         Parameters:
             pattern (:obj:`~pyrogram.types.Identifier`):
-                The Identifier to match agains.
+                The Identifier to match against.
 
             listener_type (:obj:`~pyrogram.enums.ListenerTypes`):
                 The type of listener to get.
diff --git a/pyrogram/methods/pyromod/get_many_listeners_matching_with_data.py b/pyrogram/methods/pyromod/get_many_listeners_matching_with_data.py
@@ -27,13 +27,13 @@ def get_many_listeners_matching_with_data(
         data: Identifier,
         listener_type: "pyrogram.enums.ListenerTypes",
     ) -> List[Listener]:
-        """Gets multiple listener that matches the given data.
+        """Gets multiple listeners that match the given data.
 
         .. include:: /_includes/usable-by/users-bots.rst
 
         Parameters:
             data (:obj:`~pyrogram.types.Identifier`):
-                The Identifier to match agains.
+                The Identifier to match against.
 
             listener_type (:obj:`~pyrogram.enums.ListenerTypes`):
                 The type of listener to get.
diff --git a/pyrogram/methods/pyromod/get_many_listeners_matching_with_identifier_pattern.py b/pyrogram/methods/pyromod/get_many_listeners_matching_with_identifier_pattern.py
@@ -27,7 +27,7 @@ def get_many_listeners_matching_with_identifier_pattern(
         pattern: Identifier,
         listener_type: "pyrogram.enums.ListenerTypes",
     ) -> List[Listener]:
-        """Gets multiple listener that matches the given identifier pattern.
+        """Gets multiple listeners that match the given identifier pattern.
 
         .. include:: /_includes/usable-by/users-bots.rst
 
@@ -37,7 +37,7 @@ def get_many_listeners_matching_with_identifier_pattern(
 
         Parameters:
             pattern (:obj:`~pyrogram.types.Identifier`):
-                The Identifier to match agains.
+                The Identifier to match against.
 
             listener_type (:obj:`~pyrogram.enums.ListenerTypes`):
                 The type of listener to get.
diff --git a/pyrogram/methods/pyromod/listen.py b/pyrogram/methods/pyromod/listen.py
@@ -17,9 +17,9 @@
 #  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
 
 import asyncio
-import inspect
 import pyrogram
 
+from pyrogram import utils
 from pyrogram.errors import ListenerTimeout
 from pyrogram.filters import Filter
 from typing import List, Optional, Union
@@ -108,24 +108,14 @@ async def listen(
 
         try:
             return await asyncio.wait_for(future, timeout)
-        except asyncio.exceptions.TimeoutError:
+        except asyncio.TimeoutError:
             if callable(PyromodConfig.timeout_handler):
-                handler = PyromodConfig.timeout_handler
-
-                if (
-                    inspect.iscoroutinefunction(handler)
-                    or inspect.iscoroutinefunction(getattr(handler, "__call__", None))
-                ):
-                    result = handler(pattern, listener, timeout)
-                    if inspect.isawaitable(result):
-                        await result
-                else:
-                    await self.loop.run_in_executor(
-                        None, handler, pattern, listener, timeout
-                    )
+                await utils.invoke_callable(
+                    PyromodConfig.timeout_handler, pattern, listener, timeout,
+                    executor=self.executor, loop=self.loop
+                )
             elif PyromodConfig.throw_exceptions:
                 raise ListenerTimeout(timeout)
-            # Cleanup listener on timeout to avoid zombie listeners
             try:
                 self.remove_listener(listener)
             except Exception:
diff --git a/pyrogram/methods/pyromod/register_next_step_handler.py b/pyrogram/methods/pyromod/register_next_step_handler.py
@@ -81,4 +81,6 @@ def register_next_step_handler(
             listener_type=listener_type,
         )
 
-        self.listeners[listener_type].append(listener)
+        self.listeners[listener_type].append(listener)
+
+        return listener
diff --git a/pyrogram/methods/pyromod/remove_listener.py b/pyrogram/methods/pyromod/remove_listener.py
diff --git a/pyrogram/methods/pyromod/stop_listener.py b/pyrogram/methods/pyromod/stop_listener.py
@@ -16,9 +16,9 @@
 #  You should have received a copy of the GNU Lesser General Public License
 #  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
 
-import inspect
 import pyrogram
 
+from pyrogram import utils
 from pyrogram.errors import ListenerStopped
 from pyrogram.types import Listener
 from pyrogram.utils import PyromodConfig
@@ -41,20 +41,17 @@ async def stop_listener(
         """
         self.remove_listener(listener)
 
-        if listener.future.done():
+        if listener.future and listener.future.done():
             return
 
         if callable(PyromodConfig.stopped_handler):
-            handler = PyromodConfig.stopped_handler
-
-            if (
-                inspect.iscoroutinefunction(handler)
-                or inspect.iscoroutinefunction(getattr(handler, "__call__", None))
-            ):
-                result = handler(None, listener)
-                if inspect.isawaitable(result):
-                    await result
+            await utils.invoke_callable(
+                PyromodConfig.stopped_handler, listener,
+                executor=self.executor, loop=self.loop
+            )
+
+        if listener.future and not listener.future.done():
+            if PyromodConfig.throw_exceptions:
+                listener.future.set_exception(ListenerStopped())
             else:
-                await self.loop.run_in_executor(None, handler, None, listener)
-        elif PyromodConfig.throw_exceptions:
-            listener.future.set_exception(ListenerStopped())
+                listener.future.cancel()
diff --git a/pyrogram/types/messages_and_media/message.py b/pyrogram/types/messages_and_media/message.py
@@ -9436,3 +9436,42 @@ async def summarize(self, translate_to_language_code: Optional[str] = None) -> "
             message_id=self.id,
             translate_to_language_code=translate_to_language_code
         )
+
+    async def wait_for_click(
+        self,
+        from_user_id=None,
+        timeout=None,
+        filters=None,
+        alert=True,
+    ):
+        """Bound method *wait_for_click* of :obj:`~pyrogram.types.Message`.
+
+        Waits for a callback query (inline button click) on this message.
+
+        Parameters:
+            from_user_id (``int`` | ``str`` | Iterable, *optional*):
+                The user ID to listen for. If None, listens for any user.
+
+            timeout (``int``, *optional*):
+                Maximum time to wait in seconds.
+
+            filters (:obj:`~pyrogram.filters`, *optional*):
+                A filter to check the callback query against.
+
+            alert (``str`` | ``bool``, *optional*):
+                Alert text for unallowed clicks. True uses default text.
+
+        Returns:
+            :obj:`~pyrogram.types.CallbackQuery`: The received callback query.
+        """
+        message_id = getattr(self, "id", getattr(self, "message_id", None))
+
+        return await self._client.listen(
+            listener_type=pyrogram.enums.ListenerTypes.CALLBACK_QUERY,
+            timeout=timeout,
+            filters=filters,
+            unallowed_click_alert=alert,
+            chat_id=self.chat.id,
+            user_id=from_user_id,
+            message_id=message_id,
+        )
diff --git a/pyrogram/types/user_and_chats/chat.py b/pyrogram/types/user_and_chats/chat.py
@@ -1940,3 +1940,30 @@ async def unmute(self) -> bool:
             ``bool``: On success, True is returned.
         """
         return await self._client.update_chat_notifications(self.id, mute=False)
+
+    def listen(self, *args, **kwargs):
+        """Bound method *listen* of :obj:`~pyrogram.types.Chat`.
+
+        Listens for a message or callback query in this chat.
+        Uses the same parameters as :meth:`~pyrogram.Client.listen`,
+        with ``chat_id`` automatically set.
+        """
+        return self._client.listen(*args, chat_id=self.id, **kwargs)
+
+    def ask(self, text, *args, **kwargs):
+        """Bound method *ask* of :obj:`~pyrogram.types.Chat`.
+
+        Sends a message to this chat and waits for a response.
+        Uses the same parameters as :meth:`~pyrogram.Client.ask`,
+        with ``chat_id`` automatically set.
+        """
+        return self._client.ask(self.id, text, *args, **kwargs)
+
+    def stop_listening(self, *args, **kwargs):
+        """Bound method *stop_listening* of :obj:`~pyrogram.types.Chat`.
+
+        Stops listening for messages in this chat.
+        Uses the same parameters as :meth:`~pyrogram.Client.stop_listening`,
+        with ``chat_id`` automatically set.
+        """
+        return self._client.stop_listening(*args, chat_id=self.id, **kwargs)
diff --git a/pyrogram/types/user_and_chats/user.py b/pyrogram/types/user_and_chats/user.py
@@ -940,3 +940,30 @@ async def get_common_chats(self):
         """
 
         return await self._client.get_common_chats(self.id)
+
+    def listen(self, *args, **kwargs):
+        """Bound method *listen* of :obj:`~pyrogram.types.User`.
+
+        Listens for a message or callback query from this user.
+        Uses the same parameters as :meth:`~pyrogram.Client.listen`,
+        with ``user_id`` automatically set.
+        """
+        return self._client.listen(*args, user_id=self.id, **kwargs)
+
+    def ask(self, text, *args, **kwargs):
+        """Bound method *ask* of :obj:`~pyrogram.types.User`.
+
+        Sends a message to this user and waits for a response.
+        Uses the same parameters as :meth:`~pyrogram.Client.ask`,
+        with ``user_id`` automatically set.
+        """
+        return self._client.ask(self.id, text, *args, user_id=self.id, **kwargs)
+
+    def stop_listening(self, *args, **kwargs):
+        """Bound method *stop_listening* of :obj:`~pyrogram.types.User`.
+
+        Stops listening for messages from this user.
+        Uses the same parameters as :meth:`~pyrogram.Client.stop_listening`,
+        with ``user_id`` automatically set.
+        """
+        return self._client.stop_listening(*args, user_id=self.id, **kwargs)
