diff --git a/compiler/docs/compiler.py b/compiler/docs/compiler.py index 9b5d5dd0..347054ce 100644 --- a/compiler/docs/compiler.py +++ b/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 diff --git a/compiler/docs/template/methods.rst b/compiler/docs/template/methods.rst index effe19f5..e69a89c2 100644 --- a/compiler/docs/template/methods.rst +++ b/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: diff --git a/compiler/docs/template/types.rst b/compiler/docs/template/types.rst index 08630cbb..0ae41f4b 100644 --- a/compiler/docs/template/types.rst +++ b/compiler/docs/template/types.rst @@ -60,6 +60,19 @@ Stories {stories} +Pyromod +------- + +.. autosummary:: + :nosignatures: + + {pyromod} + +.. toctree:: + :hidden: + + {pyromod} + Bot keyboards ------------- diff --git a/pyrogram/methods/messages/__init__.py b/pyrogram/methods/messages/__init__.py index 94a6b80e..3007290c 100644 --- a/pyrogram/methods/messages/__init__.py +++ b/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, - WaitForMessage, - WaitForCallbackQuery + GetCustomEmojiStickers ): pass diff --git a/pyrogram/methods/pyromod/__init__.py b/pyrogram/methods/pyromod/__init__.py index e3f4d1c6..933c132f 100644 --- a/pyrogram/methods/pyromod/__init__.py +++ b/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 diff --git a/pyrogram/methods/pyromod/ask.py b/pyrogram/methods/pyromod/ask.py index 2e6ddca9..94be08c8 100644 --- a/pyrogram/methods/pyromod/ask.py +++ b/pyrogram/methods/pyromod/ask.py @@ -38,22 +38,50 @@ class Ask: *args, **kwargs, ): - """ - Sends a message and waits for a response. + """Send a message then listen for a message, callback query, etc. - :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``. + 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() != "": diff --git a/pyrogram/methods/pyromod/get_listener_matching_with_data.py b/pyrogram/methods/pyromod/get_listener_matching_with_data.py index 9e1319ad..a6816a21 100644 --- a/pyrogram/methods/pyromod/get_listener_matching_with_data.py +++ b/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. - :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. + .. 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. + + Returns: + :obj:`~pyrogram.types.Listener`: On success, a Listener is returned. """ matching = [] for listener in self.listeners[listener_type]: diff --git a/pyrogram/methods/pyromod/get_listener_matching_with_identifier_pattern.py b/pyrogram/methods/pyromod/get_listener_matching_with_identifier_pattern.py index 222483a1..3a946a28 100644 --- a/pyrogram/methods/pyromod/get_listener_matching_with_identifier_pattern.py +++ b/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. - :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]: diff --git a/pyrogram/methods/pyromod/get_many_listeners_matching_with_data.py b/pyrogram/methods/pyromod/get_many_listeners_matching_with_data.py index cb5b9ae2..aab83fc9 100644 --- a/pyrogram/methods/pyromod/get_many_listeners_matching_with_data.py +++ b/pyrogram/methods/pyromod/get_many_listeners_matching_with_data.py @@ -28,12 +28,19 @@ class GetManyListenersMatchingWithData: 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. - :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. + .. 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. + + Returns: + List of :obj:`~pyrogram.types.Listener`: On success, a list of Listener is returned. """ listeners = [] for listener in self.listeners[listener_type]: 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 index dd177d0a..aadf16e6 100644 --- a/pyrogram/methods/pyromod/get_many_listeners_matching_with_identifier_pattern.py +++ b/pyrogram/methods/pyromod/get_many_listeners_matching_with_identifier_pattern.py @@ -28,12 +28,23 @@ class GetManyListenersMatchingWithIdentifierPattern: 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. - :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. + .. 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. + + Returns: + List of :obj:`~pyrogram.types.Listener`: On success, a list of Listener is returned. """ listeners = [] for listener in self.listeners[listener_type]: diff --git a/pyrogram/methods/pyromod/listen.py b/pyrogram/methods/pyromod/listen.py index 81fc8fee..02784e9a 100644 --- a/pyrogram/methods/pyromod/listen.py +++ b/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, ): - """ - Creates a listener and waits for it to be fulfilled. + """Listen for a message, callback query, etc. - :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. + 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) """ + pattern = Identifier( from_user_id=user_id, chat_id=chat_id, diff --git a/pyrogram/methods/pyromod/register_next_step_handler.py b/pyrogram/methods/pyromod/register_next_step_handler.py index defa1d82..94d766c4 100644 --- a/pyrogram/methods/pyromod/register_next_step_handler.py +++ b/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. - :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`` + .. include:: /_includes/usable-by/users-bots.rst + + Parameters: + callback (``Callable``): + The callback to call when the listener is fulfilled. + + 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. """ pattern = Identifier( from_user_id=user_id, diff --git a/pyrogram/methods/pyromod/remove_listerner.py b/pyrogram/methods/pyromod/remove_listerner.py index d3dabc5a..9171c96d 100644 --- a/pyrogram/methods/pyromod/remove_listerner.py +++ b/pyrogram/methods/pyromod/remove_listerner.py @@ -25,11 +25,13 @@ class RemoveListener: self: "pyrogram.Client", listener: Listener ): - """ - Removes a listener from the :meth:`pyromod.types.Client.listeners` dictionary. + """Removes a listener from the :meth:`~pyrogram.Client.listeners` dictionary. - :param listener: The listener to remove. - :return: ``void`` + .. include:: /_includes/usable-by/users-bots.rst + + Parameters: + listener (:obj:`~pyrogram.types.Listener`): + The listener to remove. """ try: self.listeners[listener.listener_type].remove(listener) diff --git a/pyrogram/methods/pyromod/stop_listener.py b/pyrogram/methods/pyromod/stop_listener.py index 099eb4e5..2df3ee24 100644 --- a/pyrogram/methods/pyromod/stop_listener.py +++ b/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. - :return: ``void`` - :raises ListenerStopped: If throw_exceptions is True. + .. include:: /_includes/usable-by/users-bots.rst + + Parameters: + listener (:obj:`~pyrogram.types.Listener`): + The listener to remove. + + Raises: + ListenerStopped: If throw_exceptions is True. """ self.remove_listener(listener) diff --git a/pyrogram/methods/pyromod/stop_listening.py b/pyrogram/methods/pyromod/stop_listening.py index 03fefd6d..1143fa60 100644 --- a/pyrogram/methods/pyromod/stop_listening.py +++ b/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. - Uses :meth:`pyromod.types.Client.get_many_listeners_matching_with_identifier_pattern`. + """Stops all listeners that match the given 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`` + .. include:: /_includes/usable-by/users-bots.rst + + Uses :meth:`~pyrogram.Client.get_many_listeners_matching_with_identifier_pattern`. + + Parameters: + 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, diff --git a/pyrogram/methods/messages/wait_for_callback_query.py b/pyrogram/methods/pyromod/wait_for_callback_query.py similarity index 82% rename from pyrogram/methods/messages/wait_for_callback_query.py rename to pyrogram/methods/pyromod/wait_for_callback_query.py index f85eb6d4..3fa7d94a 100644 --- a/pyrogram/methods/messages/wait_for_callback_query.py +++ b/pyrogram/methods/pyromod/wait_for_callback_query.py @@ -1,22 +1,24 @@ -# Pyrogram - Telegram MTProto API Client Library for Python -# Copyright (C) 2017-present Dan +# Pyrofork - Telegram MTProto API Client Library for Python +# Copyright (C) 2020 Cezar H. +# Copyright (C) 2022-present 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 . +# along with Pyrofork. If not, see . 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. diff --git a/pyrogram/methods/messages/wait_for_message.py b/pyrogram/methods/pyromod/wait_for_message.py similarity index 81% rename from pyrogram/methods/messages/wait_for_message.py rename to pyrogram/methods/pyromod/wait_for_message.py index 53e698ca..3a814e38 100644 --- a/pyrogram/methods/messages/wait_for_message.py +++ b/pyrogram/methods/pyromod/wait_for_message.py @@ -1,37 +1,41 @@ -# Pyrogram - Telegram MTProto API Client Library for Python -# Copyright (C) 2017-present Dan +# Pyrofork - Telegram MTProto API Client Library for Python +# Copyright (C) 2020 Cezar H. +# Copyright (C) 2022-present 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 . +# along with Pyrofork. If not, see . 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. diff --git a/pyrogram/nav/__init__.py b/pyrogram/nav/__init__.py index 9bdf5298..812f6256 100644 --- a/pyrogram/nav/__init__.py +++ b/pyrogram/nav/__init__.py @@ -1,16 +1,20 @@ -""" -pyromod - A monkeypatcher add-on for Pyrogram -Copyright (C) 2020 Cezar H. -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 . -""" +# Pyrofork - Telegram MTProto API Client Library for Python +# Copyright (C) 2020 Cezar H. +# Copyright (C) 2022-present 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 . + from .pagination import Pagination \ No newline at end of file diff --git a/pyrogram/nav/pagination.py b/pyrogram/nav/pagination.py index bd107140..59511885 100644 --- a/pyrogram/nav/pagination.py +++ b/pyrogram/nav/pagination.py @@ -1,22 +1,22 @@ -""" -pyromod - A monkeypatcher add-on for Pyrogram -Copyright (C) 2020 Cezar H. +# Pyrofork - Telegram MTProto API Client Library for Python +# Copyright (C) 2020 Cezar H. +# Copyright (C) 2022-present 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 . -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 . -""" import math from pyrogram.helpers import array_chunk diff --git a/pyrogram/types/messages_and_media/message.py b/pyrogram/types/messages_and_media/message.py index 9e0696dd..ff57d5fe 100644 --- a/pyrogram/types/messages_and_media/message.py +++ b/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. - :param timeout: The timeout in seconds. If None, waits forever. - :param filters: The filters to pass to Client.listen(). - :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. + Parameters: + user_id (``int`` | ``str`` | Iterable of ``int`` | Iterable of ``str``, *optional*): + The user ID to listen for. + + 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. diff --git a/pyrogram/types/pyromod/identifier.py b/pyrogram/types/pyromod/identifier.py index 9dff7cd9..f07eff4b 100644 --- a/pyrogram/types/pyromod/identifier.py +++ b/pyrogram/types/pyromod/identifier.py @@ -1,9 +1,42 @@ +# Pyrofork - Telegram MTProto API Client Library for Python +# Copyright (C) 2020 Cezar H. +# Copyright (C) 2022-present 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 . + 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 diff --git a/pyrogram/types/pyromod/listener.py b/pyrogram/types/pyromod/listener.py index 1f1fe6fe..4c8eaefe 100644 --- a/pyrogram/types/pyromod/listener.py +++ b/pyrogram/types/pyromod/listener.py @@ -1,9 +1,27 @@ +# Pyrofork - Telegram MTProto API Client Library for Python +# Copyright (C) 2020 Cezar H. +# Copyright (C) 2022-present 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 . + 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 diff --git a/pyrogram/types/user_and_chats/chat.py b/pyrogram/types/user_and_chats/chat.py index 94d3fcc1..892a3c90 100644 --- a/pyrogram/types/user_and_chats/chat.py +++ b/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): - """ - Listens for messages in the chat. Calls Client.listen() with the chat_id set to the chat's id. + """Bound method *listen* of :obj:`~pyrogram.types.Chat`. + + Use as a shortcut for: - :param args: Arguments to pass to Client.listen(). - :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): - """ - 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. - :param args: Arguments to pass to Client.ask(). - :param kwargs: Keyword arguments to pass to Client.ask(). - :return: The return value of Client.ask(). + """Bound method *ask* of :obj:`~pyrogram.types.Chat`. + + Use as a shortcut for: + + .. code-block:: python + + 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): - """ - Stops listening for messages in the chat. Calls Client.stop_listening() with the chat_id set to the chat's id. + """Bound method *stop_listening* of :obj:`~pyrogram.types.Chat`. + + 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) diff --git a/pyrogram/types/user_and_chats/user.py b/pyrogram/types/user_and_chats/user.py index 35358e2f..c8135543 100644 --- a/pyrogram/types/user_and_chats/user.py +++ b/pyrogram/types/user_and_chats/user.py @@ -309,33 +309,88 @@ class User(Object, Update): ) def listen(self, *args, **kwargs): - """ - Listens for messages from the user. Calls Client.listen() with the user_id set to the user's id. + """Bound method *listen* of :obj:`~pyrogram.types.User`. - :param args: Arguments to pass to Client.listen(). - :param kwargs: Keyword arguments to pass to Client.listen(). - :return: The return value of Client.listen(). + Use as a shortcut for: + + .. 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): - """ - Asks a question to the user. Calls Client.ask() with both chat_id and user_id set to the user's id. + """Bound method *ask* of :obj:`~pyrogram.types.User`. + + Use as a shortcut for: - :param text: The text to send. - :param args: Arguments to pass to Client.ask(). - :param kwargs: Keyword arguments to pass to Client.ask(). - :return: The return value of Client.ask(). + .. code-block:: python + + 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): - """ - Stops listening for messages from the user. Calls Client.stop_listening() with the user_id set to the user's id. + """Bound method *stop_listening* of :obj:`~pyrogram.types.User`. + + Use as a shortcut for: - :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(). + .. 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)