2016-04-12 06:23:52 +02:00
|
|
|
#!/usr/bin/env python
|
|
|
|
#
|
|
|
|
# A library that provides a Python interface to the Telegram Bot API
|
2022-01-03 08:15:18 +01:00
|
|
|
# Copyright (C) 2015-2022
|
2016-04-12 06:23:52 +02:00
|
|
|
# Leandro Toledo de Souza <devs@python-telegram-bot.org>
|
|
|
|
#
|
|
|
|
# This program is free software: you can redistribute it and/or modify
|
|
|
|
# it under the terms of the GNU Lesser Public License as published by
|
|
|
|
# the Free Software Foundation, either version 3 of the License, or
|
|
|
|
# (at your option) any later version.
|
|
|
|
#
|
|
|
|
# This program 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 Public License for more details.
|
|
|
|
#
|
|
|
|
# You should have received a copy of the GNU Lesser Public License
|
|
|
|
# along with this program. If not, see [http://www.gnu.org/licenses/].
|
2017-09-01 08:43:08 +02:00
|
|
|
"""This module contains an object that represents a Telegram InlineKeyboardButton."""
|
2016-04-14 01:26:38 +02:00
|
|
|
|
2022-10-07 11:51:53 +02:00
|
|
|
from typing import TYPE_CHECKING, Optional, Union
|
2020-10-31 16:33:34 +01:00
|
|
|
|
2022-05-05 09:27:54 +02:00
|
|
|
from telegram._games.callbackgame import CallbackGame
|
|
|
|
from telegram._loginurl import LoginUrl
|
|
|
|
from telegram._telegramobject import TelegramObject
|
2022-05-03 18:21:50 +02:00
|
|
|
from telegram._utils.types import JSONDict
|
2022-05-05 09:27:54 +02:00
|
|
|
from telegram._webappinfo import WebAppInfo
|
2020-10-09 17:22:07 +02:00
|
|
|
|
2020-10-06 19:28:40 +02:00
|
|
|
if TYPE_CHECKING:
|
2022-05-03 18:21:50 +02:00
|
|
|
from telegram import Bot
|
2016-04-14 01:26:38 +02:00
|
|
|
|
|
|
|
|
|
|
|
class InlineKeyboardButton(TelegramObject):
|
2017-09-01 08:43:08 +02:00
|
|
|
"""This object represents one button of an inline keyboard.
|
2017-07-23 22:33:08 +02:00
|
|
|
|
2020-07-14 21:33:56 +02:00
|
|
|
Objects of this class are comparable in terms of equality. Two objects of this class are
|
|
|
|
considered equal, if their :attr:`text`, :attr:`url`, :attr:`login_url`, :attr:`callback_data`,
|
2022-05-18 07:48:20 +02:00
|
|
|
:attr:`switch_inline_query`, :attr:`switch_inline_query_current_chat`, :attr:`callback_game`,
|
|
|
|
:attr:`web_app` and :attr:`pay` are equal.
|
2020-07-14 21:33:56 +02:00
|
|
|
|
2017-07-23 22:33:08 +02:00
|
|
|
Note:
|
2021-06-06 11:48:48 +02:00
|
|
|
* You must use exactly one of the optional fields. Mind that :attr:`callback_game` is not
|
|
|
|
working as expected. Putting a game short name in it might, but is not guaranteed to
|
|
|
|
work.
|
|
|
|
* If your bot allows for arbitrary callback data, in keyboards returned in a response
|
|
|
|
from telegram, :attr:`callback_data` maybe be an instance of
|
|
|
|
:class:`telegram.ext.InvalidCallbackData`. This will be the case, if the data
|
|
|
|
associated with the button was already deleted.
|
|
|
|
|
|
|
|
.. versionadded:: 13.6
|
|
|
|
|
2021-12-11 15:21:56 +01:00
|
|
|
* Since Bot API 5.5, it's now allowed to mention users by their ID in inline keyboards.
|
|
|
|
This will only work in Telegram versions released after December 7, 2021.
|
|
|
|
Older clients will display *unsupported message*.
|
|
|
|
|
2021-06-06 11:48:48 +02:00
|
|
|
Warning:
|
2022-05-03 18:21:50 +02:00
|
|
|
* If your bot allows your arbitrary callback data, buttons whose callback data is a
|
|
|
|
non-hashable object will become unhashable. Trying to evaluate ``hash(button)`` will
|
|
|
|
result in a :class:`TypeError`.
|
2021-06-06 11:48:48 +02:00
|
|
|
|
2022-05-03 18:21:50 +02:00
|
|
|
.. versionchanged:: 13.6
|
|
|
|
|
|
|
|
* After Bot API 6.1, only ``HTTPS`` links will be allowed in :paramref:`login_url`.
|
2016-04-21 14:21:12 +02:00
|
|
|
|
2022-08-27 11:46:51 +02:00
|
|
|
.. seealso:: `Inline Keyboard Example 1 <examples.inlinekeyboard.html>`_,
|
|
|
|
`Inline Keyboard Example 2 <examples.inlinekeyboard2.html>`_,
|
|
|
|
:class:`telegram.InlineKeyboardMarkup`
|
|
|
|
|
2022-05-18 07:48:20 +02:00
|
|
|
.. versionchanged:: 20.0
|
|
|
|
:attr:`web_app` is considered as well when comparing objects of this type in terms of
|
|
|
|
equality.
|
|
|
|
|
2016-04-21 14:21:12 +02:00
|
|
|
Args:
|
2017-07-23 22:33:08 +02:00
|
|
|
text (:obj:`str`): Label text on the button.
|
2021-12-11 15:21:56 +01:00
|
|
|
url (:obj:`str`, optional): HTTP or tg:// url to be opened when the button is pressed.
|
|
|
|
Links ``tg://user?id=<user_id>`` can be used to mention a user by
|
|
|
|
their ID without using a username, if this is allowed by their privacy settings.
|
|
|
|
|
|
|
|
.. versionchanged:: 13.9
|
|
|
|
You can now mention a user using ``tg://user?id=<user_id>``.
|
2022-05-03 18:21:50 +02:00
|
|
|
login_url (:class:`telegram.LoginUrl`, optional): An ``HTTPS`` URL used to automatically
|
2020-04-07 17:25:17 +02:00
|
|
|
authorize the user. Can be used as a replacement for the Telegram Login Widget.
|
2022-05-03 18:21:50 +02:00
|
|
|
|
|
|
|
Caution:
|
|
|
|
Only ``HTTPS`` links are allowed after Bot API 6.1.
|
2022-02-09 17:30:16 +01:00
|
|
|
callback_data (:obj:`str` | :obj:`object`, optional): Data to be sent in a callback query
|
|
|
|
to the bot when button is pressed, UTF-8 1-64 bytes. If the bot instance allows
|
|
|
|
arbitrary callback data, anything can be passed.
|
2022-06-09 17:08:54 +02:00
|
|
|
|
|
|
|
Tip:
|
|
|
|
The value entered here will be available in :attr:`telegram.CallbackQuery.data`.
|
|
|
|
|
2022-05-03 18:21:50 +02:00
|
|
|
web_app (:obj:`telegram.WebAppInfo`, optional): Description of the `Web App
|
|
|
|
<https://core.telegram.org/bots/webapps>`_ that will be launched when the user presses
|
|
|
|
the button. The Web App will be able to send an arbitrary message on behalf of the user
|
|
|
|
using the method :meth:`~telegram.Bot.answer_web_app_query`. Available only in
|
|
|
|
private chats between a user and the bot.
|
|
|
|
|
|
|
|
.. versionadded:: 20.0
|
2017-07-23 22:33:08 +02:00
|
|
|
switch_inline_query (:obj:`str`, optional): If set, pressing the button will prompt the
|
|
|
|
user to select one of their chats, open that chat and insert the bot's username and the
|
2016-10-04 00:02:18 +02:00
|
|
|
specified inline query in the input field. Can be empty, in which case just the bot's
|
2017-07-23 22:33:08 +02:00
|
|
|
username will be inserted. This offers an easy way for users to start using your bot
|
|
|
|
in inline mode when they are currently in a private chat with it. Especially useful
|
|
|
|
when combined with switch_pm* actions - in this case the user will be automatically
|
|
|
|
returned to the chat they switched from, skipping the chat selection screen.
|
|
|
|
switch_inline_query_current_chat (:obj:`str`, optional): If set, pressing the button will
|
|
|
|
insert the bot's username and the specified inline query in the current chat's input
|
|
|
|
field. Can be empty, in which case only the bot's username will be inserted. This
|
|
|
|
offers a quick way for the user to open your bot in inline mode in the same chat - good
|
|
|
|
for selecting something from multiple options.
|
|
|
|
callback_game (:class:`telegram.CallbackGame`, optional): Description of the game that will
|
|
|
|
be launched when the user presses the button. This type of button must always be
|
|
|
|
the ``first`` button in the first row.
|
Documentation Improvements (#2008)
* Minor doc updates, following official API docs
* Fix spelling in Defaults docstrings
* Clarify Changelog of v12.7 about aware dates
* Fix typo in CHANGES.rst (#2024)
* Fix PicklePersistence.flush() with only bot_data (#2017)
* Update pylint in pre-commit to fix CI (#2018)
* Add Filters.via_bot (#2009)
* feat: via_bot filter
also fixing a small mistake in the empty parameter of the user filter and improve docs slightly
* fix: forgot to set via_bot to None
* fix: redoing subclassing to copy paste solution
* Cosmetic changes
Co-authored-by: Hinrich Mahler <hinrich.mahler@freenet.de>
* Update CHANGES.rst
Fixed Typo
Co-authored-by: Bibo-Joshi <hinrich.mahler@freenet.de>
Co-authored-by: Poolitzer <25934244+Poolitzer@users.noreply.github.com>
* Update downloads badge, add info on IRC Channel to Getting Help section
* Remove RegexHandler from ConversationHandlers Docs (#1973)
Replaced RegexHandler with MessageHandler, since the former is deprecated
* Fix Filters.via_bot docstrings
* Add notes on Markdown v1 being legacy mode
* Fixed typo in the Regex doc.. (#2036)
* Typo: Spelling
* Minor cleanup from #2043
* Document CommandHandler ignoring channel posts
* Doc fixes for a few telegram.ext classes
* Doc fixes for most `telegram` classes.
* pep-8
forgot the hard wrap is at 99 chars, not 100!
fixed a few spelling mistakes too.
* Address review and made rendering of booleans consistent
True, False, None are now rendered with ``bool`` wherever they weren't in telegram and telegram.ext classes.
* Few doc fixes for inline* classes
As usual, docs were cross-checked with official tg api docs.
* Doc fixes for telegram/files classes
As usual, docs were cross-checked with official tg api docs.
* Doc fixes for telegram.Game
Mostly just added hyperlinks. And fixed message length doc.
As usual, docs were cross-checked with official tg api docs.
* Very minor doc fix for passportfile.py and passportelementerrors.py
Didn't bother changing too much since this seems to be a custom implementation.
* Doc fixes for telegram.payments
As usual, cross-checked with official bot api docs.
* Address review 2
Few tiny other fixes too.
* Changed from ``True/False/None`` to :obj:`True/False/None` project-wide.
Few tiny other doc fixes too.
Co-authored-by: Robert Geislinger <mitachundkrach@gmail.com>
Co-authored-by: Poolitzer <25934244+Poolitzer@users.noreply.github.com>
Co-authored-by: GauthamramRavichandran <30320759+GauthamramRavichandran@users.noreply.github.com>
Co-authored-by: Mahesh19 <maheshvagicherla99438@gmail.com>
Co-authored-by: hoppingturtles <ilovebhagwan@gmail.com>
2020-08-24 19:35:57 +02:00
|
|
|
pay (:obj:`bool`, optional): Specify :obj:`True`, to send a Pay button. This type of button
|
2021-12-11 15:21:56 +01:00
|
|
|
must always be the `first` button in the first row and can only be used in invoice
|
|
|
|
messages.
|
2017-09-01 08:43:08 +02:00
|
|
|
|
2020-12-30 15:59:50 +01:00
|
|
|
Attributes:
|
|
|
|
text (:obj:`str`): Label text on the button.
|
2021-12-11 15:21:56 +01:00
|
|
|
url (:obj:`str`): Optional. HTTP or tg:// url to be opened when the button is pressed.
|
|
|
|
Links ``tg://user?id=<user_id>`` can be used to mention a user by
|
|
|
|
their ID without using a username, if this is allowed by their privacy settings.
|
|
|
|
|
|
|
|
.. versionchanged:: 13.9
|
|
|
|
You can now mention a user using ``tg://user?id=<user_id>``.
|
2022-05-03 18:21:50 +02:00
|
|
|
login_url (:class:`telegram.LoginUrl`): Optional. An ``HTTPS`` URL used to automatically
|
2020-12-30 15:59:50 +01:00
|
|
|
authorize the user. Can be used as a replacement for the Telegram Login Widget.
|
2022-05-03 18:21:50 +02:00
|
|
|
|
|
|
|
Caution:
|
|
|
|
Only ``HTTPS`` links are allowed after Bot API 6.1.
|
2021-06-06 11:48:48 +02:00
|
|
|
callback_data (:obj:`str` | :obj:`object`): Optional. Data to be sent in a callback query
|
|
|
|
to the bot when button is pressed, UTF-8 1-64 bytes.
|
2022-05-03 18:21:50 +02:00
|
|
|
web_app (:obj:`telegram.WebAppInfo`): Optional. Description of the `Web App
|
|
|
|
<https://core.telegram.org/bots/webapps>`_ that will be launched when the user presses
|
|
|
|
the button. The Web App will be able to send an arbitrary message on behalf of the user
|
|
|
|
using the method :meth:`~telegram.Bot.answer_web_app_query`. Available only in
|
|
|
|
private chats between a user and the bot.
|
|
|
|
|
|
|
|
.. versionadded:: 20.0
|
2020-12-30 15:59:50 +01:00
|
|
|
switch_inline_query (:obj:`str`): Optional. Will prompt the user to select one of their
|
|
|
|
chats, open that chat and insert the bot's username and the specified inline query in
|
2022-05-03 18:21:50 +02:00
|
|
|
the input field. Can be empty, in which case just the bot's username will be inserted.
|
2020-12-30 15:59:50 +01:00
|
|
|
switch_inline_query_current_chat (:obj:`str`): Optional. Will insert the bot's username and
|
|
|
|
the specified inline query in the current chat's input field. Can be empty, in which
|
2022-05-03 18:21:50 +02:00
|
|
|
case just the bot's username will be inserted.
|
2020-12-30 15:59:50 +01:00
|
|
|
callback_game (:class:`telegram.CallbackGame`): Optional. Description of the game that will
|
|
|
|
be launched when the user presses the button.
|
2021-02-01 17:59:39 +01:00
|
|
|
pay (:obj:`bool`): Optional. Specify :obj:`True`, to send a Pay button.
|
2020-12-30 15:59:50 +01:00
|
|
|
|
2016-04-21 14:21:12 +02:00
|
|
|
"""
|
2016-04-14 01:26:38 +02:00
|
|
|
|
2021-05-29 16:18:16 +02:00
|
|
|
__slots__ = (
|
|
|
|
"callback_game",
|
|
|
|
"url",
|
|
|
|
"switch_inline_query_current_chat",
|
|
|
|
"callback_data",
|
|
|
|
"pay",
|
|
|
|
"switch_inline_query",
|
|
|
|
"text",
|
|
|
|
"login_url",
|
2022-05-03 18:21:50 +02:00
|
|
|
"web_app",
|
2021-05-29 16:18:16 +02:00
|
|
|
)
|
|
|
|
|
2017-01-09 19:16:28 +01:00
|
|
|
def __init__(
|
2020-11-05 18:12:01 +01:00
|
|
|
self,
|
2020-10-06 19:28:40 +02:00
|
|
|
text: str,
|
|
|
|
url: str = None,
|
2022-06-27 18:58:51 +02:00
|
|
|
callback_data: Union[str, object] = None,
|
2020-10-06 19:28:40 +02:00
|
|
|
switch_inline_query: str = None,
|
|
|
|
switch_inline_query_current_chat: str = None,
|
2022-05-03 18:21:50 +02:00
|
|
|
callback_game: CallbackGame = None,
|
2020-10-06 19:28:40 +02:00
|
|
|
pay: bool = None,
|
2022-05-03 18:21:50 +02:00
|
|
|
login_url: LoginUrl = None,
|
|
|
|
web_app: WebAppInfo = None,
|
2022-10-07 11:51:53 +02:00
|
|
|
*,
|
|
|
|
api_kwargs: JSONDict = None,
|
2020-10-06 19:28:40 +02:00
|
|
|
):
|
2022-10-07 11:51:53 +02:00
|
|
|
super().__init__(api_kwargs=api_kwargs)
|
2016-04-14 01:26:38 +02:00
|
|
|
# Required
|
|
|
|
self.text = text
|
|
|
|
|
|
|
|
# Optionals
|
2019-11-23 17:05:03 +01:00
|
|
|
self.url = url
|
|
|
|
self.login_url = login_url
|
|
|
|
self.callback_data = callback_data
|
|
|
|
self.switch_inline_query = switch_inline_query
|
|
|
|
self.switch_inline_query_current_chat = switch_inline_query_current_chat
|
|
|
|
self.callback_game = callback_game
|
|
|
|
self.pay = pay
|
2022-05-03 18:21:50 +02:00
|
|
|
self.web_app = web_app
|
2021-06-06 11:48:48 +02:00
|
|
|
self._id_attrs = ()
|
|
|
|
self._set_id_attrs()
|
2019-08-23 21:20:41 +02:00
|
|
|
|
2021-06-06 11:48:48 +02:00
|
|
|
def _set_id_attrs(self) -> None:
|
2020-07-14 21:33:56 +02:00
|
|
|
self._id_attrs = (
|
|
|
|
self.text,
|
|
|
|
self.url,
|
|
|
|
self.login_url,
|
|
|
|
self.callback_data,
|
2022-05-18 07:48:20 +02:00
|
|
|
self.web_app,
|
2020-07-14 21:33:56 +02:00
|
|
|
self.switch_inline_query,
|
|
|
|
self.switch_inline_query_current_chat,
|
|
|
|
self.callback_game,
|
|
|
|
self.pay,
|
|
|
|
)
|
2021-06-06 11:48:48 +02:00
|
|
|
|
2022-05-03 18:21:50 +02:00
|
|
|
@classmethod
|
|
|
|
def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["InlineKeyboardButton"]:
|
|
|
|
"""See :meth:`telegram.TelegramObject.de_json`."""
|
|
|
|
data = cls._parse_data(data)
|
|
|
|
|
|
|
|
if not data:
|
|
|
|
return None
|
|
|
|
|
|
|
|
data["login_url"] = LoginUrl.de_json(data.get("login_url"), bot)
|
|
|
|
data["web_app"] = WebAppInfo.de_json(data.get("web_app"), bot)
|
|
|
|
data["callback_game"] = CallbackGame.de_json(data.get("callback_game"), bot)
|
|
|
|
|
2022-10-07 11:51:53 +02:00
|
|
|
return super().de_json(data=data, bot=bot)
|
2022-05-03 18:21:50 +02:00
|
|
|
|
2022-06-27 18:58:51 +02:00
|
|
|
def update_callback_data(self, callback_data: Union[str, object]) -> None:
|
2021-06-06 11:48:48 +02:00
|
|
|
"""
|
|
|
|
Sets :attr:`callback_data` to the passed object. Intended to be used by
|
|
|
|
:class:`telegram.ext.CallbackDataCache`.
|
|
|
|
|
|
|
|
.. versionadded:: 13.6
|
|
|
|
|
|
|
|
Args:
|
2022-02-09 17:30:16 +01:00
|
|
|
callback_data (:class:`object`): The new callback data.
|
2021-06-06 11:48:48 +02:00
|
|
|
"""
|
|
|
|
self.callback_data = callback_data
|
|
|
|
self._set_id_attrs()
|