From 9520c6eeba8d1332c6080134f042d338948a47a2 Mon Sep 17 00:00:00 2001 From: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> Date: Tue, 15 Nov 2022 09:06:23 +0100 Subject: [PATCH] Documentation Improvements (#3214, #3217, #3218, #3271, #3289, #3292, #3303, #3312, #3306, #3319, #3326, #3314) Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: Simon Fong <44134941+simonfongnt@users.noreply.github.com> Co-authored-by: Piotr Rogulski Co-authored-by: poolitzer <25934244+Poolitzer@users.noreply.github.com> Co-authored-by: Or Bin Co-authored-by: Sandro Co-authored-by: Hatim Zahid <63000127+HatimZ@users.noreply.github.com> Co-authored-by: Robi <53259730+RobiMez@users.noreply.github.com> Co-authored-by: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> --- .github/CONTRIBUTING.rst | 2 +- .readthedocs.yml | 27 +- docs/requirements-docs.txt | 1 + docs/source/conf.py | 108 +- .../source/inclusions/application_run_tip.rst | 7 + docs/source/inclusions/bot_methods.rst | 8 + docs/source/telegram.at-tree.rst | 82 + docs/source/telegram.ext.rst | 1 + docs/source/telegram.rst | 82 +- docs/source/telegram.telegramobject.rst | 2 +- docs/substitutions/global.rst | 16 + telegram/_bot.py | 2011 ++--------------- telegram/_botcommandscope.py | 19 +- telegram/_chat.py | 20 +- telegram/_chatmember.py | 3 +- telegram/_chatmemberupdated.py | 3 + telegram/_inline/inlinekeyboardbutton.py | 11 +- telegram/_inline/inlinekeyboardmarkup.py | 5 +- telegram/_inline/inlinequeryresult.py | 3 + telegram/_inline/inlinequeryresultarticle.py | 3 +- telegram/_inline/inputtextmessagecontent.py | 3 +- telegram/_keyboardbuttonpolltype.py | 3 +- telegram/_message.py | 246 +- telegram/_messageentity.py | 21 +- telegram/_payment/labeledprice.py | 3 +- telegram/_payment/shippingoption.py | 3 +- telegram/_poll.py | 19 +- telegram/_replykeyboardmarkup.py | 9 +- telegram/_replykeyboardremove.py | 12 +- telegram/_telegramobject.py | 102 +- telegram/_update.py | 6 + telegram/_webappdata.py | 6 +- telegram/_webappinfo.py | 3 +- telegram/_webhookinfo.py | 13 +- telegram/error.py | 20 +- telegram/ext/_aioratelimiter.py | 5 +- telegram/ext/_application.py | 56 +- telegram/ext/_applicationbuilder.py | 9 +- telegram/ext/_basepersistence.py | 5 + telegram/ext/_baseratelimiter.py | 5 + telegram/ext/_callbackcontext.py | 25 +- telegram/ext/_callbackdatacache.py | 20 +- telegram/ext/_callbackqueryhandler.py | 6 + telegram/ext/_chatjoinrequesthandler.py | 3 + telegram/ext/_chatmemberhandler.py | 6 +- telegram/ext/_choseninlineresulthandler.py | 3 + telegram/ext/_commandhandler.py | 7 + telegram/ext/_contexttypes.py | 8 +- telegram/ext/_conversationhandler.py | 12 +- telegram/ext/_defaults.py | 5 + telegram/ext/_dictpersistence.py | 3 + telegram/ext/_extbot.py | 19 +- telegram/ext/_handler.py | 6 + telegram/ext/_inlinequeryhandler.py | 7 +- telegram/ext/_jobqueue.py | 9 +- telegram/ext/_messagehandler.py | 6 + telegram/ext/_picklepersistence.py | 6 + telegram/ext/_pollanswerhandler.py | 6 +- telegram/ext/_pollhandler.py | 6 +- telegram/ext/_precheckoutqueryhandler.py | 6 +- telegram/ext/_prefixhandler.py | 3 + telegram/ext/_shippingqueryhandler.py | 6 +- telegram/ext/_stringcommandhandler.py | 3 + telegram/ext/_stringregexhandler.py | 3 + telegram/ext/_typehandler.py | 3 + telegram/ext/_updater.py | 8 + telegram/ext/filters.py | 16 +- telegram/helpers.py | 17 +- telegram/request/_baserequest.py | 5 + telegram/warnings.py | 3 + 70 files changed, 1104 insertions(+), 2095 deletions(-) create mode 100644 docs/source/inclusions/application_run_tip.rst create mode 100644 docs/source/telegram.at-tree.rst diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst index 040a37277..6b813ead8 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.rst @@ -13,7 +13,7 @@ Setting things up .. code-block:: bash - $ git clone https://github.com//python-telegram-bot --recursive + $ git clone https://github.com//python-telegram-bot $ cd python-telegram-bot 3. Add a track to the original repository: diff --git a/.readthedocs.yml b/.readthedocs.yml index 7a2c8f32a..bd9f8c51f 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -21,6 +21,31 @@ python: - requirements: docs/requirements-docs.txt build: - os: ubuntu-20.04 + os: ubuntu-22.04 tools: python: "3" # latest stable cpython version + +search: + ranking: # bump up rank of commonly searched pages: (default: 0, values range from -10 to 10) + telegram.bot.html: 7 + telegram.message.html: 3 + telegram.update.html: 3 + telegram.user.html: 2 + telegram.chat.html: 2 + telegram.ext.application.html: 3 + telegram.ext.filters.html: 3 + telegram.ext.callbackcontext.html: 2 + telegram.ext.inlinekeyboardbutton.html: 1 + + telegram.passport*.html: -7 + + ignore: + - changelog.html + - coc.html + - bot_methods.html# + - bot_methods.html + # Defaults + - search.html + - search/index.html + - 404.html + - 404/index.html' diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index 3e2f40f98..51e35d83d 100644 --- a/docs/requirements-docs.txt +++ b/docs/requirements-docs.txt @@ -1,5 +1,6 @@ sphinx==5.3.0 sphinx-pypi-upload furo==2022.9.29 +git+https://github.com/harshil21/furo-sphinx-search@be5cfa221a01f6e259bb2bb1f76d6ede7ffc1f11#egg=furo-sphinx-search sphinx-paramlinks==0.5.4 sphinxcontrib-mermaid==0.7.1 \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 0d1049ba7..331ab61c5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -5,7 +5,7 @@ import subprocess import sys from enum import Enum from pathlib import Path -from typing import Tuple +from typing import List, Tuple # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -34,7 +34,7 @@ version = "20.0a4" # telegram.__version__[:3] release = "20.0a4" # telegram.__version__ # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = "4.5.0" +needs_sphinx = "5.1.1" # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -46,6 +46,7 @@ extensions = [ "sphinx.ext.linkcode", "sphinx_paramlinks", "sphinxcontrib.mermaid", + "sphinx_search.extension", ] # Use intersphinx to reference the python builtin library docs @@ -215,11 +216,9 @@ html_favicon = "ptb-logo_1024.ico" # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] -html_css_files = [ - "style_external_link.css", - "style_mermaid_diagrams.css", -] -html_permalinks_icon = "¶" # Furo's default permalink icon is `#`` which doesn't look great imo. +html_css_files = ["style_external_link.css", "style_mermaid_diagrams.css"] + +html_permalinks_icon = "¶" # Furo's default permalink icon is `#` which doesn't look great imo. # Output file base name for HTML help builder. htmlhelp_basename = "python-telegram-bot-doc" @@ -260,6 +259,7 @@ latex_logo = "ptb-logo_1024.png" # (source start file, name, description, authors, manual section). man_pages = [(master_doc, "python-telegram-bot", "python-telegram-bot Documentation", [author], 1)] +# rtd_sphinx_search_file_type = "un-minified" # Configuration for furo-sphinx-search # -- Options for Texinfo output ------------------------------------------- @@ -378,12 +378,98 @@ line_numbers = {} file_root = Path(inspect.getsourcefile(telegram)).parent.parent.resolve() import telegram.ext # Needed for checking if an object is a BaseFilter +keyword_args = [ + ":keyword _sphinx_paramlinks_telegram.Bot.{method}.read_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to {read_timeout}.", + ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.read_timeout: {read_timeout_type}, optional", + ":keyword _sphinx_paramlinks_telegram.Bot.{method}.write_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to {write_timeout}.", + ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.write_timeout: :obj:`float` | :obj:`None`, optional", + ":keyword _sphinx_paramlinks_telegram.Bot.{method}.connect_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.", + ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.connect_timeout: :obj:`float` | :obj:`None`, optional", + ":keyword _sphinx_paramlinks_telegram.Bot.{method}.pool_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.", + ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.pool_timeout: :obj:`float` | :obj:`None`, optional", + ":keyword _sphinx_paramlinks_telegram.Bot.{method}.api_kwargs: Arbitrary keyword arguments to be passed to the Telegram API.", + ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.api_kwargs: :obj:`dict`, optional", + "", +] -def autodoc_process_docstring(app: Sphinx, what, name: str, obj: object, options, lines): - """We misuse this autodoc hook to get the file names & line numbers because we have access - to the actual object here. +write_timeout_sub = [":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`", "``20``"] +read_timeout_sub = [ + ":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.", + "``2``. :paramref:`timeout` will be added to this value", +] +read_timeout_type = [":obj:`float` | :obj:`None`", ":obj:`float`"] + + +def find_insert_pos(lines: List[str]) -> int: + """Finds the correct position to insert the keyword arguments and returns the index.""" + for idx, value in reversed(list(enumerate(lines))): # reversed since :returns: is at the end + if value.startswith(":returns:"): + return idx + else: + return False + + +def is_write_timeout_20(obj: object) -> int: + """inspects the default value of write_timeout parameter of the bot method.""" + sig = inspect.signature(obj) + return 1 if (sig.parameters["write_timeout"].default == 20) else 0 + + +def check_timeout_and_api_kwargs_presence(obj: object) -> int: + """Checks if the method has timeout and api_kwargs keyword only parameters.""" + sig = inspect.signature(obj) + params_to_check = ( + "read_timeout", + "write_timeout", + "connect_timeout", + "pool_timeout", + "api_kwargs", + ) + return all( + param in sig.parameters and sig.parameters[param].kind == inspect.Parameter.KEYWORD_ONLY + for param in params_to_check + ) + + +def autodoc_process_docstring( + app: Sphinx, what, name: str, obj: object, options, lines: List[str] +): + """We do two things: + 1) Use this method to automatically insert the Keyword Args for the Bot methods. + + 2) Misuse this autodoc hook to get the file names & line numbers because we have access + to the actual object here. """ - # Ce can't properly handle ordinary attributes. + # 1) Insert the Keyword Args for the Bot methods + method_name = name.split(".")[-1] + if ( + name.startswith("telegram.Bot.") + and what == "method" + and method_name.islower() + and check_timeout_and_api_kwargs_presence(obj) + ): + insert_index = find_insert_pos(lines) + if not insert_index: + raise ValueError( + f"Couldn't find the correct position to insert the keyword args for {obj}." + ) + + long_write_timeout = is_write_timeout_20(obj) + get_updates_sub = 1 if (method_name == "get_updates") else 0 + # The below can be done in 1 line with itertools.chain, but this must be modified in-place + for i in range(insert_index, insert_index + len(keyword_args)): + lines.insert( + i, + keyword_args[i - insert_index].format( + method=method_name, + write_timeout=write_timeout_sub[long_write_timeout], + read_timeout=read_timeout_sub[get_updates_sub], + read_timeout_type=read_timeout_type[get_updates_sub], + ), + ) + + # 2) Get the file names & line numbers + # We can't properly handle ordinary attributes. # In linkcode_resolve we'll resolve to the `__init__` or module instead if what == "attribute": return diff --git a/docs/source/inclusions/application_run_tip.rst b/docs/source/inclusions/application_run_tip.rst new file mode 100644 index 000000000..f6b1261b2 --- /dev/null +++ b/docs/source/inclusions/application_run_tip.rst @@ -0,0 +1,7 @@ +.. tip:: + When combining ``python-telegram-bot`` with other :mod:`asyncio` based frameworks, using this + method is likely not the best choice, as it blocks the event loop until it receives a stop + signal as described above. + Instead, you can manually call the methods listed below to start and shut down the application + and the :attr:`~telegram.ext.Application.updater`. + Keeping the event loop running and listening for a stop signal is then up to you. \ No newline at end of file diff --git a/docs/source/inclusions/bot_methods.rst b/docs/source/inclusions/bot_methods.rst index 605194f3f..df699e796 100644 --- a/docs/source/inclusions/bot_methods.rst +++ b/docs/source/inclusions/bot_methods.rst @@ -290,6 +290,10 @@ :align: left :widths: 1 4 + * - :attr:`~telegram.Bot.base_file_url` + - Telegram Bot API file URL + * - :attr:`~telegram.Bot.base_url` + - Telegram Bot API service URL * - :attr:`~telegram.Bot.bot` - The user instance of the bot as returned by :meth:`~telegram.Bot.get_me` * - :attr:`~telegram.Bot.can_join_groups` @@ -310,8 +314,12 @@ - The username of the bot, without leading ``@`` * - :attr:`~telegram.Bot.link` - The t.me link of the bot + * - :attr:`~telegram.Bot.private_key` + - Deserialized private key for decryption of telegram passport data * - :attr:`~telegram.Bot.supports_inline_queries` - Whether the bot supports inline queries + * - :attr:`~telegram.Bot.token` + - Bot's unique authentication token .. raw:: html diff --git a/docs/source/telegram.at-tree.rst b/docs/source/telegram.at-tree.rst new file mode 100644 index 000000000..4f2a4ec1a --- /dev/null +++ b/docs/source/telegram.at-tree.rst @@ -0,0 +1,82 @@ +Available Types +--------------- + +.. toctree:: + + telegram.animation + telegram.audio + telegram.botcommand + telegram.botcommandscope + telegram.botcommandscopeallchatadministrators + telegram.botcommandscopeallgroupchats + telegram.botcommandscopeallprivatechats + telegram.botcommandscopechat + telegram.botcommandscopechatadministrators + telegram.botcommandscopechatmember + telegram.botcommandscopedefault + telegram.callbackquery + telegram.chat + telegram.chatadministratorrights + telegram.chatinvitelink + telegram.chatjoinrequest + telegram.chatlocation + telegram.chatmember + telegram.chatmemberadministrator + telegram.chatmemberbanned + telegram.chatmemberleft + telegram.chatmembermember + telegram.chatmemberowner + telegram.chatmemberrestricted + telegram.chatmemberupdated + telegram.chatpermissions + telegram.chatphoto + telegram.contact + telegram.dice + telegram.document + telegram.file + telegram.forcereply + telegram.inlinekeyboardbutton + telegram.inlinekeyboardmarkup + telegram.inputfile + telegram.inputmedia + telegram.inputmediaanimation + telegram.inputmediaaudio + telegram.inputmediadocument + telegram.inputmediaphoto + telegram.inputmediavideo + telegram.keyboardbutton + telegram.keyboardbuttonpolltype + telegram.location + telegram.loginurl + telegram.menubutton + telegram.menubuttoncommands + telegram.menubuttondefault + telegram.menubuttonwebapp + telegram.message + telegram.messageautodeletetimerchanged + telegram.messageentity + telegram.messageid + telegram.photosize + telegram.poll + telegram.pollanswer + telegram.polloption + telegram.proximityalerttriggered + telegram.replykeyboardmarkup + telegram.replykeyboardremove + telegram.sentwebappmessage + telegram.telegramobject + telegram.update + telegram.user + telegram.userprofilephotos + telegram.venue + telegram.video + telegram.videochatended + telegram.videochatparticipantsinvited + telegram.videochatscheduled + telegram.videochatstarted + telegram.videonote + telegram.voice + telegram.webappdata + telegram.webappinfo + telegram.webhookinfo + diff --git a/docs/source/telegram.ext.rst b/docs/source/telegram.ext.rst index 578df56fa..1116fa31d 100644 --- a/docs/source/telegram.ext.rst +++ b/docs/source/telegram.ext.rst @@ -2,6 +2,7 @@ telegram.ext package ==================== .. toctree:: + :titlesonly: telegram.ext.application telegram.ext.applicationbuilder diff --git a/docs/source/telegram.rst b/docs/source/telegram.rst index 600913a5d..fe3eac4a0 100644 --- a/docs/source/telegram.rst +++ b/docs/source/telegram.rst @@ -7,88 +7,14 @@ Version Constants .. automodule:: telegram :members: __version__, __version_info__, __bot_api_version__, __bot_api_version_info__ -Available Types ---------------- +Classes in this package +----------------------- .. toctree:: + :titlesonly: - telegram.animation - telegram.audio telegram.bot - telegram.botcommand - telegram.botcommandscope - telegram.botcommandscopeallchatadministrators - telegram.botcommandscopeallgroupchats - telegram.botcommandscopeallprivatechats - telegram.botcommandscopechat - telegram.botcommandscopechatadministrators - telegram.botcommandscopechatmember - telegram.botcommandscopedefault - telegram.callbackquery - telegram.chat - telegram.chatadministratorrights - telegram.chatinvitelink - telegram.chatjoinrequest - telegram.chatlocation - telegram.chatmember - telegram.chatmemberadministrator - telegram.chatmemberbanned - telegram.chatmemberleft - telegram.chatmembermember - telegram.chatmemberowner - telegram.chatmemberrestricted - telegram.chatmemberupdated - telegram.chatpermissions - telegram.chatphoto - telegram.contact - telegram.dice - telegram.document - telegram.file - telegram.forcereply - telegram.inlinekeyboardbutton - telegram.inlinekeyboardmarkup - telegram.inputfile - telegram.inputmedia - telegram.inputmediaanimation - telegram.inputmediaaudio - telegram.inputmediadocument - telegram.inputmediaphoto - telegram.inputmediavideo - telegram.keyboardbutton - telegram.keyboardbuttonpolltype - telegram.location - telegram.loginurl - telegram.menubutton - telegram.menubuttoncommands - telegram.menubuttondefault - telegram.menubuttonwebapp - telegram.message - telegram.messageautodeletetimerchanged - telegram.messageentity - telegram.messageid - telegram.photosize - telegram.poll - telegram.pollanswer - telegram.polloption - telegram.proximityalerttriggered - telegram.replykeyboardmarkup - telegram.replykeyboardremove - telegram.sentwebappmessage - telegram.telegramobject - telegram.update - telegram.user - telegram.userprofilephotos - telegram.venue - telegram.video - telegram.videochatended - telegram.videochatparticipantsinvited - telegram.videochatscheduled - telegram.videochatstarted - telegram.videonote - telegram.voice - telegram.webappdata - telegram.webappinfo - telegram.webhookinfo + telegram.at-tree.rst telegram.stickers-tree.rst telegram.inline-tree.rst telegram.payments-tree.rst diff --git a/docs/source/telegram.telegramobject.rst b/docs/source/telegram.telegramobject.rst index 9a3d85d6c..c9ce365a4 100644 --- a/docs/source/telegram.telegramobject.rst +++ b/docs/source/telegram.telegramobject.rst @@ -4,4 +4,4 @@ telegram.TelegramObject .. autoclass:: telegram.TelegramObject :members: :show-inheritance: - :special-members: __repr__ + :special-members: __repr__, __getitem__, __eq__, __hash__, __setstate__, __getstate__, __deepcopy__ diff --git a/docs/substitutions/global.rst b/docs/substitutions/global.rst index fc1bb3dda..46067cbc8 100644 --- a/docs/substitutions/global.rst +++ b/docs/substitutions/global.rst @@ -21,3 +21,19 @@ .. |toapikwargsarg| replace:: Arbitrary keyword arguments. Can be used to store data for which there are no dedicated attributes. |toapikwargsbase| .. |toapikwargsattr| replace:: Optional. Arbitrary keyword arguments. Used to store data for which there are no dedicated attributes. |toapikwargsbase| + +.. |chat_id_channel| replace:: Unique identifier for the target chat or username of the target channel (in the format ``@channelusername``). + +.. |chat_id_group| replace:: Unique identifier for the target chat or username of the target supergroup (in the format ``@supergroupusername``). + +.. |parse_mode| replace:: Send Markdown or HTML, if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your bot's message. See the constants in :class:`telegram.constants.ParseMode` for the available modes. + +.. |allow_sending_without_reply| replace:: Pass :obj:`True`, if the message should be sent even if the specified replied-to message is not found. + +.. |caption_entities| replace:: List of special entities that appear in the caption, which can be specified instead of ``parse_mode``. + +.. |protect_content| replace:: Protects the contents of the sent message from forwarding and saving. + +.. |disable_notification| replace:: Sends the message silently. Users will receive a notification with no sound. + +.. |reply_to_msg_id| replace:: If the message is a reply, ID of the original message. \ No newline at end of file diff --git a/telegram/_bot.py b/telegram/_bot.py index bd47fe266..d7e83362f 100644 --- a/telegram/_bot.py +++ b/telegram/_bot.py @@ -141,9 +141,16 @@ class Bot(TelegramObject, AbstractAsyncContextManager): serialized instance will not reflect that change. Trying to pickle a bot instance will raise :exc:`pickle.PicklingError`. + Examples: + :any:`Raw API Bot ` + .. seealso:: :attr:`telegram.ext.Application.bot`, :attr:`telegram.ext.CallbackContext.bot`, - :attr:`telegram.ext.Updater.bot` + :attr:`telegram.ext.Updater.bot`, + `Your First Bot `_, + `Builder Pattern `_ .. versionadded:: 13.2 Objects of this class are comparable in terms of equality. Two objects of this class are @@ -621,22 +628,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): ) -> User: """A simple method for testing your bot's auth token. Requires no parameters. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.User`: A :class:`telegram.User` instance representing that bot if the credentials are valid, :obj:`None` otherwise. @@ -682,50 +673,27 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.send_message` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| text (:obj:`str`): Text of the message to be sent. Max :tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters after entities parsing. - parse_mode (:obj:`str`): Send Markdown or HTML, if you want Telegram apps to show bold, - italic, fixed-width text or inline URLs in your bot's message. See the constants in - :class:`telegram.constants.ParseMode` for the available modes. + parse_mode (:obj:`str`): |parse_mode| entities (List[:class:`telegram.MessageEntity`], optional): List of special entities that appear in message text, which can be specified instead of :paramref:`parse_mode`. disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in this message. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of sent messages from - forwarding and saving. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.Message`: On success, the sent message is returned. @@ -789,26 +757,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :meth:`telegram.CallbackQuery.delete_message` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| message_id (:obj:`int`): Identifier of the message to delete. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -858,34 +809,16 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.Chat.forward_from` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| from_chat_id (:obj:`int` | :obj:`str`): Unique identifier for the chat where the original message was sent (or channel username in the format ``@channelusername``). - message_id (:obj:`int`): Message identifier in the chat specified in from_chat_id. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + message_id (:obj:`int`): Message identifier in the chat specified in + :paramref:`from_chat_id`. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -939,8 +872,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.send_photo` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| photo (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \ :class:`telegram.PhotoSize`): Photo to send. |fileinput| @@ -955,23 +887,14 @@ class Bot(TelegramObject, AbstractAsyncContextManager): caption (:obj:`str`, optional): Photo caption (may also be used when resending photos by file_id), 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. - parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to - show bold, italic, fixed-width text or inline URLs in the media caption. See the - constants in :class:`telegram.constants.ParseMode` for the available modes. - caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special - entities that appear in message text, which can be specified instead of - :paramref:`parse_mode`. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + parse_mode (:obj:`str`, optional): |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities| + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply @@ -983,19 +906,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :obj:`tempfile` module. .. versionadded:: 13.1 - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to ``20``. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -1058,7 +968,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): ) -> Message: """ Use this method to send audio files, if you want Telegram clients to display them in the - music player. Your audio must be in the .mp3 or .m4a format. + music player. Your audio must be in the ``.mp3`` or ``.m4a`` format. Bots can currently send audio files of up to :tg-const:`telegram.constants.FileSizeLimit.FILESIZE_UPLOAD` in size, this limit may be @@ -1070,8 +980,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.send_audio` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| audio (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \ :class:`telegram.Audio`): Audio file to send. |fileinput| @@ -1086,26 +995,17 @@ class Bot(TelegramObject, AbstractAsyncContextManager): caption (:obj:`str`, optional): Audio caption, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. - parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to - show bold, italic, fixed-width text or inline URLs in the media caption. See the - constants in :class:`telegram.constants.ParseMode` for the available modes. - caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special - entities that appear in message text, which can be specified instead of - :paramref:`parse_mode`. + parse_mode (:obj:`str`, optional): |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities| duration (:obj:`int`, optional): Duration of sent audio in seconds. performer (:obj:`str`, optional): Performer. title (:obj:`str`, optional): Track name. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply @@ -1126,19 +1026,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :obj:`tempfile` module. .. versionadded:: 13.1 - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to ``20``. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -1216,8 +1103,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.send_document` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| document (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \ :class:`telegram.Document`): File to send. |fileinput| @@ -1237,23 +1123,14 @@ class Bot(TelegramObject, AbstractAsyncContextManager): characters after entities parsing. disable_content_type_detection (:obj:`bool`, optional): Disables automatic server-side content type detection for files uploaded using multipart/form-data. - parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to - show bold, italic, fixed-width text or inline URLs in the media caption. See the - constants in :class:`telegram.constants.ParseMode` for the available modes. - caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special - entities that appear in message text, which can be specified instead of - :paramref:`parse_mode`. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + parse_mode (:obj:`str`, optional): |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities| + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply @@ -1272,19 +1149,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): filename (:obj:`str`, optional): Custom file name for the document, when uploading a new file. Convenience parameter, useful e.g. when sending files generated by the :obj:`tempfile` module. - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to ``20``. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -1348,8 +1212,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.send_sticker` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| sticker (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \ :class:`telegram.Sticker`): Sticker to send. |fileinput| @@ -1361,37 +1224,17 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionchanged:: 20.0 File paths as input is also accepted for bots *not* running in :paramref:`~telegram.Bot.local_mode`. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to ``20``. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -1458,8 +1301,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.send_video` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| video (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \ :class:`telegram.Video`): Video file to send. |fileinput| @@ -1477,25 +1319,16 @@ class Bot(TelegramObject, AbstractAsyncContextManager): caption (:obj:`str`, optional): Video caption (may also be used when resending videos by file_id), 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. - parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to - show bold, italic, fixed-width text or inline URLs in the media caption. See the - constants in :class:`telegram.constants.ParseMode` for the available modes. - caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special - entities that appear in message text, which can be specified instead of - :paramref:`parse_mode`. + parse_mode (:obj:`str`, optional): |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities| supports_streaming (:obj:`bool`, optional): Pass :obj:`True`, if the uploaded video is suitable for streaming. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply @@ -1516,19 +1349,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :obj:`tempfile` module. .. versionadded:: 13.1 - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to ``20``. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -1608,8 +1428,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.send_video_note` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| video_note (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \ :class:`telegram.VideoNote`): Video note to send. Pass a file_id as String to send a video note that exists on the Telegram @@ -1627,17 +1446,12 @@ class Bot(TelegramObject, AbstractAsyncContextManager): duration (:obj:`int`, optional): Duration of sent video in seconds. length (:obj:`int`, optional): Video width and height, i.e. diameter of the video message. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply @@ -1658,19 +1472,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :obj:`tempfile` module. .. versionadded:: 13.1 - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to ``20``. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -1747,8 +1548,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.send_animation` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| animation (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \ :class:`telegram.Animation`): Animation to send. |fileinput| @@ -1773,23 +1573,14 @@ class Bot(TelegramObject, AbstractAsyncContextManager): animations by file_id), 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. - parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to - show bold, italic, fixed-width text or inline URLs in the media caption. See the - constants in :class:`telegram.constants.ParseMode` for the available modes. - caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special - entities that appear in message text, which can be specified instead of - :paramref:`parse_mode`. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + parse_mode (:obj:`str`, optional): |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities| + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply @@ -1801,19 +1592,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :obj:`tempfile` module. .. versionadded:: 13.1 - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to ``20``. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -1893,8 +1671,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.send_voice` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| voice (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \ :class:`telegram.Voice`): Voice file to send. |fileinput| @@ -1909,24 +1686,15 @@ class Bot(TelegramObject, AbstractAsyncContextManager): caption (:obj:`str`, optional): Voice message caption, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. - parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to - show bold, italic, fixed-width text or inline URLs in the media caption. See the - constants in :class:`telegram.constants.ParseMode` for the available modes. - caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special - entities that appear in message text, which can be specified instead of - :paramref:`parse_mode`. + parse_mode (:obj:`str`, optional): |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities| duration (:obj:`int`, optional): Duration of the voice message in seconds. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply @@ -1938,19 +1706,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :obj:`tempfile` module. .. versionadded:: 13.1 - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to ``20``. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -2012,59 +1767,46 @@ class Bot(TelegramObject, AbstractAsyncContextManager): """Use this method to send a group of photos or videos as an album. Note: - If you supply a :paramref:`caption` (along with either - :paramref:`parse_mode` or :paramref:`caption_entities`), - then items in :paramref:`media` must have no captions, and vice verca. + If you supply a :paramref:`caption` (along with either :paramref:`parse_mode` or + :paramref:`caption_entities`), then items in :paramref:`media` must have no captions, + and vice versa. .. seealso:: :attr:`telegram.Message.reply_media_group`, :attr:`telegram.Chat.send_media_group`, :attr:`telegram.User.send_media_group` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| media (List[:class:`telegram.InputMediaAudio`, :class:`telegram.InputMediaDocument`, \ :class:`telegram.InputMediaPhoto`, :class:`telegram.InputMediaVideo`]): An array describing messages to be sent, must include 2–10 items. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to ``20``. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. caption (:obj:`str`, optional): Caption that will be added to the first element of :paramref:`media`, so that it will be used as caption for the whole media group. Defaults to :obj:`None`. + + .. versionadded:: 20.0 parse_mode (:obj:`str` | :obj:`None`, optional): Parse mode for :paramref:`caption`. See the constants in :class:`telegram.constants.ParseMode` for the available modes. + + .. versionadded:: 20.0 caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special entities for :paramref:`caption`, which can be specified instead of :paramref:`parse_mode`. Defaults to :obj:`None`. + .. versionadded:: 20.0 + Returns: List[:class:`telegram.Message`]: An array of the sent Messages. @@ -2150,8 +1892,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.send_location` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| latitude (:obj:`float`, optional): Latitude of location. longitude (:obj:`float`, optional): Longitude of location. horizontal_accuracy (:obj:`int`, optional): The radius of uncertainty for the location, @@ -2165,17 +1906,12 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 1 and :tg-const:`telegram.constants.LocationLimit.HEADING` if specified. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply @@ -2183,20 +1919,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Keyword Args: location (:class:`telegram.Location`, optional): The location to send. - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -2278,8 +2000,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Args: chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not - specified. Unique identifier for the target chat or username of the target channel - (in the format ``@channelusername``). + specified. |chat_id_channel| message_id (:obj:`int`, optional): Required if inline_message_id is not specified. Identifier of the message to edit. inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not @@ -2299,20 +2020,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Keyword Args: location (:class:`telegram.Location`, optional): The location to send. - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. Returns: :class:`telegram.Message`: On success, if edited message is not an inline message, the @@ -2374,38 +2081,21 @@ class Bot(TelegramObject, AbstractAsyncContextManager): api_kwargs: JSONDict = None, ) -> Union[Message, bool]: """Use this method to stop updating a live location message sent by the bot or via the bot - (for inline bots) before live_period expires. + (for inline bots) before :paramref:`~telegram.Location.live_period` expires. - .. seealso:: :attr:`telegram.Message.stop_live_location` + .. seealso:: :attr:`telegram.Message.stop_live_location`, :attr:`telegram.CallbackQuery.stop_message_live_location` Args: - chat_id (:obj:`int` | :obj:`str`): Required if inline_message_id is not specified. - Unique identifier for the target chat or username of the target channel - (in the format ``@channelusername``). - message_id (:obj:`int`, optional): Required if inline_message_id is not specified. - Identifier of the sent message with live location to stop. - inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not - specified. Identifier of the inline message. + chat_id (:obj:`int` | :obj:`str`, optional): Required if :paramref:`inline_message_id` + is not specified. |chat_id_channel| + message_id (:obj:`int`, optional): Required if :paramref:`inline_message_id` is not + specified. Identifier of the sent message with live location to stop. + inline_message_id (:obj:`str`, optional): Required if :paramref:`chat_id` and + :paramref:`message_id` are not specified. Identifier of the inline message. reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): An object for a new inline keyboard. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.Message`: On success, if edited message is not an inline message, the edited message is returned, otherwise :obj:`True` is returned. @@ -2469,8 +2159,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.send_venue` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| latitude (:obj:`float`, optional): Latitude of venue. longitude (:obj:`float`, optional): Longitude of venue. title (:obj:`str`, optional): Name of the venue. @@ -2483,17 +2172,13 @@ class Bot(TelegramObject, AbstractAsyncContextManager): google_place_type (:obj:`str`, optional): Google Places type of the venue. (See `supported types \ `_.) - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply @@ -2501,20 +2186,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Keyword Args: venue (:class:`telegram.Venue`, optional): The venue to send. - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -2610,24 +2281,19 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.send_contact` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| phone_number (:obj:`str`, optional): Contact's phone number. first_name (:obj:`str`, optional): Contact's first name. last_name (:obj:`str`, optional): Contact's last name. vcard (:obj:`str`, optional): Additional data about the contact in the form of a vCard, 0-2048 bytes. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply @@ -2635,20 +2301,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Keyword Args: contact (:class:`telegram.Contact`, optional): The contact to send. - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -2727,37 +2379,16 @@ class Bot(TelegramObject, AbstractAsyncContextManager): chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat. game_short_name (:obj:`str`): Short name of the game, serves as the unique identifier for the game. Set up your games via `@BotFather `_. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): An object for a new - inline keyboard. If empty, one ‘Play game_title’ button will be + inline keyboard. If empty, one "Play game_title" button will be shown. If not empty, the first button must launch the game. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -2804,28 +2435,11 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.send_chat_action` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| action(:obj:`str`): Type of action to broadcast. Choose one, depending on what the user is about to receive. For convenience look at the constants in :class:`telegram.constants.ChatAction`. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -2959,6 +2573,15 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Use this method to send answers to an inline query. No more than :tg-const:`telegram.InlineQuery.MAX_RESULTS` results per query are allowed. + Example: + An inline bot that sends YouTube videos can ask the user to connect the bot to their + YouTube account to adapt search results accordingly. To do this, it displays a + 'Connect your YouTube account' button above the results, or even before showing any. + The user presses the button, switches to a private chat with the bot and, in doing so, + passes a start parameter that instructs the bot to return an oauth link. Once done, the + bot can offer a switch_inline button so that the user can easily return to the chat + where they wanted to use the bot's inline capabilities. + Warning: In most use cases :paramref:`current_offset` should not be passed manually. Instead of calling this method directly, use the shortcut :meth:`telegram.InlineQuery.answer` with @@ -2997,29 +2620,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): the inline query to answer. If passed, PTB will automatically take care of the pagination for you, i.e. pass the correct :paramref:`next_offset` and truncate the results list/get the results from the callable you passed. - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - - Example: - An inline bot that sends YouTube videos can ask the user to connect the bot to their - YouTube account to adapt search results accordingly. To do this, it displays a - 'Connect your YouTube account' button above the results, or even before showing any. - The user presses the button, switches to a private chat with the bot and, in doing so, - passes a start parameter that instructs the bot to return an oauth link. Once done, the - bot can offer a switch_inline button so that the user can easily return to the chat - where they wanted to use the bot's inline capabilities. Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -3084,22 +2684,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): limit (:obj:`int`, optional): Limits the number of photos to be retrieved. Values between 1-100 are accepted. Defaults to ``100``. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.UserProfilePhotos` @@ -3148,9 +2732,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): requested by calling get_file again. Note: - This function may not preserve the original file name and MIME type. - You should save the file's MIME type and name (if available) when the File object - is received. + This function may not preserve the original file name and MIME type. + You should save the file's MIME type and name (if available) when the File object + is received. Args: file_id (:obj:`str` | :class:`telegram.Animation` | :class:`telegram.Audio` | \ @@ -3161,22 +2745,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Either the file identifier or an object that has a file_id attribute to get file information about. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.File` @@ -3232,7 +2800,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.ban_member` - .. versionadded:: 13.7 + .. versionadded:: 13.7 Args: chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target group or username @@ -3252,22 +2820,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionadded:: 13.4 - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -3322,22 +2874,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): of the target supergroup or channel (in the format ``@channelusername``). sender_chat_id (:obj:`int`): Unique identifier of the target sender chat. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -3383,27 +2919,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.unban_member` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target supergroup or channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| user_id (:obj:`int`): Unique identifier of the target user. only_if_banned (:obj:`bool`, optional): Do nothing if the user is not banned. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -3449,26 +2968,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionadded:: 13.9 Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target supergroup or channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| sender_chat_id (:obj:`int`): Unique identifier of the target sender chat. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -3533,22 +3035,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): cache_time (:obj:`int`, optional): The maximum amount of time in seconds that the result of the callback query may be cached client-side. Defaults to 0. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool` On success, :obj:`True` is returned. @@ -3607,19 +3093,16 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.CallbackQuery.edit_message_text` Args: - chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not - specified. Unique identifier for the target chat or username of the target channel - (in the format ``@channelusername``) - message_id (:obj:`int`, optional): Required if inline_message_id is not specified. - Identifier of the message to edit. - inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not - specified. Identifier of the inline message. + chat_id (:obj:`int` | :obj:`str`, optional): Required if :paramref:`inline_message_id` + is not specified. |chat_id_channel| + message_id (:obj:`int`, optional): Required if :paramref:`inline_message_id` is not + specified. Identifier of the message to edit. + inline_message_id (:obj:`str`, optional): Required if :paramref:`chat_id` and + :paramref:`message_id` are not specified. Identifier of the inline message. text (:obj:`str`): New text of the message, 1-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters after entities parsing. - parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to - show bold, italic, fixed-width text or inline URLs in your bot's message. See the - constants in :class:`telegram.constants.ParseMode` for the available modes. + parse_mode (:obj:`str`, optional): |parse_mode| entities (List[:class:`telegram.MessageEntity`], optional): List of special entities that appear in message text, which can be specified instead of :paramref:`parse_mode`. @@ -3628,22 +3111,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): An object for an inline keyboard. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.Message`: On success, if edited message is not an inline message, the edited message is returned, otherwise :obj:`True` is returned. @@ -3706,8 +3173,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Args: chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not - specified. Unique identifier for the target chat or username of the target channel - (in the format ``@channelusername``) + specified. |chat_id_channel| message_id (:obj:`int`, optional): Required if inline_message_id is not specified. Identifier of the message to edit. inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not @@ -3715,31 +3181,11 @@ class Bot(TelegramObject, AbstractAsyncContextManager): caption (:obj:`str`, optional): New caption of the message, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities parsing. - parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to - show bold, italic, fixed-width text or inline URLs in the media caption. See the - constants in :class:`telegram.constants.ParseMode` for the available modes. - caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special - entities that appear in message text, which can be specified instead of - :paramref:`parse_mode`. + parse_mode (:obj:`str`, optional): |parse_mode| + caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities| reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): An object for an inline keyboard. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.Message`: On success, if edited message is not an inline message, the edited message is returned, otherwise :obj:`True` is returned. @@ -3804,8 +3250,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): media (:class:`telegram.InputMedia`): An object for a new media content of the message. chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not - specified. Unique identifier for the target chat or username of the target channel - (in the format ``@channelusername``). + specified. |chat_id_channel| message_id (:obj:`int`, optional): Required if inline_message_id is not specified. Identifier of the message to edit. inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not @@ -3813,22 +3258,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): An object for an inline keyboard. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.Message`: On success, if edited message is not an inline message, the edited Message is returned, otherwise :obj:`True` is returned. @@ -3882,8 +3311,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Args: chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not - specified. Unique identifier for the target chat or username of the target channel - (in the format ``@channelusername``). + specified. |chat_id_channel| message_id (:obj:`int`, optional): Required if inline_message_id is not specified. Identifier of the message to edit. inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not @@ -3891,22 +3319,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): An object for an inline keyboard. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.Message`: On success, if edited message is not an inline message, the edited message is returned, otherwise :obj:`True` is returned. @@ -3980,22 +3392,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): created before the call to the get_updates, so unwanted updates may be received for a short period of time. - Keyword Args: - read_timeout (:obj:`float`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - ``2``. :paramref:`timeout` will be added to this value. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: List[:class:`telegram.Update`] @@ -4076,6 +3472,21 @@ class Bot(TelegramObject, AbstractAsyncContextManager): If you're having any trouble setting up webhooks, please check out this `guide to Webhooks`_. + Note: + 1. You will not be able to receive updates using :meth:`get_updates` for long as an + outgoing webhook is set up. + 2. To use a self-signed certificate, you need to upload your public key certificate + using certificate parameter. Please upload as InputFile, sending a String will not + work. + 3. Ports currently supported for Webhooks: + :attr:`telegram.constants.SUPPORTED_WEBHOOK_PORTS`. + + If you're having any trouble setting up webhooks, please check out this `guide to + Webhooks`_. + + Examples: + :any:`Custom Webhook Bot ` + Args: url (:obj:`str`): HTTPS url to send updates to. Use an empty string to remove webhook integration. @@ -4110,22 +3521,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionadded:: 20.0 - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool` On success, :obj:`True` is returned. @@ -4181,22 +3576,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): drop_pending_updates (:obj:`bool`, optional): Pass :obj:`True` to drop all pending updates. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -4237,24 +3616,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.leave` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target supergroup or channel (in the format ``@channelusername``). - - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -4293,24 +3655,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): one-on-one conversations, current username of a user, group or channel, etc.). Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target supergroup or channel (in the format ``@channelusername``). - - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| Returns: :class:`telegram.Chat` @@ -4350,24 +3695,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.get_administrators` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target supergroup or channel (in the format ``@channelusername``). - - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| Returns: List[:class:`telegram.ChatMember`]: On success, returns a list of ``ChatMember`` @@ -4409,24 +3737,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionadded:: 13.7 Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target supergroup or channel (in the format ``@channelusername``). - - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| Returns: :obj:`int`: Number of members in the chat. @@ -4464,26 +3775,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.get_member` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target supergroup or channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| user_id (:obj:`int`): Unique identifier of the target user. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.ChatMember` @@ -4521,27 +3815,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager): in :meth:`get_chat` requests to check if the bot can use this method. Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target supergroup (in the format @supergroupusername). + chat_id (:obj:`int` | :obj:`str`): |chat_id_group| sticker_set_name (:obj:`str`): Name of the sticker set to be set as the group sticker set. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. """ @@ -4574,24 +3851,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :meth:`get_chat` requests to check if the bot can use this method. Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target supergroup (in the format @supergroupusername). - - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. + chat_id (:obj:`int` | :obj:`str`): |chat_id_group| Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -4622,22 +3882,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): If the bot is using :meth:`get_updates`, will return an object with the :attr:`telegram.WebhookInfo.url` field empty. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.WebhookInfo` @@ -4682,28 +3926,12 @@ class Bot(TelegramObject, AbstractAsyncContextManager): decrease. This can be useful when fixing mistakes or banning cheaters. disable_edit_message (:obj:`bool`, optional): Pass :obj:`True`, if the game message should not be automatically edited to include the current scoreboard. - chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not - specified. Unique identifier for the target chat. - message_id (:obj:`int`, optional): Required if inline_message_id is not specified. - Identifier of the sent message. - inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not - specified. Identifier of the inline message. - - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. + chat_id (:obj:`int` | :obj:`str`, optional): Required if :paramref:`inline_message_id` + is not specified. Unique identifier for the target chat. + message_id (:obj:`int`, optional): Required if :paramref:`inline_message_id` is not + specified. Identifier of the sent message. + inline_message_id (:obj:`str`, optional): Required if :paramref:`chat_id` and + :paramref:`message_id` are not specified. Identifier of the inline message. Returns: :class:`telegram.Message`: The edited message. If the message is not an inline message @@ -4711,7 +3939,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Raises: :class:`telegram.error.TelegramError`: If the new score is not greater than the user's - current score in the chat and force is :obj:`False`. + current score in the chat and :paramref:`force` is :obj:`False`. """ data: JSONDict = {"user_id": user_id, "score": score} @@ -4764,28 +3992,12 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Args: user_id (:obj:`int`): Target user id. - chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not - specified. Unique identifier for the target chat. - message_id (:obj:`int`, optional): Required if inline_message_id is not specified. - Identifier of the sent message. - inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not - specified. Identifier of the inline message. - - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. + chat_id (:obj:`int` | :obj:`str`, optional): Required if :paramref:`inline_message_id` + is not specified. Unique identifier for the target chat. + message_id (:obj:`int`, optional): Required if :paramref:`inline_message_id` is not + specified. Identifier of the sent message. + inline_message_id (:obj:`str`, optional): Required if :paramref:`chat_id` and + :paramref:`message_id` are not specified. Identifier of the inline message. Returns: List[:class:`telegram.GameHighScore`] @@ -4866,8 +4078,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): As of Bot API 5.2, the parameter :paramref:`start_parameter` is optional. Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| title (:obj:`str`): Product name. :tg-const:`telegram.Invoice.MIN_TITLE_LENGTH`- :tg-const:`telegram.Invoice.MAX_TITLE_LENGTH` characters. description (:obj:`str`): Product description. @@ -4932,37 +4143,16 @@ class Bot(TelegramObject, AbstractAsyncContextManager): address should be sent to provider. is_flexible (:obj:`bool`, optional): Pass :obj:`True`, if the final price depends on the shipping method. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): An object for an inline keyboard. If empty, one 'Pay total price' button will be shown. If not empty, the first button must be a Pay button. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -5052,28 +4242,12 @@ class Bot(TelegramObject, AbstractAsyncContextManager): ok (:obj:`bool`): Specify :obj:`True` if delivery to the specified address is possible and :obj:`False` if there are any problems (for example, if delivery to the specified address is not possible). - shipping_options (List[:class:`telegram.ShippingOption`]), optional]: Required if ok is - :obj:`True`. An array of available shipping options. - error_message (:obj:`str`, optional): Required if ok is :obj:`False`. Error message in - human readable form that explains why it is impossible to complete the order (e.g. - "Sorry, delivery to your desired address is unavailable"). Telegram will display - this message to the user. - - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. + shipping_options (List[:class:`telegram.ShippingOption`]), optional]: Required if + :paramref:`ok` is :obj:`True`. A list of available shipping options. + error_message (:obj:`str`, optional): Required if :paramref:`ok` is :obj:`False`. + Error message in human readable form that explains why it is impossible to complete + the order (e.g. "Sorry, delivery to your desired address is unavailable"). Telegram + will display this message to the user. Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -5131,30 +4305,14 @@ class Bot(TelegramObject, AbstractAsyncContextManager): ok (:obj:`bool`): Specify :obj:`True` if everything is alright (goods are available, etc.) and the bot is ready to proceed with the order. Use :obj:`False` if there are any problems. - error_message (:obj:`str`, optional): Required if ok is :obj:`False`. Error message - in human readable form that explains the reason for failure to proceed with + error_message (:obj:`str`, optional): Required if :paramref:`ok` is :obj:`False`. Error + message in human readable form that explains the reason for failure to proceed with the checkout (e.g. "Sorry, somebody just bought the last of our amazing black T-shirts while you were busy filling out your payment details. Please choose a different color or garment!"). Telegram will display this message to the user. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: - :obj:`bool`: On success, :obj:`True` is returned. + :obj:`bool`: On success, :obj:`True` is returned Raises: :class:`telegram.error.TelegramError` @@ -5199,22 +4357,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): result (:class:`telegram.InlineQueryResult`): An object describing the message to be sent. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.SentWebAppMessage`: On success, a sent :class:`telegram.SentWebAppMessage` is returned. @@ -5263,8 +4405,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.Chat.restrict_member` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target supergroup (in the format @supergroupusername). + chat_id (:obj:`int` | :obj:`str`): |chat_id_group| user_id (:obj:`int`): Unique identifier of the target user. until_date (:obj:`int` | :obj:`datetime.datetime`, optional): Date when restrictions will be lifted for the user, unix time. If user is restricted for more than 366 @@ -5276,22 +4417,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): permissions (:class:`telegram.ChatPermissions`): An object for new user permissions. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -5354,8 +4479,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :paramref:`can_manage_video_chats` in accordance to Bot API 6.0. Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| user_id (:obj:`int`): Unique identifier of the target user. is_anonymous (:obj:`bool`, optional): Pass :obj:`True`, if the administrator's presence in the chat is hidden. @@ -5390,22 +4514,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): that he has promoted, directly or indirectly (promoted by administrators that were appointed by him). - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -5470,26 +4578,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.set_permissions` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username of - the target supergroup (in the format `@supergroupusername`). + chat_id (:obj:`int` | :obj:`str`): |chat_id_group| permissions (:class:`telegram.ChatPermissions`): New default chat permissions. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -5529,28 +4620,11 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.set_administrator_custom_title` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username of - the target supergroup (in the format `@supergroupusername`). + chat_id (:obj:`int` | :obj:`str`): |chat_id_group| user_id (:obj:`int`): Unique identifier of the target administrator. custom_title (:obj:`str`): New custom title for the administrator; 0-16 characters, emoji are not allowed. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -5598,24 +4672,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.export_invite_link` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). - - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| Returns: :obj:`str`: New invite link on success. @@ -5661,8 +4718,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionadded:: 13.4 Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| expire_date (:obj:`int` | :obj:`datetime.datetime`, optional): Date when the link will expire. Integer input will be interpreted as Unix timestamp. For timezone naive :obj:`datetime.datetime` objects, the default timezone of the @@ -5681,22 +4737,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionadded:: 13.8 - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.ChatInviteLink` @@ -5761,8 +4801,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionadded:: 13.4 Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| invite_link (:obj:`str` | :obj:`telegram.ChatInviteLink`): The invite link to edit. .. versionchanged:: 20.0 @@ -5785,22 +4824,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionadded:: 13.8 - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.ChatInviteLink` @@ -5857,29 +4880,12 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionadded:: 13.4 Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| invite_link (:obj:`str` | :obj:`telegram.ChatInviteLink`): The invite link to revoke. .. versionchanged:: 20.0 Now also accepts :obj:`telegram.ChatInviteLink` instances. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.ChatInviteLink` @@ -5925,26 +4931,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionadded:: 13.8 Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| user_id (:obj:`int`): Unique identifier of the target user. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -5988,26 +4977,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionadded:: 13.8 Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| user_id (:obj:`int`): Unique identifier of the target user. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -6048,8 +5020,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.set_photo` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| photo (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`): New chat photo. |uploadinput| @@ -6060,22 +5031,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): File paths as input is also accepted for bots *not* running in :paramref:`~telegram.Bot.local_mode`. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -6114,24 +5069,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.delete_photo` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). - - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -6172,26 +5110,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.set_title` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| title (:obj:`str`): New chat title, 1-255 characters. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -6231,26 +5152,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.set_description` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| description (:obj:`str`, optional): New chat description, 0-255 characters. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -6296,29 +5200,12 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.pin_message`, :attr:`telegram.User.pin_message` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| message_id (:obj:`int`): Identifier of a message to pin. disable_notification (:obj:`bool`, optional): Pass :obj:`True`, if it is not necessary to send a notification to all chat members about the new pinned message. Notifications are always disabled in channels and private chats. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -6364,27 +5251,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. seealso:: :attr:`telegram.Chat.unpin_message`, :attr:`telegram.User.unpin_message` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| message_id (:obj:`int`, optional): Identifier of a message to unpin. If not specified, the most recent pinned message (by sending date) will be unpinned. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -6429,24 +5299,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): :attr:`telegram.User.unpin_all_messages` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). - - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -6482,22 +5335,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Args: name (:obj:`str`): Name of the sticker set. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.StickerSet` @@ -6537,22 +5374,6 @@ class Bot(TelegramObject, AbstractAsyncContextManager): At most :tg-const:`telegram.constants.CustomEmojiStickerLimit.\ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: List[:class:`telegram.Sticker`] @@ -6603,22 +5424,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. File paths as input is also accepted for bots *not* running in :paramref:`~telegram.Bot.local_mode`. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.File`: On success, the uploaded File is returned. @@ -6694,7 +5499,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. :paramref:`~telegram.Bot.local_mode`. tgs_sticker (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, \ optional): **TGS** animation with the sticker. |uploadinput| - See https://core.telegram.org/stickers#animated-sticker-requirements for technical + See https://core.telegram.org/stickers#animation-requirements for technical requirements. .. versionchanged:: 13.2 @@ -6705,7 +5510,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. :paramref:`~telegram.Bot.local_mode`. webm_sticker (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path`,\ optional): **WEBM** video with the sticker. |uploadinput| - See https://core.telegram.org/stickers#video-sticker-requirements for + See https://core.telegram.org/stickers#video-requirements for technical requirements. .. versionadded:: 13.11 @@ -6724,22 +5529,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. .. versionadded:: 20.0 - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -6803,7 +5592,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. Args: user_id (:obj:`int`): User identifier of created sticker set owner. - name (:obj:`str`): Sticker set name. png_sticker (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, \ optional): **PNG** image with the sticker, @@ -6819,7 +5607,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. :paramref:`~telegram.Bot.local_mode`. tgs_sticker (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, \ optional): **TGS** animation with the sticker. |uploadinput| - See https://core.telegram.org/stickers#animated-sticker-requirements for technical + See https://core.telegram.org/stickers#animation-requirements for technical requirements. .. versionchanged:: 13.2 @@ -6830,7 +5618,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. :paramref:`~telegram.Bot.local_mode`. webm_sticker (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path`,\ optional): **WEBM** video with the sticker. |uploadinput| - See https://core.telegram.org/stickers#video-sticker-requirements for + See https://core.telegram.org/stickers#video-requirements for technical requirements. .. versionadded:: 13.11 @@ -6842,22 +5630,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. mask_position (:class:`telegram.MaskPosition`, optional): Position where the mask should be placed on faces. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -6906,22 +5678,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. sticker (:obj:`str`): File identifier of the sticker. position (:obj:`int`): New sticker position in the set, zero-based. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -6957,22 +5713,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. Args: sticker (:obj:`str`): File identifier of the sticker. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -7016,10 +5756,10 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. optional): A **PNG** image with the thumbnail, must be up to 128 kilobytes in size and have width and height exactly 100px, or a **TGS** animation with the thumbnail up to 32 kilobytes in size; see - https://core.telegram.org/stickers#animated-sticker-requirements for animated + https://core.telegram.org/stickers#animation-requirements for animated sticker technical requirements, or a **WEBM** video with the thumbnail up to 32 kilobytes in size; see - https://core.telegram.org/stickers#video-sticker-requirements for video sticker + https://core.telegram.org/stickers#video-requirements for video sticker technical requirements. |fileinput| Animated sticker set thumbnails can't be uploaded via HTTP URL. @@ -7027,22 +5767,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. .. versionchanged:: 13.2 Accept :obj:`bytes` as input. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -7090,24 +5814,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. Args: user_id (:obj:`int`): User identifier - errors (List[:class:`PassportElementError`]): An array describing the - errors. - - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. + errors (List[:class:`PassportElementError`]): A list describing the errors. Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -7163,8 +5870,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. :attr:`telegram.User.send_poll` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| question (:obj:`str`): Poll question, 1-:tg-const:`telegram.Poll.MAX_QUESTION_LENGTH` characters. options (List[:obj:`str`]): List of answer options, @@ -7198,38 +5904,17 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. used. is_closed (:obj:`bool`, optional): Pass :obj:`True`, if the poll needs to be immediately closed. This can be useful for poll preview. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -7297,28 +5982,11 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. .. seealso:: :attr:`telegram.Message.stop_poll` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| message_id (:obj:`int`): Identifier of the original message with the poll. reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): An object for a new message inline keyboard. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.Poll`: On success, the stopped Poll is returned. @@ -7366,12 +6034,9 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. :attr:`telegram.User.send_dice` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| + disable_notification (:obj:`bool`, optional): |disable_notification| + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply @@ -7388,29 +6053,11 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. .. versionchanged:: 13.4 Added the :tg-const:`telegram.constants.DiceEmoji.BOWLING` emoji.. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.Message`: On success, the sent Message is returned. @@ -7459,22 +6106,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. rights of the bot in channels. Otherwise, default administrator rights of the bot for groups and supergroups will be returned. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.ChatAdministratorRights`: On success. @@ -7526,22 +6157,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. administrator rights of the bot in channels. Otherwise, the default administrator rights of the bot for groups and supergroups will be changed. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: Returns :obj:`True` on success. @@ -7595,22 +6210,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. .. versionadded:: 13.7 - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: List[:class:`telegram.BotCommand`]: On success, the commands set for the bot. An empty list is returned if commands are not set. @@ -7654,8 +6253,8 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. ) -> bool: """ Use this method to change the list of the bot's commands. See the - `Telegram docs `_ for more details about bot - commands. + `Telegram docs `_ for more details about + bot commands. Args: commands (List[:class:`BotCommand` | (:obj:`str`, :obj:`str`)]): A list @@ -7673,22 +6272,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. .. versionadded:: 13.7 - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -7745,22 +6328,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. commands will be applied to all users from the given scope, for whose language there are no dedicated commands. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -7804,24 +6371,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. local server, but will not be able to log in back to the cloud Bot API server for 10 minutes. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - - .. versionadded:: 20.0 - Returns: :obj:`True`: On success @@ -7854,22 +6403,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. isn't launched again after server restart. The method will return error 429 in the first 10 minutes after the bot is launched. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`True`: On success @@ -7917,8 +6450,7 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. :attr:`telegram.User.copy_message` Args: - chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username - of the target channel (in the format ``@channelusername``). + chat_id (:obj:`int` | :obj:`str`): |chat_id_channel| from_chat_id (:obj:`int` | :obj:`str`): Unique identifier for the chat where the original message was sent (or channel username in the format ``@channelusername``). message_id (:obj:`int`): Message identifier in the chat specified in from_chat_id. @@ -7927,41 +6459,18 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. entities parsing. If not specified, the original caption is kept. parse_mode (:obj:`str`, optional): Mode for parsing entities in the new caption. See the constants in :class:`telegram.constants.ParseMode` for the available modes. - caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special - entities that appear in the new caption, which can be specified instead - of parse_mode. - disable_notification (:obj:`bool`, optional): Sends the message silently. Users will - receive a notification with no sound. - protect_content (:obj:`bool`, optional): Protects the contents of the sent message from - forwarding and saving. + caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities| + disable_notification (:obj:`bool`, optional): |disable_notification| + protect_content (:obj:`bool`, optional): |protect_content| .. versionadded:: 13.10 - - reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the - original message. - allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message - should be sent even if the specified replied-to message is not found. + reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id| + allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply| reply_markup (:class:`InlineKeyboardMarkup` | :class:`ReplyKeyboardMarkup` | \ :class:`ReplyKeyboardRemove` | :class:`ForceReply`, optional): Additional interface options. An object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.MessageId`: On success @@ -8025,22 +6534,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. menu_button (:class:`telegram.MenuButton`, optional): An object for the new bot's menu button. Defaults to :class:`telegram.MenuButtonDefault`. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -8085,22 +6578,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. chat_id (:obj:`int`, optional): Unique identifier for the target private chat. If not specified, default bot's menu button will be returned. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`telegram.MenuButton`: On success, the current menu button is returned. @@ -8206,22 +6683,6 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified. is_flexible (:obj:`bool`, optional): Pass :obj:`True`, if the final price depends on the shipping method. - Keyword Args: - read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to - :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to - :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. - api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the - Telegram API. - Returns: :class:`str`: On success, the created invoice link is returned. diff --git a/telegram/_botcommandscope.py b/telegram/_botcommandscope.py index c0686b91d..e04af64b2 100644 --- a/telegram/_botcommandscope.py +++ b/telegram/_botcommandscope.py @@ -182,12 +182,11 @@ class BotCommandScopeChat(BotCommandScope): .. versionadded:: 13.7 Args: - chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the - target supergroup (in the format ``@supergroupusername``) + chat_id (:obj:`str` | :obj:`int`): |chat_id_group| + Attributes: type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT`. - chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the - target supergroup (in the format ``@supergroupusername``) + chat_id (:obj:`str` | :obj:`int`): |chat_id_group| """ __slots__ = ("chat_id",) @@ -210,12 +209,10 @@ class BotCommandScopeChatAdministrators(BotCommandScope): .. versionadded:: 13.7 Args: - chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the - target supergroup (in the format ``@supergroupusername``) + chat_id (:obj:`str` | :obj:`int`): |chat_id_group| Attributes: type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT_ADMINISTRATORS`. - chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the - target supergroup (in the format ``@supergroupusername``) + chat_id (:obj:`str` | :obj:`int`): |chat_id_group| """ __slots__ = ("chat_id",) @@ -238,14 +235,12 @@ class BotCommandScopeChatMember(BotCommandScope): .. versionadded:: 13.7 Args: - chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the - target supergroup (in the format ``@supergroupusername``) + chat_id (:obj:`str` | :obj:`int`): |chat_id_group| user_id (:obj:`int`): Unique identifier of the target user. Attributes: type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT_MEMBER`. - chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the - target supergroup (in the format ``@supergroupusername``) + chat_id (:obj:`str` | :obj:`int`): |chat_id_group| user_id (:obj:`int`): Unique identifier of the target user. """ diff --git a/telegram/_chat.py b/telegram/_chat.py index 03b961624..296a32cc4 100644 --- a/telegram/_chat.py +++ b/telegram/_chat.py @@ -149,21 +149,28 @@ class Chat(TelegramObject): .. versionadded:: 20.0 Attributes: - id (:obj:`int`): Unique identifier for this chat. - type (:obj:`str`): Type of chat. + id (:obj:`int`): Unique identifier for this chat. This number may be greater than 32 bits + and some programming languages may have difficulty/silent defects in interpreting it. + But it is smaller than 52 bits, so a signed 64-bit integer or double-precision float + type are safe for storing this identifier. + type (:obj:`str`): Type of chat, can be either :attr:`PRIVATE`, :attr:`GROUP`, + :attr:`SUPERGROUP` or :attr:`CHANNEL`. title (:obj:`str`): Optional. Title, for supergroups, channels and group chats. - username (:obj:`str`): Optional. Username. + username (:obj:`str`): Optional. Username, for private chats, supergroups and channels if + available. first_name (:obj:`str`): Optional. First name of the other party in a private chat. last_name (:obj:`str`): Optional. Last name of the other party in a private chat. photo (:class:`telegram.ChatPhoto`): Optional. Chat photo. + Returned only in :meth:`telegram.Bot.get_chat`. bio (:obj:`str`): Optional. Bio of the other party in a private chat. Returned only in :meth:`telegram.Bot.get_chat`. has_private_forwards (:obj:`bool`): Optional. :obj:`True`, if privacy settings of the other party in the private chat allows to use ``tg://user?id=`` links only in chats - with the user. + with the user. Returned only in :meth:`telegram.Bot.get_chat`. .. versionadded:: 13.9 description (:obj:`str`): Optional. Description, for groups, supergroups and channel chats. + Returned only in :meth:`telegram.Bot.get_chat`. invite_link (:obj:`str`): Optional. Primary invite link, for groups, supergroups and channel. Returned only in :meth:`telegram.Bot.get_chat`. pinned_message (:class:`telegram.Message`): Optional. The most recent pinned message @@ -179,12 +186,13 @@ class Chat(TelegramObject): .. versionadded:: 13.4 has_protected_content (:obj:`bool`): Optional. :obj:`True`, if messages from the chat can't - be forwarded to other chats. + be forwarded to other chats. Returned only in :meth:`telegram.Bot.get_chat`. .. versionadded:: 13.9 sticker_set_name (:obj:`str`): Optional. For supergroups, name of Group sticker set. + Returned only in :meth:`telegram.Bot.get_chat`. can_set_sticker_set (:obj:`bool`): Optional. :obj:`True`, if the bot can change group the - sticker set. + sticker set. Returned only in :meth:`telegram.Bot.get_chat`. linked_chat_id (:obj:`int`): Optional. Unique identifier for the linked chat, i.e. the discussion group identifier for a channel and vice versa; for supergroups and channel chats. Returned only in :meth:`telegram.Bot.get_chat`. diff --git a/telegram/_chatmember.py b/telegram/_chatmember.py index 69d0a00cd..363009af6 100644 --- a/telegram/_chatmember.py +++ b/telegram/_chatmember.py @@ -44,7 +44,8 @@ class ChatMember(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`user` and :attr:`status` are equal. - .. seealso:: `Chat Member Example `_ + Examples: + :any:`Chat Member Bot ` .. versionchanged:: 20.0 diff --git a/telegram/_chatmemberupdated.py b/telegram/_chatmemberupdated.py index 39344d702..c497318a9 100644 --- a/telegram/_chatmemberupdated.py +++ b/telegram/_chatmemberupdated.py @@ -44,6 +44,9 @@ class ChatMemberUpdated(TelegramObject): Note: In Python :keyword:`from` is a reserved word use :paramref:`from_user` instead. + Examples: + :any:`Chat Member Bot ` + Args: chat (:class:`telegram.Chat`): Chat the user belongs to. from_user (:class:`telegram.User`): Performer of the action, which resulted in the change. diff --git a/telegram/_inline/inlinekeyboardbutton.py b/telegram/_inline/inlinekeyboardbutton.py index 145766ce8..efa18d915 100644 --- a/telegram/_inline/inlinekeyboardbutton.py +++ b/telegram/_inline/inlinekeyboardbutton.py @@ -62,9 +62,11 @@ class InlineKeyboardButton(TelegramObject): * After Bot API 6.1, only ``HTTPS`` links will be allowed in :paramref:`login_url`. - .. seealso:: `Inline Keyboard Example 1 `_, - `Inline Keyboard Example 2 `_, - :class:`telegram.InlineKeyboardMarkup` + Examples: + * :any:`Inline Keyboard 1 ` + * :any:`Inline Keyboard 2 ` + + .. seealso:: :class:`telegram.InlineKeyboardMarkup` .. versionchanged:: 20.0 :attr:`web_app` is considered as well when comparing objects of this type in terms of @@ -90,6 +92,9 @@ class InlineKeyboardButton(TelegramObject): Tip: The value entered here will be available in :attr:`telegram.CallbackQuery.data`. + .. seealso:: `Arbitrary callback_data `_ + web_app (:obj:`telegram.WebAppInfo`, optional): 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 diff --git a/telegram/_inline/inlinekeyboardmarkup.py b/telegram/_inline/inlinekeyboardmarkup.py index 5ee25ecf3..9fb6d4ee1 100644 --- a/telegram/_inline/inlinekeyboardmarkup.py +++ b/telegram/_inline/inlinekeyboardmarkup.py @@ -36,8 +36,9 @@ class InlineKeyboardMarkup(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their size of :attr:`inline_keyboard` and all the buttons are equal. - .. seealso:: `Inline Keyboard Example 1 `_, - `Inline Keyboard Example 2 `_ + Examples: + * :any:`Inline Keyboard 1 ` + * :any:`Inline Keyboard 2 ` Args: inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): List of button rows, diff --git a/telegram/_inline/inlinequeryresult.py b/telegram/_inline/inlinequeryresult.py index e6ce5fc92..53cae76f4 100644 --- a/telegram/_inline/inlinequeryresult.py +++ b/telegram/_inline/inlinequeryresult.py @@ -33,6 +33,9 @@ class InlineQueryResult(TelegramObject): All URLs passed in inline query results will be available to end users and therefore must be assumed to be *public*. + Examples: + :any:`Inline Bot ` + Args: type (:obj:`str`): Type of the result. id (:obj:`str`): Unique identifier for this result, 1-64 Bytes. diff --git a/telegram/_inline/inlinequeryresultarticle.py b/telegram/_inline/inlinequeryresultarticle.py index 116065ab1..61cd22913 100644 --- a/telegram/_inline/inlinequeryresultarticle.py +++ b/telegram/_inline/inlinequeryresultarticle.py @@ -32,7 +32,8 @@ if TYPE_CHECKING: class InlineQueryResultArticle(InlineQueryResult): """This object represents a Telegram InlineQueryResultArticle. - .. seealso:: `Inline Example `_ + Examples: + :any:`Inline Bot ` Args: id (:obj:`str`): Unique identifier for this result, 1-64 Bytes. diff --git a/telegram/_inline/inputtextmessagecontent.py b/telegram/_inline/inputtextmessagecontent.py index c106cb2d6..76fee9152 100644 --- a/telegram/_inline/inputtextmessagecontent.py +++ b/telegram/_inline/inputtextmessagecontent.py @@ -33,7 +33,8 @@ class InputTextMessageContent(InputMessageContent): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`message_text` is equal. - .. seealso:: `Inline Example `_ + Examples: + :any:`Inline Bot ` Args: message_text (:obj:`str`): Text of the message to be sent, diff --git a/telegram/_keyboardbuttonpolltype.py b/telegram/_keyboardbuttonpolltype.py index 2cc010f39..ae7838980 100644 --- a/telegram/_keyboardbuttonpolltype.py +++ b/telegram/_keyboardbuttonpolltype.py @@ -29,7 +29,8 @@ class KeyboardButtonPollType(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`type` is equal. - .. seealso:: `Pollbot Example `_ + Examples: + :any:`Poll Bot ` Attributes: type (:obj:`str`): Optional. If :tg-const:`telegram.Poll.QUIZ` is passed, the user will be diff --git a/telegram/_message.py b/telegram/_message.py index 60a14b3f3..9aad571c8 100644 --- a/telegram/_message.py +++ b/telegram/_message.py @@ -104,7 +104,7 @@ class Message(TelegramObject): sent to channels. For backward compatibility, this will contain a fake sender user in non-channel chats, if the message was sent on behalf of a chat. sender_chat (:class:`telegram.Chat`, optional): Sender of the message, sent on behalf of a - chat. For example, the channel itself for channel posts, the supergroup itself for + chat. For example, the channel itself for channel posts, the supergroup itself for messages from anonymous group administrators, the linked channel for messages automatically forwarded to the discussion group. For backward compatibility, :attr:`from_user` contains a fake sender user in non-channel chats, if the message was @@ -118,15 +118,17 @@ class Message(TelegramObject): or from anonymous administrators, information about the original sender chat. forward_from_message_id (:obj:`int`, optional): For forwarded channel posts, identifier of the original message in the channel. - 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. + 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. forward_date (:class:`datetime.datetime`, optional): For forwarded messages, date the original message was sent in Unix time. Converted to :class:`datetime.datetime`. - is_automatic_forward (:obj:`bool`, optional): :obj:`True`, if the message is a channel post - that was automatically forwarded to the connected discussion group. + is_automatic_forward (:obj:`bool`, optional): :obj:`True`, if the message is a channel + post that was automatically forwarded to the connected discussion group. .. versionadded:: 13.9 reply_to_message (:class:`telegram.Message`, optional): For replies, the original message. + Note that the Message object in this field will not contain further + ``reply_to_message`` fields even if it itself is a reply. edit_date (:class:`datetime.datetime`, optional): Date the message was last edited in Unix time. Converted to :class:`datetime.datetime`. has_protected_content (:obj:`bool`, optional): :obj:`True`, if the message can't be @@ -136,15 +138,16 @@ class Message(TelegramObject): media_group_id (:obj:`str`, optional): The unique identifier of a media message group this message belongs to. text (:obj:`str`, optional): For text messages, the actual UTF-8 text of the message, - 0-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` - characters. + 0-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters. entities (List[:class:`telegram.MessageEntity`], optional): For text messages, special entities like usernames, URLs, bot commands, etc. that appear in the text. See :attr:`parse_entity` and :attr:`parse_entities` methods for how to use properly. + This list is empty if the message does not contain entities. caption_entities (List[:class:`telegram.MessageEntity`], optional): For messages with a Caption. Special entities like usernames, URLs, bot commands, etc. that appear in the caption. See :attr:`Message.parse_caption_entity` and :attr:`parse_caption_entities` - methods for how to use properly. + methods for how to use properly. This list is empty if the message does not contain + caption entities. audio (:class:`telegram.Audio`, optional): Message is an audio file, information about the file. document (:class:`telegram.Document`, optional): Message is a general file, information @@ -153,32 +156,33 @@ class Message(TelegramObject): about the animation. For backward compatibility, when this field is set, the document field will also be set. game (:class:`telegram.Game`, optional): Message is a game, information about the game. - photo (List[:class:`telegram.PhotoSize`], optional): Message is a photo, available - sizes of the photo. + photo (List[: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. sticker (:class:`telegram.Sticker`, optional): Message is a sticker, information about the sticker. - video (:class:`telegram.Video`, optional): Message is a video, information about the video. + video (:class:`telegram.Video`, optional): Message is a video, information about the + video. voice (:class:`telegram.Voice`, optional): Message is a voice message, information about the file. video_note (:class:`telegram.VideoNote`, optional): Message is a video note, information about the video message. new_chat_members (List[: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). + members). This list is empty if the message does not contain new chat members. 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 about the contact. location (:class:`telegram.Location`, optional): Message is a shared location, information about the location. - venue (:class:`telegram.Venue`, optional): Message is a venue, information about the venue. - For backward compatibility, when this field is set, the location field will also be - set. + venue (:class:`telegram.Venue`, optional): Message is a venue, information about the + venue. For backward compatibility, when this field is set, the location field will + also be set. left_chat_member (:class:`telegram.User`, optional): A member was removed from the group, information about them (this member may be the bot itself). new_chat_title (:obj:`str`, optional): A chat title was changed to this value. new_chat_photo (List[:class:`telegram.PhotoSize`], optional): A chat photo was changed to - this value. + this value. This list is empty if the message does not contain a new chat photo. delete_chat_photo (:obj:`bool`, optional): Service message: The chat photo was deleted. group_chat_created (:obj:`bool`, optional): Service message: The group has been created. supergroup_chat_created (:obj:`bool`, optional): Service message: The supergroup has been @@ -194,19 +198,13 @@ class Message(TelegramObject): optional): Service message: auto-delete timer settings changed in the chat. .. versionadded:: 13.4 - migrate_to_chat_id (:obj:`int`, optional): The group has been migrated to a supergroup with - the specified identifier. This number may be greater than 32 bits and some programming - languages may have difficulty/silent defects in interpreting it. But it is smaller than - 52 bits, so a signed 64 bit integer or double-precision float type are safe for storing - this identifier. + migrate_to_chat_id (:obj:`int`, optional): The group has been migrated to a supergroup + with the specified identifier. migrate_from_chat_id (:obj:`int`, optional): The supergroup has been migrated from a group - with the specified identifier. This number may be greater than 32 bits and some - programming languages may have difficulty/silent defects in interpreting it. But it is - smaller than 52 bits, so a signed 64 bit integer or double-precision float type are - safe for storing this identifier. + with the specified identifier. pinned_message (:class:`telegram.Message`, optional): Specified message was pinned. Note - that the Message object in this field will not contain further :attr:`reply_to_message` - fields even if it is itself a reply. + that the Message object in this field will not contain further + :attr:`reply_to_message` fields even if it is itself a reply. invoice (:class:`telegram.Invoice`, optional): Message is an invoice for a payment, information about the invoice. successful_payment (:class:`telegram.SuccessfulPayment`, optional): Message is a service @@ -215,13 +213,15 @@ class Message(TelegramObject): has logged in. forward_signature (:obj:`str`, optional): For messages forwarded from channels, signature of the post author if present. - author_signature (:obj:`str`, optional): Signature of the post author for messages in + 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. - dice (:class:`telegram.Dice`, optional): Message is a dice with random value from 1 to 6. - via_bot (:class:`telegram.User`, optional): Message was sent through an inline bot. + dice (:class:`telegram.Dice`, optional): Message is a dice with random value. + via_bot (:class:`telegram.User`, optional): Bot through which message was sent. proximity_alert_triggered (:class:`telegram.ProximityAlertTriggered`, optional): Service message. A user in the chat triggered another user's proximity alert while sharing Live Location. @@ -246,7 +246,8 @@ class Message(TelegramObject): .. versionadded:: 20.0 reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached - to the message. ``login_url`` buttons are represented as ordinary url buttons. + to the message. :paramref:`~telegram.InlineKeyboardButton.login_url` buttons are + represented as ordinary url buttons. Attributes: message_id (:obj:`int`): Unique message identifier inside this chat. @@ -254,94 +255,125 @@ class Message(TelegramObject): sent to channels. For backward compatibility, this will contain a fake sender user in non-channel chats, if the message was sent on behalf of a chat. sender_chat (:class:`telegram.Chat`): Optional. Sender of the message, sent on behalf of a - chat. For backward compatibility, :attr:`from_user` contains a fake sender user in - non-channel chats, if the message was sent on behalf of a chat. - date (:class:`datetime.datetime`): Date the message was sent. + chat. For example, the channel itself for channel posts, the supergroup itself for + messages from anonymous group administrators, the linked channel for messages + automatically forwarded to the discussion group. For backward compatibility, + :attr:`from_user` contains a fake sender user in non-channel chats, if the message was + sent on behalf of a chat. + date (:class:`datetime.datetime`): Date the message was sent in Unix time. Converted to + :class:`datetime.datetime`. chat (:class:`telegram.Chat`): Conversation the message belongs to. - forward_from (:class:`telegram.User`): Optional. Sender of the original message. + forward_from (:class:`telegram.User`): Optional. For forwarded messages, sender of the + original message. forward_from_chat (:class:`telegram.Chat`): Optional. For messages forwarded from channels or from anonymous administrators, information about the original sender chat. - forward_from_message_id (:obj:`int`): Optional. Identifier of the original message in the - channel. - forward_date (:class:`datetime.datetime`): Optional. Date the original message was sent. - is_automatic_forward (:obj:`bool`): Optional. :obj:`True`, if the message is a channel post - that was automatically forwarded to the connected discussion group. + forward_from_message_id (:obj:`int`): Optional. For forwarded channel posts, identifier of + the original message in the channel. + forward_date (:class:`datetime.datetime`): Optional. For forwarded messages, date the + original message was sent in Unix time. Converted to :class:`datetime.datetime`. + is_automatic_forward (:obj:`bool`): Optional. :obj:`True`, if the message is a channel + post that was automatically forwarded to the connected discussion group. .. versionadded:: 13.9 reply_to_message (:class:`telegram.Message`): Optional. For replies, the original message. Note that the Message object in this field will not contain further ``reply_to_message`` fields even if it itself is a reply. - edit_date (:class:`datetime.datetime`): Optional. Date the message was last edited. + edit_date (:class:`datetime.datetime`): Optional. Date the message was last edited in Unix + time. Converted to :class:`datetime.datetime`. has_protected_content (:obj:`bool`): Optional. :obj:`True`, if the message can't be forwarded. .. versionadded:: 13.9 media_group_id (:obj:`str`): Optional. The unique identifier of a media message group this message belongs to. - text (:obj:`str`): Optional. The actual UTF-8 text of the message. - entities (List[:class:`telegram.MessageEntity`]): Special entities like - usernames, URLs, bot commands, etc. that appear in the text. See - :attr:`Message.parse_entity` and :attr:`parse_entities` methods for how to use - properly. This list is empty if the message does not contain entities. - caption_entities (List[:class:`telegram.MessageEntity`]): Special entities like - usernames, URLs, bot commands, etc. that appear in the caption. See - :attr:`Message.parse_caption_entity` and :attr:`parse_caption_entities` methods for how - to use properly. This list is empty if the message does not contain caption entities. - audio (:class:`telegram.Audio`): Optional. Information about the file. - document (:class:`telegram.Document`): Optional. Information about the file. - animation (:class:`telegram.Animation`) Optional. Information about the file. - For backward compatibility, when this field is set, the document field will also be - set. - game (:class:`telegram.Game`): Optional. Information about the game. - photo (List[:class:`telegram.PhotoSize`]): Available sizes of the photo. - This list is empty if the message does not contain a photo. - sticker (:class:`telegram.Sticker`): Optional. Information about the sticker. - video (:class:`telegram.Video`): Optional. Information about the video. - voice (:class:`telegram.Voice`): Optional. Information about the file. - video_note (:class:`telegram.VideoNote`): Optional. Information about the video message. - new_chat_members (List[:class:`telegram.User`]): Information about new members to - the chat. The bot itself may be one of these members. - This list is empty if the message does not contain new chat members. - caption (:obj:`str`): Optional. Caption for the document, photo or video, - 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` - characters. - contact (:class:`telegram.Contact`): Optional. Information about the contact. - location (:class:`telegram.Location`): Optional. Information about the location. - venue (:class:`telegram.Venue`): Optional. Information about the venue. - left_chat_member (:class:`telegram.User`): Optional. Information about the user that left - the group. (this member may be the bot itself). + text (:obj:`str`): Optional. For text messages, the actual UTF-8 text of the message, + 0-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters. + entities (List[:class:`telegram.MessageEntity`]): Optional. For text messages, special + entities like usernames, URLs, bot commands, etc. that appear in the text. See + :attr:`parse_entity` and :attr:`parse_entities` methods for how to use properly. + This list is empty if the message does not contain entities. + caption_entities (List[:class:`telegram.MessageEntity`]): Optional. For messages with a + Caption. Special entities like usernames, URLs, bot commands, etc. that appear in the + caption. See :attr:`Message.parse_caption_entity` and :attr:`parse_caption_entities` + methods for how to use properly. This list is empty if the message does not contain + caption entities. + audio (:class:`telegram.Audio`): Optional. Message is an audio file, information + about the file. + document (:class:`telegram.Document`): Optional. Message is a general file, information + about the file. + 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. + game (:class:`telegram.Game`): Optional. Message is a game, information about the game. + photo (List[: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. + sticker (:class:`telegram.Sticker`): Optional. Message is a sticker, information + about the sticker. + video (:class:`telegram.Video`): Optional. Message is a video, information about the + video. + voice (:class:`telegram.Voice`): Optional. Message is a voice message, information about + the file. + video_note (:class:`telegram.VideoNote`): Optional. Message is a video note, information + about the video message. + new_chat_members (List[: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. + 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 + about the contact. + location (:class:`telegram.Location`): Optional. Message is a shared location, information + about the location. + venue (:class:`telegram.Venue`): Optional. Message is a venue, information about the + venue. For backward compatibility, when this field is set, the location field will + also be set. + left_chat_member (:class:`telegram.User`): Optional. A member was removed from the group, + information about them (this member may be the bot itself). new_chat_title (:obj:`str`): Optional. A chat title was changed to this value. new_chat_photo (List[:class:`telegram.PhotoSize`]): A chat photo was changed to this value. This list is empty if the message does not contain a new chat photo. - delete_chat_photo (:obj:`bool`): Optional. The chat photo was deleted. - group_chat_created (:obj:`bool`): Optional. The group has been created. - supergroup_chat_created (:obj:`bool`): Optional. The supergroup has been created. - channel_chat_created (:obj:`bool`): Optional. The channel has been created. + delete_chat_photo (:obj:`bool`): Optional. Service message: The chat photo was deleted. + group_chat_created (:obj:`bool`): Optional. Service message: The group has been created. + supergroup_chat_created (:obj:`bool`): Optional. Service message: The supergroup has been + created. This field can't be received in a message coming through updates, because bot + can't be a member of a supergroup when it is created. It can only be found in + :attr:`reply_to_message` if someone replies to a very first message in a directly + created supergroup. + channel_chat_created (:obj:`bool`): Optional. Service message: The channel has been + created. This field can't be received in a message coming through updates, because bot + can't be a member of a channel when it is created. It can only be found in + :attr:`reply_to_message` if someone replies to a very first message in a channel. message_auto_delete_timer_changed (:class:`telegram.MessageAutoDeleteTimerChanged`): Optional. Service message: auto-delete timer settings changed in the chat. .. versionadded:: 13.4 - migrate_to_chat_id (:obj:`int`): Optional. The group has been migrated to a supergroup with - the specified identifier. + migrate_to_chat_id (:obj:`int`): Optional. The group has been migrated to a supergroup + with the specified identifier. migrate_from_chat_id (:obj:`int`): Optional. The supergroup has been migrated from a group with the specified identifier. - pinned_message (:class:`telegram.Message`): Optional. Specified message was pinned. - invoice (:class:`telegram.Invoice`): Optional. Information about the invoice. - successful_payment (:class:`telegram.SuccessfulPayment`): Optional. Information about the - payment. + pinned_message (:class:`telegram.Message`): Optional. Specified message was pinned. Note + that the Message object in this field will not contain further + :attr:`reply_to_message` fields even if it is itself a reply. + invoice (:class:`telegram.Invoice`): Optional. Message is an invoice for a payment, + information about the invoice. + successful_payment (:class:`telegram.SuccessfulPayment`): Optional. Message is a service + message about a successful payment, information about the payment. connected_website (:obj:`str`): Optional. The domain name of the website on which the user has logged in. - forward_signature (:obj:`str`): Optional. Signature of the post author for messages - forwarded from channels. - 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. + forward_signature (:obj:`str`): Optional. For messages forwarded from channels, signature + 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. + + Examples: + :any:`Passport Bot ` poll (:class:`telegram.Poll`): Optional. Message is a native poll, information about the poll. - dice (:class:`telegram.Dice`): Optional. Message is a dice. - via_bot (:class:`telegram.User`): Optional. Bot through which the message was sent. + dice (:class:`telegram.Dice`): Optional. Message is a dice with random value. + via_bot (:class:`telegram.User`): Optional. Bot through which message was sent. proximity_alert_triggered (:class:`telegram.ProximityAlertTriggered`): Optional. Service message. A user in the chat triggered another user's proximity alert while sharing Live Location. @@ -366,7 +398,8 @@ class Message(TelegramObject): .. versionadded:: 20.0 reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached - to the message. + to the message. :paramref:`~telegram.InlineKeyboardButton.login_url` buttons are + represented as ordinary url buttons. .. |custom_emoji_formatting_note| replace:: Custom emoji entities will currently be ignored by this function. Instead, the supplied replacement for the emoji will be used. @@ -700,7 +733,7 @@ class Message(TelegramObject): * :class:`telegram.VideoNote` * :class:`telegram.Voice` - Otherwise :obj:`None` is returned. + Otherwise :obj:`None` is returned. .. versionchanged:: 20.0 :attr:`dice`, :attr:`passport_data` and :attr:`poll` are now also considered to be an @@ -3086,10 +3119,11 @@ class Message(TelegramObject): in the same way the original message was formatted. Note: - :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by - Telegram for backward compatibility. You should use :meth:`text_markdown_v2` instead. + * :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by + Telegram for backward compatibility. You should use + :meth:`text_markdown_v2` instead. - |custom_emoji_formatting_note| + * |custom_emoji_formatting_note| Returns: :obj:`str`: Message text with entities formatted as Markdown. @@ -3129,11 +3163,11 @@ class Message(TelegramObject): This also formats :attr:`telegram.MessageEntity.URL` as a hyperlink. Note: - :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by - Telegram for backward compatibility. You should use :meth:`text_markdown_v2_urled` - instead. + * :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by + Telegram for backward compatibility. You should use :meth:`text_markdown_v2_urled` + instead. - |custom_emoji_formatting_note| + * |custom_emoji_formatting_note| Returns: :obj:`str`: Message text with entities formatted as Markdown. @@ -3173,11 +3207,11 @@ class Message(TelegramObject): Markdown in the same way the original message was formatted. Note: - :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by - Telegram for backward compatibility. You should use :meth:`caption_markdown_v2` - instead. + * :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by + Telegram for backward compatibility. You should use :meth:`caption_markdown_v2` + instead. - |custom_emoji_formatting_note| + * |custom_emoji_formatting_note| Returns: :obj:`str`: Message caption with caption entities formatted as Markdown. @@ -3219,11 +3253,11 @@ class Message(TelegramObject): Markdown. This also formats :attr:`telegram.MessageEntity.URL` as a hyperlink. Note: - :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by - Telegram for backward compatibility. You should use :meth:`caption_markdown_v2_urled` - instead. + * :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by + Telegram for backward compatibility. You should use + :meth:`caption_markdown_v2_urled` instead. - |custom_emoji_formatting_note| + * |custom_emoji_formatting_note| Returns: :obj:`str`: Message caption with caption entities formatted as Markdown. diff --git a/telegram/_messageentity.py b/telegram/_messageentity.py index 9fcbd33c6..72438b1aa 100644 --- a/telegram/_messageentity.py +++ b/telegram/_messageentity.py @@ -63,13 +63,26 @@ class MessageEntity(TelegramObject): .. versionadded:: 20.0 Attributes: - type (:obj:`str`): Type of the entity. + type (:obj:`str`): Type of the entity. Can be :attr:`MENTION` (@username), + :attr:`HASHTAG`, :attr:`BOT_COMMAND`, + :attr:`URL`, :attr:`EMAIL`, :attr:`PHONE_NUMBER`, :attr:`BOLD` (bold text), + :attr:`ITALIC` (italic text), :attr:`STRIKETHROUGH`, :attr:`SPOILER` (spoiler message), + :attr:`CODE` (monowidth string), :attr:`PRE` (monowidth block), :attr:`TEXT_LINK` (for + clickable text URLs), :attr:`TEXT_MENTION` (for users without usernames), + :attr:`CUSTOM_EMOJI` (for inline custom emoji stickers). + + .. versionadded:: 20.0 + 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. Url that will be opened after user taps on the text. + 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. Programming language of the entity text. - custom_emoji_id (:obj:`str`): Optional. Unique identifier of the custom emoji. + 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 + information about the sticker. .. versionadded:: 20.0 diff --git a/telegram/_payment/labeledprice.py b/telegram/_payment/labeledprice.py index 73d165031..91811ca10 100644 --- a/telegram/_payment/labeledprice.py +++ b/telegram/_payment/labeledprice.py @@ -28,7 +28,8 @@ class LabeledPrice(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`label` and :attr:`amount` are equal. - .. seealso:: `Paymentbot Example `_ + Examples: + :any:`Payment Bot ` Args: label (:obj:`str`): Portion label. diff --git a/telegram/_payment/shippingoption.py b/telegram/_payment/shippingoption.py index 667cb82f6..e4275ad1c 100644 --- a/telegram/_payment/shippingoption.py +++ b/telegram/_payment/shippingoption.py @@ -33,7 +33,8 @@ class ShippingOption(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`id` is equal. - .. seealso:: `Paymentbot Example `_ + Examples: + :any:`Payment Bot ` Args: id (:obj:`str`): Shipping option identifier. diff --git a/telegram/_poll.py b/telegram/_poll.py index 8a8854854..684bc0bba 100644 --- a/telegram/_poll.py +++ b/telegram/_poll.py @@ -116,7 +116,8 @@ class Poll(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`id` is equal. - .. seealso:: `Pollbot Example `_ + Examples: + :any:`Poll Bot ` Args: id (:obj:`str`): Unique poll identifier. @@ -126,13 +127,17 @@ class Poll(TelegramObject): is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous. type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`. allows_multiple_answers (:obj:`bool`): :obj:`True`, if the poll allows multiple answers. - correct_option_id (:obj:`int`, optional): 0-based identifier of the correct answer option. - Available only for polls in the quiz mode, which are closed, or was sent (not - forwarded) by the bot or to the private chat with the bot. + correct_option_id (:obj:`int`, optional): A zero based identifier of the correct answer + option. Available only for closed polls in the quiz mode, which were sent + (not forwarded), by the bot or to a private chat with the bot. explanation (:obj:`str`, optional): Text that is shown when a user chooses an incorrect answer or taps on the lamp icon in a quiz-style poll, 0-200 characters. explanation_entities (List[:class:`telegram.MessageEntity`], optional): Special entities like usernames, URLs, bot commands, etc. that appear in the :attr:`explanation`. + This list is empty if the message does not contain explanation entities. + + .. versionchanged:: 20.0 + This attribute is now always a (possibly empty) list and never :obj:`None`. open_period (:obj:`int`, optional): Amount of time in seconds the poll will be active after creation. close_date (:obj:`datetime.datetime`, optional): Point in time (Unix timestamp) when the @@ -147,9 +152,11 @@ class Poll(TelegramObject): is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous. type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`. allows_multiple_answers (:obj:`bool`): :obj:`True`, if the poll allows multiple answers. - correct_option_id (:obj:`int`): Optional. Identifier of the correct answer option. + correct_option_id (:obj:`int`, optional): A zero based identifier of the correct answer + option. Available only for closed polls in the quiz mode, which were sent + (not forwarded), by the bot or to a private chat with the bot. explanation (:obj:`str`): Optional. Text that is shown when a user chooses an incorrect - answer or taps on the lamp icon in a quiz-style poll. + answer or taps on the lamp icon in a quiz-style poll, 0-200 characters. explanation_entities (List[:class:`telegram.MessageEntity`]): Special entities like usernames, URLs, bot commands, etc. that appear in the :attr:`explanation`. This list is empty if the message does not contain explanation entities. diff --git a/telegram/_replykeyboardmarkup.py b/telegram/_replykeyboardmarkup.py index 97deeae3f..467d505f5 100644 --- a/telegram/_replykeyboardmarkup.py +++ b/telegram/_replykeyboardmarkup.py @@ -32,9 +32,12 @@ class ReplyKeyboardMarkup(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their size of :attr:`keyboard` and all the buttons are equal. - Example: - A user requests to change the bot's language, bot replies to the request with a keyboard - to select the new language. Other users in the group don't see the keyboard. + Examples: + * Example usage: A user requests to change the bot's language, bot replies to the request + with a keyboard to select the new language. Other users in the group don't see + the keyboard. + * :any:`Conversation Bot ` + * :any:`Conversation Bot 2 ` Args: keyboard (List[List[:obj:`str` | :class:`telegram.KeyboardButton`]]): Array of button rows, diff --git a/telegram/_replykeyboardremove.py b/telegram/_replykeyboardremove.py index 57750b2a2..7765c37f7 100644 --- a/telegram/_replykeyboardremove.py +++ b/telegram/_replykeyboardremove.py @@ -29,15 +29,17 @@ class ReplyKeyboardRemove(TelegramObject): until a new keyboard is sent by a bot. An exception is made for one-time keyboards that are hidden immediately after the user presses a button (see :class:`telegram.ReplyKeyboardMarkup`). - Example: - A user votes in a poll, bot returns confirmation message in reply to the vote and removes - the keyboard for that user, while still showing the keyboard with poll options to users who - haven't voted yet. - Note: User will not be able to summon this keyboard; if you want to hide the keyboard from sight but keep it accessible, use :attr:`telegram.ReplyKeyboardMarkup.one_time_keyboard`. + Examples: + * Example usage: A user votes in a poll, bot returns confirmation message in reply to + the vote and removes the keyboard for that user, while still showing the keyboard with + poll options to users who haven't voted yet. + * :any:`Conversation Bot ` + * :any:`Conversation Bot 2 ` + Args: selective (:obj:`bool`, optional): Use this parameter if you want to remove the keyboard for specific users only. Targets: diff --git a/telegram/_telegramobject.py b/telegram/_telegramobject.py index de132940f..a9a31cd3c 100644 --- a/telegram/_telegramobject.py +++ b/telegram/_telegramobject.py @@ -37,20 +37,12 @@ Tele_co = TypeVar("Tele_co", bound="TelegramObject", covariant=True) class TelegramObject: """Base class for most Telegram objects. - Objects of this type are subscriptable with strings, where ``telegram_object[attribute_name]`` - is equivalent to ``telegram_object.attribute_name``. If the object does not have an attribute - with the appropriate name, a :exc:`KeyError` will be raised. - - When objects of this type are pickled, the :class:`~telegram.Bot` attribute associated with the - object will be removed. However, when copying the object via :func:`copy.deepcopy`, the copy - will have the *same* bot instance associated with it, i.e:: - - assert telegram_object.get_bot() is copy.deepcopy(telegram_object).get_bot() + Objects of this type are subscriptable with strings. See :meth:`__getitem__` for more details. + The :mod:`pickle` and :func:`~copy.deepcopy` behavior of objects of this type are defined by + :meth:`__getstate__`, :meth:`__setstate__` and :meth:`__deepcopy__`. .. versionchanged:: 20.0 - * ``telegram_object['from']`` will look up the key ``from_user``. This is to account for - special cases like :attr:`Message.from_user` that deviate from the official Bot API. * Removed argument and attribute ``bot`` for several subclasses. Use :meth:`set_bot` and :meth:`get_bot` instead. * Removed the possibility to pass arbitrary keyword arguments for several subclasses. @@ -108,7 +100,7 @@ class TelegramObject: def __repr__(self) -> str: """Gives a string representation of this object in the form ``ClassName(attr_1=value_1, attr_2=value_2, ...)``, where attributes are omitted if they - have the value :obj:`None` or empty instances of :class:`collections.abc.Sized` (e.g. + have the value :obj:`None` or are empty instances of :class:`collections.abc.Sized` (e.g. :class:`list`, :class:`dict`, :class:`set`, :class:`str`, etc.). As this class doesn't implement :meth:`object.__str__`, the default implementation @@ -141,6 +133,30 @@ class TelegramObject: return f"{self.__class__.__name__}({contents})" def __getitem__(self, item: str) -> object: + """ + Objects of this type are subscriptable with strings, where + ``telegram_object["attribute_name"]`` is equivalent to ``telegram_object.attribute_name``. + + Tip: + This is useful for dynamic attribute lookup, i.e. ``telegram_object[arg]`` where the + value of ``arg`` is determined at runtime. + In all other cases, it's recommended to use the dot notation instead, i.e. + ``telegram_object.attribute_name``. + + .. versionchanged:: 20.0 + + ``telegram_object['from']`` will look up the key ``from_user``. This is to account for + special cases like :attr:`Message.from_user` that deviate from the official Bot API. + + Args: + item (:obj:`str`): The name of the attribute to look up. + + Returns: + :obj:`object` + + Raises: + :exc:`KeyError`: If the object does not have an attribute with the appropriate name. + """ if item == "from": item = "from_user" try: @@ -153,15 +169,28 @@ class TelegramObject: def __getstate__(self) -> Dict[str, Union[str, object]]: """ - This method is used for pickling. We remove the bot attribute of the object since those - are not pickable. + Overrides :meth:`object.__getstate__` to customize the pickling process of objects of this + type. + The returned state does `not` contain the :class:`telegram.Bot` instance set with + :meth:`set_bot` (if any), as it can't be pickled. + + Returns: + state (Dict[:obj:`str`, :obj:`object`]): The state of the object. """ return self._get_attrs(include_private=True, recursive=False, remove_bot=True) def __setstate__(self, state: dict) -> None: """ - This method is used for unpickling. The data, which is in the form a dictionary, is - converted back into a class. Should be modified in place. + Overrides :meth:`object.__setstate__` to customize the unpickling process of objects of + this type. Modifies the object in-place. + If any data was stored in the :attr:`api_kwargs` of the pickled object, this method checks + if the class now has dedicated attributes for those keys and moves the values from + :attr:`api_kwargs` to the dedicated attributes. + This can happen, if serialized data is loaded with a new version of this library, where + the new version was updated to account for updates of the Telegram Bot API. + + Args: + state (:obj:`dict`): The data to set as attributes of this object. """ # Make sure that we have a `_bot` attribute. This is necessary, since __getstate__ omits # this as Bots are not pickable. @@ -172,7 +201,20 @@ class TelegramObject: self._apply_api_kwargs() def __deepcopy__(self: Tele_co, memodict: dict) -> Tele_co: - """This method deepcopies the object and sets the bot on the newly created copy.""" + """ + Customizes how :func:`copy.deepcopy` processes objects of this type. + The only difference to the default implementation is that the :class:`telegram.Bot` + instance set via :meth:`set_bot` (if any) is not copied, but shared between the original + and the copy, i.e.:: + + assert telegram_object.get_bot() is copy.deepcopy(telegram_object).get_bot() + + Args: + memodict (:obj:`dict`): A dictionary that maps objects to their copies. + + Returns: + :obj:`telegram.TelegramObject`: The copied object. + """ bot = self._bot # Save bot so we can set it after copying self.set_bot(None) # set to None so it is not deepcopied cls = self.__class__ @@ -387,6 +429,26 @@ class TelegramObject: self._bot = bot def __eq__(self, other: object) -> bool: + """Compares this object with :paramref:`other` in terms of equality. + If this object and :paramref:`other` are `not` objects of the same class, + this comparison will fall back to Python's default implementation of :meth:`object.__eq__`. + Otherwise, both objects may be compared in terms of equality, if the corresponding + subclass of :class:`TelegramObject` has defined a set of attributes to compare and + the objects are considered to be equal, if all of these attributes are equal. + If the subclass has not defined a set of attributes to compare, a warning will be issued. + + Tip: + If instances of a class in the :mod:`telegram` module are comparable in terms of + equality, the documentation of the class will state the attributes that will be used + for this comparison. + + Args: + other (:obj:`object`): The object to compare with. + + Returns: + :obj:`bool` + + """ if isinstance(other, self.__class__): if not self._id_attrs: warn( @@ -404,6 +466,12 @@ class TelegramObject: return super().__eq__(other) def __hash__(self) -> int: + """Builds a hash value for this object such that the hash of two objects is equal if and + only if the objects are equal in terms of :meth:`__eq__`. + + Returns: + :obj:`int` + """ if self._id_attrs: return hash((self.__class__, self._id_attrs)) return super().__hash__() diff --git a/telegram/_update.py b/telegram/_update.py index c2db64281..e29597b30 100644 --- a/telegram/_update.py +++ b/telegram/_update.py @@ -46,6 +46,9 @@ class Update(TelegramObject): Note: At most one of the optional parameters can be present in any given update. + .. seealso:: `Your First Bot `_ + Args: 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 @@ -104,6 +107,9 @@ class Update(TelegramObject): chosen_inline_result (:class:`telegram.ChosenInlineResult`): Optional. The result of an inline query that was chosen by a user. 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. pre_checkout_query (:class:`telegram.PreCheckoutQuery`): Optional. New incoming pre-checkout query. diff --git a/telegram/_webappdata.py b/telegram/_webappdata.py index 361c26079..085a3d689 100644 --- a/telegram/_webappdata.py +++ b/telegram/_webappdata.py @@ -28,7 +28,8 @@ class WebAppData(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`data` and :attr:`button_text` are equal. - .. seealso:: `Webappbot Example `_ + Examples: + :any:`Webapp Bot ` .. versionadded:: 20.0 @@ -45,8 +46,7 @@ class WebAppData(TelegramObject): button, from which the Web App was opened. Warning: - Be aware that a bad client can send - arbitrary data in this field. + Be aware that a bad client can send arbitrary data in this field. """ __slots__ = ("data", "button_text") diff --git a/telegram/_webappinfo.py b/telegram/_webappinfo.py index 581ef099a..b09c416c4 100644 --- a/telegram/_webappinfo.py +++ b/telegram/_webappinfo.py @@ -29,7 +29,8 @@ class WebAppInfo(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`url` are equal. - .. seealso:: `Webappbot Example `_ + Examples: + :any:`Webapp Bot ` .. versionadded:: 20.0 diff --git a/telegram/_webhookinfo.py b/telegram/_webhookinfo.py index 3bb58d78f..5b1defb44 100644 --- a/telegram/_webhookinfo.py +++ b/telegram/_webhookinfo.py @@ -62,14 +62,17 @@ class WebhookInfo(TelegramObject): .. versionadded:: 20.0 Attributes: - url (:obj:`str`): Webhook URL. - has_custom_certificate (:obj:`bool`): If a custom certificate was provided for webhook. + url (:obj:`str`): Webhook URL, may be empty if webhook is not set up. + has_custom_certificate (:obj:`bool`): :obj:`True`, if a custom certificate was provided for + webhook certificate checks. pending_update_count (:obj:`int`): Number of updates awaiting delivery. ip_address (:obj:`str`): Optional. Currently used webhook IP address. - last_error_date (:obj:`int`): Optional. Unix time for the most recent error that happened. - last_error_message (:obj:`str`): Optional. Error message in human-readable format. + last_error_date (:obj:`int`): Optional. Unix time for the most recent error that happened + when trying to deliver an update via webhook. + last_error_message (:obj:`str`): Optional. Error message in human-readable format for the + most recent error that happened when trying to deliver an update via webhook. max_connections (:obj:`int`): Optional. Maximum allowed number of simultaneous HTTPS - connections. + connections to the webhook for update delivery. allowed_updates (List[:obj:`str`]): Optional. A list of update types the bot is subscribed to. Defaults to all update types, except :attr:`telegram.Update.chat_member`. last_synchronization_error_date (:obj:`int`): Optional. Unix time of the most recent error diff --git a/telegram/error.py b/telegram/error.py index 8318a1d06..7e92bfaa9 100644 --- a/telegram/error.py +++ b/telegram/error.py @@ -56,7 +56,12 @@ def _lstrip_str(in_s: str, lstr: str) -> str: class TelegramError(Exception): - """Base class for Telegram errors.""" + """ + Base class for Telegram errors. + + .. seealso:: `Exceptions, Warnings and Logging `_ + """ __slots__ = ("message",) @@ -84,6 +89,9 @@ class TelegramError(Exception): class Forbidden(TelegramError): """Raised when the bot has not enough rights to perform the requested action. + Examples: + :any:`Raw API Bot ` + .. versionchanged:: 20.0 This class was previously named ``Unauthorized``. """ @@ -107,7 +115,11 @@ class InvalidToken(TelegramError): class NetworkError(TelegramError): - """Base class for exceptions due to networking errors.""" + """Base class for exceptions due to networking errors. + + Examples: + :any:`Raw API Bot ` + """ __slots__ = () @@ -137,6 +149,10 @@ 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 `_, + 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 d17204885..d6b8a2293 100644 --- a/telegram/ext/_aioratelimiter.py +++ b/telegram/ext/_aioratelimiter.py @@ -51,7 +51,7 @@ else: class AIORateLimiter(BaseRateLimiter[int]): """ Implementation of :class:`~telegram.ext.BaseRateLimiter` using the library - `aiolimiter `_. + `aiolimiter `_. Important: If you want to use this class, you must install PTB with the optional requirement @@ -90,6 +90,9 @@ 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 `_ + .. versionadded:: 20.0 Args: diff --git a/telegram/ext/_application.py b/telegram/ext/_application.py index 3b0883813..e48c180b5 100644 --- a/telegram/ext/_application.py +++ b/telegram/ext/_application.py @@ -133,6 +133,14 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) finally: await application.shutdown() + Examples: + :any:`Echo Bot ` + + .. seealso:: `Your First Bot `_, + `Architecture Overview `_ + .. versionchanged:: 20.0 * Initialization is now done through the :class:`telegram.ext.ApplicationBuilder`. @@ -146,19 +154,27 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) job_queue (:class:`telegram.ext.JobQueue`): Optional. The :class:`telegram.ext.JobQueue` instance to pass onto handler callbacks. chat_data (:obj:`types.MappingProxyType`): A dictionary handlers can use to store data for - the chat. + the chat. For each integer chat id, the corresponding value of this mapping is + available as :attr:`telegram.ext.CallbackContext.chat_data` in handler callbacks for + updates from that chat. .. versionchanged:: 20.0 - :attr:`chat_data` is now read-only + :attr:`chat_data` is now read-only. Note that the values of the mapping are still + mutable, i.e. editing ``context.chat_data`` within a handler callback is possible + (and encouraged), but editing the mapping ``application.chat_data`` itself is not. .. tip:: Manually modifying :attr:`chat_data` is almost never needed and unadvisable. user_data (:obj:`types.MappingProxyType`): A dictionary handlers can use to store data for - the user. + the user. For each integer user id, the corresponding value of this mapping is + available as :attr:`telegram.ext.CallbackContext.user_data` in handler callbacks for + updates from that user. .. versionchanged:: 20.0 - :attr:`user_data` is now read-only + :attr:`user_data` is now read-only. Note that the values of the mapping are still + mutable, i.e. editing ``context.user_data`` within a handler callback is possible + (and encouraged), but editing the mapping ``application.user_data`` itself is not. .. tip:: Manually modifying :attr:`user_data` is almost never needed and unadvisable. @@ -315,6 +331,9 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) 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 `_ """ return self._concurrent_updates @@ -584,9 +603,12 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) If :attr:`post_shutdown` is set, it will be called after both :meth:`shutdown` and :meth:`telegram.ext.Updater.shutdown`. + .. include:: inclusions/application_run_tip.rst + .. seealso:: :meth:`initialize`, :meth:`start`, :meth:`stop`, :meth:`shutdown` - :meth:`telegram.ext.Updater.start_polling`, :meth:`run_webhook` + :meth:`telegram.ext.Updater.start_polling`, :meth:`telegram.ext.Updater.stop`, + :meth:`run_webhook` Args: poll_interval (:obj:`float`, optional): Time to wait between polling updates from @@ -677,7 +699,7 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) secret_token: str = None, ) -> None: """Convenience method that takes care of initializing and starting the app, - polling updates from Telegram using :meth:`telegram.ext.Updater.start_webhook` and + listening for updates from Telegram using :meth:`telegram.ext.Updater.start_webhook` and a graceful shutdown of the app on exit. The app will shut down when :exc:`KeyboardInterrupt` or :exc:`SystemExit` is raised. @@ -705,9 +727,13 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) pip install python-telegram-bot[webhooks] + .. include:: inclusions/application_run_tip.rst + .. seealso:: :meth:`initialize`, :meth:`start`, :meth:`stop`, :meth:`shutdown` - :meth:`telegram.ext.Updater.start_webhook`, :meth:`run_polling` + :meth:`telegram.ext.Updater.start_webhook`, :meth:`telegram.ext.Updater.stop`, + :meth:`run_polling`, + `Webhooks `_ Args: listen (:obj:`str`, optional): IP-Address to listen on. Defaults to @@ -852,6 +878,9 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) * If the application is currently running, tasks created by this method will be awaited with :meth:`stop`. + .. seealso:: `Concurrency `_ + Args: coroutine (:term:`coroutine function`): The coroutine to run as task. update (:obj:`object`, optional): If set, will be passed to :meth:`process_error` @@ -968,6 +997,9 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) """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 `_ + .. versionchanged:: 20.0 Persistence is now updated in an interval set by :attr:`telegram.ext.BasePersistence.update_interval`. @@ -1207,6 +1239,10 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) 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 `_, + Args: message (:class:`telegram.Message`, optional): A message with either :attr:`~telegram.Message.migrate_from_chat_id` or @@ -1423,7 +1459,11 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) Note: Attempts to add the same callback multiple times will be ignored. - .. seealso:: `Errorhandler Example `_ + Examples: + :any:`Errorhandler Bot ` + + .. seealso:: `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 48b79a314..1f464e79f 100644 --- a/telegram/ext/_applicationbuilder.py +++ b/telegram/ext/_applicationbuilder.py @@ -112,6 +112,11 @@ 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 `_ + .. _`builder pattern`: https://en.wikipedia.org/wiki/Builder_pattern """ @@ -729,8 +734,8 @@ class ApplicationBuilder(Generic[BT, CCT, UD, CD, BD, JQ]): pip install python-telegram-bot[callback-data] - .. seealso:: `Arbitrary callback_data `_, + .. seealso:: `Arbitrary callback_data `_, :any:`examples.arbitrarycallbackdatabot` Args: diff --git a/telegram/ext/_basepersistence.py b/telegram/ext/_basepersistence.py index 429158335..8b01a3bfa 100644 --- a/telegram/ext/_basepersistence.py +++ b/telegram/ext/_basepersistence.py @@ -111,6 +111,11 @@ 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 `_ + .. versionchanged:: 20.0 * The parameters and attributes ``store_*_data`` were replaced by :attr:`store_data`. diff --git a/telegram/ext/_baseratelimiter.py b/telegram/ext/_baseratelimiter.py index 06223b906..b64b76da5 100644 --- a/telegram/ext/_baseratelimiter.py +++ b/telegram/ext/_baseratelimiter.py @@ -37,6 +37,11 @@ class BaseRateLimiter(ABC, Generic[RLARGS]): Hint: Requests to :meth:`~telegram.Bot.get_updates` are never rate limited. + .. seealso:: `Architecture Overview `_, + `Avoiding Flood Limits `_ + .. versionadded:: 20.0 """ diff --git a/telegram/ext/_callbackcontext.py b/telegram/ext/_callbackcontext.py index 40252d4fd..e7b99b4c1 100644 --- a/telegram/ext/_callbackcontext.py +++ b/telegram/ext/_callbackcontext.py @@ -66,7 +66,13 @@ class CallbackContext(Generic[BT, UD, CD, BD]): 3. The type of :attr:`chat_data` (if :attr:`chat_data` is not :obj:`None`). 4. The type of :attr:`bot_data` (if :attr:`bot_data` is not :obj:`None`). - .. seealso:: :attr:`telegram.ext.ContextTypes.DEFAULT_TYPE` + Examples: + * :any:`Context Types Bot ` + * :any:`Custom Webhook Bot ` + + .. seealso:: :attr:`telegram.ext.ContextTypes.DEFAULT_TYPE`, + `Job Queue `_ Args: application (:class:`telegram.ext.Application`): The application associated with this @@ -138,6 +144,10 @@ class CallbackContext(Generic[BT, UD, CD, BD]): 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 `_, """ return self.application.bot_data @@ -159,6 +169,10 @@ class CallbackContext(Generic[BT, UD, CD, BD]): `_. + .. seealso:: `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. """ @@ -178,6 +192,10 @@ class CallbackContext(Generic[BT, UD, CD, BD]): 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 `_, + .. versionchanged:: 20.0 The user data is now also present in error handlers if the error is caused by a job. """ @@ -225,6 +243,9 @@ class CallbackContext(Generic[BT, UD, CD, BD]): 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 `_ + Args: callback_query (:class:`telegram.CallbackQuery`): The callback query. @@ -365,6 +386,8 @@ class CallbackContext(Generic[BT, UD, CD, BD]): :class:`telegram.ext.JobQueue`: The :class:`JobQueue` used by the :class:`telegram.ext.Application`. + .. seealso:: `Job Queue `_ """ return self._application.job_queue diff --git a/telegram/ext/_callbackdatacache.py b/telegram/ext/_callbackdatacache.py index 6fb618fd1..7e694bf10 100644 --- a/telegram/ext/_callbackdatacache.py +++ b/telegram/ext/_callbackdatacache.py @@ -44,6 +44,12 @@ class InvalidCallbackData(TelegramError): """ Raised when the received callback data has been tempered with or deleted from cache. + Examples: + :any:`Arbitrary Callback Data Bot ` + + .. seealso:: `Arbitrary callback_data `_ + .. versionadded:: 13.6 Args: @@ -93,8 +99,8 @@ class CallbackDataCache: """A custom cache for storing the callback data of a :class:`telegram.ext.ExtBot`. Internally, it keeps two mappings with fixed maximum size: - * One for mapping the data received in callback queries to the cached objects - * One for mapping the IDs of received callback queries to the cached objects + * One for mapping the data received in callback queries to the cached objects + * One for mapping the IDs of received callback queries to the cached objects The second mapping allows to manually drop data that has been cached for keyboards of messages sent via inline mode. @@ -108,10 +114,14 @@ class CallbackDataCache: pip install python-telegram-bot[callback-data] + Examples: + :any:`Arbitrary Callback Data Bot ` + .. seealso:: :attr:`telegram.ext.ExtBot.callback_data_cache`, - `Arbitrary callback_data `_, - Arbitrary Callback Data Example + `Architecture Overview `_, + `Arbitrary callback_data `_ .. versionadded:: 13.6 diff --git a/telegram/ext/_callbackqueryhandler.py b/telegram/ext/_callbackqueryhandler.py index 847f7ea07..c2590f14d 100644 --- a/telegram/ext/_callbackqueryhandler.py +++ b/telegram/ext/_callbackqueryhandler.py @@ -81,12 +81,18 @@ class CallbackQueryHandler(BaseHandler[Update, CCT]): If :attr:`telegram.CallbackQuery.data` is :obj:`None`, the :class:`telegram.CallbackQuery` update will not be handled. + .. seealso:: `Arbitrary callback_data `_ + .. versionchanged:: 13.6 Added support for arbitrary callback data. block (:obj:`bool`, optional): Determines whether the return value of the callback should be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `Concurrency `_ + Attributes: callback (:term:`coroutine function`): The callback function for this handler. pattern (:func:`re.Pattern ` | :obj:`callable` | :obj:`type`): Optional. diff --git a/telegram/ext/_chatjoinrequesthandler.py b/telegram/ext/_chatjoinrequesthandler.py index fa0504a59..d8b26d1a1 100644 --- a/telegram/ext/_chatjoinrequesthandler.py +++ b/telegram/ext/_chatjoinrequesthandler.py @@ -66,6 +66,9 @@ class ChatJoinRequestHandler(BaseHandler[Update, CCT]): be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `Concurrency `_ + Attributes: callback (:term:`coroutine function`): The callback function for this handler. block (:obj:`bool`): Determines whether the callback will run in a blocking way.. diff --git a/telegram/ext/_chatmemberhandler.py b/telegram/ext/_chatmemberhandler.py index 267a92b24..304a490f4 100644 --- a/telegram/ext/_chatmemberhandler.py +++ b/telegram/ext/_chatmemberhandler.py @@ -35,7 +35,8 @@ class ChatMemberHandler(BaseHandler[Update, CCT]): When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info. - .. seealso:: `Chat Member Example `_ + Examples: + :any:`Chat Member Bot ` .. versionadded:: 13.4 @@ -56,6 +57,9 @@ class ChatMemberHandler(BaseHandler[Update, CCT]): be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `Concurrency `_ + Attributes: callback (:term:`coroutine function`): The callback function for this handler. chat_member_types (:obj:`int`, optional): Specifies if this handler should handle diff --git a/telegram/ext/_choseninlineresulthandler.py b/telegram/ext/_choseninlineresulthandler.py index 8adb1167e..ff0000ce7 100644 --- a/telegram/ext/_choseninlineresulthandler.py +++ b/telegram/ext/_choseninlineresulthandler.py @@ -52,6 +52,9 @@ class ChosenInlineResultHandler(BaseHandler[Update, CCT]): block (:obj:`bool`, optional): Determines whether the return value of the callback should be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + + .. seealso:: `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 955b9c0b2..659e20fa6 100644 --- a/telegram/ext/_commandhandler.py +++ b/telegram/ext/_commandhandler.py @@ -57,6 +57,10 @@ class CommandHandler(BaseHandler[Update, CCT]): When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info. + Examples: + * :any:`Timer Bot ` + * :any:`Error Handler Bot ` + .. versionchanged:: 20.0 * Renamed the attribute ``command`` to :attr:`commands`, which now is always a @@ -83,6 +87,9 @@ class CommandHandler(BaseHandler[Update, CCT]): be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `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 e49acec3d..30b8430b1 100644 --- a/telegram/ext/_contexttypes.py +++ b/telegram/ext/_contexttypes.py @@ -33,7 +33,13 @@ class ContextTypes(Generic[CCT, UD, CD, BD]): Convenience class to gather customizable types of the :class:`telegram.ext.CallbackContext` interface. - .. seealso:: `ContextTypes Example `_ + Examples: + :any:`ContextTypes Bot ` + + .. seealso:: `Architecture Overview `_, + `Storing Bot, User and Chat Related Data `_ .. versionadded:: 13.6 diff --git a/telegram/ext/_conversationhandler.py b/telegram/ext/_conversationhandler.py index 2abd6ca56..0402f740a 100644 --- a/telegram/ext/_conversationhandler.py +++ b/telegram/ext/_conversationhandler.py @@ -185,10 +185,11 @@ class ConversationHandler(BaseHandler[Update, CCT]): conversation. For an example on nested :class:`ConversationHandler` s, see :any:`examples.nestedconversationbot`. - .. seealso:: `Conversation Example `_, - `Conversation Example 2 `_, - `Nested Conversation Example `_, - `Persistent Conversation Example `_ + Examples: + * :any:`Conversation Bot ` + * :any:`Conversation Bot 2 ` + * :any:`Nested Conversation Bot ` + * :any:`Persistent Conversation Bot ` Args: entry_points (List[:class:`telegram.ext.BaseHandler`]): A list of :obj:`BaseHandler` @@ -248,6 +249,9 @@ 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 `_ + .. 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 d41e14b4d..da9cce48a 100644 --- a/telegram/ext/_defaults.py +++ b/telegram/ext/_defaults.py @@ -26,6 +26,11 @@ from telegram._utils.datetime import UTC class Defaults: """Convenience Class to gather all parameters with a (user defined) default value + .. seealso:: `Architecture Overview `_, + `Adding Defaults to Your Bot `_ + .. versionchanged:: 20.0 Removed the argument and attribute ``timeout``. Specify default timeout behavior for the networking backend directly via :class:`telegram.ext.ApplicationBuilder` instead. diff --git a/telegram/ext/_dictpersistence.py b/telegram/ext/_dictpersistence.py index e341790f6..c02b49ec2 100644 --- a/telegram/ext/_dictpersistence.py +++ b/telegram/ext/_dictpersistence.py @@ -43,6 +43,9 @@ 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 `_ + .. 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 a344123f9..b6622108f 100644 --- a/telegram/ext/_extbot.py +++ b/telegram/ext/_extbot.py @@ -118,9 +118,11 @@ class ExtBot(Bot, Generic[RLARGS]): * The method :meth:`~telegram.Bot.get_updates` is the only method that does not have the additional argument, as this method will never be rate limited. - .. seealso:: `Arbitrary Callback Example `_, - `Arbitrary callback_data `_ + Examples: + :any:`Arbitrary Callback Data Bot ` + + .. seealso:: `Arbitrary callback_data `_ .. versionadded:: 13.6 @@ -134,9 +136,11 @@ class ExtBot(Bot, Generic[RLARGS]): be used if not set explicitly in the bot methods. arbitrary_callback_data (:obj:`bool` | :obj:`int`, optional): Whether to allow arbitrary objects as callback data for :class:`telegram.InlineKeyboardButton`. - Pass an integer to specify the maximum number of objects cached in memory. For more - details, please see our `wiki `_. Defaults to :obj:`False`. + Pass an integer to specify the maximum number of objects cached in memory. + Defaults to :obj:`False`. + + .. seealso:: `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. @@ -226,6 +230,9 @@ class ExtBot(Bot, Generic[RLARGS]): """:class:`telegram.ext.CallbackDataCache`: Optional. The cache for objects passed as callback data for :class:`telegram.InlineKeyboardButton`. + Examples: + :any:`Arbitrary Callback Data Bot ` + .. versionchanged:: 20.0 * This property is now read-only. * This property is now optional and can be :obj:`None` if diff --git a/telegram/ext/_handler.py b/telegram/ext/_handler.py index f050813aa..fc98c616c 100644 --- a/telegram/ext/_handler.py +++ b/telegram/ext/_handler.py @@ -54,6 +54,9 @@ 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 `_ + .. versionchanged:: 20.0 * The attribute ``run_async`` is now :paramref:`block`. @@ -72,6 +75,9 @@ class BaseHandler(Generic[UT, CCT], ABC): be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `Concurrency `_ + Attributes: callback (:term:`coroutine function`): The callback function for this handler. block (:obj:`bool`): Determines whether the callback will run in a blocking way.. diff --git a/telegram/ext/_inlinequeryhandler.py b/telegram/ext/_inlinequeryhandler.py index d006fa159..ae451e709 100644 --- a/telegram/ext/_inlinequeryhandler.py +++ b/telegram/ext/_inlinequeryhandler.py @@ -46,7 +46,9 @@ class InlineQueryHandler(BaseHandler[Update, CCT]): chats and may not be set for inline queries coming from third-party clients. These updates won't be handled, if :attr:`chat_types` is passed. - .. seealso:: `Inlinebot Example `_ + Examples: + :any:`Inline Bot ` + Args: callback (:term:`coroutine function`): The callback function for this handler. Will be @@ -63,6 +65,9 @@ class InlineQueryHandler(BaseHandler[Update, CCT]): block (:obj:`bool`, optional): Determines whether the return value of the callback should be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + + .. seealso:: `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 442cc5c77..e646b3429 100644 --- a/telegram/ext/_jobqueue.py +++ b/telegram/ext/_jobqueue.py @@ -53,9 +53,13 @@ class JobQueue: pip install python-telegram-bot[job-queue] + Examples: + :any:`Timer Bot ` + .. seealso:: :attr:`telegram.ext.Application.job_queue`, :attr:`telegram.ext.CallbackContext.job_queue`, - `Timerbot Example `_, + `Architecture Overview `_, `Job Queue `_ @@ -639,6 +643,9 @@ class Job: This class should not be instantiated manually. Use the methods of :class:`telegram.ext.JobQueue` to schedule jobs. + .. seealso:: `Job Queue `_ + .. versionchanged:: 20.0 * Removed argument and attribute ``job_queue``. diff --git a/telegram/ext/_messagehandler.py b/telegram/ext/_messagehandler.py index e62472ffc..addf72c33 100644 --- a/telegram/ext/_messagehandler.py +++ b/telegram/ext/_messagehandler.py @@ -49,6 +49,9 @@ class MessageHandler(BaseHandler[Update, CCT]): :attr:`telegram.Update.channel_post` and :attr:`telegram.Update.edited_channel_post`. If you don't want or need any of those pass ``~filters.UpdateType.*`` in the filter argument. + + .. seealso:: `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,6 +64,9 @@ class MessageHandler(BaseHandler[Update, CCT]): be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `Concurrency `_ + Attributes: filters (:class:`telegram.ext.filters.BaseFilter`): Only allow updates with these Filters. See :mod:`telegram.ext.filters` for a full list of all available filters. diff --git a/telegram/ext/_picklepersistence.py b/telegram/ext/_picklepersistence.py index af5126af6..f8a64dc2b 100644 --- a/telegram/ext/_picklepersistence.py +++ b/telegram/ext/_picklepersistence.py @@ -130,6 +130,12 @@ class PicklePersistence(BasePersistence[UD, CD, BD]): :attr:`~BasePersistence.bot` will be replaced by a placeholder before pickling and :attr:`~BasePersistence.bot` will be inserted back when loading the data. + Examples: + :any:`Persistent Conversation Bot ` + + .. seealso:: `Making Your Bot Persistent `_ + .. versionchanged:: 20.0 * The parameters and attributes ``store_*_data`` were replaced by :attr:`store_data`. diff --git a/telegram/ext/_pollanswerhandler.py b/telegram/ext/_pollanswerhandler.py index 7b99ea5cd..faa4733ea 100644 --- a/telegram/ext/_pollanswerhandler.py +++ b/telegram/ext/_pollanswerhandler.py @@ -32,7 +32,8 @@ class PollAnswerHandler(BaseHandler[Update, CCT]): When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info. - .. seealso:: `Pollbot EXample `_ + Examples: + :any:`Poll Bot ` Args: callback (:term:`coroutine function`): The callback function for this handler. Will be @@ -47,6 +48,9 @@ class PollAnswerHandler(BaseHandler[Update, CCT]): be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `Concurrency `_ + Attributes: callback (:term:`coroutine function`): The callback function for this handler. block (:obj:`bool`): Determines whether the callback will run in a blocking way.. diff --git a/telegram/ext/_pollhandler.py b/telegram/ext/_pollhandler.py index 5e0543196..67d7b92ad 100644 --- a/telegram/ext/_pollhandler.py +++ b/telegram/ext/_pollhandler.py @@ -32,7 +32,8 @@ class PollHandler(BaseHandler[Update, CCT]): When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info. - .. seealso:: `Pollbot Example `_ + Examples: + :any:`Poll Bot ` Args: callback (:term:`coroutine function`): The callback function for this handler. Will be @@ -47,6 +48,9 @@ class PollHandler(BaseHandler[Update, CCT]): be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `Concurrency `_ + Attributes: callback (:term:`coroutine function`): The callback function for this handler. block (:obj:`bool`): Determines whether the callback will run in a blocking way.. diff --git a/telegram/ext/_precheckoutqueryhandler.py b/telegram/ext/_precheckoutqueryhandler.py index f7365cd65..d02cf50da 100644 --- a/telegram/ext/_precheckoutqueryhandler.py +++ b/telegram/ext/_precheckoutqueryhandler.py @@ -31,7 +31,8 @@ class PreCheckoutQueryHandler(BaseHandler[Update, CCT]): When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info. - .. seealso:: `Paymentbot Example `_ + Examples: + :any:`Payment Bot ` Args: callback (:term:`coroutine function`): The callback function for this handler. Will be @@ -46,6 +47,9 @@ class PreCheckoutQueryHandler(BaseHandler[Update, CCT]): be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `Concurrency `_ + Attributes: callback (:term:`coroutine function`): The callback function for this handler. block (:obj:`bool`): Determines whether the callback will run in a blocking way.. diff --git a/telegram/ext/_prefixhandler.py b/telegram/ext/_prefixhandler.py index 87e442a7e..67c619bbd 100644 --- a/telegram/ext/_prefixhandler.py +++ b/telegram/ext/_prefixhandler.py @@ -105,6 +105,9 @@ class PrefixHandler(BaseHandler[Update, CCT]): be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `Concurrency `_ + Attributes: commands (FrozenSet[:obj:`str`]): The commands that this handler will listen for, i.e. the combinations of :paramref:`prefix` and :paramref:`command`. diff --git a/telegram/ext/_shippingqueryhandler.py b/telegram/ext/_shippingqueryhandler.py index 39eceedc3..5a78a8147 100644 --- a/telegram/ext/_shippingqueryhandler.py +++ b/telegram/ext/_shippingqueryhandler.py @@ -31,7 +31,8 @@ class ShippingQueryHandler(BaseHandler[Update, CCT]): When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info. - .. seealso:: `Paymentbot Example `_ + Examples: + :any:`Payment Bot ` Args: callback (:term:`coroutine function`): The callback function for this handler. Will be @@ -46,6 +47,9 @@ class ShippingQueryHandler(BaseHandler[Update, CCT]): be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `Concurrency `_ + Attributes: callback (:term:`coroutine function`): The callback function for this handler. block (:obj:`bool`): Determines whether the callback will run in a blocking way.. diff --git a/telegram/ext/_stringcommandhandler.py b/telegram/ext/_stringcommandhandler.py index 10787d3ef..7dc0f53e3 100644 --- a/telegram/ext/_stringcommandhandler.py +++ b/telegram/ext/_stringcommandhandler.py @@ -57,6 +57,9 @@ class StringCommandHandler(BaseHandler[str, CCT]): be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `Concurrency `_ + Attributes: command (:obj:`str`): The command this handler should listen for. callback (:term:`coroutine function`): The callback function for this handler. diff --git a/telegram/ext/_stringregexhandler.py b/telegram/ext/_stringregexhandler.py index e6b219a7d..0a6f0db71 100644 --- a/telegram/ext/_stringregexhandler.py +++ b/telegram/ext/_stringregexhandler.py @@ -60,6 +60,9 @@ class StringRegexHandler(BaseHandler[str, CCT]): be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `Concurrency `_ + Attributes: pattern (:obj:`str` | :func:`re.Pattern `): The regex pattern. callback (:term:`coroutine function`): The callback function for this handler. diff --git a/telegram/ext/_typehandler.py b/telegram/ext/_typehandler.py index d72d58710..2984e00e3 100644 --- a/telegram/ext/_typehandler.py +++ b/telegram/ext/_typehandler.py @@ -53,6 +53,9 @@ class TypeHandler(BaseHandler[UT, CCT]): be awaited before processing the next handler in :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`. + .. seealso:: `Concurrency `_ + Attributes: type (:external:class:`type`): The :external:class:`type` of updates this handler should process. diff --git a/telegram/ext/_updater.py b/telegram/ext/_updater.py index 6bcc0d487..907ea1f36 100644 --- a/telegram/ext/_updater.py +++ b/telegram/ext/_updater.py @@ -65,6 +65,11 @@ class Updater(AbstractAsyncContextManager): finally: await updater.shutdown() + .. seealso:: `Architecture Overview `_, + `Builder Pattern `_ + .. versionchanged:: 20.0 * Removed argument and attribute ``user_sig_handler`` @@ -392,6 +397,9 @@ class Updater(AbstractAsyncContextManager): pip install python-telegram-bot[webhooks] + .. seealso:: `Webhooks `_ + .. versionchanged:: 13.4 :meth:`start_webhook` now *always* calls :meth:`telegram.Bot.set_webhook`, so pass ``webhook_url`` instead of calling ``updater.bot.set_webhook(webhook_url)`` manually. diff --git a/telegram/ext/filters.py b/telegram/ext/filters.py index 3cf6b23a7..5ad236153 100644 --- a/telegram/ext/filters.py +++ b/telegram/ext/filters.py @@ -28,11 +28,11 @@ This module contains filters for use with :class:`telegram.ext.MessageHandler`, :mod:`~telegram.ext.filters` module. #. The names of all filters has been updated: - * Filter classes which are ready for use, e.g ``Filters.all`` are now capitalized, e.g - ``filters.ALL``. - * Filters which need to be initialized are now in CamelCase. E.g. ``filters.User(...)``. - * Filters which do both (like ``Filters.text``) are now split as ready-to-use version - ``filters.TEXT`` and class version ``filters.Text(...)``. + * Filter classes which are ready for use, e.g ``Filters.all`` are now capitalized, e.g + ``filters.ALL``. + * Filters which need to be initialized are now in CamelCase. E.g. ``filters.User(...)``. + * Filters which do both (like ``Filters.text``) are now split as ready-to-use version + ``filters.TEXT`` and class version ``filters.Text(...)``. """ @@ -231,6 +231,9 @@ class MessageFilter(BaseFilter): Please see :class:`BaseFilter` for details on how to create custom filters. + .. seealso:: `Advanced Filters `_ + Attributes: name (:obj:`str`): Name for this filter. Defaults to the type of filter. data_filter (:obj:`bool`): Whether this filter is a data filter. A data filter should @@ -1527,6 +1530,9 @@ 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 `_ + Args: pattern (:obj:`str` | :func:`re.Pattern `): The regex pattern. """ diff --git a/telegram/helpers.py b/telegram/helpers.py index 7a3eac635..460a2c923 100644 --- a/telegram/helpers.py +++ b/telegram/helpers.py @@ -72,6 +72,8 @@ def escape_markdown(text: str, version: int = 1, entity_type: str = None) -> str def mention_html(user_id: Union[int, str], name: str) -> str: """ + Helper function to create a user mention as HTML tag. + Args: user_id (:obj:`int`): The user's id which you want to mention. name (:obj:`str`): The name the mention is showing. @@ -84,6 +86,8 @@ def mention_html(user_id: Union[int, str], name: str) -> str: def mention_markdown(user_id: Union[int, str], name: str, version: int = 1) -> str: """ + Helper function to create a user mention in Markdown syntax. + Args: user_id (:obj:`int`): The user's id which you want to mention. name (:obj:`str`): The name the mention is showing. @@ -110,7 +114,7 @@ def effective_message_type(entity: Union["Message", "Update"]) -> Optional[str]: Returns: :obj:`str` | :obj:`None`: One of :class:`telegram.constants.MessageType` if the entity - contains a message that matches one of those types. :obj:`None` otherwise. + contains a message that matches one of those types. :obj:`None` otherwise. """ # Importing on file-level yields cyclic Import Errors @@ -146,19 +150,18 @@ def create_deep_linked_url(bot_username: str, payload: str = None, group: bool = ``CommandHandler("start", callback, filters=filters.Regex('payload'))`` Examples: - ``create_deep_linked_url(bot.get_me().username, "some-params")`` - - .. seealso:: `Deeplinking Example `_ + * ``create_deep_linked_url(bot.get_me().username, "some-params")`` + * :any:`Deep Linking ` Args: - bot_username (:obj:`str`): The username to link to - payload (:obj:`str`, optional): Parameters to encode in the created URL + bot_username (:obj:`str`): The username to link to. + payload (:obj:`str`, optional): Parameters to encode in the created URL. group (:obj:`bool`, optional): If :obj:`True` the user is prompted to select a group to add the bot to. If :obj:`False`, opens a one-on-one conversation with the bot. Defaults to :obj:`False`. Returns: - :obj:`str`: An URL to start the bot with specific parameters + :obj:`str`: An URL to start the bot with specific parameters. """ if bot_username is None or len(bot_username) <= 3: raise ValueError("You must provide a valid bot_username.") diff --git a/telegram/request/_baserequest.py b/telegram/request/_baserequest.py index 6d54d3494..b544e45e0 100644 --- a/telegram/request/_baserequest.py +++ b/telegram/request/_baserequest.py @@ -73,6 +73,11 @@ 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 `_ + .. versionadded:: 20.0 """ diff --git a/telegram/warnings.py b/telegram/warnings.py index 0f25ea820..dee3ff4c2 100644 --- a/telegram/warnings.py +++ b/telegram/warnings.py @@ -28,6 +28,9 @@ class PTBUserWarning(UserWarning): """ Custom user warning class used for warnings in this library. + .. seealso:: `Exceptions, Warnings and Logging `_ + .. versionadded:: 20.0 """