1#!/usr/bin/env python
2# pylint: disable=R0902,R0913
3#
4# A library that provides a Python interface to the Telegram Bot API
5# Copyright (C) 2015-2020
6# Leandro Toledo de Souza <devs@python-telegram-bot.org>
7#
8# This program is free software: you can redistribute it and/or modify
9# it under the terms of the GNU Lesser Public License as published by
10# the Free Software Foundation, either version 3 of the License, or
11# (at your option) any later version.
12#
13# This program is distributed in the hope that it will be useful,
14# but WITHOUT ANY WARRANTY; without even the implied warranty of
15# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16# GNU Lesser Public License for more details.
17#
18# You should have received a copy of the GNU Lesser Public License
19# along with this program.  If not, see [http://www.gnu.org/licenses/].
20"""This module contains an object that represents a Telegram InlineQuery."""
21
22from typing import TYPE_CHECKING, Any, Optional
23
24from telegram import Location, TelegramObject, User
25from telegram.utils.types import JSONDict
26
27if TYPE_CHECKING:
28    from telegram import Bot
29
30
31class InlineQuery(TelegramObject):
32    """
33    This object represents an incoming inline query. When the user sends an empty query, your bot
34    could return some default or trending results.
35
36    Objects of this class are comparable in terms of equality. Two objects of this class are
37    considered equal, if their :attr:`id` is equal.
38
39    Note:
40        * In Python `from` is a reserved word, use `from_user` instead.
41
42    Attributes:
43        id (:obj:`str`): Unique identifier for this query.
44        from_user (:class:`telegram.User`): Sender.
45        location (:class:`telegram.Location`): Optional. Sender location, only for bots that
46            request user location.
47        query (:obj:`str`): Text of the query (up to 256 characters).
48        offset (:obj:`str`): Offset of the results to be returned, can be controlled by the bot.
49
50    Args:
51        id (:obj:`str`): Unique identifier for this query.
52        from_user (:class:`telegram.User`): Sender.
53        location (:class:`telegram.Location`, optional): Sender location, only for bots that
54            request user location.
55        query (:obj:`str`): Text of the query (up to 256 characters).
56        offset (:obj:`str`): Offset of the results to be returned, can be controlled by the bot.
57        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
58        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
59
60    """
61
62    def __init__(
63        self,
64        id: str,  # pylint: disable=W0622
65        from_user: User,
66        query: str,
67        offset: str,
68        location: Location = None,
69        bot: 'Bot' = None,
70        **_kwargs: Any,
71    ):
72        # Required
73        self.id = id  # pylint: disable=C0103
74        self.from_user = from_user
75        self.query = query
76        self.offset = offset
77
78        # Optional
79        self.location = location
80
81        self.bot = bot
82        self._id_attrs = (self.id,)
83
84    @classmethod
85    def de_json(cls, data: Optional[JSONDict], bot: 'Bot') -> Optional['InlineQuery']:
86        data = cls.parse_data(data)
87
88        if not data:
89            return None
90
91        data['from_user'] = User.de_json(data.get('from'), bot)
92        data['location'] = Location.de_json(data.get('location'), bot)
93
94        return cls(bot=bot, **data)
95
96    def answer(self, *args: Any, auto_pagination: bool = False, **kwargs: Any) -> bool:
97        """Shortcut for::
98
99            bot.answer_inline_query(update.inline_query.id,
100                                    *args,
101                                    current_offset=self.offset if auto_pagination else None,
102                                    **kwargs)
103
104        Args:
105            results (List[:class:`telegram.InlineQueryResult`] | Callable): A list of results for
106                the inline query. In case :attr:`auto_pagination` is set to :obj:`True`,
107                ``results`` may also be a callable may also be a callable accepts the current page
108                index starting from 0. It must return either a list of
109                :class:`telegram.InlineResult` instances or :obj:`None` if there are no more
110                results.
111            cache_time (:obj:`int`, optional): The maximum amount of time in seconds that the
112                result of the inline query may be cached on the server. Defaults to 300.
113            is_personal (:obj:`bool`, optional): Pass :obj:`True`, if results may be cached on the
114                server side only for the user that sent the query. By default, results may be
115                returned to any user who sends the same query.
116            next_offset (:obj:`str`, optional): Pass the offset that a client should send in the
117                next query with the same text to receive more results. Pass an empty string if
118                there are no more results or if you don't support pagination. Offset length can't
119                exceed 64 bytes.
120            switch_pm_text (:obj:`str`, optional): If passed, clients will display a button with
121                specified text that switches the user to a private chat with the bot and sends the
122                bot a start message with the parameter switch_pm_parameter.
123            switch_pm_parameter (:obj:`str`, optional): Deep-linking parameter for the /start
124                message sent to the bot when user presses the switch button. 1-64 characters,
125                only A-Z, a-z, 0-9, _ and - are allowed.
126            auto_pagination (:obj:`bool`, optional): If set to :obj:`True`, :attr:`offset` will be
127                passed as :attr:`current_offset` to :meth:telegram.Bot.answer_inline_query`.
128                Defaults to :obj:`False`.
129
130        """
131        return self.bot.answer_inline_query(
132            self.id, *args, current_offset=self.offset if auto_pagination else None, **kwargs
133        )
134