yasirarism/pyrofork
1
0
Fork 0
mirror of https://github.com/Mayuri-Chan/pyrofork.git synced 2025-12-29 12:04:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Pyrofork: Add pyromod documentation

Browse source 
Signed-off-by: wulan17 <wulan17@nusantararom.org>
This commit is contained in:
wulan17 2023-12-13 10:16:18 +07:00
parent 16bc4a4178
commit d6e0a4f520
No known key found for this signature in database
GPG key ID: 318CD6CD3A6AC0A5
24 changed files with 587 additions and 176 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
compiler/docs/compiler.py
View file

@ -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

15
compiler/docs/template/methods.rst vendored
View file

@ -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:

13
compiler/docs/template/types.rst vendored
View file

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

6
pyrogram/methods/messages/__init__.py
View file

@ -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

6
pyrogram/methods/pyromod/__init__.py
View file

@ -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

58
pyrogram/methods/pyromod/ask.py
View file

@ -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() != "":

17
pyrogram/methods/pyromod/get_listener_matching_with_data.py
View file

@ -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]:

19
pyrogram/methods/pyromod/get_listener_matching_with_identifier_pattern.py
View file

@ -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]:

17
pyrogram/methods/pyromod/get_many_listeners_matching_with_data.py
View file

@ -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]:

21
pyrogram/methods/pyromod/get_many_listeners_matching_with_identifier_pattern.py
View file

@ -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]:

55
pyrogram/methods/pyromod/listen.py
View file

@ -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,

40
pyrogram/methods/pyromod/register_next_step_handler.py
View file

@ -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,

10
pyrogram/methods/pyromod/remove_listerner.py
View file

@ -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)

14
pyrogram/methods/pyromod/stop_listener.py
View file

@ -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)

30
pyrogram/methods/pyromod/stop_listening.py
View file

@ -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,

19
pyrogram/methods/messages/wait_for_callback_query.py → pyrogram/methods/pyromod/wait_for_callback_query.py
View file

@ -1,22 +1,24 @@
# Pyrogram - Telegram MTProto API Client Library for Python
# Copyright (C) 2017-present Dan <https://github.com/delivrance>
# 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 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.

20
pyrogram/methods/messages/wait_for_message.py → pyrogram/methods/pyromod/wait_for_message.py
View file

@ -1,37 +1,41 @@
# Pyrogram - Telegram MTProto API Client Library for Python
# Copyright (C) 2017-present Dan <https://github.com/delivrance>
# 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 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.

34
pyrogram/nav/__init__.py
View file

@ -1,16 +1,20 @@
"""
pyromod - A monkeypatcher add-on for Pyrogram
Copyright (C) 2020 Cezar H. <https://github.com/usernein>
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/>.
"""
# 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 .pagination import Pagination

36
pyrogram/nav/pagination.py
View file

@ -1,22 +1,22 @@
"""
pyromod - A monkeypatcher add-on for Pyrogram
Copyright (C) 2020 Cezar H. <https://github.com/usernein>
# 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/>.
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

47
pyrogram/types/messages_and_media/message.py
View file

@ -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.

35
pyrogram/types/pyromod/identifier.py
View file

@ -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

46
pyrogram/types/pyromod/listener.py
View file

@ -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

89
pyrogram/types/user_and_chats/chat.py
View file

@ -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)

87
pyrogram/types/user_and_chats/user.py
View file

@ -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)