feat: update pyromod patch with changes from pyromod v3.1.5 (#8)

* feat: bring changes from pyromod v3.1.5
* chore: fix whitespace issues around function parameters

---------

Co-authored-by: Alisson Lauffer <alissonvitortc@gmail.com>

Author: usernein

pyrogram/client.py

@@ -336,11 +336,24 @@ async def listen(
         listener_type: ListenerTypes = ListenerTypes.MESSAGE,
         timeout: Optional[int] = None,
         unallowed_click_alert: bool = True,
-        chat_id: int = None,
-        user_id: int = None,
-        message_id: int = None,
-        inline_message_id: str = None,
+        chat_id: Union[Union[int, str], List[Union[int, str]]] = None,
+        user_id: Union[Union[int, str], List[Union[int, str]]] = None,
+        message_id: Union[int, List[int]] = None,
+        inline_message_id: Union[str, List[str]] = None,
     ):
+        """
+        Creates a listener and waits for it to be fulfilled.
+
+        :param filters: A filter to check if the listener should be fulfilled.
+        :param listener_type: The type of listener to create. Defaults to :attr:`pyromod.types.ListenerTypes.MESSAGE`.
+        :param timeout: The maximum amount of time to wait for the listener to be fulfilled. Defaults to ``None``.
+        :param unallowed_click_alert: Whether to alert the user if they click on a button that is not intended for them. Defaults to ``True``.
+        :param chat_id: The chat ID(s) to listen for. Defaults to ``None``.
+        :param user_id: The user ID(s) to listen for. Defaults to ``None``.
+        :param message_id: The message ID(s) to listen for. Defaults to ``None``.
+        :param inline_message_id: The inline message ID(s) to listen for. Defaults to ``None``.
+        :return: The Message or CallbackQuery that fulfilled the listener.
+        """
         pattern = Identifier(
             from_user_id=user_id,
             chat_id=chat_id,
@@ -350,15 +363,6 @@ async def listen(
 
         loop = asyncio.get_event_loop()
         future = loop.create_future()
-        future.add_done_callback(
-            lambda f: self.stop_listening(
-                listener_type,
-                user_id=user_id,
-                chat_id=chat_id,
-                message_id=message_id,
-                inline_message_id=inline_message_id,
-            )
-        )
 
         listener = Listener(
             future=future,
@@ -368,33 +372,58 @@ async def listen(
             listener_type=listener_type,
         )
 
+        future.add_done_callback(lambda _future: self.remove_listener(listener))
+
         self.listeners[listener_type].append(listener)
 
         try:
             return await asyncio.wait_for(future, timeout)
         except asyncio.exceptions.TimeoutError:
             if callable(PyromodConfig.timeout_handler):
-                PyromodConfig.timeout_handler(pattern, listener, timeout)
+                if inspect.iscoroutinefunction(PyromodConfig.timeout_handler.__call__):
+                    await PyromodConfig.timeout_handler(pattern, listener, timeout)
+                else:
+                    await self.loop.run_in_executor(
+                        None, PyromodConfig.timeout_handler, pattern, listener, timeout
+                    )
             elif PyromodConfig.throw_exceptions:
                 raise ListenerTimeout(timeout)
 
     async def ask(
         self,
-        chat_id: int,
+        chat_id: Union[Union[int, str], List[Union[int, str]]],
         text: str,
         filters: Optional[Filter] = None,
         listener_type: ListenerTypes = ListenerTypes.MESSAGE,
         timeout: Optional[int] = None,
         unallowed_click_alert: bool = True,
-        user_id: int = None,
-        message_id: int = None,
-        inline_message_id: str = None,
+        user_id: Union[Union[int, str], List[Union[int, str]]] = None,
+        message_id: Union[int, List[int]] = None,
+        inline_message_id: Union[str, List[str]] = None,
         *args,
         **kwargs,
     ):
+        """
+        Sends a message and waits for a response.
+
+        :param chat_id: The chat ID(s) to wait for a message from. The first chat ID will be used to send the message.
+        :param text: The text to send.
+        :param filters: Same as :meth:`pyromod.types.Client.listen`.
+        :param listener_type: Same as :meth:`pyromod.types.Client.listen`.
+        :param timeout: Same as :meth:`pyromod.types.Client.listen`.
+        :param unallowed_click_alert: Same as :meth:`pyromod.types.Client.listen`.
+        :param user_id: Same as :meth:`pyromod.types.Client.listen`.
+        :param message_id: Same as :meth:`pyromod.types.Client.listen`.
+        :param inline_message_id: Same as :meth:`pyromod.types.Client.listen`.
+        :param args: Additional arguments to pass to :meth:`pyrogram.Client.send_message`.
+        :param kwargs: Additional keyword arguments to pass to :meth:`pyrogram.Client.send_message`.
+        :return:
+            Same as :meth:`pyromod.types.Client.listen`. The sent message is returned as the attribute ``sent_message``.
+        """
         sent_message = None
         if text.strip() != "":
-            sent_message = await self.send_message(chat_id, text, *args, **kwargs)
+            chat_to_ask = chat_id[0] if isinstance(chat_id, list) else chat_id
+            sent_message = await self.send_message(chat_to_ask, text, *args, **kwargs)
 
         response = await self.listen(
             filters=filters,
@@ -411,12 +440,31 @@ async def ask(
 
         return response
 
-    def get_matching_listener(
-        self, pattern: Identifier, listener_type: ListenerTypes
+    def remove_listener(self, listener: Listener):
+        """
+        Removes a listener from the :meth:`pyromod.types.Client.listeners` dictionary.
+
+        :param listener: The listener to remove.
+        :return: ``void``
+        """
+        try:
+            self.listeners[listener.listener_type].remove(listener)
+        except ValueError:
+            pass
+
+    def get_listener_matching_with_data(
+            self, data: Identifier, listener_type: ListenerTypes
     ) -> Optional[Listener]:
+        """
+        Gets a listener that matches the given data.
+
+        :param data: A :class:`pyromod.types.Identifier` to match against.
+        :param listener_type: The type of listener to get. Must be a value from :class:`pyromod.types.ListenerTypes`.
+        :return: The listener that matches the given data or ``None`` if no listener matches.
+        """
         matching = []
         for listener in self.listeners[listener_type]:
-            if listener.identifier.matches(pattern):
+            if listener.identifier.matches(data):
                 matching.append(listener)
 
         # in case of multiple matching listeners, the most specific should be returned
@@ -425,44 +473,163 @@ def count_populated_attributes(listener_item: Listener):
 
         return max(matching, key=count_populated_attributes, default=None)
 
-    def remove_listener(self, listener: Listener):
-        self.listeners[listener.listener_type].remove(listener)
+    def get_listener_matching_with_identifier_pattern(
+            self, pattern: Identifier, listener_type: ListenerTypes
+    ) -> Optional[Listener]:
+        """
+        Gets a listener that matches the given identifier pattern.
+
+        The difference from :meth:`pyromod.types.Client.get_listener_matching_with_data` is that this method
+        intends to get a listener by passing partial info of the listener identifier, while the other method
+        intends to get a listener by passing the full info of the update data, which the listener should match with.
 
-    def get_many_matching_listeners(
-        self, pattern: Identifier, listener_type: ListenerTypes
+        :param pattern: A :class:`pyromod.types.Identifier` to match against.
+        :param listener_type: The type of listener to get. Must be a value from :class:`pyromod.types.ListenerTypes`.
+        :return: The listener that matches the given identifier pattern or ``None`` if no listener matches.
+        """
+        matching = []
+        for listener in self.listeners[listener_type]:
+            if pattern.matches(listener.identifier):
+                matching.append(listener)
+
+        # in case of multiple matching listeners, the most specific should be returned
+
+        def count_populated_attributes(listener_item: Listener):
+            return listener_item.identifier.count_populated()
+
+        return max(matching, key=count_populated_attributes, default=None)
+
+    def get_many_listeners_matching_with_data(
+        self,
+        data: Identifier,
+        listener_type: ListenerTypes,
     ) -> List[Listener]:
+        """
+        Same of :meth:`pyromod.types.Client.get_listener_matching_with_data` but returns a list of listeners instead of one.
+
+        :param data: Same as :meth:`pyromod.types.Client.get_listener_matching_with_data`.
+        :param listener_type: Same as :meth:`pyromod.types.Client.get_listener_matching_with_data`.
+        :return: A list of listeners that match the given data.
+        """
         listeners = []
         for listener in self.listeners[listener_type]:
-            if listener.identifier.matches(pattern):
+            if listener.identifier.matches(data):
                 listeners.append(listener)
         return listeners
 
-    def stop_listening(
+    def get_many_listeners_matching_with_identifier_pattern(
+        self,
+        pattern: Identifier,
+        listener_type: ListenerTypes,
+    ) -> List[Listener]:
+        """
+        Same of :meth:`pyromod.types.Client.get_listener_matching_with_identifier_pattern` but returns a list of listeners instead of one.
+
+        :param pattern: Same as :meth:`pyromod.types.Client.get_listener_matching_with_identifier_pattern`.
+        :param listener_type: Same as :meth:`pyromod.types.Client.get_listener_matching_with_identifier_pattern`.
+        :return: A list of listeners that match the given identifier pattern.
+        """
+        listeners = []
+        for listener in self.listeners[listener_type]:
+            if pattern.matches(listener.identifier):
+                listeners.append(listener)
+        return listeners
+
+    async def stop_listening(
         self,
         listener_type: ListenerTypes = ListenerTypes.MESSAGE,
-        chat_id: int = None,
-        user_id: int = None,
-        message_id: int = None,
-        inline_message_id: str = None,
+        chat_id: Union[Union[int, str], List[Union[int, str]]] = None,
+        user_id: Union[Union[int, str], List[Union[int, str]]] = None,
+        message_id: Union[int, List[int]] = None,
+        inline_message_id: Union[str, List[str]] = None,
     ):
+        """
+        Stops all listeners that match the given identifier pattern.
+        Uses :meth:`pyromod.types.Client.get_many_listeners_matching_with_identifier_pattern`.
+
+        :param listener_type: The type of listener to stop. Must be a value from :class:`pyromod.types.ListenerTypes`.
+        :param chat_id: The chat_id to match against.
+        :param user_id: The user_id to match against.
+        :param message_id: The message_id to match against.
+        :param inline_message_id: The inline_message_id to match against.
+        :return: ``void``
+        """
         pattern = Identifier(
             from_user_id=user_id,
             chat_id=chat_id,
             message_id=message_id,
             inline_message_id=inline_message_id,
         )
-        listeners = self.get_many_matching_listeners(pattern, listener_type)
+        listeners = self.get_many_listeners_matching_with_identifier_pattern(
+            pattern, listener_type
+        )
 
         for listener in listeners:
-            self.remove_listener(listener)
+            await self.stop_listener(listener)
 
-            if listener.future.done():
-                return
+    async def stop_listener(self, listener: Listener):
+        """
+        Stops a listener, calling stopped_handler if applicable or raising ListenerStopped if throw_exceptions is True.
 
-            if callable(PyromodConfig.stopped_handler):
-                PyromodConfig.stopped_handler(pattern, listener)
-            elif PyromodConfig.throw_exceptions:
-                listener.future.set_exception(ListenerStopped())
+        :param listener: The :class:`pyromod.types.Listener` to stop.
+        :return: ``void``
+        :raises ListenerStopped: If throw_exceptions is True.
+        """
+        self.remove_listener(listener)
+
+        if listener.future.done():
+            return
+
+        if callable(PyromodConfig.stopped_handler):
+            if inspect.iscoroutinefunction(PyromodConfig.stopped_handler.__call__):
+                await PyromodConfig.stopped_handler(None, listener)
+            else:
+                await self.loop.run_in_executor(
+                    None, PyromodConfig.stopped_handler, None, listener
+                )
+        elif PyromodConfig.throw_exceptions:
+            listener.future.set_exception(ListenerStopped())
+
+    def register_next_step_handler(
+        self,
+        callback: Callable,
+        filters: Optional[Filter] = None,
+        listener_type: ListenerTypes = ListenerTypes.MESSAGE,
+        unallowed_click_alert: bool = True,
+        chat_id: Union[Union[int, str], List[Union[int, str]]] = None,
+        user_id: Union[Union[int, str], List[Union[int, str]]] = None,
+        message_id: Union[int, List[int]] = None,
+        inline_message_id: Union[str, List[str]] = None,
+    ):
+        """
+        Registers a listener with a callback to be called when the listener is fulfilled.
+
+        :param callback: The callback to call when the listener is fulfilled.
+        :param filters: Same as :meth:`pyromod.types.Client.listen`.
+        :param listener_type: Same as :meth:`pyromod.types.Client.listen`.
+        :param unallowed_click_alert: Same as :meth:`pyromod.types.Client.listen`.
+        :param chat_id: Same as :meth:`pyromod.types.Client.listen`.
+        :param user_id: Same as :meth:`pyromod.types.Client.listen`.
+        :param message_id: Same as :meth:`pyromod.types.Client.listen`.
+        :param inline_message_id: Same as :meth:`pyromod.types.Client.listen`.
+        :return: ``void``
+        """
+        pattern = Identifier(
+            from_user_id=user_id,
+            chat_id=chat_id,
+            message_id=message_id,
+            inline_message_id=inline_message_id,
+        )
+
+        listener = Listener(
+            callback=callback,
+            filters=filters,
+            unallowed_click_alert=unallowed_click_alert,
+            identifier=pattern,
+            listener_type=listener_type,
+        )
+
+        self.listeners[listener_type].append(listener)
 
     async def authorize(self) -> User:
         if self.bot_token: