diff --git a/AUTHORS.rst b/AUTHORS.rst index dbec9777330..7f38b601ceb 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -74,6 +74,7 @@ The following wonderful people contributed directly or indirectly to this projec - `LRezende `_ - `macrojames `_ - `Matheus Lemos `_ +- `Michael Dix `_ - `Michael Elovskikh `_ - `miles `_ - `Mischa Krüger `_ diff --git a/CHANGES.rst b/CHANGES.rst index 81d68ffb823..0b990757d53 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,6 +1,7 @@ ========= Changelog ========= + Version 20.0b0 ============== *Released 2022-12-15* @@ -10,7 +11,7 @@ This is the technical changelog for version 20.0b0. More elaborate release notes Major Changes ------------- -- Make `TelegramObject` Immutable (`#3249`_) +- Make ``TelegramObject`` Immutable (`#3249`_) Minor Changes, Documentation Improvements and CI ------------------------------------------------ diff --git a/README.rst b/README.rst index 5229da62f08..e461f198733 100644 --- a/README.rst +++ b/README.rst @@ -148,9 +148,9 @@ Optional Dependencies PTB can be installed with optional dependencies: * ``pip install python-telegram-bot[passport]`` installs the `cryptography>=3.0 `_ library. Use this, if you want to use Telegram Passport related functionality. -* ``pip install python-telegram-bot[socks]`` installs ``httpx[socks]``. Use this, if you want to work behind a Socks5 server. -* ``pip install python-telegram-bot[rate-limiter]`` installs ``aiolimiter~=1.0.0``. Use this, if you want to use ``telegram.ext.AIORateLimiter``. -* ``pip install python-telegram-bot[webhooks]`` installs the `tornado~=6.2 `_ library. Use this, if you want to use ``telegram.ext.Updater.start_webhook``/``telegram.ext.Application.start_webhook``. +* ``pip install python-telegram-bot[socks]`` installs `httpx[socks] `_. Use this, if you want to work behind a Socks5 server. +* ``pip install python-telegram-bot[rate-limiter]`` installs `aiolimiter~=1.0.0 `_. Use this, if you want to use ``telegram.ext.AIORateLimiter``. +* ``pip install python-telegram-bot[webhooks]`` installs the `tornado~=6.2 `_ library. Use this, if you want to use ``telegram.ext.Updater.start_webhook``/``telegram.ext.Application.run_webhook``. * ``pip install python-telegram-bot[callback-data]`` installs the `cachetools~=5.2.0 `_ library. Use this, if you want to use `arbitrary callback_data `_. * ``pip install python-telegram-bot[job-queue]`` installs the `APScheduler~=3.9.1 `_ library and enforces `pytz>=2018.6 `_, where ``pytz`` is a dependency of ``APScheduler``. Use this, if you want to use the ``telegram.ext.JobQueue``. diff --git a/README_RAW.rst b/README_RAW.rst index 47dd8c7fe8d..5db4d5c8794 100644 --- a/README_RAW.rst +++ b/README_RAW.rst @@ -34,7 +34,7 @@ :target: https://github.com/python-telegram-bot/python-telegram-bot/ :alt: Github Actions workflow -.. image:: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot +.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot :alt: Code coverage @@ -149,7 +149,7 @@ Optional Dependencies PTB can be installed with optional dependencies: * ``pip install python-telegram-bot-raw[passport]`` installs the `cryptography>=3.0 `_ library. Use this, if you want to use Telegram Passport related functionality. -* ``pip install python-telegram-bot-raw[socks]`` installs ``httpx[socks]``. Use this, if you want to work behind a Socks5 server. +* ``pip install python-telegram-bot-raw[socks]`` installs `httpx[socks] `_. Use this, if you want to work behind a Socks5 server. To install multiple optional dependencies, separate them by commas, e.g. ``pip install python-telegram-bot-raw[passport,socks]``. diff --git a/docs/source/conf.py b/docs/source/conf.py index 8ac32495df1..6b3de8c6516 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -44,11 +44,15 @@ "sphinx.ext.napoleon", "sphinx.ext.intersphinx", "sphinx.ext.linkcode", + "sphinx.ext.extlinks", "sphinx_paramlinks", "sphinxcontrib.mermaid", "sphinx_search.extension", ] +# For shorter links to Wiki in docstrings +extlinks = {"wiki": ("https://github.com/python-telegram-bot/python-telegram-bot/wiki/%s", "%s")} + # Use intersphinx to reference the python builtin library docs intersphinx_mapping = { "python": ("https://docs.python.org/3", None), diff --git a/telegram/_bot.py b/telegram/_bot.py index 355ca22c667..bac228a26ac 100644 --- a/telegram/_bot.py +++ b/telegram/_bot.py @@ -150,10 +150,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.ext.Application.bot`, :attr:`telegram.ext.CallbackContext.bot`, :attr:`telegram.ext.Updater.bot`, - `Your First Bot `_, - `Builder Pattern `_ + :wiki:`Your First Bot `, + :wiki:`Builder Pattern ` .. versionadded:: 13.2 Objects of this class are comparable in terms of equality. Two objects of this class are @@ -932,7 +930,8 @@ async def send_photo( """Use this method to send photos. .. seealso:: :meth:`telegram.Message.reply_photo`, :meth:`telegram.Chat.send_photo`, - :meth:`telegram.User.send_photo` + :meth:`telegram.User.send_photo`, + :wiki:`Working with Files and Media ` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -941,6 +940,11 @@ async def send_photo( |fileinput| Lastly you can pass an existing :class:`telegram.PhotoSize` object to send. + Caution: + * The photo must be at most 10MB in size. + * The photo's width and height must not exceed 10000 in total. + * Width and height ratio must be at most 20. + .. versionchanged:: 13.2 Accept :obj:`bytes` as input. @@ -1045,7 +1049,8 @@ async def send_audio( For sending voice messages, use the :meth:`send_voice` method instead. .. seealso:: :meth:`telegram.Message.reply_audio`, :meth:`telegram.Chat.send_audio`, - :meth:`telegram.User.send_audio` + :meth:`telegram.User.send_audio`, + :wiki:`Working with Files and Media ` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1170,7 +1175,8 @@ async def send_document( changed in the future. .. seealso:: :meth:`telegram.Message.reply_document`, :meth:`telegram.Chat.send_document`, - :meth:`telegram.User.send_document` + :meth:`telegram.User.send_document`, + :wiki:`Working with Files and Media ` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1283,7 +1289,8 @@ async def send_sticker( Use this method to send static ``.WEBP``, animated ``.TGS``, or video ``.WEBM`` stickers. .. seealso:: :meth:`telegram.Message.reply_sticker`, :meth:`telegram.Chat.send_sticker`, - :meth:`telegram.User.send_sticker` + :meth:`telegram.User.send_sticker`, + :wiki:`Working with Files and Media ` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1378,7 +1385,8 @@ async def send_video( changed by Telegram. .. seealso:: :meth:`telegram.Message.reply_video`, :meth:`telegram.Chat.send_video`, - :meth:`telegram.User.send_video` + :meth:`telegram.User.send_video`, + :wiki:`Working with Files and Media ` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1507,7 +1515,8 @@ async def send_video_note( .. seealso:: :meth:`telegram.Message.reply_video_note`, :meth:`telegram.Chat.send_video_note`, - :meth:`telegram.User.send_video_note` + :meth:`telegram.User.send_video_note`, + :wiki:`Working with Files and Media ` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1629,7 +1638,8 @@ async def send_animation( .. seealso:: :meth:`telegram.Message.reply_animation`, :meth:`telegram.Chat.send_animation`, - :meth:`telegram.User.send_animation` + :meth:`telegram.User.send_animation`, + :wiki:`Working with Files and Media ` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1758,7 +1768,8 @@ async def send_voice( sent as files. .. seealso:: :meth:`telegram.Message.reply_voice`, :meth:`telegram.Chat.send_voice`, - :meth:`telegram.User.send_voice` + :meth:`telegram.User.send_voice`, + :wiki:`Working with Files and Media ` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -1859,7 +1870,8 @@ async def send_media_group( parse_mode: ODVInput[str] = DEFAULT_NONE, caption_entities: Sequence["MessageEntity"] = None, ) -> Tuple[Message, ...]: - """Use this method to send a group of photos or videos as an album. + """Use this method to send a group of photos, videos, documents or audios as an album. + Documents and audio files can be only grouped in an album with messages of the same type. .. versionchanged:: 20.0 Returns a tuple instead of a list. @@ -1871,7 +1883,8 @@ async def send_media_group( .. seealso:: :meth:`telegram.Message.reply_media_group`, :meth:`telegram.Chat.send_media_group`, - :meth:`telegram.User.send_media_group` + :meth:`telegram.User.send_media_group`, + :wiki:`Working with Files and Media ` Args: chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| @@ -2717,7 +2730,8 @@ async def answer_inline_query( :paramref:`telegram.InlineQuery.answer.auto_pagination` set to :obj:`True`, which will take care of passing the correct value. - .. seealso:: :meth:`telegram.InlineQuery.answer` + .. seealso:: :meth:`telegram.InlineQuery.answer`, + :wiki:`Working with Files and Media ` Args: inline_query_id (:obj:`str`): Unique identifier for the answered query. @@ -2865,7 +2879,8 @@ async def get_file( :meth:`telegram.Document.get_file`, :meth:`telegram.PassportFile.get_file`, :meth:`telegram.PhotoSize.get_file`, :meth:`telegram.Sticker.get_file`, :meth:`telegram.Video.get_file`, :meth:`telegram.VideoNote.get_file`, - :meth:`telegram.Voice.get_file` + :meth:`telegram.Voice.get_file`, + :wiki:`Working with Files and Media ` Args: file_id (:obj:`str` | :class:`telegram.Animation` | :class:`telegram.Audio` | \ @@ -3364,7 +3379,8 @@ async def edit_message_media( |editreplymarkup| .. seealso:: :meth:`telegram.Message.edit_media`, - :meth:`telegram.CallbackQuery.edit_message_media` + :meth:`telegram.CallbackQuery.edit_message_media`, + :wiki:`Working with Files and Media ` Args: media (:class:`telegram.InputMedia`): An object for a new media content @@ -3619,9 +3635,9 @@ async def set_webhook( integration. certificate (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | :obj:`str`): Upload your public key certificate so that the root - certificate in use can be checked. See our `self-signed guide `_ for details. |uploadinputnopath| + certificate in use can be checked. See our :wiki:`self-signed guide\ + ` for details. + |uploadinputnopath| ip_address (:obj:`str`, optional): The fixed IP address which will be used to send webhook requests instead of the IP address resolved through DNS. max_connections (:obj:`int`, optional): Maximum allowed number of simultaneous HTTPS diff --git a/telegram/_botcommand.py b/telegram/_botcommand.py index 362d95fbcf7..8bba7c29f52 100644 --- a/telegram/_botcommand.py +++ b/telegram/_botcommand.py @@ -41,8 +41,12 @@ class BotCommand(TelegramObject): :tg-const:`telegram.BotCommand.MAX_DESCRIPTION` characters. Attributes: - command (:obj:`str`): Text of the command. - description (:obj:`str`): Description of the command. + command (:obj:`str`): Text of the command; :tg-const:`telegram.BotCommand.MIN_COMMAND`- + :tg-const:`telegram.BotCommand.MAX_COMMAND` characters. Can contain only lowercase + English letters, digits and underscores. + description (:obj:`str`): Description of the command; + :tg-const:`telegram.BotCommand.MIN_DESCRIPTION`- + :tg-const:`telegram.BotCommand.MAX_DESCRIPTION` characters. """ diff --git a/telegram/_callbackquery.py b/telegram/_callbackquery.py index b72541f62c6..d65323a83a3 100644 --- a/telegram/_callbackquery.py +++ b/telegram/_callbackquery.py @@ -78,23 +78,27 @@ class CallbackQuery(TelegramObject): inline_message_id (:obj:`str`, optional): Identifier of the message sent via the bot in inline mode, that originated the query. game_short_name (:obj:`str`, optional): Short name of a Game to be returned, serves as - the unique identifier for the game + the unique identifier for the game. Attributes: id (:obj:`str`): Unique identifier for this query. from_user (:class:`telegram.User`): Sender. chat_instance (:obj:`str`): Global identifier, uniquely corresponding to the chat to which - the message with the callback button was sent. + the message with the callback button was sent. Useful for high scores in games. message (:class:`telegram.Message`): Optional. Message with the callback button that - originated the query. + originated the query. Note that message content and message date will not be available + if the message is too old. data (:obj:`str` | :obj:`object`): Optional. Data associated with the callback button. + Be aware that the message, which originated the query, can contain no callback buttons + with this data. Tip: The value here is the same as the value passed in :paramref:`telegram.InlineKeyboardButton.callback_data`. inline_message_id (:obj:`str`): Optional. Identifier of the message sent via the bot in - inline mode, that originated the query. - game_short_name (:obj:`str`): Optional. Short name of a Game to be returned. + inline mode, that originated the query. + game_short_name (:obj:`str`): Optional. Short name of a Game to be returned, serves as + the unique identifier for the game. """ diff --git a/telegram/_chatinvitelink.py b/telegram/_chatinvitelink.py index a281b37cb67..5022f759de4 100644 --- a/telegram/_chatinvitelink.py +++ b/telegram/_chatinvitelink.py @@ -83,6 +83,7 @@ class ChatInviteLink(TelegramObject): :tg-const:`telegram.constants.ChatInviteLinkLimit.MIN_MEMBER_LIMIT`- :tg-const:`telegram.constants.ChatInviteLinkLimit.MAX_MEMBER_LIMIT`. name (:obj:`str`): Optional. Invite link name. + 0-:tg-const:`telegram.constants.ChatInviteLinkLimit.NAME_LENGTH` characters. .. versionadded:: 13.8 pending_join_request_count (:obj:`int`): Optional. Number of pending join requests diff --git a/telegram/_chatlocation.py b/telegram/_chatlocation.py index 0b885d436bb..209873e4532 100644 --- a/telegram/_chatlocation.py +++ b/telegram/_chatlocation.py @@ -40,10 +40,13 @@ class ChatLocation(TelegramObject): Can't be a live location. address (:obj:`str`): Location address; :tg-const:`telegram.ChatLocation.MIN_ADDRESS`- - :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner + :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner. Attributes: location (:class:`telegram.Location`): The location to which the supergroup is connected. - address (:obj:`str`): Location address, as defined by the chat owner + Can't be a live location. + address (:obj:`str`): Location address; + :tg-const:`telegram.ChatLocation.MIN_ADDRESS`- + :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner. """ diff --git a/telegram/_chatmember.py b/telegram/_chatmember.py index 678e682b7a3..aff4750925a 100644 --- a/telegram/_chatmember.py +++ b/telegram/_chatmember.py @@ -45,7 +45,7 @@ class ChatMember(TelegramObject): considered equal, if their :attr:`user` and :attr:`status` are equal. Examples: - :any:`Chat Member Bot ` + :any:`Chat Member Bot ` .. versionchanged:: 20.0 @@ -65,7 +65,10 @@ class ChatMember(TelegramObject): Attributes: user (:class:`telegram.User`): Information about the user. - status (:obj:`str`): The member's status in the chat. + status (:obj:`str`): The member's status in the chat. Can be + :attr:`~telegram.ChatMember.ADMINISTRATOR`, :attr:`~telegram.ChatMember.OWNER`, + :attr:`~telegram.ChatMember.BANNED`, :attr:`~telegram.ChatMember.LEFT`, + :attr:`~telegram.ChatMember.MEMBER` or :attr:`~telegram.ChatMember.RESTRICTED`. """ diff --git a/telegram/_chatmemberupdated.py b/telegram/_chatmemberupdated.py index f7f8833f991..b730a3a404e 100644 --- a/telegram/_chatmemberupdated.py +++ b/telegram/_chatmemberupdated.py @@ -65,7 +65,7 @@ class ChatMemberUpdated(TelegramObject): old_chat_member (:class:`telegram.ChatMember`): Previous information about the chat member. new_chat_member (:class:`telegram.ChatMember`): New information about the chat member. invite_link (:class:`telegram.ChatInviteLink`): Optional. Chat invite link, which was used - by the user to join the chat. + by the user to join the chat. For joining by invite link events only. """ diff --git a/telegram/_choseninlineresult.py b/telegram/_choseninlineresult.py index 37ed70eb313..a74a070017b 100644 --- a/telegram/_choseninlineresult.py +++ b/telegram/_choseninlineresult.py @@ -56,8 +56,11 @@ class ChosenInlineResult(TelegramObject): Attributes: result_id (:obj:`str`): The unique identifier for the result that was chosen. from_user (:class:`telegram.User`): The user that chose the result. - location (:class:`telegram.Location`): Optional. Sender location. - inline_message_id (:obj:`str`): Optional. Identifier of the sent inline message. + location (:class:`telegram.Location`): Optional. Sender location, only for bots that + require user location. + inline_message_id (:obj:`str`): Optional. Identifier of the sent inline message. Available + only if there is an inline keyboard attached to the message. Will be also received in + callback queries and can be used to edit the message. query (:obj:`str`): The query that was used to obtain the result. """ diff --git a/telegram/_dice.py b/telegram/_dice.py index 74086f6829f..8a5b268994f 100644 --- a/telegram/_dice.py +++ b/telegram/_dice.py @@ -52,8 +52,8 @@ class Dice(TelegramObject): If :attr:`emoji` is :tg-const:`telegram.Dice.SLOT_MACHINE`, each value corresponds to a unique combination of symbols, which - can be found at our `wiki `_. + can be found in our + :wiki:`wiki `. However, this behaviour is undocumented and might be changed by Telegram. .. @@ -75,6 +75,14 @@ class Dice(TelegramObject): Attributes: value (:obj:`int`): Value of the dice. + :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_BOWLING` + for :tg-const:`telegram.Dice.DICE`, :tg-const:`telegram.Dice.DARTS` and + :tg-const:`telegram.Dice.BOWLING` base emoji, + :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_BASKETBALL` + for :tg-const:`telegram.Dice.BASKETBALL` and :tg-const:`telegram.Dice.FOOTBALL` + base emoji, + :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_SLOT_MACHINE` + for :tg-const:`telegram.Dice.SLOT_MACHINE` base emoji. emoji (:obj:`str`): Emoji on which the dice throw animation is based. """ diff --git a/telegram/_files/animation.py b/telegram/_files/animation.py index eb6f795414a..59ad2c526db 100644 --- a/telegram/_files/animation.py +++ b/telegram/_files/animation.py @@ -44,7 +44,8 @@ class Animation(_BaseThumbedMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): File identifier. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. diff --git a/telegram/_files/audio.py b/telegram/_files/audio.py index 1b67748b34d..0d05519f92e 100644 --- a/telegram/_files/audio.py +++ b/telegram/_files/audio.py @@ -46,11 +46,11 @@ class Audio(_BaseThumbedMedium): which the music file belongs. Attributes: - file_id (:obj:`str`): Identifier for this file. - file_unique_id (:obj:`str`): Unique identifier for this file, which - is supposed to be the same over time and for different bots. - Can't be used to download or reuse the file. - duration (:obj:`int`): Duration of the audio in seconds. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. + file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be + the same over time and for different bots. Can't be used to download or reuse the file. + duration (:obj:`int`): Duration of the audio in seconds as defined by sender. performer (:obj:`str`): Optional. Performer of the audio as defined by sender or by audio tags. title (:obj:`str`): Optional. Title of the audio as defined by sender or by audio tags. diff --git a/telegram/_files/chatphoto.py b/telegram/_files/chatphoto.py index fabfa06d4db..f30b3a352eb 100644 --- a/telegram/_files/chatphoto.py +++ b/telegram/_files/chatphoto.py @@ -36,7 +36,7 @@ class ChatPhoto(TelegramObject): equal. Args: - small_file_id (:obj:`str`): Unique file identifier of small + small_file_id (:obj:`str`): File identifier of small (:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`) chat photo. This file_id can be used only for photo download and only for as long as the photo is not changed. @@ -44,7 +44,7 @@ class ChatPhoto(TelegramObject): (:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`) chat photo, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - big_file_id (:obj:`str`): Unique file identifier of big + big_file_id (:obj:`str`): File identifier of big (:tg-const:`telegram.ChatPhoto.SIZE_BIG` x :tg-const:`telegram.ChatPhoto.SIZE_BIG`) chat photo. This file_id can be used only for photo download and only for as long as the photo is not changed. diff --git a/telegram/_files/document.py b/telegram/_files/document.py index 621154914f2..023ab7be9f2 100644 --- a/telegram/_files/document.py +++ b/telegram/_files/document.py @@ -41,16 +41,15 @@ class Document(_BaseThumbedMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): File identifier. - file_unique_id (:obj:`str`): Unique identifier for this file, which - is supposed to be the same over time and for different bots. - Can't be used to download or reuse the file. - thumb (:class:`telegram.PhotoSize`): Optional. Document thumbnail. - file_name (:obj:`str`): Original filename. - mime_type (:obj:`str`): Optional. MIME type of the file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. + file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be + the same over time and for different bots. Can't be used to download or reuse the file. + thumb (:class:`telegram.PhotoSize`): Optional. Document thumbnail as defined by sender. + file_name (:obj:`str`): Optional. Original filename as defined by sender. + mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender. file_size (:obj:`int`): Optional. File size in bytes. - """ __slots__ = ("file_name", "mime_type") diff --git a/telegram/_files/file.py b/telegram/_files/file.py index dbcfe2b4ca8..796f8c73d98 100644 --- a/telegram/_files/file.py +++ b/telegram/_files/file.py @@ -42,7 +42,7 @@ class File(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`file_unique_id` is equal. - .. versionchanged:: 20.0: + .. versionchanged:: 20.0 ``download`` was split into :meth:`download_to_drive` and :meth:`download_to_memory`. Note: @@ -58,18 +58,19 @@ class File(TelegramObject): file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - file_size (:obj:`int`, optional): Optional. File size in bytes, if known. + file_size (:obj:`int`, optional): File size in bytes, if known. file_path (:obj:`str`, optional): File path. Use e.g. :meth:`download_to_drive` to get the file. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - file_size (:obj:`str`): Optional. File size in bytes. - file_path (:obj:`str`): Optional. File path. Use e.g. :meth:`download_to_drive` to get - the file. + file_size (:obj:`int`): Optional. File size in bytes, if known. + file_path (:obj:`str`): Optional. File path. Use e.g. :meth:`download_to_drive` to get the + file. """ __slots__ = ( @@ -141,6 +142,8 @@ async def download_to_drive( original file in order to decrypt the file without changing the existing one in-place. + .. seealso:: :wiki:`Working with Files and Media ` + .. versionchanged:: 20.0 * :paramref:`custom_path` parameter now also accepts :class:`pathlib.Path` as argument. @@ -224,6 +227,8 @@ async def download_to_memory( :obj:`io.BufferedIOBase`, the file contents will be saved to that object using the :obj:`out.write` method. + .. seealso:: :wiki:`Working with Files and Media ` + .. versionadded:: 20.0 Args: diff --git a/telegram/_files/inputmedia.py b/telegram/_files/inputmedia.py index 1e346456966..7fa4eb6763d 100644 --- a/telegram/_files/inputmedia.py +++ b/telegram/_files/inputmedia.py @@ -40,10 +40,12 @@ class InputMedia(TelegramObject): """ Base class for Telegram InputMedia Objects. - .. versionchanged:: 20.0: + .. versionchanged:: 20.0 Added arguments and attributes :attr:`type`, :attr:`media`, :attr:`caption`, :attr:`caption_entities`, :paramref:`parse_mode`. + .. seealso:: :wiki:`Working with Files and Media ` + Args: media_type (:obj:`str`): Type of media that the instance represents. media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \ @@ -66,8 +68,10 @@ class InputMedia(TelegramObject): Attributes: type (:obj:`str`): Type of the input media. media (:obj:`str` | :class:`telegram.InputFile`): Media to send. - caption (:obj:`str`): Optional. Caption of the media to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. + caption (:obj:`str`): Optional. Caption of the media to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities + parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr| .. versionchanged:: 20.0 @@ -115,6 +119,8 @@ class InputMediaAnimation(InputMedia): width, height and duration from that video, unless otherwise specified with the optional arguments. + .. seealso:: :wiki:`Working with Files and Media ` + Args: media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \ :class:`telegram.Animation`): File to send. |fileinputnopath| @@ -148,7 +154,10 @@ class InputMediaAnimation(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.ANIMATION`. media (:obj:`str` | :class:`telegram.InputFile`): Animation to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. + thumb (:class:`telegram.InputFile`): Optional. |thumbdocstringbase| + caption (:obj:`str`): Optional. Caption of the animation to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr| @@ -156,8 +165,6 @@ class InputMediaAnimation(InputMedia): * |tupleclassattrs| * |alwaystuple| - - thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. width (:obj:`int`): Optional. Animation width. height (:obj:`int`): Optional. Animation height. duration (:obj:`int`): Optional. Animation duration in seconds. @@ -208,6 +215,8 @@ def __init__( class InputMediaPhoto(InputMedia): """Represents a photo to be sent. + .. seealso:: :wiki:`Working with Files and Media ` + Args: media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \ :class:`telegram.PhotoSize`): File to send. |fileinputnopath| @@ -232,8 +241,10 @@ class InputMediaPhoto(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.PHOTO`. media (:obj:`str` | :class:`telegram.InputFile`): Photo to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. + caption (:obj:`str`): Optional. Caption of the photo to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr| .. versionchanged:: 20.0 @@ -273,6 +284,8 @@ def __init__( class InputMediaVideo(InputMedia): """Represents a video to be sent. + .. seealso:: :wiki:`Working with Files and Media ` + Note: * When using a :class:`telegram.Video` for the :attr:`media` attribute, it will take the width, height and duration from that video, unless otherwise specified with the optional @@ -316,8 +329,10 @@ class InputMediaVideo(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.VIDEO`. media (:obj:`str` | :class:`telegram.InputFile`): Video file to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. + caption (:obj:`str`): Optional. Caption of the video to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr| .. versionchanged:: 20.0 @@ -327,9 +342,9 @@ class InputMediaVideo(InputMedia): width (:obj:`int`): Optional. Video width. height (:obj:`int`): Optional. Video height. duration (:obj:`int`): Optional. Video duration in seconds. - supports_streaming (:obj:`bool`): Optional. Pass :obj:`True`, if the uploaded video is + supports_streaming (:obj:`bool`): Optional. :obj:`True`, if the uploaded video is suitable for streaming. - thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. + thumb (:class:`telegram.InputFile`): Optional. |thumbdocstringbase| """ @@ -380,6 +395,8 @@ def __init__( class InputMediaAudio(InputMedia): """Represents an audio file to be treated as music to be sent. + .. seealso:: :wiki:`Working with Files and Media ` + Note: When using a :class:`telegram.Audio` for the :attr:`media` attribute, it will take the duration, performer and title from that video, unless otherwise specified with the @@ -406,7 +423,7 @@ class InputMediaAudio(InputMedia): .. versionchanged:: 20.0 |sequenceclassargs| - duration (:obj:`int`): Duration of the audio in seconds as defined by sender. + duration (:obj:`int`, optional): Duration of the audio in seconds as defined by sender. performer (:obj:`str`, optional): Performer of the audio as defined by sender or by audio tags. title (:obj:`str`, optional): Title of the audio as defined by sender or by audio tags. @@ -419,19 +436,21 @@ class InputMediaAudio(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.AUDIO`. media (:obj:`str` | :class:`telegram.InputFile`): Audio file to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. + caption (:obj:`str`): Optional. Caption of the audio to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr| .. versionchanged:: 20.0 * |tupleclassattrs| * |alwaystuple| - duration (:obj:`int`): Duration of the audio in seconds. + duration (:obj:`int`): Optional. Duration of the audio in seconds. performer (:obj:`str`): Optional. Performer of the audio as defined by sender or by audio tags. title (:obj:`str`): Optional. Title of the audio as defined by sender or by audio tags. - thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. + thumb (:class:`telegram.InputFile`): Optional. |thumbdocstringbase| """ @@ -479,6 +498,8 @@ def __init__( class InputMediaDocument(InputMedia): """Represents a general file to be sent. + .. seealso:: :wiki:`Working with Files and Media ` + Args: media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \ :class:`telegram.Document`): File to send. |fileinputnopath| @@ -512,18 +533,20 @@ class InputMediaDocument(InputMedia): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.DOCUMENT`. media (:obj:`str` | :class:`telegram.InputFile`): File to send. - caption (:obj:`str`): Optional. Caption of the document to be sent. - parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting. + caption (:obj:`str`): Optional. Caption of the document to be sent, + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters + after entities parsing. + parse_mode (:obj:`str`): Optional. |parse_mode| caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr| .. versionchanged:: 20.0 * |tupleclassattrs| * |alwaystuple| - thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. + thumb (:class:`telegram.InputFile`): Optional. |thumbdocstringbase| disable_content_type_detection (:obj:`bool`): Optional. Disables automatic server-side - content type detection for files uploaded using multipart/form-data. Always true, if - the document is sent as part of an album. + content type detection for files uploaded using multipart/form-data. Always + :obj:`True`, if the document is sent as part of an album. """ diff --git a/telegram/_files/location.py b/telegram/_files/location.py index 59edda4e497..0a95058769d 100644 --- a/telegram/_files/location.py +++ b/telegram/_files/location.py @@ -48,10 +48,11 @@ class Location(TelegramObject): longitude (:obj:`float`): Longitude as defined by sender. latitude (:obj:`float`): Latitude as defined by sender. horizontal_accuracy (:obj:`float`): Optional. The radius of uncertainty for the location, - measured in meters. + measured in meters; 0-:tg-const:`telegram.Location.HORIZONTAL_ACCURACY`. live_period (:obj:`int`): Optional. Time relative to the message sending date, during which the location can be updated, in seconds. For active live locations only. - heading (:obj:`int`): Optional. The direction in which user is moving, in degrees. + heading (:obj:`int`): Optional. The direction in which user is moving, in degrees; + :tg-const:`telegram.Location.MIN_HEADING`-:tg-const:`telegram.Location.MAX_HEADING`. For active live locations only. proximity_alert_radius (:obj:`int`): Optional. Maximum distance for proximity alerts about approaching another chat member, in meters. For sent live locations only. diff --git a/telegram/_files/photosize.py b/telegram/_files/photosize.py index 0628529578e..dba1fd6ff09 100644 --- a/telegram/_files/photosize.py +++ b/telegram/_files/photosize.py @@ -39,7 +39,8 @@ class PhotoSize(_BaseMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. diff --git a/telegram/_files/sticker.py b/telegram/_files/sticker.py index f024652944b..df9b6a597da 100644 --- a/telegram/_files/sticker.py +++ b/telegram/_files/sticker.py @@ -62,10 +62,9 @@ class Sticker(_BaseThumbedMedium): thumb (:class:`telegram.PhotoSize`, optional): Sticker thumbnail in the ``.WEBP`` or ``.JPG`` format. emoji (:obj:`str`, optional): Emoji associated with the sticker - set_name (:obj:`str`, optional): Name of the sticker set to which the sticker - belongs. - mask_position (:class:`telegram.MaskPosition`, optional): For mask stickers, the - position where the mask should be placed. + set_name (:obj:`str`, optional): Name of the sticker set to which the sticker belongs. + mask_position (:class:`telegram.MaskPosition`, optional): For mask stickers, the position + where the mask should be placed. file_size (:obj:`int`, optional): File size in bytes. premium_animation (:class:`telegram.File`, optional): For premium regular stickers, @@ -78,7 +77,8 @@ class Sticker(_BaseThumbedMedium): .. versionadded:: 20.0 Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. @@ -197,7 +197,7 @@ class StickerSet(TelegramObject): arguments had to be changed. Use keyword arguments to make sure that the arguments are passed correctly. - .. versionchanged:: 20.0: + .. versionchanged:: 20.0 The parameter ``contains_masks`` has been removed. Use :paramref:`sticker_type` instead. Args: @@ -232,11 +232,13 @@ class StickerSet(TelegramObject): .. versionchanged:: 20.0 |tupleclassattrs| - sticker_type (:obj:`str`): Type of stickers in the set. + sticker_type (:obj:`str`): Type of stickers in the set, currently one of + :attr:`telegram.Sticker.REGULAR`, :attr:`telegram.Sticker.MASK`, + :attr:`telegram.Sticker.CUSTOM_EMOJI`. .. versionadded:: 20.0 thumb (:class:`telegram.PhotoSize`): Optional. Sticker set thumbnail in the ``.WEBP``, - ``.TGS`` or ``.WEBM`` format. + ``.TGS``, or ``.WEBM`` format. """ @@ -316,9 +318,11 @@ class MaskPosition(TelegramObject): point (:obj:`str`): The part of the face relative to which the mask should be placed. One of :attr:`FOREHEAD`, :attr:`EYES`, :attr:`MOUTH`, or :attr:`CHIN`. x_shift (:obj:`float`): Shift by X-axis measured in widths of the mask scaled to the face - size, from left to right. + size, from left to right. For example, choosing ``-1.0`` will place mask just to the + left of the default mask position. y_shift (:obj:`float`): Shift by Y-axis measured in heights of the mask scaled to the face - size, from top to bottom. + size, from top to bottom. For example, ``1.0`` will place the mask just below the + default mask position. scale (:obj:`float`): Mask scaling coefficient. For example, ``2.0`` means double size. """ diff --git a/telegram/_files/venue.py b/telegram/_files/venue.py index 8106c275e5e..ef6f54d0fe3 100644 --- a/telegram/_files/venue.py +++ b/telegram/_files/venue.py @@ -55,9 +55,12 @@ class Venue(TelegramObject): title (:obj:`str`): Name of the venue. address (:obj:`str`): Address of the venue. foursquare_id (:obj:`str`): Optional. Foursquare identifier of the venue. - foursquare_type (:obj:`str`): Optional. Foursquare type of the venue. + foursquare_type (:obj:`str`): Optional. Foursquare type of the venue. (For example, + "arts_entertainment/default", "arts_entertainment/aquarium" or "food/icecream".) google_place_id (:obj:`str`): Optional. Google Places identifier of the venue. - google_place_type (:obj:`str`): Optional. Google Places type of the venue. + google_place_type (:obj:`str`): Optional. Google Places type of the venue. (See + `supported types `_.) """ diff --git a/telegram/_files/video.py b/telegram/_files/video.py index b305bf32530..2944c7e65ed 100644 --- a/telegram/_files/video.py +++ b/telegram/_files/video.py @@ -44,7 +44,8 @@ class Video(_BaseThumbedMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. @@ -56,7 +57,6 @@ class Video(_BaseThumbedMedium): mime_type (:obj:`str`): Optional. MIME type of a file as defined by sender. file_size (:obj:`int`): Optional. File size in bytes. - """ __slots__ = ("duration", "file_name", "height", "mime_type", "width") diff --git a/telegram/_files/videonote.py b/telegram/_files/videonote.py index 31ec471f2c4..8b48440f306 100644 --- a/telegram/_files/videonote.py +++ b/telegram/_files/videonote.py @@ -42,11 +42,13 @@ class VideoNote(_BaseThumbedMedium): file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - length (:obj:`int`): Video width and height as defined by sender. + length (:obj:`int`): Video width and height (diameter of the video message) as defined + by sender. duration (:obj:`int`): Duration of the video in seconds as defined by sender. thumb (:class:`telegram.PhotoSize`): Optional. Video thumbnail. file_size (:obj:`int`): Optional. File size in bytes. diff --git a/telegram/_files/voice.py b/telegram/_files/voice.py index 47d6f7b6799..e922644e670 100644 --- a/telegram/_files/voice.py +++ b/telegram/_files/voice.py @@ -34,12 +34,13 @@ class Voice(_BaseMedium): file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - duration (:obj:`int`, optional): Duration of the audio in seconds as defined by sender. + duration (:obj:`int`): Duration of the audio in seconds as defined by sender. mime_type (:obj:`str`, optional): MIME type of the file as defined by sender. file_size (:obj:`int`, optional): File size in bytes. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. diff --git a/telegram/_forcereply.py b/telegram/_forcereply.py index 1123bb60017..a17c14507d7 100644 --- a/telegram/_forcereply.py +++ b/telegram/_forcereply.py @@ -59,9 +59,17 @@ class ForceReply(TelegramObject): Attributes: force_reply (:obj:`True`): Shows reply interface to the user, as if they manually selected the bots message and tapped 'Reply'. - selective (:obj:`bool`): Optional. Force reply from specific users only. - input_field_placeholder (:obj:`str`): Optional. The placeholder shown in the input - field when the reply is active. + selective (:obj:`bool`): Optional. Force reply from specific users only. Targets: + + 1) Users that are @mentioned in the :attr:`~telegram.Message.text` of the + :class:`telegram.Message` object. + 2) If the bot's message is a reply (has ``reply_to_message_id``), sender of the + original message. + input_field_placeholder (:obj:`str`): Optional. The placeholder to be shown in the input + field when the reply is active; + :tg-const:`telegram.ForceReply.MIN_INPUT_FIELD_PLACEHOLDER`- + :tg-const:`telegram.ForceReply.MAX_INPUT_FIELD_PLACEHOLDER` + characters. .. versionadded:: 13.7 diff --git a/telegram/_games/game.py b/telegram/_games/game.py index 849b0c27062..a78c5487d57 100644 --- a/telegram/_games/game.py +++ b/telegram/_games/game.py @@ -75,6 +75,7 @@ class Game(TelegramObject): game message. Can be automatically edited to include current high scores for the game when the bot calls :meth:`telegram.Bot.set_game_score`, or manually edited using :meth:`telegram.Bot.edit_message_text`. + 0-:tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` characters. text_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. Special entities that appear in text, such as usernames, URLs, bot commands, etc. This tuple is empty if the message does not contain text entities. diff --git a/telegram/_inline/inlinekeyboardbutton.py b/telegram/_inline/inlinekeyboardbutton.py index 34afb1e0ca3..e234058369e 100644 --- a/telegram/_inline/inlinekeyboardbutton.py +++ b/telegram/_inline/inlinekeyboardbutton.py @@ -95,8 +95,7 @@ class InlineKeyboardButton(TelegramObject): Tip: The value entered here will be available in :attr:`telegram.CallbackQuery.data`. - .. seealso:: `Arbitrary callback_data `_ + .. seealso:: :wiki:`Arbitrary callback_data ` web_app (:obj:`telegram.WebAppInfo`, optional): Description of the `Web App `_ that will be launched when the user presses @@ -110,7 +109,7 @@ class InlineKeyboardButton(TelegramObject): specified inline query in the input field. Can be empty, in which case just the bot's 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 + 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 @@ -118,11 +117,11 @@ class InlineKeyboardButton(TelegramObject): 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. + be launched when the user presses the button. This type of button **must** always be + the **first** button in the first row. pay (:obj:`bool`, optional): Specify :obj:`True`, to send a Pay button. This type of button - must always be the `first` button in the first row and can only be used in invoice - messages. + **must** always be the **first** button in the first row and can only be used in + invoice messages. Attributes: text (:obj:`str`): Label text on the button. @@ -148,15 +147,24 @@ class InlineKeyboardButton(TelegramObject): private chats between a user and the bot. .. versionadded:: 20.0 - 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 - the input field. Can be empty, in which case just the bot's username will be inserted. - 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 - case just the bot's username will be inserted. + 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 + specified inline query in the input field. Can be empty, in which case just the bot's + 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. - pay (:obj:`bool`): Optional. Specify :obj:`True`, to send a Pay button. + be launched when the user presses the button. This type of button **must** always be + the **first** button in the first row. + pay (:obj:`bool`): Optional. Specify :obj:`True`, to send a Pay button. This type of button + **must** always be the **first** button in the first row and can only be used in + invoice messages. """ diff --git a/telegram/_inline/inlinequery.py b/telegram/_inline/inlinequery.py index abd2a40b205..ff478438443 100644 --- a/telegram/_inline/inlinequery.py +++ b/telegram/_inline/inlinequery.py @@ -72,11 +72,16 @@ class InlineQuery(TelegramObject): query (:obj:`str`): Text of the query (up to :tg-const:`telegram.InlineQuery.MAX_QUERY_LENGTH` characters). offset (:obj:`str`): Offset of the results to be returned, can be controlled by the bot. - location (:class:`telegram.Location`): Optional. Sender location, only for bots that - request user location. chat_type (:obj:`str`): Optional. Type of the chat, from which the inline query was sent. + Can be either :tg-const:`telegram.Chat.SENDER` for a private chat with the inline query + sender, :tg-const:`telegram.Chat.PRIVATE`, :tg-const:`telegram.Chat.GROUP`, + :tg-const:`telegram.Chat.SUPERGROUP` or :tg-const:`telegram.Chat.CHANNEL`. The chat + type should be always known for requests sent from official clients and most + third-party clients, unless the request was sent from a secret chat. .. versionadded:: 13.5 + location (:class:`telegram.Location`): Optional. Sender location, only for bots that + request user location. """ diff --git a/telegram/_inline/inlinequeryresultaudio.py b/telegram/_inline/inlinequeryresultaudio.py index 3feffbe2f28..2ece3c2cbc6 100644 --- a/telegram/_inline/inlinequeryresultaudio.py +++ b/telegram/_inline/inlinequeryresultaudio.py @@ -37,6 +37,8 @@ class InlineQueryResultAudio(InlineQueryResult): Alternatively, you can use :attr:`input_message_content` to send a message with the specified content instead of the audio. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- diff --git a/telegram/_inline/inlinequeryresultcachedaudio.py b/telegram/_inline/inlinequeryresultcachedaudio.py index b811dccdcc5..608f1d5f714 100644 --- a/telegram/_inline/inlinequeryresultcachedaudio.py +++ b/telegram/_inline/inlinequeryresultcachedaudio.py @@ -37,6 +37,8 @@ class InlineQueryResultCachedAudio(InlineQueryResult): file will be sent by the user. Alternatively, you can use :attr:`input_message_content` to send a message with the specified content instead of the audio. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- diff --git a/telegram/_inline/inlinequeryresultcacheddocument.py b/telegram/_inline/inlinequeryresultcacheddocument.py index 55fa23df066..81df1c1d5af 100644 --- a/telegram/_inline/inlinequeryresultcacheddocument.py +++ b/telegram/_inline/inlinequeryresultcacheddocument.py @@ -37,6 +37,8 @@ class InlineQueryResultCachedDocument(InlineQueryResult): by the user with an optional caption. Alternatively, you can use :attr:`input_message_content` to send a message with the specified content instead of the file. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- diff --git a/telegram/_inline/inlinequeryresultcachedgif.py b/telegram/_inline/inlinequeryresultcachedgif.py index e0da75c5ba9..b295dee6b9c 100644 --- a/telegram/_inline/inlinequeryresultcachedgif.py +++ b/telegram/_inline/inlinequeryresultcachedgif.py @@ -38,12 +38,14 @@ class InlineQueryResultCachedGif(InlineQueryResult): use :attr:`input_message_content` to send a message with specified content instead of the animation. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes. gif_file_id (:obj:`str`): A valid file identifier for the GIF file. - title (:obj:`str`, optional): Title for the result.caption (:obj:`str`, optional): + title (:obj:`str`, optional): Title for the result. caption (:obj:`str`, optional): Caption of the GIF file to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. diff --git a/telegram/_inline/inlinequeryresultcachedmpeg4gif.py b/telegram/_inline/inlinequeryresultcachedmpeg4gif.py index 5505dcdbce7..80f8c2629c5 100644 --- a/telegram/_inline/inlinequeryresultcachedmpeg4gif.py +++ b/telegram/_inline/inlinequeryresultcachedmpeg4gif.py @@ -38,6 +38,8 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult): optional caption. Alternatively, you can use :attr:`input_message_content` to send a message with the specified content instead of the animation. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- diff --git a/telegram/_inline/inlinequeryresultcachedphoto.py b/telegram/_inline/inlinequeryresultcachedphoto.py index a0017ed0df4..314fd576fb0 100644 --- a/telegram/_inline/inlinequeryresultcachedphoto.py +++ b/telegram/_inline/inlinequeryresultcachedphoto.py @@ -38,6 +38,8 @@ class InlineQueryResultCachedPhoto(InlineQueryResult): :attr:`input_message_content` to send a message with the specified content instead of the photo. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- diff --git a/telegram/_inline/inlinequeryresultcachedsticker.py b/telegram/_inline/inlinequeryresultcachedsticker.py index f4a121e6cab..76e31c0b7d3 100644 --- a/telegram/_inline/inlinequeryresultcachedsticker.py +++ b/telegram/_inline/inlinequeryresultcachedsticker.py @@ -35,6 +35,8 @@ class InlineQueryResultCachedSticker(InlineQueryResult): be sent by the user. Alternatively, you can use :attr:`input_message_content` to send a message with the specified content instead of the sticker. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- diff --git a/telegram/_inline/inlinequeryresultcachedvideo.py b/telegram/_inline/inlinequeryresultcachedvideo.py index f0bea8dce00..4c3a7651090 100644 --- a/telegram/_inline/inlinequeryresultcachedvideo.py +++ b/telegram/_inline/inlinequeryresultcachedvideo.py @@ -38,6 +38,8 @@ class InlineQueryResultCachedVideo(InlineQueryResult): :attr:`input_message_content` to send a message with the specified content instead of the video. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- diff --git a/telegram/_inline/inlinequeryresultcachedvoice.py b/telegram/_inline/inlinequeryresultcachedvoice.py index 99611b4bd54..13ea8603237 100644 --- a/telegram/_inline/inlinequeryresultcachedvoice.py +++ b/telegram/_inline/inlinequeryresultcachedvoice.py @@ -37,6 +37,8 @@ class InlineQueryResultCachedVoice(InlineQueryResult): message will be sent by the user. Alternatively, you can use :attr:`input_message_content` to send a message with the specified content instead of the voice message. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- diff --git a/telegram/_inline/inlinequeryresultdocument.py b/telegram/_inline/inlinequeryresultdocument.py index f05d27afb7d..34aea17261e 100644 --- a/telegram/_inline/inlinequeryresultdocument.py +++ b/telegram/_inline/inlinequeryresultdocument.py @@ -38,6 +38,8 @@ class InlineQueryResultDocument(InlineQueryResult): specified content instead of the file. Currently, only .PDF and .ZIP files can be sent using this method. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- diff --git a/telegram/_inline/inlinequeryresultgif.py b/telegram/_inline/inlinequeryresultgif.py index 5c4bdb099a6..96aa82c0a07 100644 --- a/telegram/_inline/inlinequeryresultgif.py +++ b/telegram/_inline/inlinequeryresultgif.py @@ -37,6 +37,8 @@ class InlineQueryResultGif(InlineQueryResult): the user with optional caption. Alternatively, you can use :attr:`input_message_content` to send a message with the specified content instead of the animation. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- @@ -75,7 +77,8 @@ class InlineQueryResultGif(InlineQueryResult): gif_duration (:obj:`int`): Optional. Duration of the GIF in seconds. thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for the result. - thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail. + thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail, must be one of + ``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``. title (:obj:`str`): Optional. Title for the result. caption (:obj:`str`): Optional. Caption of the GIF file to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters diff --git a/telegram/_inline/inlinequeryresultlocation.py b/telegram/_inline/inlinequeryresultlocation.py index 145d5138134..b6293d82fc7 100644 --- a/telegram/_inline/inlinequeryresultlocation.py +++ b/telegram/_inline/inlinequeryresultlocation.py @@ -75,13 +75,21 @@ class InlineQueryResultLocation(InlineQueryResult): longitude (:obj:`float`): Location longitude in degrees. title (:obj:`str`): Location title. horizontal_accuracy (:obj:`float`): Optional. The radius of uncertainty for the location, - measured in meters. - live_period (:obj:`int`): Optional. Period in seconds for which the location can be - updated, should be between 60 and 86400. + measured in meters; 0- + :tg-const:`telegram.InlineQueryResultLocation.HORIZONTAL_ACCURACY`. + live_period (:obj:`int`): Optional. Period in seconds for which the location will be + updated, should be between + :tg-const:`telegram.InlineQueryResultLocation.MIN_LIVE_PERIOD` and + :tg-const:`telegram.InlineQueryResultLocation.MAX_LIVE_PERIOD`. heading (:obj:`int`): Optional. For live locations, a direction in which the user is - moving, in degrees. - proximity_alert_radius (:obj:`int`): Optional. For live locations, a maximum distance for - proximity alerts about approaching another chat member, in meters. + moving, in degrees. Must be between + :tg-const:`telegram.InlineQueryResultLocation.MIN_HEADING` and + :tg-const:`telegram.InlineQueryResultLocation.MAX_HEADING` if specified. + proximity_alert_radius (:obj:`int`): Optional. For live locations, a maximum distance + for proximity alerts about approaching another chat member, in meters. Must be + between :tg-const:`telegram.InlineQueryResultLocation.MIN_PROXIMITY_ALERT_RADIUS` + and :tg-const:`telegram.InlineQueryResultLocation.MAX_PROXIMITY_ALERT_RADIUS` + if specified. reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached to the message. input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the diff --git a/telegram/_inline/inlinequeryresultmpeg4gif.py b/telegram/_inline/inlinequeryresultmpeg4gif.py index b37077f2bc4..633d87abe20 100644 --- a/telegram/_inline/inlinequeryresultmpeg4gif.py +++ b/telegram/_inline/inlinequeryresultmpeg4gif.py @@ -38,6 +38,8 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult): use :attr:`input_message_content` to send a message with the specified content instead of the animation. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- @@ -46,7 +48,8 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult): mpeg4_width (:obj:`int`, optional): Video width. mpeg4_height (:obj:`int`, optional): Video height. mpeg4_duration (:obj:`int`, optional): Video duration in seconds. - thumb_url (:obj:`str`): URL of the static thumbnail (jpeg or gif) for the result. + thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for + the result. thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail, must be one of ``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``. title (:obj:`str`, optional): Title for the result. @@ -76,7 +79,8 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult): mpeg4_duration (:obj:`int`): Optional. Video duration in seconds. thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for the result. - thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail. + thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail, must be one of + ``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``. title (:obj:`str`): Optional. Title for the result. caption (:obj:`str`): Optional. Caption of the MPEG-4 file to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters diff --git a/telegram/_inline/inlinequeryresultphoto.py b/telegram/_inline/inlinequeryresultphoto.py index 35b5898b553..82caec1e935 100644 --- a/telegram/_inline/inlinequeryresultphoto.py +++ b/telegram/_inline/inlinequeryresultphoto.py @@ -37,6 +37,8 @@ class InlineQueryResultPhoto(InlineQueryResult): caption. Alternatively, you can use :attr:`input_message_content` to send a message with the specified content instead of the photo. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- diff --git a/telegram/_inline/inlinequeryresultvenue.py b/telegram/_inline/inlinequeryresultvenue.py index 9b6359b456c..b3494fbc33b 100644 --- a/telegram/_inline/inlinequeryresultvenue.py +++ b/telegram/_inline/inlinequeryresultvenue.py @@ -58,7 +58,7 @@ class InlineQueryResultVenue(InlineQueryResult): reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached to the message. input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the - message to be sent instead of the location. + message to be sent instead of the venue. thumb_url (:obj:`str`, optional): Url of the thumbnail for the result. thumb_width (:obj:`int`, optional): Thumbnail width. thumb_height (:obj:`int`, optional): Thumbnail height. @@ -74,8 +74,12 @@ class InlineQueryResultVenue(InlineQueryResult): address (:obj:`str`): Address of the venue. foursquare_id (:obj:`str`): Optional. Foursquare identifier of the venue if known. foursquare_type (:obj:`str`): Optional. Foursquare type of the venue, if known. + (For example, "arts_entertainment/default", "arts_entertainment/aquarium" or + "food/icecream".) google_place_id (:obj:`str`): Optional. Google Places identifier of the venue. - google_place_type (:obj:`str`): Optional. Google Places type of the venue. + google_place_type (:obj:`str`): Optional. Google Places type of the venue. (See + `supported types `_.) reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached to the message. input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the diff --git a/telegram/_inline/inlinequeryresultvideo.py b/telegram/_inline/inlinequeryresultvideo.py index cbd4aa85687..2d590edd377 100644 --- a/telegram/_inline/inlinequeryresultvideo.py +++ b/telegram/_inline/inlinequeryresultvideo.py @@ -42,6 +42,8 @@ class InlineQueryResultVideo(InlineQueryResult): If an InlineQueryResultVideo message contains an embedded video (e.g., YouTube), you must replace its content using :attr:`input_message_content`. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- @@ -50,7 +52,7 @@ class InlineQueryResultVideo(InlineQueryResult): mime_type (:obj:`str`): Mime type of the content of video url, "text/html" or "video/mp4". thumb_url (:obj:`str`): URL of the thumbnail (JPEG only) for the video. title (:obj:`str`): Title for the result. - caption (:obj:`str`, optional): Caption, + caption (:obj:`str`, optional): Caption of the video to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. parse_mode (:obj:`str`, optional): |parse_mode| @@ -67,7 +69,7 @@ class InlineQueryResultVideo(InlineQueryResult): to the message. input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the message to be sent instead of the video. This field is required if - InlineQueryResultVideo is used to send an HTML-page as a result + ``InlineQueryResultVideo`` is used to send an HTML-page as a result (e.g., a YouTube video). Attributes: @@ -80,10 +82,10 @@ class InlineQueryResultVideo(InlineQueryResult): thumb_url (:obj:`str`): URL of the thumbnail (JPEG only) for the video. title (:obj:`str`): Title for the result. caption (:obj:`str`): Optional. Caption of the video to be sent, - 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after - entities parsing. + 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities + parsing. parse_mode (:obj:`str`): Optional. |parse_mode| - caption_entities (Sequence[:class:`telegram.MessageEntity`]): Optional. + caption_entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr| .. versionchanged:: 20.0 @@ -95,11 +97,11 @@ class InlineQueryResultVideo(InlineQueryResult): video_height (:obj:`int`): Optional. Video height. video_duration (:obj:`int`): Optional. Video duration in seconds. description (:obj:`str`): Optional. Short description of the result. - reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached + reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached to the message. input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the message to be sent instead of the video. This field is required if - InlineQueryResultVideo is used to send an HTML-page as a result + ``InlineQueryResultVideo`` is used to send an HTML-page as a result (e.g., a YouTube video). """ diff --git a/telegram/_inline/inlinequeryresultvoice.py b/telegram/_inline/inlinequeryresultvoice.py index 2ec3cff50cd..77bf4c22cb1 100644 --- a/telegram/_inline/inlinequeryresultvoice.py +++ b/telegram/_inline/inlinequeryresultvoice.py @@ -38,6 +38,8 @@ class InlineQueryResultVoice(InlineQueryResult): :attr:`input_message_content` to send a message with the specified content instead of the voice message. + .. seealso:: :wiki:`Working with Files and Media ` + Args: id (:obj:`str`): Unique identifier for this result, :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`- diff --git a/telegram/_inline/inputinvoicemessagecontent.py b/telegram/_inline/inputinvoicemessagecontent.py index 93781fec584..b3161d169ec 100644 --- a/telegram/_inline/inputinvoicemessagecontent.py +++ b/telegram/_inline/inputinvoicemessagecontent.py @@ -115,22 +115,33 @@ class InputInvoiceMessageContent(InputMessageContent): currency (:obj:`str`): Three-letter ISO 4217 currency code, see more on `currencies `_ prices (Tuple[:class:`telegram.LabeledPrice`]): Price breakdown, a list of - components. + components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, + etc.) .. versionchanged:: 20.0 |tupleclassattrs| - max_tip_amount (:obj:`int`): Optional. The maximum accepted amount for tips in the smallest - units of the currency (integer, not float/double). + max_tip_amount (:obj:`int`): Optional. The maximum accepted amount for tips in the + *smallest* units of the currency (integer, **not** float/double). For example, for a + maximum tip of US$ 1.45 ``max_tip_amount`` is ``145``. See the ``exp`` parameter in + `currencies.json `_, it + shows the number of digits past the decimal point for each currency (2 for the majority + of currencies). Defaults to ``0``. suggested_tip_amounts (Tuple[:obj:`int`]): Optional. An array of suggested - amounts of tip in the smallest units of the currency (integer, not float/double). + amounts of tip in the *smallest* units of the currency (integer, **not** float/double). + At most 4 suggested tip amounts can be specified. The suggested tip amounts must be + positive, passed in a strictly increased order and must not exceed + :attr:`max_tip_amount`. .. versionchanged:: 20.0 |tupleclassattrs| provider_data (:obj:`str`): Optional. An object for data about the invoice, - which will be shared with the payment provider. - photo_url (:obj:`str`): Optional. URL of the product photo for the invoice. + which will be shared with the payment provider. A detailed description of the required + fields should be provided by the payment provider. + photo_url (:obj:`str`): Optional. URL of the product photo for the invoice. Can be a photo + of the goods or a marketing image for a service. People like it better when they see + what they are paying for. photo_size (:obj:`int`): Optional. Photo size. photo_width (:obj:`int`): Optional. Photo width. photo_height (:obj:`int`): Optional. Photo height. diff --git a/telegram/_inline/inputlocationmessagecontent.py b/telegram/_inline/inputlocationmessagecontent.py index a0a00285cb9..91124264473 100644 --- a/telegram/_inline/inputlocationmessagecontent.py +++ b/telegram/_inline/inputlocationmessagecontent.py @@ -57,13 +57,21 @@ class InputLocationMessageContent(InputMessageContent): latitude (:obj:`float`): Latitude of the location in degrees. longitude (:obj:`float`): Longitude of the location in degrees. horizontal_accuracy (:obj:`float`): Optional. The radius of uncertainty for the location, - measured in meters. - live_period (:obj:`int`): Optional. Period in seconds for which the location can be - updated. + measured in meters; 0- + :tg-const:`telegram.InputLocationMessageContent.HORIZONTAL_ACCURACY`. + live_period (:obj:`int`): Optional. Period in seconds for which the location can be + updated, should be between + :tg-const:`telegram.InputLocationMessageContent.MIN_LIVE_PERIOD` and + :tg-const:`telegram.InputLocationMessageContent.MAX_LIVE_PERIOD`. heading (:obj:`int`): Optional. For live locations, a direction in which the user is - moving, in degrees. - proximity_alert_radius (:obj:`int`): Optional. For live locations, a maximum distance for - proximity alerts about approaching another chat member, in meters. + moving, in degrees. Must be between + :tg-const:`telegram.InputLocationMessageContent.MIN_HEADING` and + :tg-const:`telegram.InputLocationMessageContent.MAX_HEADING` if specified. + proximity_alert_radius (:obj:`int`): Optional. For live locations, a maximum distance + for proximity alerts about approaching another chat member, in meters. Must be + between :tg-const:`telegram.InputLocationMessageContent.MIN_PROXIMITY_ALERT_RADIUS` + and :tg-const:`telegram.InputLocationMessageContent.MAX_PROXIMITY_ALERT_RADIUS` + if specified. """ diff --git a/telegram/_inline/inputtextmessagecontent.py b/telegram/_inline/inputtextmessagecontent.py index 8664ca49ffb..17759a19b93 100644 --- a/telegram/_inline/inputtextmessagecontent.py +++ b/telegram/_inline/inputtextmessagecontent.py @@ -52,7 +52,8 @@ class InputTextMessageContent(InputMessageContent): Attributes: message_text (:obj:`str`): Text of the message to be sent, - 1-:tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` characters after entities + :tg-const:`telegram.constants.MessageLimit.MIN_TEXT_LENGTH`- + :tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` characters after entities parsing. parse_mode (:obj:`str`): Optional. |parse_mode| entities (Tuple[:class:`telegram.MessageEntity`]): Optional. |captionentitiesattr| diff --git a/telegram/_inline/inputvenuemessagecontent.py b/telegram/_inline/inputvenuemessagecontent.py index 15ef7293f4e..f8c3ddd5794 100644 --- a/telegram/_inline/inputvenuemessagecontent.py +++ b/telegram/_inline/inputvenuemessagecontent.py @@ -54,8 +54,12 @@ class InputVenueMessageContent(InputMessageContent): address (:obj:`str`): Address of the venue. foursquare_id (:obj:`str`): Optional. Foursquare identifier of the venue, if known. foursquare_type (:obj:`str`): Optional. Foursquare type of the venue, if known. + (For example, "arts_entertainment/default", "arts_entertainment/aquarium" or + "food/icecream".) google_place_id (:obj:`str`): Optional. Google Places identifier of the venue. - google_place_type (:obj:`str`): Optional. Google Places type of the venue. + google_place_type (:obj:`str`): Optional. Google Places type of the venue. (See + `supported types `_.) """ diff --git a/telegram/_keyboardbutton.py b/telegram/_keyboardbutton.py index 0368496b92f..68f0f86b16f 100644 --- a/telegram/_keyboardbutton.py +++ b/telegram/_keyboardbutton.py @@ -68,12 +68,19 @@ class KeyboardButton(TelegramObject): .. versionadded:: 20.0 Attributes: - text (:obj:`str`): Text of the button. - request_contact (:obj:`bool`): Optional. The user's phone number will be sent. - request_location (:obj:`bool`): Optional. The user's current location will be sent. - request_poll (:class:`KeyboardButtonPollType`): Optional. If the user should create a poll. - web_app (:class:`WebAppInfo`): Optional. If the described Web App will be launched when the - button is pressed. + text (:obj:`str`): Text of the button. If none of the optional fields are used, it will be + sent to the bot as a message when the button is pressed. + request_contact (:obj:`bool`): Optional. If :obj:`True`, the user's phone number will be + sent as a contact when the button is pressed. Available in private chats only. + request_location (:obj:`bool`): Optional. If :obj:`True`, the user's current location will + be sent when the button is pressed. Available in private chats only. + request_poll (:class:`KeyboardButtonPollType`): Optional. If specified, the user will be + asked to create a poll and send it to the bot when the button is pressed. Available in + private chats only. + web_app (:class:`WebAppInfo`): Optional. If specified, the described `Web App + `_ will be launched when the button is pressed. + The Web App will be able to send a :attr:`Message.web_app_data` service message. + Available in private chats only. .. versionadded:: 20.0 """ diff --git a/telegram/_keyboardbuttonpolltype.py b/telegram/_keyboardbuttonpolltype.py index 9a26930d5aa..cb171edbc33 100644 --- a/telegram/_keyboardbuttonpolltype.py +++ b/telegram/_keyboardbuttonpolltype.py @@ -32,11 +32,16 @@ class KeyboardButtonPollType(TelegramObject): Examples: :any:`Poll Bot ` - Attributes: - type (:obj:`str`): Optional. If :tg-const:`telegram.Poll.QUIZ` is passed, the user will be + Args: + type (:obj:`str`, optional): If :tg-const:`telegram.Poll.QUIZ` is passed, the user will be allowed to create only polls in the quiz mode. If :tg-const:`telegram.Poll.REGULAR` is passed, only regular polls will be allowed. Otherwise, the user will be allowed to create a poll of any type. + Attributes: + type (:obj:`str`): Optional. If equals :tg-const:`telegram.Poll.QUIZ`, the user will + be allowed to create only polls in the quiz mode. If equals + :tg-const:`telegram.Poll.REGULAR`, only regular polls will be allowed. + Otherwise, the user will be allowed to create a poll of any type. """ __slots__ = ("type",) diff --git a/telegram/_loginurl.py b/telegram/_loginurl.py index ec2654ee42a..f46bfe27e6c 100644 --- a/telegram/_loginurl.py +++ b/telegram/_loginurl.py @@ -44,7 +44,7 @@ class LoginUrl(TelegramObject): the original URL without information about the user will be opened. The data added is the same as described in `Receiving authorization data - `_ + `_. forward_text (:obj:`str`, optional): New text of the button in forwarded messages. bot_username (:obj:`str`, optional): Username of a bot, which will be used for user authorization. See @@ -59,10 +59,22 @@ class LoginUrl(TelegramObject): for your bot to send messages to the user. Attributes: - url (:obj:`str`): An HTTPS URL to be opened with user authorization data. + url (:obj:`str`): An HTTPS URL to be opened with user authorization data added to the query + string when the button is pressed. If the user refuses to provide authorization data, + the original URL without information about the user will be opened. The data added is + the same as described in + `Receiving authorization data + `_. forward_text (:obj:`str`): Optional. New text of the button in forwarded messages. bot_username (:obj:`str`): Optional. Username of a bot, which will be used for user - authorization. + authorization. See + `Setting up a bot `_ + for more details. If not specified, the current + bot's username will be assumed. The url's domain must be the same as the domain linked + with the bot. See + `Linking your domain to the bot + `_ + for more details. request_write_access (:obj:`bool`): Optional. Pass :obj:`True` to request the permission for your bot to send messages to the user. diff --git a/telegram/_menubutton.py b/telegram/_menubutton.py index ea10434e658..192c6d37a1b 100644 --- a/telegram/_menubutton.py +++ b/telegram/_menubutton.py @@ -133,14 +133,16 @@ class MenuButtonWebApp(MenuButton): text (:obj:`str`): Text of the button. web_app (:class:`telegram.WebAppInfo`): Description of the Web App 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.answerWebAppQuery`. + message on behalf of the user using the method :meth:`~telegram.Bot.answerWebAppQuery` + of :class:`~telegram.Bot`. Attributes: type (:obj:`str`): :tg-const:`telegram.constants.MenuButtonType.WEB_APP`. text (:obj:`str`): Text of the button. web_app (:class:`telegram.WebAppInfo`): Description of the Web App 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.answerWebAppQuery`. + message on behalf of the user using the method :meth:`~telegram.Bot.answerWebAppQuery` + of :class:`~telegram.Bot`. """ __slots__ = ("text", "web_app") diff --git a/telegram/_message.py b/telegram/_message.py index e1be325622f..38562260ffc 100644 --- a/telegram/_message.py +++ b/telegram/_message.py @@ -237,8 +237,6 @@ class Message(TelegramObject): of the post author if present. author_signature (:obj:`str`, optional): Signature of the post author for messages in channels, or the custom title of an anonymous group administrator. - forward_sender_name (:obj:`str`, optional): Sender's name for messages forwarded from - users who disallow adding a link to their account in forwarded messages. passport_data (:class:`telegram.PassportData`, optional): Telegram Passport data. poll (:class:`telegram.Poll`, optional): Message is a native poll, information about the poll. @@ -349,33 +347,48 @@ class Message(TelegramObject): audio (:class:`telegram.Audio`): Optional. Message is an audio file, information about the file. + + .. seealso:: :wiki:`Working with Files and Media ` document (:class:`telegram.Document`): Optional. Message is a general file, information about the file. + + .. seealso:: :wiki:`Working with Files and Media ` animation (:class:`telegram.Animation`): Optional. Message is an animation, information about the animation. For backward compatibility, when this field is set, the document field will also be set. + + .. seealso:: :wiki:`Working with Files and Media ` game (:class:`telegram.Game`): Optional. Message is a game, information about the game. photo (Tuple[:class:`telegram.PhotoSize`]): Optional. Message is a photo, available sizes of the photo. This list is empty if the message does not contain a photo. + .. seealso:: :wiki:`Working with Files and Media ` + .. versionchanged:: 20.0 |tupleclassattrs| sticker (:class:`telegram.Sticker`): Optional. Message is a sticker, information about the sticker. + + .. seealso:: :wiki:`Working with Files and Media ` video (:class:`telegram.Video`): Optional. Message is a video, information about the video. + + .. seealso:: :wiki:`Working with Files and Media ` voice (:class:`telegram.Voice`): Optional. Message is a voice message, information about the file. + + .. seealso:: :wiki:`Working with Files and Media ` video_note (:class:`telegram.VideoNote`): Optional. Message is a video note, information about the video message. + + .. seealso:: :wiki:`Working with Files and Media ` new_chat_members (Tuple[:class:`telegram.User`]): Optional. New members that were added to the group or supergroup and information about them (the bot itself may be one of these members). This list is empty if the message does not contain new chat members. .. versionchanged:: 20.0 |tupleclassattrs| - caption (:obj:`str`): Optional. Caption for the animation, audio, document, photo, video or voice, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters. contact (:class:`telegram.Contact`): Optional. Message is a shared contact, information @@ -841,6 +854,8 @@ def effective_attachment( Otherwise :obj:`None` is returned. + .. seealso:: :wiki:`Working with Files and Media ` + .. versionchanged:: 20.0 :attr:`dice`, :attr:`passport_data` and :attr:`poll` are now also considered to be an attachment. diff --git a/telegram/_messageentity.py b/telegram/_messageentity.py index d2d83b25901..f04d69f94f3 100644 --- a/telegram/_messageentity.py +++ b/telegram/_messageentity.py @@ -48,7 +48,7 @@ class MessageEntity(TelegramObject): :attr:`CUSTOM_EMOJI` (for inline custom emoji stickers). .. versionadded:: 20.0 - added inline custom emoji + Added inline custom emoji offset (:obj:`int`): Offset in UTF-16 code units to the start of the entity. length (:obj:`int`): Length of the entity in UTF-16 code units. url (:obj:`str`, optional): For :attr:`TEXT_LINK` only, url that will be opened after @@ -77,8 +77,9 @@ class MessageEntity(TelegramObject): length (:obj:`int`): Length of the entity in UTF-16 code units. url (:obj:`str`): Optional. For :attr:`TEXT_LINK` only, url that will be opened after user taps on the text. - user (:class:`telegram.User`): Optional. The mentioned user. - language (:obj:`str`): Optional. For :attr:`PRE` only, The programming language of + user (:class:`telegram.User`): Optional. For :attr:`TEXT_MENTION` only, the mentioned + user. + language (:obj:`str`): Optional. For :attr:`PRE` only, the programming language of the entity text. custom_emoji_id (:obj:`str`): Optional. For :attr:`CUSTOM_EMOJI` only, unique identifier of the custom emoji. Use :meth:`telegram.Bot.get_custom_emoji_stickers` to get full diff --git a/telegram/_passport/credentials.py b/telegram/_passport/credentials.py index d2d86c24604..9bfeaa23892 100644 --- a/telegram/_passport/credentials.py +++ b/telegram/_passport/credentials.py @@ -249,6 +249,28 @@ class SecureData(TelegramObject): This object represents the credentials that were used to decrypt the encrypted data. All fields are optional and depend on fields that were requested. + Args: + personal_details (:class:`telegram.SecureValue`, optional): Credentials for encrypted + personal details. + passport (:class:`telegram.SecureValue`, optional): Credentials for encrypted passport. + internal_passport (:class:`telegram.SecureValue`, optional): Credentials for encrypted + internal passport. + driver_license (:class:`telegram.SecureValue`, optional): Credentials for encrypted + driver license. + identity_card (:class:`telegram.SecureValue`, optional): Credentials for encrypted ID card + address (:class:`telegram.SecureValue`, optional): Credentials for encrypted + residential address. + utility_bill (:class:`telegram.SecureValue`, optional): Credentials for encrypted + utility bill. + bank_statement (:class:`telegram.SecureValue`, optional): Credentials for encrypted + bank statement. + rental_agreement (:class:`telegram.SecureValue`, optional): Credentials for encrypted + rental agreement. + passport_registration (:class:`telegram.SecureValue`, optional): Credentials for encrypted + registration from internal passport. + temporary_registration (:class:`telegram.SecureValue`, optional): Credentials for encrypted + temporary registration. + Attributes: personal_details (:class:`telegram.SecureValue`): Optional. Credentials for encrypted personal details. @@ -351,6 +373,26 @@ class SecureValue(TelegramObject): This object represents the credentials that were used to decrypt the encrypted value. All fields are optional and depend on the type of field. + Args: + data (:class:`telegram.DataCredentials`, optional): Credentials for encrypted Telegram + Passport data. Available for "personal_details", "passport", "driver_license", + "identity_card", "identity_passport" and "address" types. + front_side (:class:`telegram.FileCredentials`, optional): Credentials for encrypted + document's front side. Available for "passport", "driver_license", "identity_card" + and "internal_passport". + reverse_side (:class:`telegram.FileCredentials`, optional): Credentials for encrypted + document's reverse side. Available for "driver_license" and "identity_card". + selfie (:class:`telegram.FileCredentials`, optional): Credentials for encrypted selfie + of the user with a document. Can be available for "passport", "driver_license", + "identity_card" and "internal_passport". + translation (List[:class:`telegram.FileCredentials`], optional): Credentials for an + encrypted translation of the document. Available for "passport", "driver_license", + "identity_card", "internal_passport", "utility_bill", "bank_statement", + "rental_agreement", "passport_registration" and "temporary_registration". + files (List[:class:`telegram.FileCredentials`], optional): Credentials for encrypted + files. Available for "utility_bill", "bank_statement", "rental_agreement", + "passport_registration" and "temporary_registration" types. + Attributes: data (:class:`telegram.DataCredentials`): Optional. Credentials for encrypted Telegram Passport data. Available for "personal_details", "passport", "driver_license", diff --git a/telegram/_passport/data.py b/telegram/_passport/data.py index ff015214644..282b9420309 100644 --- a/telegram/_passport/data.py +++ b/telegram/_passport/data.py @@ -26,6 +26,22 @@ class PersonalDetails(TelegramObject): """ This object represents personal details. + Args: + first_name (:obj:`str`): First Name. + middle_name (:obj:`str`): Optional. First Name. + last_name (:obj:`str`): Last Name. + birth_date (:obj:`str`): Date of birth in DD.MM.YYYY format. + gender (:obj:`str`): Gender, male or female. + country_code (:obj:`str`): Citizenship (ISO 3166-1 alpha-2 country code). + residence_country_code (:obj:`str`): Country of residence (ISO 3166-1 alpha-2 country + code). + first_name_native (:obj:`str`): First Name in the language of the user's country of + residence. + middle_name_native (:obj:`str`): Optional. Middle Name in the language of the user's + country of residence. + last_name_native (:obj:`str`): Last Name in the language of the user's country of + residence. + Attributes: first_name (:obj:`str`): First Name. middle_name (:obj:`str`): Optional. First Name. @@ -91,6 +107,14 @@ class ResidentialAddress(TelegramObject): """ This object represents a residential address. + Args: + street_line1 (:obj:`str`): First line for the address. + street_line2 (:obj:`str`): Optional. Second line for the address. + city (:obj:`str`): City. + state (:obj:`str`): Optional. State. + country_code (:obj:`str`): ISO 3166-1 alpha-2 country code. + post_code (:obj:`str`): Address post code. + Attributes: street_line1 (:obj:`str`): First line for the address. street_line2 (:obj:`str`): Optional. Second line for the address. @@ -136,6 +160,10 @@ class IdDocumentData(TelegramObject): """ This object represents the data of an identity document. + Args: + document_no (:obj:`str`): Document number. + expiry_date (:obj:`str`): Optional. Date of expiry, in DD.MM.YYYY format. + Attributes: document_no (:obj:`str`): Document number. expiry_date (:obj:`str`): Optional. Date of expiry, in DD.MM.YYYY format. diff --git a/telegram/_passport/passportelementerrors.py b/telegram/_passport/passportelementerrors.py index 58ce566a7c8..6aa5398177f 100644 --- a/telegram/_passport/passportelementerrors.py +++ b/telegram/_passport/passportelementerrors.py @@ -35,6 +35,7 @@ class PassportElementError(TelegramObject): Args: source (:obj:`str`): Error source. type (:obj:`str`): The section of the user's Telegram Passport which has the error. + message (:obj:`str`): Error message. Attributes: source (:obj:`str`): Error source. diff --git a/telegram/_passport/passportfile.py b/telegram/_passport/passportfile.py index a1fd67234c0..4a4f05eb5ab 100644 --- a/telegram/_passport/passportfile.py +++ b/telegram/_passport/passportfile.py @@ -46,7 +46,8 @@ class PassportFile(TelegramObject): file_date (:obj:`int`): Unix time when the file was uploaded. Attributes: - file_id (:obj:`str`): Identifier for this file. + file_id (:obj:`str`): Identifier for this file, which can be used to download + or reuse the file. file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. diff --git a/telegram/_payment/invoice.py b/telegram/_payment/invoice.py index 2c33e1fdc68..6f012d4b6f4 100644 --- a/telegram/_payment/invoice.py +++ b/telegram/_payment/invoice.py @@ -48,9 +48,15 @@ class Invoice(TelegramObject): Attributes: title (:obj:`str`): Product name. description (:obj:`str`): Product description. - start_parameter (:obj:`str`): Unique bot deep-linking parameter. + start_parameter (:obj:`str`): Unique bot deep-linking parameter that can be used to + generate this invoice. currency (:obj:`str`): Three-letter ISO 4217 currency code. - total_amount (:obj:`int`): Total price in the smallest units of the currency. + total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not + float/double). For example, for a price of US$ 1.45 ``amount`` is ``145``. See the + ``exp`` parameter in + `currencies.json `_, + it shows the number of digits past the decimal point for each currency + (2 for the majority of currencies). """ diff --git a/telegram/_payment/labeledprice.py b/telegram/_payment/labeledprice.py index ca3e295d08f..ec0daa2046f 100644 --- a/telegram/_payment/labeledprice.py +++ b/telegram/_payment/labeledprice.py @@ -42,7 +42,12 @@ class LabeledPrice(TelegramObject): Attributes: label (:obj:`str`): Portion label. - amount (:obj:`int`): Price of the product in the smallest units of the currency. + amount (:obj:`int`): Price of the product in the smallest units of the currency (integer, + not float/double). For example, for a price of US$ 1.45 ``amount`` is ``145``. + See the ``exp`` parameter in + `currencies.json `_, + it shows the number of digits past the decimal point for each currency + (2 for the majority of currencies). """ diff --git a/telegram/_payment/precheckoutquery.py b/telegram/_payment/precheckoutquery.py index fbea2ebcda5..5c1f2d431a8 100644 --- a/telegram/_payment/precheckoutquery.py +++ b/telegram/_payment/precheckoutquery.py @@ -58,7 +58,12 @@ class PreCheckoutQuery(TelegramObject): id (:obj:`str`): Unique query identifier. from_user (:class:`telegram.User`): User who sent the query. currency (:obj:`str`): Three-letter ISO 4217 currency code. - total_amount (:obj:`int`): Total price in the smallest units of the currency. + total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not + float/double). For example, for a price of US$ 1.45 ``amount`` is ``145``. + See the ``exp`` parameter in + `currencies.json `_, + it shows the number of digits past the decimal point for each currency + (2 for the majority of currencies). invoice_payload (:obj:`str`): Bot specified invoice payload. shipping_option_id (:obj:`str`): Optional. Identifier of the shipping option chosen by the user. diff --git a/telegram/_payment/successfulpayment.py b/telegram/_payment/successfulpayment.py index 3cc30af7fd3..7e83bf2e4ed 100644 --- a/telegram/_payment/successfulpayment.py +++ b/telegram/_payment/successfulpayment.py @@ -52,7 +52,12 @@ class SuccessfulPayment(TelegramObject): Attributes: currency (:obj:`str`): Three-letter ISO 4217 currency code. - total_amount (:obj:`int`): Total price in the smallest units of the currency. + total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not + float/double). For example, for a price of US$ 1.45 ``amount`` is ``145``. + See the ``exp`` parameter in + `currencies.json `_, + it shows the number of digits past the decimal point for each currency + (2 for the majority of currencies). invoice_payload (:obj:`str`): Bot specified invoice payload. shipping_option_id (:obj:`str`): Optional. Identifier of the shipping option chosen by the user. diff --git a/telegram/_replykeyboardmarkup.py b/telegram/_replykeyboardmarkup.py index 08e043a4c98..66b5271be97 100644 --- a/telegram/_replykeyboardmarkup.py +++ b/telegram/_replykeyboardmarkup.py @@ -70,14 +70,31 @@ class ReplyKeyboardMarkup(TelegramObject): .. versionadded:: 13.7 Attributes: - keyboard (Tuple[Tuple[:class:`telegram.KeyboardButton` | :obj:`str`]]): Array of button - rows. - resize_keyboard (:obj:`bool`): Optional. Requests clients to resize the keyboard. + keyboard (Tuple[Tuple[:class:`telegram.KeyboardButton`]]): Array of button rows, + each represented by an Array of :class:`telegram.KeyboardButton` objects. + resize_keyboard (:obj:`bool`): Optional. Requests clients to resize the keyboard vertically + for optimal fit (e.g., make the keyboard smaller if there are just two rows of + buttons). Defaults to :obj:`False`, in which case the custom keyboard is always of the + same height as the app's standard keyboard. one_time_keyboard (:obj:`bool`): Optional. Requests clients to hide the keyboard as soon as - it's been used. + it's been used. The keyboard will still be available, but clients will automatically + display the usual letter-keyboard in the chat - the user can press a special button in + the input field to see the custom keyboard again. Defaults to :obj:`False`. selective (:obj:`bool`): Optional. Show the keyboard to specific users only. - input_field_placeholder (:obj:`str`): Optional. The placeholder shown in the input - field when the reply is active. + Targets: + + 1) Users that are @mentioned in the :attr:`~telegram.Message.text` of the + :class:`telegram.Message` object. + 2) If the bot's message is a reply (has ``reply_to_message_id``), sender of the + original message. + + Defaults to :obj:`False`. + + input_field_placeholder (:obj:`str`): Optional. The placeholder to be shown in the input + field when the keyboard is active; + :tg-const:`telegram.ReplyKeyboardMarkup.MIN_INPUT_FIELD_PLACEHOLDER`- + :tg-const:`telegram.ReplyKeyboardMarkup.MAX_INPUT_FIELD_PLACEHOLDER` + characters. .. versionadded:: 13.7 diff --git a/telegram/_replykeyboardremove.py b/telegram/_replykeyboardremove.py index 7464830f65c..2989704ba1d 100644 --- a/telegram/_replykeyboardremove.py +++ b/telegram/_replykeyboardremove.py @@ -45,13 +45,17 @@ class ReplyKeyboardRemove(TelegramObject): for specific users only. Targets: 1) Users that are @mentioned in the text of the :class:`telegram.Message` object. - 2) If the bot's message is a reply (has `reply_to_message_id`), sender of the original - message. + 2) If the bot's message is a reply (has ``reply_to_message_id``), sender of + the original message. Attributes: remove_keyboard (:obj:`True`): Requests clients to remove the custom keyboard. - selective (:obj:`bool`): Optional. Use this parameter if you want to remove the keyboard - for specific users only. + selective (:obj:`bool`): Optional. Remove the keyboard for specific users only. + Targets: + + 1) Users that are @mentioned in the text of the :class:`telegram.Message` object. + 2) If the bot's message is a reply (has ``reply_to_message_id``), sender of + the original message. """ diff --git a/telegram/_update.py b/telegram/_update.py index 55355bce2a7..32daa2d80a8 100644 --- a/telegram/_update.py +++ b/telegram/_update.py @@ -46,8 +46,7 @@ class Update(TelegramObject): Note: At most one of the optional parameters can be present in any given update. - .. seealso:: `Your First Bot `_ + .. seealso:: :wiki:`Your First Bot ` Args: update_id (:obj:`int`): The update's unique identifier. Update identifiers start from a @@ -98,23 +97,33 @@ class Update(TelegramObject): .. versionadded:: 13.8 Attributes: - update_id (:obj:`int`): The update's unique identifier. - message (:class:`telegram.Message`): Optional. New incoming message. - edited_message (:class:`telegram.Message`): Optional. New version of a message. - channel_post (:class:`telegram.Message`): Optional. New incoming channel post. - edited_channel_post (:class:`telegram.Message`): Optional. New version of a channel post. + update_id (:obj:`int`): The update's unique identifier. Update identifiers start from a + certain positive number and increase sequentially. This ID becomes especially handy if + you're using Webhooks, since it allows you to ignore repeated updates or to restore the + correct update sequence, should they get out of order. If there are no new updates for + at least a week, then identifier of the next update will be chosen randomly instead of + sequentially. + message (:class:`telegram.Message`): Optional. New incoming message of any kind - text, + photo, sticker, etc. + edited_message (:class:`telegram.Message`): Optional. New version of a message that is + known to the bot and was edited. + channel_post (:class:`telegram.Message`): Optional. New incoming channel post of any kind + - text, photo, sticker, etc. + edited_channel_post (:class:`telegram.Message`): Optional. New version of a channel post + that is known to the bot and was edited. inline_query (:class:`telegram.InlineQuery`): Optional. New incoming inline query. chosen_inline_result (:class:`telegram.ChosenInlineResult`): Optional. The result of an - inline query that was chosen by a user. + inline query that was chosen by a user and sent to their chat partner. callback_query (:class:`telegram.CallbackQuery`): Optional. New incoming callback query. Examples: :any:`Arbitrary Callback Data Bot ` shipping_query (:class:`telegram.ShippingQuery`): Optional. New incoming shipping query. + Only for invoices with flexible price. pre_checkout_query (:class:`telegram.PreCheckoutQuery`): Optional. New incoming - pre-checkout query. - poll (:class:`telegram.Poll`): Optional. New poll state. Bots receive only updates - about stopped polls and polls, which are sent by the bot. + pre-checkout query. Contains full information about checkout. + poll (:class:`telegram.Poll`): Optional. New poll state. Bots receive only updates about + stopped polls and polls, which are sent by the bot. poll_answer (:class:`telegram.PollAnswer`): Optional. A user changed their answer in a non-anonymous poll. Bots receive new votes only in polls that were sent by the bot itself. diff --git a/telegram/_user.py b/telegram/_user.py index 10a702d2471..2fe88b69561 100644 --- a/telegram/_user.py +++ b/telegram/_user.py @@ -70,9 +70,9 @@ class User(TelegramObject): Args: id (:obj:`int`): Unique identifier for this user or bot. is_bot (:obj:`bool`): :obj:`True`, if this user is a bot. - first_name (:obj:`str`): User's or bots first name. - last_name (:obj:`str`, optional): User's or bots last name. - username (:obj:`str`, optional): User's or bots username. + first_name (:obj:`str`): User's or bot's first name. + last_name (:obj:`str`, optional): User's or bot's last name. + username (:obj:`str`, optional): User's or bot's username. language_code (:obj:`str`, optional): IETF language tag of the user's language. can_join_groups (:obj:`str`, optional): :obj:`True`, if the bot can be invited to groups. Returned only in :attr:`telegram.Bot.get_me` requests. diff --git a/telegram/_userprofilephotos.py b/telegram/_userprofilephotos.py index f6cf3dd5a06..7e25c9f489f 100644 --- a/telegram/_userprofilephotos.py +++ b/telegram/_userprofilephotos.py @@ -43,8 +43,8 @@ class UserProfilePhotos(TelegramObject): Attributes: total_count (:obj:`int`): Total number of profile pictures. - photos (Tuple[Tuple[:class:`telegram.PhotoSize`]]): Requested profile pictures (in up - to 4 sizes each). + photos (Tuple[Tuple[:class:`telegram.PhotoSize`]]): Requested profile pictures (in up to 4 + sizes each). .. versionchanged:: 20.0 |tupleclassattrs| diff --git a/telegram/error.py b/telegram/error.py index 7e92bfaa90a..cfa9fe388bf 100644 --- a/telegram/error.py +++ b/telegram/error.py @@ -59,8 +59,7 @@ class TelegramError(Exception): """ Base class for Telegram errors. - .. seealso:: `Exceptions, Warnings and Logging `_ + .. seealso:: :wiki:`Exceptions, Warnings and Logging ` """ __slots__ = ("message",) @@ -149,9 +148,8 @@ class ChatMigrated(TelegramError): """ Raised when the requested group chat migrated to supergroup and has a new chat id. - .. seealso:: `Storing Bot, User and Chat Related Data `_, + .. seealso:: + :wiki:`Storing Bot, User and Chat Related Data ` Args: new_chat_id (:obj:`int`): The new chat id of the group. diff --git a/telegram/ext/_aioratelimiter.py b/telegram/ext/_aioratelimiter.py index 300e8fabdd7..dae7de30275 100644 --- a/telegram/ext/_aioratelimiter.py +++ b/telegram/ext/_aioratelimiter.py @@ -90,8 +90,7 @@ class AIORateLimiter(BaseRateLimiter[int]): welcome you to implement your own subclass of :class:`~telegram.ext.BaseRateLimiter`. Feel free to check out the source code of this class for inspiration. - .. seealso:: `Avoiding Flood Limits `_ + .. seealso:: :wiki:`Avoiding Flood Limits ` .. versionadded:: 20.0 diff --git a/telegram/ext/_application.py b/telegram/ext/_application.py index f14c6af5d16..a879959bba8 100644 --- a/telegram/ext/_application.py +++ b/telegram/ext/_application.py @@ -136,10 +136,8 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) Examples: :any:`Echo Bot ` - .. seealso:: `Your First Bot `_, - `Architecture Overview `_ + .. seealso:: :wiki:`Your First Bot `, + :wiki:`Architecture Overview ` .. versionchanged:: 20.0 @@ -338,8 +336,7 @@ def concurrent_updates(self) -> int: """:obj:`int`: The number of concurrent updates that will be processed in parallel. A value of ``0`` indicates updates are *not* being processed concurrently. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` """ return self._concurrent_updates @@ -349,8 +346,7 @@ def job_queue(self) -> Optional["JobQueue"]: :class:`telegram.ext.JobQueue`: The :class:`JobQueue` used by the :class:`telegram.ext.Application`. - .. seealso:: `Job Queue `_ + .. seealso:: :wiki:`Job Queue ` """ if self._job_queue is None: warn( @@ -763,8 +759,7 @@ def run_webhook( .. seealso:: :meth:`initialize`, :meth:`start`, :meth:`stop`, :meth:`shutdown` :meth:`telegram.ext.Updater.start_webhook`, :meth:`telegram.ext.Updater.stop`, - :meth:`run_polling`, - `Webhooks `_ + :meth:`run_polling`, :wiki:`Webhooks` Args: listen (:obj:`str`, optional): IP-Address to listen on. Defaults to @@ -909,8 +904,7 @@ def create_task(self, coroutine: Coroutine, update: object = None) -> asyncio.Ta * If the application is currently running, tasks created by this method will be awaited with :meth:`stop`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Args: coroutine (:term:`coroutine function`): The coroutine to run as task. @@ -1028,8 +1022,7 @@ async def process_update(self, update: object) -> None: """Processes a single update and marks the update to be updated by the persistence later. Exceptions raised by handler callbacks will be processed by :meth:`process_update`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` .. versionchanged:: 20.0 Persistence is now updated in an interval set by @@ -1270,9 +1263,8 @@ def migrate_chat_data( to the asynchronous nature of these features. Please make sure that your program can avoid or handle such situations. - .. seealso:: `Storing Bot, User and Chat Related Data `_, + .. seealso:: :wiki:`Storing Bot, User and Chat Related Data\ + ` Args: message (:class:`telegram.Message`, optional): A message with either @@ -1495,8 +1487,7 @@ def add_error_handler( Examples: :any:`Errorhandler Bot ` - .. seealso:: `Exceptions, Warnings and Logging `_ + .. seealso:: :wiki:`Exceptions, Warnings and Logging ` Args: callback (:term:`coroutine function`): The callback function for this error handler. diff --git a/telegram/ext/_applicationbuilder.py b/telegram/ext/_applicationbuilder.py index 1f464e79fef..b3b270e5af1 100644 --- a/telegram/ext/_applicationbuilder.py +++ b/telegram/ext/_applicationbuilder.py @@ -112,10 +112,8 @@ class ApplicationBuilder(Generic[BT, CCT, UD, CD, BD, JQ]): * Unless a custom :class:`telegram.Bot` instance is set via :meth:`bot`, :meth:`build` will use :class:`telegram.ext.ExtBot` for the bot. - .. seealso:: `Your First Bot `_, - `Builder Pattern for Application `_ + .. seealso:: :wiki:`Your First Bot `, + :wiki:`Builder Pattern ` .. _`builder pattern`: https://en.wikipedia.org/wiki/Builder_pattern """ @@ -359,9 +357,8 @@ def base_url(self: BuilderType, base_url: str) -> BuilderType: """Sets the base URL for :attr:`telegram.ext.Application.bot`. If not called, will default to ``'https://api.telegram.org/bot'``. - .. seealso:: :paramref:`telegram.Bot.base_url`, `Local Bot API Server `_, - :meth:`base_file_url` + .. seealso:: :paramref:`telegram.Bot.base_url`, + :wiki:`Local Bot API Server `, :meth:`base_file_url` Args: base_url (:obj:`str`): The URL. @@ -378,9 +375,8 @@ def base_file_url(self: BuilderType, base_file_url: str) -> BuilderType: """Sets the base file URL for :attr:`telegram.ext.Application.bot`. If not called, will default to ``'https://api.telegram.org/file/bot'``. - .. seealso:: :paramref:`telegram.Bot.base_file_url`, `Local Bot API Server `_, - :meth:`base_url` + .. seealso:: :paramref:`telegram.Bot.base_file_url`, + :wiki:`Local Bot API Server `, :meth:`base_url` Args: base_file_url (:obj:`str`): The URL. @@ -673,8 +669,10 @@ def private_key( """Sets the private key and corresponding password for decryption of telegram passport data for :attr:`telegram.ext.Application.bot`. - .. seealso:: :any:`examples.passportbot`, `Telegram Passports - `_ + Examples: + :any:`Passport Bot ` + + .. seealso:: :wiki:`Telegram Passports ` Args: private_key (:obj:`bytes` | :obj:`str` | :obj:`pathlib.Path`): The private key or the @@ -704,8 +702,7 @@ def defaults(self: BuilderType, defaults: "Defaults") -> BuilderType: """Sets the :class:`telegram.ext.Defaults` instance for :attr:`telegram.ext.Application.bot`. - .. seealso:: `Adding Defaults `_ + .. seealso:: :wiki:`Adding Defaults to Your Bot ` Args: defaults (:class:`telegram.ext.Defaults`): The defaults instance. @@ -734,9 +731,10 @@ def arbitrary_callback_data( pip install python-telegram-bot[callback-data] - .. seealso:: `Arbitrary callback_data `_, - :any:`examples.arbitrarycallbackdatabot` + Examples: + :any:`Arbitrary callback_data Bot ` + + .. seealso:: :wiki:`Arbitrary callback_data ` Args: arbitrary_callback_data (:obj:`bool` | :obj:`int`): If :obj:`True` is passed, the @@ -756,8 +754,7 @@ def local_mode(self: BuilderType, local_mode: bool) -> BuilderType: :attr:`telegram.ext.Application.bot`. If not called, will default to :obj:`False`. - .. seealso:: `Local Bot API Server `_, + .. seealso:: :wiki:`Local Bot API Server ` Args: local_mode (:obj:`bool`): Whether the bot should run in local mode. @@ -842,8 +839,10 @@ def job_queue( :attr:`telegram.ext.Application.job_queue`. If not called, a job queue will be instantiated if the requirements of :class:`telegram.ext.JobQueue` are installed. - .. seealso:: `JobQueue `_, :any:`examples.timerbot` + Examples: + :any:`Timer Bot ` + + .. seealso:: :wiki:`Job Queue ` Note: * :meth:`telegram.ext.JobQueue.set_application` will be called automatically by @@ -878,9 +877,10 @@ def persistence(self: BuilderType, persistence: "BasePersistence") -> BuilderTyp :func:`copy.deepcopy`. This is due to the data being deep copied before handing it over to the persistence in order to avoid race conditions. - .. seealso:: `Making your bot persistent `_, - :any:`examples.persistentconversationbot` + Examples: + :any:`Persistent Conversation Bot ` + + .. seealso:: :wiki:`Making Your Bot Persistent ` Warning: If a :class:`telegram.ext.ContextTypes` instance is set via :meth:`context_types`, @@ -902,7 +902,8 @@ def context_types( """Sets a :class:`telegram.ext.ContextTypes` instance for :attr:`telegram.ext.Application.context_types`. - .. seealso:: :any:`examples.contexttypesbot` + Examples: + :any:`Context Types Bot ` Args: context_types (:class:`telegram.ext.ContextTypes`): The context types. diff --git a/telegram/ext/_basepersistence.py b/telegram/ext/_basepersistence.py index 69bdd4d31c9..fa3e455f919 100644 --- a/telegram/ext/_basepersistence.py +++ b/telegram/ext/_basepersistence.py @@ -111,10 +111,8 @@ class BasePersistence(Generic[UD, CD, BD], ABC): type of the argument of :meth:`refresh_bot_data` and the return value of :meth:`get_bot_data`. - .. seealso:: `Architecture Overview `_, - `Making Your Bot Persistent `_ + .. seealso:: :wiki:`Architecture Overview `, + :wiki:`Making Your Bot Persistent ` .. versionchanged:: 20.0 diff --git a/telegram/ext/_baseratelimiter.py b/telegram/ext/_baseratelimiter.py index 4726d8e336d..aa43fae4a44 100644 --- a/telegram/ext/_baseratelimiter.py +++ b/telegram/ext/_baseratelimiter.py @@ -37,10 +37,8 @@ class BaseRateLimiter(ABC, Generic[RLARGS]): Hint: Requests to :meth:`~telegram.Bot.get_updates` are never rate limited. - .. seealso:: `Architecture Overview `_, - `Avoiding Flood Limits `_ + .. seealso:: :wiki:`Architecture Overview `, + :wiki:`Avoiding Flood Limits ` .. versionadded:: 20.0 """ diff --git a/telegram/ext/_callbackcontext.py b/telegram/ext/_callbackcontext.py index eaa99f03197..a226c6a2560 100644 --- a/telegram/ext/_callbackcontext.py +++ b/telegram/ext/_callbackcontext.py @@ -72,8 +72,7 @@ class CallbackContext(Generic[BT, UD, CD, BD]): * :any:`Custom Webhook Bot ` .. seealso:: :attr:`telegram.ext.ContextTypes.DEFAULT_TYPE`, - `Job Queue `_ + :wiki:`Job Queue ` Args: application (:class:`telegram.ext.Application`): The application associated with this @@ -146,9 +145,8 @@ def bot_data(self) -> BD: """:obj:`ContextTypes.bot_data`: Optional. An object that can be used to keep any data in. For each update it will be the same :attr:`ContextTypes.bot_data`. Defaults to :obj:`dict`. - .. seealso:: `Storing Bot, User and Chat Related Data `_, + .. seealso:: :wiki:`Storing Bot, User and Chat Related Data\ + ` """ return self.application.bot_data @@ -166,13 +164,11 @@ def chat_data(self) -> Optional[CD]: Warning: When a group chat migrates to a supergroup, its chat id will change and the - ``chat_data`` needs to be transferred. For details see our `wiki page - `_. + ``chat_data`` needs to be transferred. For details see our + :wiki:`wiki page `. - .. seealso:: `Storing Bot, User and Chat Related Data `_, + .. seealso:: :wiki:`Storing Bot, User and Chat Related Data\ + ` .. versionchanged:: 20.0 The chat data is now also present in error handlers if the error is caused by a job. @@ -193,9 +189,8 @@ def user_data(self) -> Optional[UD]: For each update from the same user it will be the same :obj:`ContextTypes.user_data`. Defaults to :obj:`dict`. - .. seealso:: `Storing Bot, User and Chat Related Data `_, + .. seealso:: :wiki:`Storing Bot, User and Chat Related Data\ + ` .. versionchanged:: 20.0 The user data is now also present in error handlers if the error is caused by a job. @@ -244,8 +239,7 @@ def drop_callback_data(self, callback_query: CallbackQuery) -> None: Will *not* raise exceptions in case the data is not found in the cache. *Will* raise :exc:`KeyError` in case the callback query can not be found in the cache. - .. seealso:: `Arbitrary callback_data `_ + .. seealso:: :wiki:`Arbitrary callback_data ` Args: callback_query (:class:`telegram.CallbackQuery`): The callback query. @@ -387,8 +381,7 @@ def job_queue(self) -> Optional["JobQueue"]: :class:`telegram.ext.JobQueue`: The :class:`JobQueue` used by the :class:`telegram.ext.Application`. - .. seealso:: `Job Queue `_ + .. seealso:: :wiki:`Job Queue ` """ if self._application._job_queue is None: # pylint: disable=protected-access warn( diff --git a/telegram/ext/_callbackdatacache.py b/telegram/ext/_callbackdatacache.py index c62d4db6255..6a2a39ae3e9 100644 --- a/telegram/ext/_callbackdatacache.py +++ b/telegram/ext/_callbackdatacache.py @@ -47,8 +47,7 @@ class InvalidCallbackData(TelegramError): Examples: :any:`Arbitrary Callback Data Bot ` - .. seealso:: `Arbitrary callback_data `_ + .. seealso:: :wiki:`Arbitrary callback_data ` .. versionadded:: 13.6 @@ -118,10 +117,8 @@ class CallbackDataCache: :any:`Arbitrary Callback Data Bot ` .. seealso:: :attr:`telegram.ext.ExtBot.callback_data_cache`, - `Architecture Overview `_, - `Arbitrary callback_data `_ + :wiki:`Architecture Overview `, + :wiki:`Arbitrary callback_data ` .. versionadded:: 13.6 diff --git a/telegram/ext/_callbackqueryhandler.py b/telegram/ext/_callbackqueryhandler.py index c2590f14d63..db79499917f 100644 --- a/telegram/ext/_callbackqueryhandler.py +++ b/telegram/ext/_callbackqueryhandler.py @@ -81,8 +81,7 @@ async def callback(update: Update, context: CallbackContext) If :attr:`telegram.CallbackQuery.data` is :obj:`None`, the :class:`telegram.CallbackQuery` update will not be handled. - .. seealso:: `Arbitrary callback_data `_ + .. seealso:: :wiki:`Arbitrary callback_data ` .. versionchanged:: 13.6 Added support for arbitrary callback data. @@ -90,8 +89,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Attributes: callback (:term:`coroutine function`): The callback function for this handler. diff --git a/telegram/ext/_chatjoinrequesthandler.py b/telegram/ext/_chatjoinrequesthandler.py index d8b26d1a18d..690cf4f25ed 100644 --- a/telegram/ext/_chatjoinrequesthandler.py +++ b/telegram/ext/_chatjoinrequesthandler.py @@ -66,8 +66,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Attributes: callback (:term:`coroutine function`): The callback function for this handler. diff --git a/telegram/ext/_chatmemberhandler.py b/telegram/ext/_chatmemberhandler.py index a746568cca4..f48d2f26829 100644 --- a/telegram/ext/_chatmemberhandler.py +++ b/telegram/ext/_chatmemberhandler.py @@ -57,8 +57,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Attributes: callback (:term:`coroutine function`): The callback function for this handler. diff --git a/telegram/ext/_choseninlineresulthandler.py b/telegram/ext/_choseninlineresulthandler.py index ff0000ce73e..7cc948527f8 100644 --- a/telegram/ext/_choseninlineresulthandler.py +++ b/telegram/ext/_choseninlineresulthandler.py @@ -53,8 +53,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` pattern (:obj:`str` | :func:`re.Pattern `, optional): Regex pattern. If not :obj:`None`, :func:`re.match` is used on :attr:`telegram.ChosenInlineResult.result_id` to determine if an update diff --git a/telegram/ext/_commandhandler.py b/telegram/ext/_commandhandler.py index c0e539986f6..bbaa90b7c26 100644 --- a/telegram/ext/_commandhandler.py +++ b/telegram/ext/_commandhandler.py @@ -87,8 +87,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Raises: :exc:`ValueError`: When the command is too long or has illegal chars. diff --git a/telegram/ext/_contexttypes.py b/telegram/ext/_contexttypes.py index 30b8430b19b..98607fa3fbe 100644 --- a/telegram/ext/_contexttypes.py +++ b/telegram/ext/_contexttypes.py @@ -36,10 +36,8 @@ class ContextTypes(Generic[CCT, UD, CD, BD]): Examples: :any:`ContextTypes Bot ` - .. seealso:: `Architecture Overview `_, - `Storing Bot, User and Chat Related Data `_ + .. seealso:: :wiki:`Architecture Overview `, + :wiki:`Storing Bot, User and Chat Related Data ` .. versionadded:: 13.6 diff --git a/telegram/ext/_conversationhandler.py b/telegram/ext/_conversationhandler.py index c972551f356..505f85158c7 100644 --- a/telegram/ext/_conversationhandler.py +++ b/telegram/ext/_conversationhandler.py @@ -250,8 +250,7 @@ class ConversationHandler(BaseHandler[Update, CCT]): 2. the value passed to this parameter (if any) 3. :attr:`telegram.ext.Defaults.block` (if defaults are used) - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` .. versionchanged:: 20.0 No longer overrides the handlers settings. Resolution order was changed. diff --git a/telegram/ext/_defaults.py b/telegram/ext/_defaults.py index 5c127154a5a..7fc5f7115f8 100644 --- a/telegram/ext/_defaults.py +++ b/telegram/ext/_defaults.py @@ -26,10 +26,8 @@ class Defaults: """Convenience Class to gather all parameters with a (user defined) default value - .. seealso:: `Architecture Overview `_, - `Adding Defaults to Your Bot `_ + .. seealso:: :wiki:`Architecture Overview `, + :wiki:`Adding Defaults to Your Bot ` .. versionchanged:: 20.0 Removed the argument and attribute ``timeout``. Specify default timeout behavior for the diff --git a/telegram/ext/_dictpersistence.py b/telegram/ext/_dictpersistence.py index c02b49ec27e..eef58a77375 100644 --- a/telegram/ext/_dictpersistence.py +++ b/telegram/ext/_dictpersistence.py @@ -43,8 +43,7 @@ class DictPersistence(BasePersistence): * This implementation of :class:`BasePersistence` does not handle data that cannot be serialized by :func:`json.dumps`. - .. seealso:: `Making Your Bot Persistent `_ + .. seealso:: :wiki:`Making Your Bot Persistent ` .. versionchanged:: 20.0 The parameters and attributes ``store_*_data`` were replaced by :attr:`store_data`. diff --git a/telegram/ext/_extbot.py b/telegram/ext/_extbot.py index e41ae887726..e0708b3e60b 100644 --- a/telegram/ext/_extbot.py +++ b/telegram/ext/_extbot.py @@ -123,8 +123,7 @@ class ExtBot(Bot, Generic[RLARGS]): Examples: :any:`Arbitrary Callback Data Bot ` - .. seealso:: `Arbitrary callback_data `_ + .. seealso:: :wiki:`Arbitrary callback_data ` .. versionadded:: 13.6 @@ -141,8 +140,7 @@ class ExtBot(Bot, Generic[RLARGS]): Pass an integer to specify the maximum number of objects cached in memory. Defaults to :obj:`False`. - .. seealso:: `Arbitrary callback_data `_ + .. seealso:: :wiki:`Arbitrary callback_data ` rate_limiter (:class:`telegram.ext.BaseRateLimiter`, optional): A rate limiter to use for limiting the number of requests made by the bot per time interval. diff --git a/telegram/ext/_handler.py b/telegram/ext/_handler.py index fc98c616c97..6b59a37abf5 100644 --- a/telegram/ext/_handler.py +++ b/telegram/ext/_handler.py @@ -54,8 +54,7 @@ class BaseHandler(Generic[UT, CCT], ABC): also used for the mentioned method arguments. That way, a type checker can check whether this handler fits the definition of the :class:`~Application`. - .. seealso:: `Types of Handlers `_ + .. seealso:: :wiki:`Types of Handlers ` .. versionchanged:: 20.0 @@ -75,8 +74,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Attributes: callback (:term:`coroutine function`): The callback function for this handler. diff --git a/telegram/ext/_inlinequeryhandler.py b/telegram/ext/_inlinequeryhandler.py index ae451e70983..2cc0ce07ed9 100644 --- a/telegram/ext/_inlinequeryhandler.py +++ b/telegram/ext/_inlinequeryhandler.py @@ -66,8 +66,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` chat_types (List[:obj:`str`], optional): List of allowed chat types. If passed, will only handle inline queries with the appropriate :attr:`telegram.InlineQuery.chat_type`. diff --git a/telegram/ext/_jobqueue.py b/telegram/ext/_jobqueue.py index 15ff4450b8b..97e18e40bed 100644 --- a/telegram/ext/_jobqueue.py +++ b/telegram/ext/_jobqueue.py @@ -58,10 +58,8 @@ class JobQueue: .. seealso:: :attr:`telegram.ext.Application.job_queue`, :attr:`telegram.ext.CallbackContext.job_queue`, - `Architecture Overview `_, - `Job Queue `_ + :wiki:`Architecture Overview `, + :wiki:`Job Queue ` .. versionchanged:: 20.0 To use this class, PTB must be installed via @@ -643,8 +641,7 @@ class Job: This class should not be instantiated manually. Use the methods of :class:`telegram.ext.JobQueue` to schedule jobs. - .. seealso:: `Job Queue `_ + .. seealso:: :wiki:`Job Queue ` .. versionchanged:: 20.0 diff --git a/telegram/ext/_messagehandler.py b/telegram/ext/_messagehandler.py index 0a0f365d3dd..60dfea42b1d 100644 --- a/telegram/ext/_messagehandler.py +++ b/telegram/ext/_messagehandler.py @@ -47,8 +47,7 @@ class MessageHandler(BaseHandler[Update, CCT]): operators (& for and, | for or, ~ for not). Passing :obj:`None` is a shortcut to passing :class:`telegram.ext.filters.ALL`. - .. seealso:: `Advanced Filters `_ + .. seealso:: :wiki:`Advanced Filters ` callback (:term:`coroutine function`): The callback function for this handler. Will be called when :meth:`check_update` has determined that an update should be processed by this handler. Callback signature:: @@ -61,8 +60,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Attributes: filters (:class:`telegram.ext.filters.BaseFilter`): Only allow updates with these Filters. diff --git a/telegram/ext/_picklepersistence.py b/telegram/ext/_picklepersistence.py index 42eb3241123..452d98630de 100644 --- a/telegram/ext/_picklepersistence.py +++ b/telegram/ext/_picklepersistence.py @@ -136,8 +136,7 @@ class PicklePersistence(BasePersistence[UD, CD, BD]): Examples: :any:`Persistent Conversation Bot ` - .. seealso:: `Making Your Bot Persistent `_ + .. seealso:: :wiki:`Making Your Bot Persistent ` .. versionchanged:: 20.0 diff --git a/telegram/ext/_pollanswerhandler.py b/telegram/ext/_pollanswerhandler.py index faa4733ea39..f258c86a58f 100644 --- a/telegram/ext/_pollanswerhandler.py +++ b/telegram/ext/_pollanswerhandler.py @@ -48,8 +48,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Attributes: callback (:term:`coroutine function`): The callback function for this handler. diff --git a/telegram/ext/_pollhandler.py b/telegram/ext/_pollhandler.py index 67d7b92adfe..79c94058d22 100644 --- a/telegram/ext/_pollhandler.py +++ b/telegram/ext/_pollhandler.py @@ -48,8 +48,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Attributes: callback (:term:`coroutine function`): The callback function for this handler. diff --git a/telegram/ext/_precheckoutqueryhandler.py b/telegram/ext/_precheckoutqueryhandler.py index d02cf50da13..3cadaaee695 100644 --- a/telegram/ext/_precheckoutqueryhandler.py +++ b/telegram/ext/_precheckoutqueryhandler.py @@ -47,8 +47,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Attributes: callback (:term:`coroutine function`): The callback function for this handler. diff --git a/telegram/ext/_prefixhandler.py b/telegram/ext/_prefixhandler.py index 67c619bbdfb..16803aca581 100644 --- a/telegram/ext/_prefixhandler.py +++ b/telegram/ext/_prefixhandler.py @@ -105,8 +105,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Attributes: commands (FrozenSet[:obj:`str`]): The commands that this handler will listen for, i.e. the diff --git a/telegram/ext/_shippingqueryhandler.py b/telegram/ext/_shippingqueryhandler.py index 5a78a8147f3..e14149a20f6 100644 --- a/telegram/ext/_shippingqueryhandler.py +++ b/telegram/ext/_shippingqueryhandler.py @@ -47,8 +47,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Attributes: callback (:term:`coroutine function`): The callback function for this handler. diff --git a/telegram/ext/_stringcommandhandler.py b/telegram/ext/_stringcommandhandler.py index 7dc0f53e346..4a7a6fd1b07 100644 --- a/telegram/ext/_stringcommandhandler.py +++ b/telegram/ext/_stringcommandhandler.py @@ -57,8 +57,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Attributes: command (:obj:`str`): The command this handler should listen for. diff --git a/telegram/ext/_stringregexhandler.py b/telegram/ext/_stringregexhandler.py index 0a6f0db7168..cdf0b453507 100644 --- a/telegram/ext/_stringregexhandler.py +++ b/telegram/ext/_stringregexhandler.py @@ -60,8 +60,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Attributes: pattern (:obj:`str` | :func:`re.Pattern `): The regex pattern. diff --git a/telegram/ext/_typehandler.py b/telegram/ext/_typehandler.py index 2984e00e3e7..811437865fa 100644 --- a/telegram/ext/_typehandler.py +++ b/telegram/ext/_typehandler.py @@ -53,8 +53,7 @@ async def callback(update: Update, context: CallbackContext) be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. - .. seealso:: `Concurrency `_ + .. seealso:: :wiki:`Concurrency` Attributes: type (:external:class:`type`): The :external:class:`type` of updates this handler should diff --git a/telegram/ext/_updater.py b/telegram/ext/_updater.py index 907ea1f3695..524e7e47c76 100644 --- a/telegram/ext/_updater.py +++ b/telegram/ext/_updater.py @@ -65,10 +65,8 @@ class Updater(AbstractAsyncContextManager): finally: await updater.shutdown() - .. seealso:: `Architecture Overview `_, - `Builder Pattern `_ + .. seealso:: :wiki:`Architecture Overview `, + :wiki:`Builder Pattern ` .. versionchanged:: 20.0 @@ -397,8 +395,7 @@ async def start_webhook( pip install python-telegram-bot[webhooks] - .. seealso:: `Webhooks `_ + .. seealso:: :wiki:`Webhooks` .. versionchanged:: 13.4 :meth:`start_webhook` now *always* calls :meth:`telegram.Bot.set_webhook`, so pass diff --git a/telegram/ext/filters.py b/telegram/ext/filters.py index cdd4cf62ccc..f60bddd61ce 100644 --- a/telegram/ext/filters.py +++ b/telegram/ext/filters.py @@ -232,8 +232,7 @@ class MessageFilter(BaseFilter): Please see :class:`BaseFilter` for details on how to create custom filters. - .. seealso:: `Advanced Filters `_ + .. seealso:: :wiki:`Advanced Filters ` Attributes: name (:obj:`str`): Name for this filter. Defaults to the type of filter. @@ -1545,8 +1544,7 @@ class Regex(MessageFilter): With a :attr:`telegram.Message.text` of `x`, will only ever return the matches for the first filter, since the second one is never evaluated. - .. seealso:: `Types of Handlers `_ + .. seealso:: :wiki:`Types of Handlers ` Args: pattern (:obj:`str` | :func:`re.Pattern `): The regex pattern. @@ -1761,6 +1759,42 @@ def filter(self, message: Message) -> bool: DELETE_CHAT_PHOTO = _DeleteChatPhoto(name="filters.StatusUpdate.DELETE_CHAT_PHOTO") """Messages that contain :attr:`telegram.Message.delete_chat_photo`.""" + class _ForumTopicClosed(MessageFilter): + __slots__ = () + + def filter(self, message: Message) -> bool: + return bool(message.forum_topic_closed) + + FORUM_TOPIC_CLOSED = _ForumTopicClosed(name="filters.StatusUpdate.FORUM_TOPIC_CLOSED") + """Messages that contain :attr:`telegram.Message.forum_topic_closed`. + + .. versionadded:: 20.0 + """ + + class _ForumTopicCreated(MessageFilter): + __slots__ = () + + def filter(self, message: Message) -> bool: + return bool(message.forum_topic_created) + + FORUM_TOPIC_CREATED = _ForumTopicCreated(name="filters.StatusUpdate.FORUM_TOPIC_CREATED") + """Messages that contain :attr:`telegram.Message.forum_topic_created`. + + .. versionadded:: 20.0 + """ + + class _ForumTopicReopened(MessageFilter): + __slots__ = () + + def filter(self, message: Message) -> bool: + return bool(message.forum_topic_reopened) + + FORUM_TOPIC_REOPENED = _ForumTopicReopened(name="filters.StatusUpdate.FORUM_TOPIC_REOPENED") + """Messages that contain :attr:`telegram.Message.forum_topic_reopened`. + + .. versionadded:: 20.0 + """ + class _LeftChatMember(MessageFilter): __slots__ = () @@ -1911,42 +1945,6 @@ def filter(self, message: Message) -> bool: .. versionadded:: 20.0 """ - class _ForumTopicCreated(MessageFilter): - __slots__ = () - - def filter(self, message: Message) -> bool: - return bool(message.forum_topic_created) - - FORUM_TOPIC_CREATED = _ForumTopicCreated(name="filters.StatusUpdate.FORUM_TOPIC_CREATED") - """Messages that contain :attr:`telegram.Message.forum_topic_created`. - - .. versionadded:: 20.0 - """ - - class _ForumTopicClosed(MessageFilter): - __slots__ = () - - def filter(self, message: Message) -> bool: - return bool(message.forum_topic_closed) - - FORUM_TOPIC_CLOSED = _ForumTopicClosed(name="filters.StatusUpdate.FORUM_TOPIC_CLOSED") - """Messages that contain :attr:`telegram.Message.forum_topic_closed`. - - .. versionadded:: 20.0 - """ - - class _ForumTopicReopened(MessageFilter): - __slots__ = () - - def filter(self, message: Message) -> bool: - return bool(message.forum_topic_reopened) - - FORUM_TOPIC_REOPENED = _ForumTopicReopened(name="filters.StatusUpdate.FORUM_TOPIC_REOPENED") - """Messages that contain :attr:`telegram.Message.forum_topic_reopened`. - - .. versionadded:: 20.0 - """ - class Sticker: """Filters messages which contain a sticker. diff --git a/telegram/request/_baserequest.py b/telegram/request/_baserequest.py index d4df2cfb3a0..96c61f20d19 100644 --- a/telegram/request/_baserequest.py +++ b/telegram/request/_baserequest.py @@ -73,10 +73,8 @@ class BaseRequest( To use a custom library for this, you can override :meth:`parse_json_payload` and implement custom logic to encode the keys of :attr:`telegram.request.RequestData.parameters`. - .. seealso:: `Architecture Overview `_, - `Builder Pattern `_ + .. seealso:: :wiki:`Architecture Overview `, + :wiki:`Builder Pattern ` .. versionadded:: 20.0 """ diff --git a/telegram/warnings.py b/telegram/warnings.py index dee3ff4c2d5..b1426eabfce 100644 --- a/telegram/warnings.py +++ b/telegram/warnings.py @@ -28,8 +28,7 @@ class PTBUserWarning(UserWarning): """ Custom user warning class used for warnings in this library. - .. seealso:: `Exceptions, Warnings and Logging `_ + .. seealso:: :wiki:`Exceptions, Warnings and Logging ` .. versionadded:: 20.0 """