Source code for pyrogram.methods.listeners.listen

#  Pyrogram - Telegram MTProto API Client Library for Python
#  Copyright (C) 2017-present Dan <https://github.com/delivrance>
#
#  This file is part of Pyrogram.
#
#  Pyrogram 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,
#  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/>.

from __future__ import annotations

import asyncio
import logging

import pyrogram
from pyrogram import enums, types, utils
from pyrogram.errors import ListenerStopped
from pyrogram.types.listeners.listener import UNSET
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from pyrogram.filters import Filter

log = logging.getLogger(__name__)


async def resolve_listener_ids(client: pyrogram.Client, value):
    """Turn whatever the caller passed into canonical peer ids.

    Listeners are filed by id, so a username has to become one at registration
    time. Ints are taken as given: resolving them would need the peer to be known
    already, and would refuse a listener for a chat the client has not met yet.
    """
    if value is None:
        return None

    if isinstance(value, list):
        return [await resolve_listener_ids(client, item) for item in value]

    if isinstance(value, str):
        return await utils.resolve_peer_id(client, value)

    return value


class Listen:
    async def listen(
        self: pyrogram.Client,
        filters: Filter | None = None,
        listener_type: enums.ListenerTypes = enums.ListenerTypes.MESSAGE,
        timeout: float | None = UNSET,
        unallowed_click_alert: bool | str = True,
        chat_id: int | str | list[int | str] | None = None,
        user_id: int | str | list[int | str] | None = None,
        message_id: int | list[int] | None = None,
        inline_message_id: str | list[str] | None = None,
    ) -> types.Message | types.CallbackQuery:
        """Wait for the next update matching the given criteria.

        The update is consumed: handlers do not see it. Raw update handlers still
        do, since they are a separate contract.

        .. include:: /_includes/usable-by/users-bots.rst

        Parameters:
            filters (:obj:`~pyrogram.filters.Filter`, *optional*):
                Extra filter the update has to pass.

            listener_type (:obj:`~pyrogram.enums.ListenerTypes`, *optional*):
                Kind of update to wait for. Defaults to a new message.

            timeout (``float``, *optional*):
                Seconds to wait before raising ``ListenerTimeout``. Defaults to
                the client's ``listener_timeout`` (300s). Pass None to wait
                forever, which leaks a listener per abandoned conversation.

            unallowed_click_alert (``bool`` | ``str``, *optional*):
                For callback query listeners, answer clicks coming from a user
                this listener does not expect. Pass a string to set the text.

            chat_id (``int`` | ``str`` | List of ``int`` | ``str``, *optional*):
                Chat the update has to come from.

            user_id (``int`` | ``str`` | List of ``int`` | ``str``, *optional*):
                User the update has to come from.

            message_id (``int`` | List of ``int``, *optional*):
                Message the update has to belong to.

            inline_message_id (``str`` | List of ``str``, *optional*):
                Inline message the update has to belong to.

        Returns:
            :obj:`~pyrogram.types.Message` | :obj:`~pyrogram.types.CallbackQuery`:
            The matching update.

        Raises:
            ListenerTimeout: In case no matching update arrived in time.
            ListenerStopped: In case the listener was stopped, or the client is.
            ListenerLimitReached: In case no listener slot was available.

        Example:
            .. code-block:: python

                # Wait for the next message in a chat
                message = await app.listen(chat_id=chat_id)

                # Wait up to 60s for one specific user, ignoring everyone else
                reply = await app.listen(chat_id=chat_id, user_id=user_id, timeout=60)

                # Wait for a button press on a message you just sent
                query = await app.listen(
                    listener_type=enums.ListenerTypes.CALLBACK_QUERY,
                    chat_id=chat_id,
                    message_id=sent.id
                )
        """
        if self.no_updates:
            raise ListenerStopped("Cannot listen for updates on a client started with no_updates")

        if timeout is UNSET:
            timeout = self.listener_timeout

        identifier = types.Identifier(
            chat_id=await resolve_listener_ids(self, chat_id),
            user_id=await resolve_listener_ids(self, user_id),
            message_id=message_id,
            inline_message_id=inline_message_id,
        )

        future = self.loop.create_future()

        listener = types.Listener(
            listener_type=listener_type,
            identifier=identifier,
            filters=filters,
            future=future,
            unallowed_click_alert=unallowed_click_alert,
        )

        self.listeners.add(listener, timeout)

        parked = self.dispatcher.park()

        try:
            return await future
        except asyncio.CancelledError:
            if future.done() and not future.cancelled() and not future.exception():
                log.warning(
                    "A listener was cancelled after its update had already been "
                    "delivered; that update is lost"
                )

            raise
        finally:
            if parked:
                self.dispatcher.unpark()

            self.listeners.remove(listener)