Pyrofork: Add pyromod documentation

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

compiler/docs/compiler.py

@@ -147,6 +147,21 @@ def get_title_list(s: str) -> list:
             export_session_string
             set_parse_mode
         """,
+        conservation="""
+        Conservation
+            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 get_title_list(s: str) -> list:
             StoriesPrivacyRules
             StoryViews
         """,
+        pyromod="""
+        Pyromod
+            Identifier
+            Listener
+            ListenerTypes
+        """,
         bot_keyboards="""
         Bot keyboards
             ReplyKeyboardMarkup
@@ -591,6 +612,7 @@ def get_title_list(s: str) -> list:
     categories = dict(
         message="""
         Message
+            Message.ask
             Message.click
             Message.delete
             Message.download
@@ -625,9 +647,13 @@ def get_title_list(s: str) -> list:
             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 get_title_list(s: str) -> list:
         """,
         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
 
+Conservation
+------------
+
+.. autosummary::
+    :nosignatures:
+
+    {conservation}
+
+.. toctree::
+    :hidden:
+
+    {conservation}
+
 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 .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,
-    WaitForMessage,
-    WaitForCallbackQuery
+    GetCustomEmojiStickers
 ):
     pass

pyrogram/methods/pyromod/__init__.py

@@ -26,6 +26,8 @@
 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 @@ async def ask(
         *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``.
+        """Send a message then listen for a message, callback query, etc.
+
+        Message:
+
+        .. include:: /_includes/usable-by/users-bots.rst
+
+        CallbackQuery:
+
+        .. include:: /_includes/usable-by/bots.rst
+
+        Parameters:
+            chat_id (``int`` | ``str`` | Iterable of ``int`` | Iterable of ``str``):
+                Unique identifier (int) or username (str) of the target chat.
+
+            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 @@ def get_listener_matching_with_data(
         data: Identifier,
         listener_type: ListenerTypes
     ) -> Optional[Listener]:
-        """
-        Gets a listener that matches the given data.
+        """Gets a listener that matches the given data.
+
+        .. include:: /_includes/usable-by/users-bots.rst
+
+        Parameters:
+            data (:obj:`~pyrogram.types.Identifier`):
+                The Identifier to match agains.
+
+            listener_type (:obj:`~pyrogram.types.ListenerTypes`):
+                The type of listener to get.
 
-        :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.
+        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 @@ def get_listener_matching_with_identifier_pattern(
         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.
+
+        .. include:: /_includes/usable-by/users-bots.rst
 
-        The difference from :meth:`pyromod.types.Client.get_listener_matching_with_data` is that this method
+        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.
-        :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.
+        Parameters:
+            pattern (: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_many_listeners_matching_with_data.py

@@ -28,12 +28,19 @@ def get_many_listeners_matching_with_data(
         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.
+        """Gets multiple listener that matches the given data.
+
+        .. include:: /_includes/usable-by/users-bots.rst
+
+        Parameters:
+            data (:obj:`~pyrogram.types.Identifier`):
+                The Identifier to match agains.
+
+            listener_type (:obj:`~pyrogram.types.ListenerTypes`):
+                The type of listener to get.
 
-        :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.
+        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 @@ def get_many_listeners_matching_with_identifier_pattern(
         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.
+        """Gets multiple listener that matches the given identifier pattern.
+
+        .. 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.
+
+        Parameters:
+            pattern (:obj:`~pyrogram.types.Identifier`):
+                The Identifier to match agains.
+
+            listener_type (:obj:`~pyrogram.types.ListenerTypes`):
+                The type of listener to get.
 
-        :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.
+        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 @@ async def listen(
         message_id: Union[int, List[int]] = None,
         inline_message_id: Union[str, List[str]] = None,
     ):
+        """Listen for a message, callback query, etc.
+
+        Message:
+
+        .. include:: /_includes/usable-by/users-bots.rst
+
+        CallbackQuery:
+
+        .. include:: /_includes/usable-by/bots.rst
+
+        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)
         """
-        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,