Pyrofork: Add pyromod documentation

Signed-off-by: wulan17 <wulan17@nusantararom.org>

compiler/docs/compiler.py

@@ -147,6 +147,21 @@ def pyrogram_api():
             export_session_string
             set_parse_mode
         """,
+        conversation="""
+        Conversation
+            ask
+            listen
+            get_listener_matching_with_data
+            get_listener_matching_with_identifier_pattern
+            get_many_listeners_matching_with_data
+            get_many_listeners_matching_with_identifier_pattern
+            register_next_step_handler
+            remove_listener
+            stop_listener
+            stop_listening
+            wait_for_callback_query
+            wait_for_message
+        """,
         messages="""
         Messages
             send_message
@@ -479,6 +494,12 @@ def pyrogram_api():
             StoriesPrivacyRules
             StoryViews
         """,
+        pyromod="""
+        Pyromod
+            Identifier
+            Listener
+            ListenerTypes
+        """,
         bot_keyboards="""
         Bot keyboards
             ReplyKeyboardMarkup
@@ -591,6 +612,7 @@ def pyrogram_api():
     categories = dict(
         message="""
         Message
+            Message.ask
             Message.click
             Message.delete
             Message.download
@@ -625,9 +647,13 @@ def pyrogram_api():
             Message.reply_web_page
             Message.get_media_group
             Message.react
+            Message.wait_for_click
         """,
         chat="""
         Chat
+            Chat.ask
+            Chat.listen
+            Chat.stop_listening
             Chat.archive
             Chat.unarchive
             Chat.set_title
@@ -648,6 +674,9 @@ def pyrogram_api():
         """,
         user="""
         User
+            User.ask
+            User.listen
+            User.stop_listening
             User.archive
             User.unarchive
             User.block

compiler/docs/template/methods.rst

@@ -47,6 +47,19 @@ Utilities
 
 .. currentmodule:: pyrogram.Client
 
+Conversation
+------------
+
+.. autosummary::
+    :nosignatures:
+
+    {conversation}
+
+.. toctree::
+    :hidden:
+
+    {conversation}
+
 Messages
 --------
 
@@ -87,7 +100,7 @@ Chats
     {chats}
 
 Stickers
------
+--------
 
 .. autosummary::
     :nosignatures:

compiler/docs/template/types.rst

@@ -60,6 +60,19 @@ Stories
 
     {stories}
 
+Pyromod
+-------
+
+.. autosummary::
+    :nosignatures:
+
+    {pyromod}
+
+.. toctree::
+    :hidden:
+
+    {pyromod}
+
 Bot keyboards
 -------------
 

pyrogram/methods/messages/__init__.py

@@ -65,8 +65,6 @@ from .send_web_page import SendWebPage
 from .stop_poll import StopPoll
 from .stream_media import StreamMedia
 from .vote_poll import VotePoll
-from .wait_for_message import WaitForMessage
-from .wait_for_callback_query import WaitForCallbackQuery
 
 
 class Messages(
@@ -118,8 +116,6 @@ class Messages(
     GetDiscussionReplies,
     GetDiscussionRepliesCount,
     StreamMedia,
-    GetCustomEmojiStickers,
+    GetCustomEmojiStickers
-    WaitForMessage,
-    WaitForCallbackQuery
 ):
     pass

pyrogram/methods/pyromod/__init__.py

@@ -26,6 +26,8 @@ from .register_next_step_handler import RegisterNextStepHandler
 from .remove_listerner import RemoveListener
 from .stop_listener import StopListener
 from .stop_listening import StopListening
+from .wait_for_callback_query import WaitForCallbackQuery
+from .wait_for_message import WaitForMessage
 
 class Pyromod(
     Ask,
@@ -37,6 +39,8 @@ class Pyromod(
     RegisterNextStepHandler,
     RemoveListener,
     StopListener,
-    StopListening
+    StopListening,
+    WaitForCallbackQuery,
+    WaitForMessage
 ):
     pass

pyrogram/methods/pyromod/ask.py

@@ -38,22 +38,50 @@ class Ask:
         *args,
         **kwargs,
     ):
-        """
+        """Send a message then listen for a message, callback query, etc.
-        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.
+        Message:
-        :param text: The text to send.
+
-        :param filters: Same as :meth:`pyromod.types.Client.listen`.
+        .. include:: /_includes/usable-by/users-bots.rst
-        :param listener_type: Same as :meth:`pyromod.types.Client.listen`.
+
-        :param timeout: Same as :meth:`pyromod.types.Client.listen`.
+        CallbackQuery:
-        :param unallowed_click_alert: Same as :meth:`pyromod.types.Client.listen`.
+
-        :param user_id: Same as :meth:`pyromod.types.Client.listen`.
+        .. include:: /_includes/usable-by/bots.rst
-        :param message_id: Same as :meth:`pyromod.types.Client.listen`.
+
-        :param inline_message_id: Same as :meth:`pyromod.types.Client.listen`.
+        Parameters:
-        :param args: Additional arguments to pass to :meth:`pyrogram.Client.send_message`.
+            chat_id (``int`` | ``str`` | Iterable of ``int`` | Iterable of ``str``):
-        :param kwargs: Additional keyword arguments to pass to :meth:`pyrogram.Client.send_message`.
+                Unique identifier (int) or username (str) of the target chat.
-        :return:
+
-            Same as :meth:`pyromod.types.Client.listen`. The sent message is returned as the attribute ``sent_message``.
+            text (``str``):
+                Text of the message to be sent.
+
+            user_id (``int`` | ``str`` | Iterable of ``int`` | Iterable of ``str``, *optional*):
+                The user ID to listen for.
+
+            filters (:obj:`~pyrogram.filters`, *optional*):
+                A filter to check the incoming message against.
+
+            listener_type (:obj:`~pyrogram.types.ListenerTypes`, *optional*):
+                The type of listener to listen for.
+                Default to Message.
+
+            timeout (``int``, *optional*):
+                The maximum amount of time to wait for a message.
+
+            unallowed_click_alert (``bool``, *optional*):
+                Whether to alert the user if they click a button that doesn’t match the filters.
+                Default to True.
+
+            inline_message_id (``str``, *optional*):
+                The inline message ID to listen for.
+
+        Returns:
+            :obj:`~pyrogram.types.Message` | :obj:`~pyrogram.types.CallbackQuery`: On success, a message/callbackquery is returned.
+
+        Example:
+            .. code-block:: python
+
+                await app.ask(chat_id, "Tell me your name:")
         """
         sent_message = None
         if text.strip() != "":

pyrogram/methods/pyromod/get_listener_matching_with_data.py

@@ -28,12 +28,19 @@ class GetListenerMatchingWithData:
         data: Identifier,
         listener_type: ListenerTypes
     ) -> Optional[Listener]:
-        """
+        """Gets a listener that matches the given data.
-        Gets a listener that matches the given data.
 
-        :param data: A :class:`pyromod.types.Identifier` to match against.
+        .. include:: /_includes/usable-by/users-bots.rst
-        :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.
+        Parameters:
+            data (:obj:`~pyrogram.types.Identifier`):
+                The Identifier to match agains.
+
+            listener_type (:obj:`~pyrogram.types.ListenerTypes`):
+                The type of listener to get.
+
+        Returns:
+            :obj:`~pyrogram.types.Listener`: On success, a Listener is returned.
         """
         matching = []
         for listener in self.listeners[listener_type]:

pyrogram/methods/pyromod/get_listener_matching_with_identifier_pattern.py

@@ -28,16 +28,23 @@ class GetListenerMatchingWithIdentifierPattern:
         pattern: Identifier,
         listener_type: ListenerTypes
     ) -> Optional[Listener]:
-        """
+        """Gets a listener that matches the given identifier pattern.
-        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
+        .. include:: /_includes/usable-by/users-bots.rst
+
+        The difference from :meth:`~pyrogram.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.
 
-        :param pattern: A :class:`pyromod.types.Identifier` to match against.
+        Parameters:
-        :param listener_type: The type of listener to get. Must be a value from :class:`pyromod.types.ListenerTypes`.
+            pattern (:obj:`~pyrogram.types.Identifier`):
-        :return: The listener that matches the given identifier pattern or ``None`` if no listener matches.
+                The Identifier to match agains.
+
+            listener_type (:obj:`~pyrogram.types.ListenerTypes`):
+                The type of listener to get.
+
+        Returns:
+            :obj:`~pyrogram.types.Listener`: On success, a Listener is returned.
         """
         matching = []
         for listener in self.listeners[listener_type]:

pyrogram/methods/pyromod/get_many_listeners_matching_with_data.py

@@ -28,12 +28,19 @@ class GetManyListenersMatchingWithData:
         data: Identifier,
         listener_type: ListenerTypes,
     ) -> List[Listener]:
-        """
+        """Gets multiple listener that matches the given data.
-        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`.
+        .. include:: /_includes/usable-by/users-bots.rst
-        :param listener_type: Same as :meth:`pyromod.types.Client.get_listener_matching_with_data`.
+
-        :return: A list of listeners that match the given data.
+        Parameters:
+            data (:obj:`~pyrogram.types.Identifier`):
+                The Identifier to match agains.
+
+            listener_type (:obj:`~pyrogram.types.ListenerTypes`):
+                The type of listener to get.
+
+        Returns:
+            List of :obj:`~pyrogram.types.Listener`: On success, a list of Listener is returned.
         """
         listeners = []
         for listener in self.listeners[listener_type]:

pyrogram/methods/pyromod/get_many_listeners_matching_with_identifier_pattern.py

@@ -28,12 +28,23 @@ class GetManyListenersMatchingWithIdentifierPattern:
         pattern: Identifier,
         listener_type: ListenerTypes,
     ) -> List[Listener]:
-        """
+        """Gets multiple listener that matches the given identifier pattern.
-        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`.
+        .. include:: /_includes/usable-by/users-bots.rst
-        :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.
+        The difference from :meth:`~pyrogram.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.
+
+        Parameters:
+            pattern (:obj:`~pyrogram.types.Identifier`):
+                The Identifier to match agains.
+
+            listener_type (:obj:`~pyrogram.types.ListenerTypes`):
+                The type of listener to get.
+
+        Returns:
+            List of :obj:`~pyrogram.types.Listener`: On success, a list of Listener is returned.
         """
         listeners = []
         for listener in self.listeners[listener_type]:

pyrogram/methods/pyromod/listen.py

@@ -39,19 +39,52 @@ class Listen:
         message_id: Union[int, List[int]] = None,
         inline_message_id: Union[str, List[str]] = None,
     ):
-        """
+        """Listen for a message, callback query, etc.
-        Creates a listener and waits for it to be fulfilled.
 
-        :param filters: A filter to check if the listener should be fulfilled.
+        Message:
-        :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``.
+        .. include:: /_includes/usable-by/users-bots.rst
-        :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``.
+        CallbackQuery:
-        :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``.
+        .. include:: /_includes/usable-by/bots.rst
-        :param inline_message_id: The inline message ID(s) to listen for. Defaults to ``None``.
+
-        :return: The Message or CallbackQuery that fulfilled the listener.
+        Parameters:
+            chat_id (``int`` | ``str`` | Iterable of ``int`` | Iterable of ``str``, *optional*):
+                Unique identifier (int) or username (str) of the target chat.
+
+            user_id (``int`` | ``str`` | Iterable of ``int`` | Iterable of ``str``, *optional*):
+                The user ID to listen for.
+
+            filters (:obj:`~pyrogram.filters`, *optional*):
+                A filter to check the incoming message against.
+
+            listener_type (:obj:`~pyrogram.types.ListenerTypes`, *optional*):
+                The type of listener to listen for.
+                Default to Message.
+
+            timeout (``int``, *optional*):
+                The maximum amount of time to wait for a message.
+
+            unallowed_click_alert (``bool``, *optional*):
+                Whether to alert the user if they click a button that doesn’t match the filters.
+                Default to True.
+
+            message_id (``int``, *optional*):
+                The message ID to listen for.
+
+            inline_message_id (``str``, *optional*):
+                The inline message ID to listen for.
+
+        Returns:
+            :obj:`~pyrogram.types.Message` | :obj:`~pyrogram.types.CallbackQuery`: On success, a message/callbackquery is returned.
+
+        Example:
+            .. code-block:: python
+
+                await app.listen(chat_id)
         """
+
         pattern = Identifier(
             from_user_id=user_id,
             chat_id=chat_id,

pyrogram/methods/pyromod/register_next_step_handler.py

@@ -35,18 +35,36 @@ class RegisterNextStepHandler:
         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.
-        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.
+        .. include:: /_includes/usable-by/users-bots.rst
-        :param filters: Same as :meth:`pyromod.types.Client.listen`.
+
-        :param listener_type: Same as :meth:`pyromod.types.Client.listen`.
+        Parameters:
-        :param unallowed_click_alert: Same as :meth:`pyromod.types.Client.listen`.
+            callback (``Callable``):
-        :param chat_id: Same as :meth:`pyromod.types.Client.listen`.
+                The callback to call when the listener is fulfilled.
-        :param user_id: Same as :meth:`pyromod.types.Client.listen`.
+
-        :param message_id: Same as :meth:`pyromod.types.Client.listen`.
+            user_id (``int`` | ``str`` | Iterable of ``int`` | Iterable of ``str``, *optional*):
-        :param inline_message_id: Same as :meth:`pyromod.types.Client.listen`.
+                The user ID to listen for.
-        :return: ``void``
+
+            filters (:obj:`~pyrogram.filters`, *optional*):
+                A filter to check the incoming message against.
+
+            listener_type (:obj:`~pyrogram.types.ListenerTypes`, *optional*):
+                The type of listener to listen for.
+                Default to Message.
+
+            timeout (``int``, *optional*):
+                The maximum amount of time to wait for a message.
+
+            unallowed_click_alert (``bool``, *optional*):
+                Whether to alert the user if they click a button that doesn’t match the filters.
+                Default to True.
+
+            message_id (``int``, *optional*):
+                The message ID to listen for.
+
+            inline_message_id (``str``, *optional*):
+                The inline message ID to listen for.
         """
         pattern = Identifier(
             from_user_id=user_id,

pyrogram/methods/pyromod/remove_listerner.py

@@ -25,11 +25,13 @@ class RemoveListener:
         self: "pyrogram.Client",
         listener: Listener
     ):
-        """
+        """Removes a listener from the :meth:`~pyrogram.Client.listeners` dictionary.
-        Removes a listener from the :meth:`pyromod.types.Client.listeners` dictionary.
 
-        :param listener: The listener to remove.
+        .. include:: /_includes/usable-by/users-bots.rst
-        :return: ``void``
+
+        Parameters:
+            listener (:obj:`~pyrogram.types.Listener`):
+                The listener to remove.
         """
         try:
             self.listeners[listener.listener_type].remove(listener)

pyrogram/methods/pyromod/stop_listener.py

@@ -29,12 +29,16 @@ class StopListener:
         self: "pyrogram.Client",
         listener: Listener
     ):
-        """
+        """Stops a listener, calling stopped_handler if applicable or raising ListenerStopped if throw_exceptions is True.
-        Stops a listener, calling stopped_handler if applicable or raising ListenerStopped if throw_exceptions is True.
 
-        :param listener: The :class:`pyromod.types.Listener` to stop.
+        .. include:: /_includes/usable-by/users-bots.rst
-        :return: ``void``
+
-        :raises ListenerStopped: If throw_exceptions is True.
+        Parameters:
+            listener (:obj:`~pyrogram.types.Listener`):
+                The listener to remove.
+
+        Raises:
+            ListenerStopped: If throw_exceptions is True.
         """
         self.remove_listener(listener)
 

pyrogram/methods/pyromod/stop_listening.py

@@ -31,16 +31,28 @@ class StopListening:
         message_id: Union[int, List[int]] = None,
         inline_message_id: Union[str, List[str]] = None,
     ):
-        """
+        """Stops all listeners that match the given identifier pattern.
-        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`.
+        .. include:: /_includes/usable-by/users-bots.rst
-        :param chat_id: The chat_id to match against.
+
-        :param user_id: The user_id to match against.
+        Uses :meth:`~pyrogram.Client.get_many_listeners_matching_with_identifier_pattern`.
-        :param message_id: The message_id to match against.
+
-        :param inline_message_id: The inline_message_id to match against.
+        Parameters:
-        :return: ``void``
+            listener_type (:obj:`~pyrogram.types.ListenerTypes`, *optional*):
+                The type of listener to stop listening for.
+                Default to Message.
+
+            chat_id (``int`` | ``str`` | Iterable of ``int`` | Iterable of ``str``, *optional*):
+                Unique identifier (int) or username (str) of the target chat.
+
+            user_id (``int`` | ``str`` | Iterable of ``int`` | Iterable of ``str``, *optional*):
+                The user ID to stop listening for.
+
+            message_id (``int``, *optional*):
+                The message ID to stop listening for.
+
+            inline_message_id (``str``, *optional*):
+                The inline message ID to stop listening for.
         """
         pattern = Identifier(
             from_user_id=user_id,

pyrogram/methods/pyromod/wait_for_callback_query.py

@@ -1,22 +1,24 @@
-#  Pyrogram - Telegram MTProto API Client Library for Python
+#  Pyrofork - Telegram MTProto API Client Library for Python
-#  Copyright (C) 2017-present Dan <https://github.com/delivrance>
+#  Copyright (C) 2020 Cezar H. <https://github.com/usernein>
+#  Copyright (C) 2022-present Mayuri-Chan <https://github.com/Mayuri-Chan>
 #
-#  This file is part of Pyrogram.
+#  This file is part of Pyrofork.
 #
-#  Pyrogram is free software: you can redistribute it and/or modify
+#  Pyrofork 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.
 #
-#  Pyrogram is distributed in the hope that it will be useful,
+#  Pyrofork 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 Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
+#  along with Pyrofork.  If not, see <http://www.gnu.org/licenses/>.
 
 import asyncio
+import pyrogram
 from typing import Union
 from functools import partial
 
@@ -26,12 +28,15 @@ from pyrogram.filters import Filter
 
 class WaitForCallbackQuery:
     async def wait_for_callback_query(
-        self,
+        self: "pyrogram.Client",
         chat_id: Union[int, str],
         filters: Filter = None,
         timeout: int = None
     ) -> "types.CallbackQuery":
         """Wait for callback query.
+
+        .. include:: /_includes/usable-by/bots.rst
+
         Parameters:
             chat_id (``int`` | ``str``):
                 Unique identifier (int) or username (str) of the target chat.

pyrogram/methods/pyromod/wait_for_message.py

@@ -1,37 +1,41 @@
-#  Pyrogram - Telegram MTProto API Client Library for Python
+#  Pyrofork - Telegram MTProto API Client Library for Python
-#  Copyright (C) 2017-present Dan <https://github.com/delivrance>
+#  Copyright (C) 2020 Cezar H. <https://github.com/usernein>
+#  Copyright (C) 2022-present Mayuri-Chan <https://github.com/Mayuri-Chan>
 #
-#  This file is part of Pyrogram.
+#  This file is part of Pyrofork.
 #
-#  Pyrogram is free software: you can redistribute it and/or modify
+#  Pyrofork 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.
 #
-#  Pyrogram is distributed in the hope that it will be useful,
+#  Pyrofork 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 Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
+#  along with Pyrofork.  If not, see <http://www.gnu.org/licenses/>.
 
 import asyncio
+import pyrogram
 from typing import Union
 from functools import partial
 
 from pyrogram import types
 from pyrogram.filters import Filter
 
-
 class WaitForMessage:
     async def wait_for_message(
-        self,
+        self: "pyrogram.Client",
         chat_id: Union[int, str],
         filters: Filter = None,
         timeout: int = None
     ) -> "types.Message":
         """Wait for message.
+
+        .. include:: /_includes/usable-by/users-bots.rst
+
         Parameters:
             chat_id (``int`` | ``str``):
                 Unique identifier (int) or username (str) of the target chat.

pyrogram/nav/__init__.py

@@ -1,16 +1,20 @@
-"""
+#  Pyrofork - Telegram MTProto API Client Library for Python
-pyromod - A monkeypatcher add-on for Pyrogram
+#  Copyright (C) 2020 Cezar H. <https://github.com/usernein>
-Copyright (C) 2020 Cezar H. <https://github.com/usernein>
+#  Copyright (C) 2022-present Mayuri-Chan <https://github.com/Mayuri-Chan>
-This file is part of pyromod.
+#
-pyromod is free software: you can redistribute it and/or modify
+#  This file is part of Pyrofork.
-it under the terms of the GNU General Public License as published by
+#
-the Free Software Foundation, either version 3 of the License, or
+#  Pyrofork is free software: you can redistribute it and/or modify
-(at your option) any later version.
+#  it under the terms of the GNU Lesser General Public License as published
-pyromod is distributed in the hope that it will be useful,
+#  by the Free Software Foundation, either version 3 of the License, or
-but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  (at your option) any later version.
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#
-GNU General Public License for more details.
+#  Pyrofork is distributed in the hope that it will be useful,
-You should have received a copy of the GNU General Public License
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
-along with pyromod.  If not, see <https://www.gnu.org/licenses/>.
+#  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 Pyrofork.  If not, see <http://www.gnu.org/licenses/>.
+
 from .pagination import Pagination

pyrogram/nav/pagination.py

@@ -1,22 +1,22 @@
-"""
+#  Pyrofork - Telegram MTProto API Client Library for Python
-pyromod - A monkeypatcher add-on for Pyrogram
+#  Copyright (C) 2020 Cezar H. <https://github.com/usernein>
-Copyright (C) 2020 Cezar H. <https://github.com/usernein>
+#  Copyright (C) 2022-present Mayuri-Chan <https://github.com/Mayuri-Chan>
+#
+#  This file is part of Pyrofork.
+#
+#  Pyrofork 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.
+#
+#  Pyrofork 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 Pyrofork.  If not, see <http://www.gnu.org/licenses/>.
 
-This file is part of pyromod.
-
-pyromod is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-pyromod 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 General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with pyromod.  If not, see <https://www.gnu.org/licenses/>.
-"""
 import math
 from pyrogram.helpers import array_chunk
 

pyrogram/types/messages_and_media/message.py

@@ -553,14 +553,23 @@ class Message(Object, Update):
             filters=None,
             alert: Union[str, bool] = True,
     ):
-        """
+        """Waits for a callback query to be clicked on the message.
-        Waits for a callback query to be clicked on the message.
 
-        :param from_user_id: The user ID(s) to wait for. If None, waits for any user.
+        Parameters:
-        :param timeout: The timeout in seconds. If None, waits forever.
+            user_id (``int`` | ``str`` | Iterable of ``int`` | Iterable of ``str``, *optional*):
-        :param filters: The filters to pass to Client.listen().
+                The user ID to listen for.
-        :param alert: The alert to show when the button is clicked by users that are not allowed in from_user_id.
+
-        :return: The callback query that was clicked.
+            timeout (``int``, *optional*):
+                The maximum amount of time to wait for a message.
+
+            filters (:obj:`~pyrogram.filters`, *optional*):
+                A filter to check the incoming message against.
+
+            alert (``str`` | ``bool``):
+                The alert to show when the button is clicked by users that are not allowed in from_user_id.
+
+        Returns:
+            :obj:`~pyrogram.types.CallbackQuery`: The callback query that was clicked.
         """
         message_id = getattr(self, "id", getattr(self, "message_id", None))
 
@@ -4411,45 +4420,61 @@ class Message(Object, Update):
         """Bound method *ask* of :obj:`~pyrogram.types.Message`.
         
         Use as a shortcut for:
+
         .. code-block:: python
+
             client.send_message(chat_id, "What is your name?")
+
             client.wait_for_message(chat_id)
 
-        Example:
-            .. code-block:: python
-                message.ask("What is your name?")
         Parameters:
             text (``str``):
                 Text of the message to be sent.
+
             quote (``bool``, *optional*):
                 If ``True``, the message will be sent as a reply to this message.
                 If *reply_to_message_id* is passed, this parameter will be ignored.
                 Defaults to ``True`` in group chats and ``False`` in private chats.
+
             parse_mode (:obj:`~pyrogram.enums.ParseMode`, *optional*):
                 By default, texts are parsed using both Markdown and HTML styles.
                 You can combine both syntaxes together.
                 Pass "markdown" or "md" to enable Markdown-style parsing only.
                 Pass "html" to enable HTML-style parsing only.
                 Pass None to completely disable style parsing.
+
             entities (List of :obj:`~pyrogram.types.MessageEntity`):
                 List of special entities that appear in message text, which can be specified instead of *parse_mode*.
+
             disable_web_page_preview (``bool``, *optional*):
                 Disables link previews for links in this message.
+
             disable_notification (``bool``, *optional*):
                 Sends the message silently.
                 Users will receive a notification with no sound.
+
             reply_to_message_id (``int``, *optional*):
                 If the message is a reply, ID of the original message.
+
             reply_markup (:obj:`~pyrogram.types.InlineKeyboardMarkup` | :obj:`~pyrogram.types.ReplyKeyboardMarkup` | :obj:`~pyrogram.types.ReplyKeyboardRemove` | :obj:`~pyrogram.types.ForceReply`, *optional*):
                 Additional interface options. An object for an inline keyboard, custom reply keyboard,
                 instructions to remove reply keyboard or to force a reply from the user.
+
             filters (:obj:`Filters`):
                 Pass one or more filters to allow only a subset of callback queries to be passed
                 in your callback function.
+
             timeout (``int``, *optional*):
                 Timeout in seconds.
+            
+        Example:
+            .. code-block:: python
+
+                message.ask("What is your name?")
+
         Returns:
             :obj:`~pyrogram.types.Message`: On success, the reply message is returned.
+
         Raises:
             RPCError: In case of a Telegram RPC error.
             asyncio.TimeoutError: In case reply not received within the timeout.

pyrogram/types/pyromod/identifier.py

@@ -1,9 +1,42 @@
+#  Pyrofork - Telegram MTProto API Client Library for Python
+#  Copyright (C) 2020 Cezar H. <https://github.com/usernein>
+#  Copyright (C) 2022-present Mayuri-Chan <https://github.com/Mayuri-Chan>
+#
+#  This file is part of Pyrofork.
+#
+#  Pyrofork 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.
+#
+#  Pyrofork 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 Pyrofork.  If not, see <http://www.gnu.org/licenses/>.
+
 from dataclasses import dataclass
 from typing import Optional, Union, List
 
-
 @dataclass
 class Identifier:
+    """A dataclass that serves as a utility for matching listeners to the data of updates.
+
+    Parameters:
+        inline_message_id (``str`` | Iterable of ``str``, *optional*):
+            The inline message ID to match. If None, it is not considered for matching.
+
+        chat_id (``int`` | ``str`` | Iterable of ``int`` | Iterable of ``str``, *optional*):
+            The chat ID to match. If None, it is not considered for matching.
+
+        message_id (``int``  | Iterable of ``int``):
+            The message ID to match. If None, it is not considered for matching.
+
+        from_user_id (``int`` | ``str`` | Iterable of ``int`` | Iterable of ``str``, *optional*):
+            The user ID to match. If None, it is not considered for matching.
+    """
     inline_message_id: Optional[Union[str, List[str]]] = None
     chat_id: Optional[Union[Union[int, str], List[Union[int, str]]]] = None
     message_id: Optional[Union[int, List[int]]] = None

pyrogram/types/pyromod/listener.py

@@ -1,9 +1,27 @@
+#  Pyrofork - Telegram MTProto API Client Library for Python
+#  Copyright (C) 2020 Cezar H. <https://github.com/usernein>
+#  Copyright (C) 2022-present Mayuri-Chan <https://github.com/Mayuri-Chan>
+#
+#  This file is part of Pyrofork.
+#
+#  Pyrofork 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.
+#
+#  Pyrofork 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 Pyrofork.  If not, see <http://www.gnu.org/licenses/>.
+
 from asyncio import Future
 from dataclasses import dataclass
 from typing import Callable
 
 import pyrogram
-from pyrogram import filters
 
 from .identifier import Identifier
 from .listener_types import ListenerTypes
@@ -11,6 +29,32 @@ from .listener_types import ListenerTypes
 
 @dataclass
 class Listener:
+    """Designed to manage and handle different types of listeners used in pyromod.
+    It enables you to wait for specific events like messages or callback queries and provides mechanisms for defining the conditions and filters that trigger these listeners.
+
+    Parameters:
+        listener_type (:obj:`~pyrogram.types.ListenerTypes`):
+            The type of listener that specifies the event you want to listen for.
+            It can be either a “message” or a “callback_query.”
+
+        filters (:meth:`~pyrogram.filters.Filter`):
+            The chat ID to match. If None, it is not considered for matching.
+
+        unallowed_click_alert (``bool``):
+            A flag that determines whether to send an alert if a button click event doesn’t match the filter conditions.
+            Setting this to True will send an alert message to the user in such cases.
+
+        identifier (:obj:`~pyrogram.types.Identifier`):
+            An :obj:`~pyrogram.types.Identifier` instance that defines the criteria for the event.
+            It includes properties like chat_id, message_id, from_user_id, and inline_message_id that you want to match against the incoming event.
+
+        future (:obj:`~asyncio.Future`, *optional*):
+            A :obj:`~asyncio.Future` object representing the asynchronous task that waits for the event.
+            When the event occurs, the :obj:`~asyncio.Future` will be resolved, and the listener will be able to proceed.
+
+        callback (``Callable``, *optional*):
+            The callback to call when the listener is fulfilled.
+    """
     listener_type: ListenerTypes
     filters: "pyrogram.filters.Filter"
     unallowed_click_alert: bool

pyrogram/types/user_and_chats/chat.py

@@ -403,32 +403,89 @@ class Chat(Object):
             return Chat._parse_channel_chat(client, chat)
 
     def listen(self, *args, **kwargs):
-        """
+        """Bound method *listen* of :obj:`~pyrogram.types.Chat`.
-        Listens for messages in the chat. Calls Client.listen() with the chat_id set to the chat's id.
         
-        :param args: Arguments to pass to Client.listen().
+        Use as a shortcut for:
-        :param kwargs: Keyword arguments to pass to Client.listen().
+
-        :return: The return value of Client.listen().
+        .. code-block:: python
+
+            client.wait_for_message(chat_id)
+
+        Parameters:
+            args (*optional*):
+                The arguments to pass to the :meth:`~pyrogram.Client.listen` method.
+
+            kwargs (*optional*):
+                The keyword arguments to pass to the :meth:`~pyrogram.Client.listen` method.
+
+        Example:
+            .. code-block:: python
+
+                chat.listen()
+
+        Returns:
+            :obj:`~pyrogram.types.Message`: On success, the reply message is returned.
+        Raises:
+            RPCError: In case of a Telegram RPC error.
+            asyncio.TimeoutError: In case reply not received within the timeout.
         """
         return self._client.listen(*args, chat_id=self.id, **kwargs)
 
     def ask(self, text, *args, **kwargs):
-        """
+        """Bound method *ask* of :obj:`~pyrogram.types.Chat`.
-        Asks a question in the chat. Calls Client.ask() with the chat_id set to the chat's id.
+        
-        :param text: The text to send.
+        Use as a shortcut for:
-        :param args: Arguments to pass to Client.ask().
+
-        :param kwargs: Keyword arguments to pass to Client.ask().
+        .. code-block:: python
-        :return: The return value of Client.ask().
+
+            client.send_message(chat_id, "What is your name?")
+
+            client.wait_for_message(chat_id)
+
+        Parameters:
+            text (``str``):
+                Text of the message to be sent.
+
+            args:
+                The arguments to pass to the :meth:`~pyrogram.Client.listen` method.
+
+            kwargs:
+                The keyword arguments to pass to the :meth:`~pyrogram.Client.listen` method.
+
+        Example:
+            .. code-block:: python
+
+                chat.ask("What is your name?")
+
+        Returns:
+            :obj:`~pyrogram.types.Message`: On success, the reply message is returned.
+        Raises:
+            RPCError: In case of a Telegram RPC error.
+            asyncio.TimeoutError: In case reply not received within the timeout.
         """
         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 the chat. Calls Client.stop_listening() with the chat_id set to the chat's id.
+        
+        Use as a shortcut for:
+
+        .. code-block:: python
+
+            client.stop_listening(chat_id=chat_id)
+
+        Parameters:
+            args (*optional*):
+                The arguments to pass to the :meth:`~pyrogram.Client.listen` method.
+
+            kwargs (*optional*):
+                The keyword arguments to pass to the :meth:`~pyrogram.Client.listen` method.
+
+        Example:
+            .. code-block:: python
+
+                chat.stop_listen()
 
-        :param args: Arguments to pass to Client.stop_listening().
-        :param kwargs: Keyword arguments to pass to Client.stop_listening().
-        :return: The return value of Client.stop_listening().
         """
         return self._client.stop_listening(*args, chat_id=self.id, **kwargs)
 

pyrogram/types/user_and_chats/user.py

@@ -309,33 +309,88 @@ class User(Object, Update):
         )
 
     def listen(self, *args, **kwargs):
-        """
+        """Bound method *listen* of :obj:`~pyrogram.types.User`.
-        Listens for messages from the user. Calls Client.listen() with the user_id set to the user's id.
 
-        :param args: Arguments to pass to Client.listen().
+        Use as a shortcut for:
-        :param kwargs: Keyword arguments to pass to Client.listen().
+
-        :return: The return value of Client.listen().
+        .. code-block:: python
+
+            client.wait_for_message(user_id)
+
+        Parameters:
+            args (*optional*):
+                The arguments to pass to the :meth:`~pyrogram.Client.listen` method.
+
+            kwargs (*optional*):
+                The keyword arguments to pass to the :meth:`~pyrogram.Client.listen` method.
+
+        Example:
+            .. code-block:: python
+
+                user.listen()
+
+        Returns:
+            :obj:`~pyrogram.types.Message`: On success, the reply message is returned.
+        Raises:
+            RPCError: In case of a Telegram RPC error.
+            asyncio.TimeoutError: In case reply not received within the timeout.
         """
         return self._client.listen(*args, user_id=self.id, **kwargs)
 
     def ask(self, text, *args, **kwargs):
-        """
+        """Bound method *ask* of :obj:`~pyrogram.types.User`.
-        Asks a question to the user. Calls Client.ask() with both chat_id and user_id set to the user's id.
         
-        :param text: The text to send.
+        Use as a shortcut for:
-        :param args: Arguments to pass to Client.ask().
+
-        :param kwargs: Keyword arguments to pass to Client.ask().
+        .. code-block:: python
-        :return: The return value of Client.ask().
+
+            client.send_message(user_id, "What is your name?")
+
+            client.wait_for_message(user_id)
+
+        Parameters:
+            text (``str``):
+                Text of the message to be sent.
+
+            args:
+                The arguments to pass to the :meth:`~pyrogram.Client.listen` method.
+
+            kwargs:
+                The keyword arguments to pass to the :meth:`~pyrogram.Client.listen` method.
+
+        Example:
+            .. code-block:: python
+
+                user.ask("What is your name?")
+
+        Returns:
+            :obj:`~pyrogram.types.Message`: On success, the reply message is returned.
+        Raises:
+            RPCError: In case of a Telegram RPC error.
+            asyncio.TimeoutError: In case reply not received within the timeout.
         """
         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 the user. Calls Client.stop_listening() with the user_id set to the user's id.
         
-        :param args: Arguments to pass to Client.stop_listening().
+        Use as a shortcut for:
-        :param kwargs: Keyword arguments to pass to Client.stop_listening().
+
-        :return: The return value of Client.stop_listening().
+        .. code-block:: python
+
+            client.stop_listening(user_id=user_id)
+
+        Parameters:
+            args (*optional*):
+                The arguments to pass to the :meth:`~pyrogram.Client.listen` method.
+
+            kwargs (*optional*):
+                The keyword arguments to pass to the :meth:`~pyrogram.Client.listen` method.
+
+        Example:
+            .. code-block:: python
+
+                user.stop_listen()
         """
         return self._client.stop_listening(*args, user_id=self.id, **kwargs)