OpenSource/python-telegram-bot
OpenSource/python-telegram-bot
1
0
Fork 0
mirror of https://github.com/python-telegram-bot/python-telegram-bot.git synced 2024-11-21 22:56:38 +01:00
Code Issues Projects Releases Packages Wiki Activity

Documentation Improvements (#2856, #2798, #2854, #2841)

Browse source 
Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>
This commit is contained in:
Bibo-Joshi 2022-02-09 17:30:16 +01:00 committed by Hinrich Mahler
parent 835434c12f
commit 7b37f9a6fa
81 changed files with 960 additions and 3869 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.github/pull_request_template.md vendored
View file

@ -32,5 +32,6 @@ Hey! You're PRing? Cool! Please have a look at the below checklist. It's here to
- [ ] Add the handlers to the warning loop in the `ConversationHandler`
- [ ] Added new filters for new message (sub)types
- [ ] Added or updated documentation for the changed class(es) and/or method(s)
- [ ] Added or updated `bot_methods.rst`
- [ ] Updated the Bot API version number in all places: `README.rst` and `README_RAW.rst` (including the badge), as well as `telegram.constants.BOT_API_VERSION`
- [ ] Added logic for arbitrary callback data in `tg.ext.Bot` for new methods that either accept a `reply_markup` in some form or have a return type that is/contains `telegram.Message`

39
.github/workflows/docs.yml vendored Normal file
View file

@ -0,0 +1,39 @@
name: Test Documentation Build
on:
pull_request:
branches:
- master
- v14
- doc-fixes
push:
branches:
- master
- v14
- doc-fixes
jobs:
test-sphinx-build:
name: test-sphinx-build
runs-on: ${{matrix.os}}
strategy:
matrix:
python-version: [3.7]
os: [ubuntu-latest]
fail-fast: False
steps:
- uses: actions/checkout@v2
- name: Initialize vendored libs
run:
git submodule update --init --recursive
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v2
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -W ignore -m pip install --upgrade pip
python -W ignore -m pip install -r requirements.txt
python -W ignore -m pip install -r requirements-dev.txt
python -W ignore -m pip install -r docs/requirements-docs.txt
- name: Build docs
run: sphinx-build docs/source docs/build/html -W --keep-going -j auto

2
docs/Makefile
View file

@ -15,7 +15,7 @@ endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -j auto
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source

11
docs/requirements-docs.txt
View file

@ -1,6 +1,7 @@
sphinx==4.2.0
sphinx==4.4.0
sphinx-pypi-upload
# When bumping this, make sure to rebuild the dark-mode CSS
# More instructions at source/_static/dark.css
# Ofc once https://github.com/readthedocs/sphinx_rtd_theme/issues/224 is closed, we should use that
sphinx_rtd_theme==0.5.2
furo==2022.1.2
# Can be replaced with a sphinx-paramlinks==... dependency once a version is released that
# includes the commit mentioned below and maybe even
# https://github.com/sqlalchemyorg/sphinx-paramlinks/pull/14
git+https://github.com/sqlalchemyorg/sphinx-paramlinks.git@acedb03149e3f87ff599174b033754c2f58f1c95

3461
docs/source/_static/dark.css
View file

File diff suppressed because it is too large Load diff

5
docs/source/_static/style_external_link.css Normal file
View file

@ -0,0 +1,5 @@
article a.reference.external:not([href*="/python-telegram-bot/blob/"])::after {
content: url('data:image/svg+xml,<svg width="12" height="12" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" stroke-width="1.5" stroke="%23607D8B" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z"/><path d="M11 7h-5a2 2 0 0 0 -2 2v9a2 2 0 0 0 2 2h9a2 2 0 0 0 2 -2v-5" /><line x1="10" y1="14" x2="20" y2="4" /><polyline points="15 4 20 4 20 9" /></svg>');
margin: 0 0.25rem;
vertical-align: middle;
}

304
docs/source/bot_methods.rst Normal file
View file

@ -0,0 +1,304 @@
.. raw:: html
<hr style="height:2px;border-width:0;color:gray;background-color:gray">
<p>Since this class has a large number of methods and attributes, below you can find a quick overview.
</p>
<details>
<summary>Sending Messages</summary>
.. list-table::
:align: left
:widths: 1 4
* - :meth:`~telegram.Bot.send_animation`
- Used for sending animations
* - :meth:`~telegram.Bot.send_audio`
- Used for sending audio files
* - :meth:`~telegram.Bot.send_chat_action`
- Used for sending chat actions
* - :meth:`~telegram.Bot.send_contact`
- Used for sending contacts
* - :meth:`~telegram.Bot.send_dice`
- Used for sending dice messages
* - :meth:`~telegram.Bot.send_document`
- Used for sending documents
* - :meth:`~telegram.Bot.send_game`
- Used for sending a game
* - :meth:`~telegram.Bot.send_invoice`
- Used for sending an invoice
* - :meth:`~telegram.Bot.send_location`
- Used for sending location
* - :meth:`~telegram.Bot.send_media_group`
- Used for sending media grouped together
* - :meth:`~telegram.Bot.send_message`
- Used for sending text messages
* - :meth:`~telegram.Bot.send_photo`
- Used for sending photos
* - :meth:`~telegram.Bot.send_poll`
- Used for sending polls
* - :meth:`~telegram.Bot.send_sticker`
- Used for sending stickers
* - :meth:`~telegram.Bot.send_venue`
- Used for sending venue locations.
* - :meth:`~telegram.Bot.send_video`
- Used for sending videos
* - :meth:`~telegram.Bot.send_video_note`
- Used for sending video notes
* - :meth:`~telegram.Bot.send_voice`
- Used for sending voice messages
* - :meth:`~telegram.Bot.copy_message`
- Used for copying the contents of an arbitrary message
* - :meth:`~telegram.Bot.forward_message`
- Used for forwarding messages
.. raw:: html
</details>
<br>
.. raw:: html
<details>
<summary>Updating Messages</summary>
.. list-table::
:align: left
:widths: 1 4
* - :meth:`~telegram.Bot.answer_callback_query`
- Used for answering the callback query
* - :meth:`~telegram.Bot.answer_inline_query`
- Used for answering the inline query
* - :meth:`~telegram.Bot.answer_pre_checkout_query`
- Used for answering a pre checkout query
* - :meth:`~telegram.Bot.answer_shipping_query`
- Used for answering a shipping query
* - :meth:`~telegram.Bot.edit_message_caption`
- Used for editing captions
* - :meth:`~telegram.Bot.edit_message_media`
- Used for editing the media on messages
* - :meth:`~telegram.Bot.edit_message_live_location`
- Used for editing the location in live location messages
* - :meth:`~telegram.Bot.edit_message_reply_markup`
- Used for editing the reply markup on messages
* - :meth:`~telegram.Bot.edit_message_text`
- Used for editing text messages
* - :meth:`~telegram.Bot.stop_poll`
- Used for stopping the running poll
* - :meth:`~telegram.Bot.delete_message`
- Used for deleting messages.
.. raw:: html
</details>
<br>
.. raw:: html
<details>
<summary>Chat Moderation and information</summary>
.. list-table::
:align: left
:widths: 1 4
* - :meth:`~telegram.Bot.ban_chat_member`
- Used for banning a member from the chat
* - :meth:`~telegram.Bot.unban_chat_member`
- Used for unbanning a member from the chat
* - :meth:`~telegram.Bot.ban_chat_sender_chat`
- Used for banning a channel in a channel or supergroup
* - :meth:`~telegram.Bot.unban_chat_sender_chat`
- Used for unbanning a channel in a channel or supergroup
* - :meth:`~telegram.Bot.restrict_chat_member`
- Used for restricting a chat member
* - :meth:`~telegram.Bot.promote_chat_member`
- Used for promoting a chat member
* - :meth:`~telegram.Bot.set_chat_administrator_custom_title`
- Used for assigning a custom admin title to an admin
* - :meth:`~telegram.Bot.set_chat_permissions`
- Used for setting the permissions of a chat
* - :meth:`~telegram.Bot.export_chat_invite_link`
- Used for creating a new primary invite link for a chat
* - :meth:`~telegram.Bot.create_chat_invite_link`
- Used for creating an additional invite link for a chat
* - :meth:`~telegram.Bot.edit_chat_invite_link`
- Used for editing a non-primary invite link
* - :meth:`~telegram.Bot.revoke_chat_invite_link`
- Used for revoking an invite link created by the bot
* - :meth:`~telegram.Bot.approve_chat_join_request`
- Used for approving a chat join request
* - :meth:`~telegram.Bot.decline_chat_join_request`
- Used for declining a chat join request
* - :meth:`~telegram.Bot.set_chat_photo`
- Used for setting a photo to a chat
* - :meth:`~telegram.Bot.delete_chat_photo`
- Used for deleting a chat photo
* - :meth:`~telegram.Bot.set_chat_title`
- Used for setting a chat title
* - :meth:`~telegram.Bot.set_chat_description`
- Used for setting the description of a chat
* - :meth:`~telegram.Bot.pin_chat_message`
- Used for pinning a message
* - :meth:`~telegram.Bot.unpin_chat_message`
- Used for unpinning a message
* - :meth:`~telegram.Bot.unpin_all_chat_messages`
- Used for unpinning all pinned chat messages
* - :meth:`~telegram.Bot.get_user_profile_photos`
- Used for obtaining user's profile pictures
* - :meth:`~telegram.Bot.get_chat`
- Used for getting information about a chat
* - :meth:`~telegram.Bot.get_chat_administrators`
- Used for getting the list of admins in a chat
* - :meth:`~telegram.Bot.get_chat_member_count`
- Used for getting the number of members in a chat
* - :meth:`~telegram.Bot.get_chat_member`
- Used for getting a member of a chat
* - :meth:`~telegram.Bot.set_my_commands`
- Used for setting the list of commands
* - :meth:`~telegram.Bot.delete_my_commands`
- Used for deleting the list of commands
* - :meth:`~telegram.Bot.get_my_commands`
- Used for obtaining the list of commands
* - :meth:`~telegram.Bot.leave_chat`
- Used for leaving a chat
.. raw:: html
</details>
<br>
.. raw:: html
<details>
<summary>Stickerset management</summary>
.. list-table::
:align: left
:widths: 1 4
* - :meth:`~telegram.Bot.add_sticker_to_set`
- Used for adding a sticker to a set
* - :meth:`~telegram.Bot.delete_sticker_from_set`
- Used for deleting a sticker from a set
* - :meth:`~telegram.Bot.create_new_sticker_set`
- Used for creating a new sticker set
* - :meth:`~telegram.Bot.set_chat_sticker_set`
- Used for setting a sticker set
* - :meth:`~telegram.Bot.delete_chat_sticker_set`
- Used for deleting the set sticker set
* - :meth:`~telegram.Bot.set_sticker_position_in_set`
- Used for moving a sticker's position in the set
* - :meth:`~telegram.Bot.set_sticker_set_thumb`
- Used for setting the thumbnail of a sticker set
* - :meth:`~telegram.Bot.get_sticker_set`
- Used for getting a sticker set
* - :meth:`~telegram.Bot.upload_sticker_file`
- Used for uploading a sticker file
.. raw:: html
</details>
<br>
.. raw:: html
<details>
<summary>Games</summary>
.. list-table::
:align: left
:widths: 1 4
* - :meth:`~telegram.Bot.get_game_high_scores`
- Used for getting the game high scores
* - :meth:`~telegram.Bot.set_game_score`
- Used for setting the game score
.. raw:: html
</details>
<br>
.. raw:: html
<details>
<summary>Getting updates</summary>
.. list-table::
:align: left
:widths: 1 4
* - :meth:`~telegram.Bot.get_updates`
- Used for getting updates using long polling
* - :meth:`~telegram.Bot.get_webhook_info`
- Used for getting current webhook status
* - :meth:`~telegram.Bot.set_webhook`
- Used for setting a webhook to receive updates
* - :meth:`~telegram.Bot.delete_webhook`
- Used for removing webhook integration
.. raw:: html
</details>
<br>
.. raw:: html
<details>
<summary>Miscellaneous</summary>
.. list-table::
:align: left
:widths: 1 4
* - :meth:`~telegram.Bot.close`
- Used for closing server instance when switching to another local server
* - :meth:`~telegram.Bot.log_out`
- Used for logging out from cloud Bot API server
* - :meth:`~telegram.Bot.get_file`
- Used for getting basic info about a file
* - :meth:`~telegram.Bot.get_me`
- Used for getting basic information about the bot
.. raw:: html
</details>
<br>
.. raw:: html
<details>
<summary>Properties</summary>
.. list-table::
:align: left
:widths: 1 4
* - :attr:`~telegram.Bot.bot`
- The user instance of the bot as returned by :meth:`~telegram.Bot.get_me`
* - :attr:`~telegram.Bot.can_join_groups`
- Whether the bot can join groups
* - :attr:`~telegram.Bot.can_read_all_group_messages`
- Whether the bot can read all incoming group messages
* - :attr:`~telegram.Bot.id`
- The user id of the bot
* - :attr:`~telegram.Bot.name`
- The username of the bot, with leading ``@``
* - :attr:`~telegram.Bot.first_name`
- The first name of the bot
* - :attr:`~telegram.Bot.last_name`
- The last name of the bot
* - :attr:`~telegram.Bot.username`
- The username of the bot, without leading ``@``
* - :attr:`~telegram.Bot.link`
- The t.me link of the bot
* - :attr:`~telegram.Bot.supports_inline_queries`
- Whether the bot supports inline queries
.. raw:: html
</details>
<br>
<hr style="height:2px;border-width:0;color:gray;background-color:gray">

174
docs/source/conf.py
View file

@ -11,15 +11,18 @@
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import subprocess
import re
import sys
import os
import inspect
from enum import Enum
from pathlib import Path
from typing import 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
# documentation root, use os.path.abspath to make it absolute, like shown here.
import inspect
from docutils.nodes import Element
from sphinx.application import Sphinx
from sphinx.domains.python import PyXRefRole
@ -31,7 +34,7 @@ sys.path.insert(0, os.path.abspath('../..'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '4.2.0'
needs_sphinx = '4.3.2'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@ -39,7 +42,9 @@ needs_sphinx = '4.2.0'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.intersphinx'
'sphinx.ext.intersphinx',
'sphinx.ext.linkcode',
'sphinx_paramlinks',
]
# Use intersphinx to reference the python builtin library docs
@ -55,6 +60,13 @@ autodoc_typehints = 'none'
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# Fail on warnings & unresolved references etc
nitpicky = True
# Paramlink style
paramlinks_hyperlink_param = 'name'
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
@ -129,13 +141,21 @@ todo_include_todos = False
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'sphinx_rtd_theme'
html_theme = 'furo'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {
'style_external_links': True,
'navigation_with_keys': True,
'dark_css_variables': {'admonition-title-font-size': '0.95rem',
'admonition-font-size': '0.92rem'},
'light_css_variables': {'admonition-title-font-size': '0.95rem',
'admonition-font-size': '0.92rem'},
"announcement": 'PTB has undergone significant changes in v14. Please read the documentation '
'carefully and also check out the transition guide in the '
'<a href="https://github.com/python-telegram-bot/python-telegram-bot/wiki">'
'wiki</a>',
}
# Add any paths that contain custom themes here, relative to this directory.
@ -143,25 +163,27 @@ html_theme_options = {
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
html_title = f"python-telegram-bot<br>v{version}"
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = 'ptb-logo-orange.png'
html_logo = 'ptb-logo_1024.png'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
html_favicon = 'ptb-logo-orange.ico'
html_favicon = 'ptb-logo_1024.ico'
# Add any paths that contain custom static files (such as style sheets) here,
# 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']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
@ -386,7 +408,141 @@ def autodoc_skip_member(app, what, name, obj, skip, options):
return True # return True to exclude from docs.
# ------------------------------------------------------------------------------------------------
# This part is for getting the [source] links on the classes, methods etc link to the correct
# files & lines on github. Can be simplified once https://github.com/sphinx-doc/sphinx/issues/1556
# is closed
line_numbers = {}
file_root = Path(inspect.getsourcefile(telegram)).parent.parent.resolve()
import telegram.ext # Needed for checking if an object is a BaseFilter
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.
"""
# Ce can't properly handle ordinary attributes.
# In linkcode_resolve we'll resolve to the `__init__` or module instead
if what == 'attribute':
return
# Special casing for properties
if hasattr(obj, 'fget'):
obj = obj.fget
# Special casing for filters
if isinstance(obj, telegram.ext.filters.BaseFilter):
obj = obj.__class__
try:
source_lines, start_line = inspect.getsourcelines(obj)
end_line = start_line + len(source_lines)
file = Path(inspect.getsourcefile(obj)).relative_to(file_root)
line_numbers[name] = (file, start_line, end_line)
except Exception:
pass
# Since we don't document the `__init__`, we call this manually to have it available for
# attributes -- see the note above
if what == 'class':
autodoc_process_docstring(app, 'method', f'{name}.__init__', obj.__init__, options, lines)
def _git_branch() -> str:
"""Get's the current git sha if available or fall back to `master`"""
try:
output = subprocess.check_output( # skipcq: BAN-B607
["git", "describe", "--tags"], stderr=subprocess.STDOUT
)
return output.decode().strip()
except Exception:
return 'master'
git_branch = _git_branch()
base_url = "https://github.com/python-telegram-bot/python-telegram-bot/blob/"
def linkcode_resolve(_, info):
"""See www.sphinx-doc.org/en/master/usage/extensions/linkcode.html"""
combined = '.'.join((info['module'], info['fullname']))
# special casing for ExtBot which is due to the special structure of extbot.rst
combined = combined.replace('ExtBot.ExtBot', 'ExtBot')
line_info = line_numbers.get(combined)
if not line_info:
# Try the __init__
line_info = line_numbers.get(f"{combined.rsplit('.', 1)[0]}.__init__")
if not line_info:
# Try the class
line_info = line_numbers.get(f"{combined.rsplit('.', 1)[0]}")
if not line_info:
# Try the module
line_info = line_numbers.get(info['module'])
if not line_info:
return
file, start_line, end_line = line_info
return f"{base_url}{git_branch}/{file}#L{start_line}-L{end_line}"
# End of logic for the [source] links
# ------------------------------------------------------------------------------------------------
# Some base classes are implementation detail
# We want to instead show *their* base class
PRIVATE_BASE_CLASSES = {
'_ChatUserBaseFilter': 'MessageFilter',
'_Dice': 'MessageFilter',
'_BaseThumbedMedium': 'TelegramObject',
'_BaseMedium': 'TelegramObject',
'_CredentialsBase': 'TelegramObject',
}
def autodoc_process_bases(app, name, obj, option, bases: list):
"""Here we fine tune how the base class's classes are displayed."""
for idx, base in enumerate(bases):
# let's use a string representation of the object
base = str(base)
# Special case because base classes are in std lib:
if "_StringEnum" in base:
bases[idx] = ":class:`enum.Enum`"
bases.insert(0, ':class:`str`')
continue
# Drop generics (at least for now)
if base.endswith("]"):
base = base.split("[", maxsplit=1)[0]
bases[idx] = f':class:`{base}`'
# Now convert `telegram._message.Message` to `telegram.Message` etc
match = re.search(pattern=r"(telegram(\.ext|))\.", string=base)
if match and '_utils' not in base:
base = base.rstrip("'>")
parts = base.rsplit(".", maxsplit=2)
# Replace private base classes with their respective parent
parts[-1] = PRIVATE_BASE_CLASSES.get(parts[-1], parts[-1])
# To make sure that e.g. `telegram.ext.filters.BaseFilter` keeps the `filters` part
if not parts[-2].startswith('_') and '_' not in parts[0]:
base = '.'.join(parts[-2:])
else:
base = parts[-1]
# add `telegram(.ext).` back in front
base = f'{match.group(0)}{base}'
bases[idx] = f':class:`{base}`'
def setup(app: Sphinx):
app.add_css_file("dark.css")
app.connect('autodoc-skip-member', autodoc_skip_member)
app.connect('autodoc-process-bases', autodoc_process_bases)
app.connect('autodoc-process-docstring', autodoc_process_docstring)
app.add_role_to_domain('py', CONSTANTS_ROLE, TGConstXRefRole())

BIN
docs/source/ptb-logo_1024.ico Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.1 KiB

151
telegram/_bot.py
View file

@ -146,6 +146,8 @@ class Bot(TelegramObject):
private_key (:obj:`bytes`, optional): Private key for decryption of telegram passport data.
private_key_password (:obj:`bytes`, optional): Password for above private key.
.. include:: bot_methods.rst
"""
__slots__ = (
@ -429,7 +431,8 @@ class Bot(TelegramObject):
italic, fixed-width text or inline URLs in your bot's message. See the constants in
:class:`telegram.constants.ParseMode` for the available modes.
entities (List[:class:`telegram.MessageEntity`], optional): List of special entities
that appear in message text, which can be specified instead of :attr:`parse_mode`.
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
@ -498,11 +501,11 @@ class Bot(TelegramObject):
hours ago.
- Bots can delete outgoing messages in private chats, groups, and supergroups.
- Bots can delete incoming messages in private chats.
- Bots granted :attr:`telegram.ChatMember.can_post_messages` permissions can delete
outgoing messages in channels.
- Bots granted :attr:`~telegram.ChatMemberAdministrator.can_post_messages` permissions
can delete outgoing messages in channels.
- If the bot is an administrator of a group, it can delete any message there.
- If the bot has :attr:`telegram.ChatMember.can_delete_messages` permission in a
supergroup or a channel, it can delete any message there.
- If the bot has :attr:`~telegram.ChatMemberAdministrator.can_delete_messages`
permission in a supergroup or a channel, it can delete any message there.
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -617,7 +620,7 @@ class Bot(TelegramObject):
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
photo (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
photo (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
:class:`telegram.PhotoSize`): Photo to send.
Pass a file_id as String to send a photo that exists on the Telegram servers
(recommended), pass an HTTP URL as a String for Telegram to get a photo from the
@ -639,7 +642,7 @@ class Bot(TelegramObject):
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
:attr:`parse_mode`.
: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
@ -728,7 +731,7 @@ class Bot(TelegramObject):
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
audio (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
audio (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
:class:`telegram.Audio`): Audio file to send.
Pass a file_id as String to send an audio file that exists on the Telegram servers
(recommended), pass an HTTP URL as a String for Telegram to get an audio file from
@ -750,7 +753,7 @@ class Bot(TelegramObject):
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
:attr:`parse_mode`.
:paramref:`parse_mode`.
duration (:obj:`int`, optional): Duration of sent audio in seconds.
performer (:obj:`str`, optional): Performer.
title (:obj:`str`, optional): Track name.
@ -769,7 +772,7 @@ class Bot(TelegramObject):
: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.
thumb (`filelike object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail
thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail
of the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be
in JPEG format and less than 200 kB in size. A thumbnail's width and height should
@ -854,7 +857,7 @@ class Bot(TelegramObject):
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
document (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
document (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
:class:`telegram.Document`): File to send.
Pass a file_id as String to send a file that exists on the Telegram servers
(recommended), pass an HTTP URL as a String for Telegram to get a file from the
@ -876,7 +879,7 @@ class Bot(TelegramObject):
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
:attr:`parse_mode`.
: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
@ -892,7 +895,7 @@ class Bot(TelegramObject):
: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.
thumb (`filelike object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail
thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail
of the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be
in JPEG format and less than 200 kB in size. A thumbnail's width and height should
@ -963,7 +966,7 @@ class Bot(TelegramObject):
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
sticker (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
sticker (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
:class:`telegram.Sticker`): Sticker to send.
Pass a file_id as String to send a file that exists on the Telegram servers
(recommended), pass an HTTP URL as a String for Telegram to get a .webp file from
@ -1052,7 +1055,7 @@ class Bot(TelegramObject):
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
video (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
video (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
:class:`telegram.Video`): Video file to send.
Pass a file_id as String to send an video file that exists on the Telegram servers
(recommended), pass an HTTP URL as a String for Telegram to get an video file from
@ -1077,7 +1080,7 @@ class Bot(TelegramObject):
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
:attr:`parse_mode`.
:paramref:`parse_mode`.
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
@ -1095,7 +1098,7 @@ class Bot(TelegramObject):
: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.
thumb (`filelike object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail
thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail
of the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be
in JPEG format and less than 200 kB in size. A thumbnail's width and height should
@ -1179,7 +1182,7 @@ class Bot(TelegramObject):
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
video_note (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
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
servers (recommended) or upload a new video using multipart/form-data. Or you can
@ -1211,7 +1214,7 @@ class Bot(TelegramObject):
: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.
thumb (`filelike object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail
thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail
of the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be
in JPEG format and less than 200 kB in size. A thumbnail's width and height should
@ -1290,7 +1293,7 @@ class Bot(TelegramObject):
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
animation (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
animation (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
:class:`telegram.Animation`): Animation to
send. Pass a file_id as String to send an animation that exists on the Telegram
servers (recommended), pass an HTTP URL as a String for Telegram to get an
@ -1307,7 +1310,7 @@ class Bot(TelegramObject):
duration (:obj:`int`, optional): Duration of sent animation in seconds.
width (:obj:`int`, optional): Animation width.
height (:obj:`int`, optional): Animation height.
thumb (`filelike object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail
thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail
of the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be
in JPEG format and less than 200 kB in size. A thumbnail's width and height should
@ -1325,7 +1328,7 @@ class Bot(TelegramObject):
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
:attr:`parse_mode`.
: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
@ -1415,7 +1418,7 @@ class Bot(TelegramObject):
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
voice (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
voice (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
:class:`telegram.Voice`): Voice file to send.
Pass a file_id as String to send an voice file that exists on the Telegram servers
(recommended), pass an HTTP URL as a String for Telegram to get an voice file from
@ -1437,7 +1440,7 @@ class Bot(TelegramObject):
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
:attr:`parse_mode`.
:paramref:`parse_mode`.
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.
@ -1571,7 +1574,8 @@ class Bot(TelegramObject):
"""Use this method to send point on the map.
Note:
You can either supply a :obj:`latitude` and :obj:`longitude` or a :obj:`location`.
You can either supply a :paramref:`latitude` and :paramref:`longitude` or a
:paramref:`location`.
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -1676,7 +1680,8 @@ class Bot(TelegramObject):
expires or editing is explicitly disabled by a call to :meth:`stop_message_live_location`.
Note:
You can either supply a :obj:`latitude` and :obj:`longitude` or a :obj:`location`.
You can either supply a :paramref:`latitude` and :paramref:`longitude` or a
:paramref:`location`.
Args:
chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
@ -1819,10 +1824,11 @@ class Bot(TelegramObject):
"""Use this method to send information about a venue.
Note:
* You can either supply :obj:`venue`, or :obj:`latitude`, :obj:`longitude`,
:obj:`title` and :obj:`address` and optionally :obj:`foursquare_id` and
:obj:`foursquare_type` or optionally :obj:`google_place_id` and
:obj:`google_place_type`.
* You can either supply :paramref:`venue`, or :paramref:`latitude`,
:paramref:`longitude`,
:paramref:title` and :paramref:address` and optionally :paramref:`foursquare_id` and
:paramref:`foursquare_type` or optionally :paramref:`google_place_id` and
:paramref:`google_place_type`.
* Foursquare details and Google Place details are mutually exclusive. However, this
behaviour is undocumented and might be changed by Telegram.
@ -1935,8 +1941,9 @@ class Bot(TelegramObject):
"""Use this method to send phone contacts.
Note:
You can either supply :obj:`contact` or :obj:`phone_number` and :obj:`first_name`
with optionally :obj:`last_name` and optionally :obj:`vcard`.
You can either supply :paramref:`contact` or :paramref:`phone_number` and
:paramref:`first_name` with optionally :paramref:`last_name` and optionally
:paramref:`vcard`.
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -2207,14 +2214,16 @@ class Bot(TelegramObject):
:tg-const:`telegram.InlineQuery.MAX_RESULTS` results per query are allowed.
Warning:
In most use cases :attr:`current_offset` should not be passed manually. Instead of
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
``auto_pagination=True``, which will take care of passing the correct value.
:paramref:`telegram.InlineQuery.answer.auto_pagination` set to :obj:`True`, which will
take care of passing the correct value.
Args:
inline_query_id (:obj:`str`): Unique identifier for the answered query.
results (List[:class:`telegram.InlineQueryResult`] | Callable): A list of results for
the inline query. In case :attr:`current_offset` is passed, ``results`` may also be
the inline query. In case :paramref:`current_offset` is passed,
:paramref:`results` may also be
a callable that accepts the current page index starting from 0. It must return
either a list of :class:`telegram.InlineQueryResult` instances or :obj:`None` if
there are no more results.
@ -2229,15 +2238,15 @@ class Bot(TelegramObject):
exceed 64 bytes.
switch_pm_text (:obj:`str`, optional): If passed, clients will display a button with
specified text that switches the user to a private chat with the bot and sends the
bot a start message with the parameter ``switch_pm_parameter``.
switch_pm_parameter (:obj:`str`, optional): Deep-linking parameter for the /start
message sent to the bot when user presses the switch button.
bot a start message with the parameter :paramref:`switch_pm_parameter`.
switch_pm_parameter (:obj:`str`, optional): Deep-linking parameter for the
:guilabel:`/start` message sent to the bot when user presses the switch button.
1-:tg-const:`telegram.InlineQuery.MAX_SWITCH_PM_TEXT_LENGTH` characters,
only A-Z, a-z, 0-9, _ and - are allowed.
only ``A-Z``, ``a-z``, ``0-9``, ``_`` and ``-`` are allowed.
current_offset (:obj:`str`, optional): The :attr:`telegram.InlineQuery.offset` of
the inline query to answer. If passed, PTB will automatically take care of
the pagination for you, i.e. pass the correct ``next_offset`` and truncate the
results list/get the results from the callable you passed.
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.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout from the server (instead of the one specified during creation of
the connection pool).
@ -2504,7 +2513,7 @@ class Bot(TelegramObject):
via link, etc. The bot must be an administrator for this to work. By default, this method
guarantees that after the call the user is not a member of the chat, but will be able to
join it. So if the user is a member of the chat they will also be *removed* from the chat.
If you don't want this, use the parameter :attr:`only_if_banned`.
If you don't want this, use the parameter :paramref:`only_if_banned`.
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -2666,7 +2675,8 @@ class Bot(TelegramObject):
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.
entities (List[:class:`telegram.MessageEntity`], optional): List of special entities
that appear in message text, which can be specified instead of :attr:`parse_mode`.
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.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): An object for an
@ -2740,7 +2750,7 @@ class Bot(TelegramObject):
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
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): An object for an
inline keyboard.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
@ -3023,7 +3033,7 @@ class Bot(TelegramObject):
Args:
url (:obj:`str`): HTTPS url to send updates to. Use an empty string to remove webhook
integration.
certificate (:obj:`filelike`): Upload your public key certificate so that the root
certificate (:term:`file object`): Upload your public key certificate so that the root
certificate in use can be checked. See our self-signed guide for details.
(https://goo.gl/rw7w6Y)
ip_address (:obj:`str`, optional): The fixed IP address which will be used to send
@ -3056,7 +3066,7 @@ class Bot(TelegramObject):
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`.
:attr:`telegram.constants.SUPPORTED_WEBHOOK_PORTS`.
If you're having any trouble setting up webhooks, please check out this `guide to
Webhooks`_.
@ -3527,12 +3537,12 @@ class Bot(TelegramObject):
"""Use this method to send invoices.
Warning:
As of API 5.2 :attr:`start_parameter` is an optional argument and therefore the order
of the arguments had to be changed. Use keyword arguments to make sure that the
As of API 5.2 :paramref:`start_parameter` is an optional argument and therefore the
order of the arguments had to be changed. Use keyword arguments to make sure that the
arguments are passed correctly.
.. versionchanged:: 13.5
As of Bot API 5.2, the parameter :attr:`start_parameter` is optional.
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
@ -3690,8 +3700,8 @@ class Bot(TelegramObject):
"""
If you sent an invoice requesting a shipping address and the parameter ``is_flexible`` was
specified, the Bot API will send an :class:`telegram.Update` with a
:attr:`Update.shipping_query` field to the bot. Use this method to reply to shipping
queries.
:attr:`telegram.Update.shipping_query` field to the bot. Use this method to reply to
shipping queries.
Args:
shipping_query_id (:obj:`str`): Unique identifier for the query to be answered.
@ -3758,7 +3768,8 @@ class Bot(TelegramObject):
"""
Once the user has confirmed their payment and shipping details, the Bot API sends the final
confirmation in the form of an :class:`telegram.Update` with the field
:attr:`Update.pre_checkout_query`. Use this method to respond to such pre-checkout queries.
:attr:`telegram.Update.pre_checkout_query`. Use this method to respond to such pre-checkout
queries.
Note:
The Bot API must receive an answer within 10 seconds after the pre-checkout
@ -3975,7 +3986,7 @@ class Bot(TelegramObject):
"""
Use this method to set default chat permissions for all members. The bot must be an
administrator in the group or a supergroup for this to work and must have the
:attr:`telegram.ChatMember.can_restrict_members` admin rights.
:attr:`telegram.ChatMemberAdministrator.can_restrict_members` admin rights.
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username of
@ -4372,7 +4383,7 @@ class Bot(TelegramObject):
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format ``@channelusername``).
photo (`filelike object` | :obj:`bytes` | :class:`pathlib.Path`): New chat photo.
photo (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`): New chat photo.
.. versionchanged:: 13.2
Accept :obj:`bytes` as input.
@ -4516,8 +4527,8 @@ class Bot(TelegramObject):
"""
Use this method to add a message to the list of pinned messages in a chat. If the
chat is not a private chat, the bot must be an administrator in the chat for this to work
and must have the :attr:`telegram.ChatMember.can_pin_messages` admin right in a supergroup
or :attr:`telegram.ChatMember.can_edit_messages` admin right in a channel.
and must have the ``can_pin_messages`` admin right in a supergroup
or :attr:`telegram.ChatMemberAdministrator.can_edit_messages` admin right in a channel.
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -4560,8 +4571,9 @@ class Bot(TelegramObject):
"""
Use this method to remove a message from the list of pinned messages in a chat. If the
chat is not a private chat, the bot must be an administrator in the chat for this to work
and must have the :attr:`telegram.ChatMember.can_pin_messages` admin right in a
supergroup or :attr:`telegram.ChatMember.can_edit_messages` admin right in a channel.
and must have the ``can_pin_messages`` admin right in a
supergroup or :attr:`telegram.ChatMemberAdministrator.can_edit_messages` admin right in a
channel.
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -4600,8 +4612,9 @@ class Bot(TelegramObject):
"""
Use this method to clear the list of pinned messages in a chat. If the
chat is not a private chat, the bot must be an administrator in the chat for this
to work and must have the :attr:`telegram.ChatMember.can_pin_messages` admin right in a
supergroup or :attr:`telegram.ChatMember.can_edit_messages` admin right in a channel.
to work and must have the ``can_pin_messages`` admin right in a
supergroup or :attr:`telegram.ChatMemberAdministrator.can_edit_messages` admin right in a
channel.
Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -4674,7 +4687,7 @@ class Bot(TelegramObject):
Args:
user_id (:obj:`int`): User identifier of sticker file owner.
png_sticker (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path`):
png_sticker (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path`):
**PNG** image with the sticker, must be up to 512 kilobytes in size,
dimensions must not exceed 512px, and either width or height must be exactly 512px.
@ -4737,7 +4750,7 @@ class Bot(TelegramObject):
must end in "_by_<bot username>". <bot_username> is case insensitive.
1-64 characters.
title (:obj:`str`): Sticker set title, 1-64 characters.
png_sticker (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path`, \
png_sticker (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, \
optional): **PNG** image with the sticker,
must be up to 512 kilobytes in size, dimensions must not exceed 512px,
and either width or height must be exactly 512px. Pass a file_id as a String to
@ -4747,7 +4760,7 @@ class Bot(TelegramObject):
.. versionchanged:: 13.2
Accept :obj:`bytes` as input.
tgs_sticker (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path`, \
tgs_sticker (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, \
optional): **TGS** animation with the sticker, uploaded using multipart/form-data.
See https://core.telegram.org/stickers#animated-sticker-requirements for technical
requirements.
@ -4831,7 +4844,7 @@ class Bot(TelegramObject):
user_id (:obj:`int`): User identifier of created sticker set owner.
name (:obj:`str`): Sticker set name.
png_sticker (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path`, \
png_sticker (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, \
optional): **PNG** image with the sticker,
must be up to 512 kilobytes in size, dimensions must not exceed 512px,
and either width or height must be exactly 512px. Pass a file_id as a String to
@ -4841,7 +4854,7 @@ class Bot(TelegramObject):
.. versionchanged:: 13.2
Accept :obj:`bytes` as input.
tgs_sticker (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path`, \
tgs_sticker (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, \
optional): **TGS** animation with the sticker, uploaded using multipart/form-data.
See https://core.telegram.org/stickers#animated-sticker-requirements for technical
requirements.
@ -4970,7 +4983,7 @@ class Bot(TelegramObject):
Args:
name (:obj:`str`): Sticker set name
user_id (:obj:`int`): User identifier of created sticker set owner.
thumb (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path`, \
thumb (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, \
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
@ -5099,13 +5112,13 @@ class Bot(TelegramObject):
available modes.
explanation_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in message text, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
open_period (:obj:`int`, optional): Amount of time in seconds the poll will be active
after creation, 5-600. Can't be used together with :attr:`close_date`.
after creation, 5-600. Can't be used together with :paramref:`close_date`.
close_date (:obj:`int` | :obj:`datetime.datetime`, optional): Point in time (Unix
timestamp) when the poll will be automatically closed. Must be at least 5 and no
more than 600 seconds in the future. Can't be used together with
:attr:`open_period`.
:paramref:`open_period`.
For timezone naive :obj:`datetime.datetime` objects, the default timezone of the
bot will be used.
is_closed (:obj:`bool`, optional): Pass :obj:`True`, if the poll needs to be

8
telegram/_callbackquery.py
View file

@ -47,13 +47,14 @@ class CallbackQuery(TelegramObject):
considered equal, if their :attr:`id` is equal.
Note:
* In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
* In Python :keyword:`from` is a reserved word, :paramref:`from_user`
* Exactly one of the fields :attr:`data` or :attr:`game_short_name` will be present.
* After the user presses an inline button, Telegram clients will display a progress bar
until you call :attr:`answer`. It is, therefore, necessary to react
by calling :attr:`telegram.Bot.answer_callback_query` even if no notification to the user
is needed (e.g., without specifying any of the optional parameters).
* If you're using :attr:`Bot.arbitrary_callback_data`, :attr:`data` may be an instance
* If you're using :attr:`telegram.ext.ExtBot.arbitrary_callback_data`, :attr:`data` may be
an instance
of :class:`telegram.ext.InvalidCallbackData`. This will be the case, if the data
associated with the button triggering the :class:`telegram.CallbackQuery` was already
deleted or if :attr:`data` was manipulated by a malicious client.
@ -520,7 +521,8 @@ class CallbackQuery(TelegramObject):
*args, **kwargs)
For the documentation of the arguments, please see
:meth:`telegram.Bot.get_game_high_scores` and :meth:`telegram.Message.get_game_high_score`.
:meth:`telegram.Bot.get_game_high_scores` and
:meth:`telegram.Message.get_game_high_scores`.
Returns:
List[:class:`telegram.GameHighScore`]

6
telegram/_chat.py
View file

@ -1110,12 +1110,12 @@ class Chat(TelegramObject):
For the documentation of the arguments, please see :meth:`telegram.Bot.send_invoice`.
Warning:
As of API 5.2 :attr:`start_parameter` is an optional argument and therefore the order
of the arguments had to be changed. Use keyword arguments to make sure that the
As of API 5.2 :paramref:`start_parameter` is an optional argument and therefore the
order of the arguments had to be changed. Use keyword arguments to make sure that the
arguments are passed correctly.
.. versionchanged:: 13.5
As of Bot API 5.2, the parameter :attr:`start_parameter` is optional.
As of Bot API 5.2, the parameter :paramref:`start_parameter` is optional.
Returns:
:class:`telegram.Message`: On success, instance representing the message posted.

6
telegram/_chatmemberupdated.py
View file

@ -38,7 +38,7 @@ class ChatMemberUpdated(TelegramObject):
.. versionadded:: 13.4
Note:
In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
In Python :keyword:`from` is a reserved word, :paramref:`from_user`
Args:
chat (:class:`telegram.Chat`): Chat the user belongs to.
@ -148,8 +148,8 @@ class ChatMemberUpdated(TelegramObject):
.. versionadded:: 13.5
Returns:
Dict[:obj:`str`, Tuple[:obj:`obj`, :obj:`obj`]]: A dictionary mapping attribute names
to tuples of the form ``(old_value, new_value)``
Dict[:obj:`str`, Tuple[:class:`object`, :class:`object`]]: A dictionary mapping
attribute names to tuples of the form ``(old_value, new_value)``
"""
# we first get the names of the attributes that have changed
# user.to_dict() is unhashable, so that needs some special casing further down

2
telegram/_choseninlineresult.py
View file

@ -37,7 +37,7 @@ class ChosenInlineResult(TelegramObject):
considered equal, if their :attr:`result_id` is equal.
Note:
* In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
* In Python :keyword:`from` is a reserved word, :paramref:`from_user`
* It is necessary to enable inline feedback via `@Botfather <https://t.me/BotFather>`_ in
order to receive these objects in updates.

30
telegram/_files/file.py
View file

@ -102,24 +102,24 @@ class File(TelegramObject):
"""
Download this file. By default, the file is saved in the current working directory with its
original filename as reported by Telegram. If the file has no filename, it the file ID will
be used as filename. If a :attr:`custom_path` is supplied, it will be saved to that path
instead. If :attr:`out` is defined, the file contents will be saved to that object using
the ``out.write`` method.
be used as filename. If a :paramref:`custom_path` is supplied, it will be saved to that
path instead. If :paramref:`out` is defined, the file contents will be saved to that object
using the ``out.write`` method.
Note:
* :attr:`custom_path` and :attr:`out` are mutually exclusive.
* If neither :attr:`custom_path` nor :attr:`out` is provided and :attr:`file_path` is
the path of a local file (which is the case when a Bot API Server is running in
local mode), this method will just return the path.
* :paramref:`custom_path` and :paramref:`out` are mutually exclusive.
* If neither :paramref:`custom_path` nor :paramref:`out` is provided and
:attr:`file_path` is the path of a local file (which is the case when a Bot API
Server is running in local mode), this method will just return the path.
.. versionchanged:: 14.0
* ``custom_path`` parameter now also accepts :obj:`pathlib.Path` as argument.
* Returns :obj:`pathlib.Path` object in cases where previously a :obj:`str` was
* :paramref:`custom_path` parameter now also accepts :class:`pathlib.Path` as argument.
* Returns :class:`pathlib.Path` object in cases where previously a :obj:`str` was
returned.
Args:
custom_path (:obj:`pathlib.Path` | :obj:`str`, optional): Custom path.
custom_path (:class:`pathlib.Path` | :obj:`str`, optional): Custom path.
out (:obj:`io.BufferedWriter`, optional): A file-like object. Must be opened for
writing in binary mode, if applicable.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
@ -127,12 +127,12 @@ class File(TelegramObject):
the connection pool).
Returns:
:obj:`pathlib.Path` | :obj:`io.BufferedWriter`: The same object as :attr:`out` if
:class:`pathlib.Path` | :obj:`io.BufferedWriter`: The same object as :paramref:`out` if
specified. Otherwise, returns the filename downloaded to or the file path of the
local file.
Raises:
ValueError: If both :attr:`custom_path` and :attr:`out` are passed.
ValueError: If both :paramref:`custom_path` and :paramref:`out` are passed.
"""
if custom_path is not None and out is not None:
@ -184,15 +184,15 @@ class File(TelegramObject):
)
)
def download_as_bytearray(self, buf: bytearray = None) -> bytes:
def download_as_bytearray(self, buf: bytearray = None) -> bytearray:
"""Download this file and return it as a bytearray.
Args:
buf (:obj:`bytearray`, optional): Extend the given bytearray with the downloaded data.
Returns:
:obj:`bytearray`: The same object as :attr:`buf` if it was specified. Otherwise a newly
allocated :obj:`bytearray`.
:obj:`bytearray`: The same object as :paramref:`buf` if it was specified. Otherwise a
newly allocated :obj:`bytearray`.
"""
if buf is None:

2
telegram/_files/inputfile.py
View file

@ -34,7 +34,7 @@ class InputFile:
"""This object represents a Telegram InputFile.
Args:
obj (:obj:`File handler` | :obj:`bytes`): An open file descriptor or the files content as
obj (:term:`file object` | :obj:`bytes`): An open file descriptor or the files content as
bytes.
filename (:obj:`str`, optional): Filename for this InputFile.
attach (:obj:`bool`, optional): Whether this should be send as one file or is part of a

24
telegram/_files/inputmedia.py
View file

@ -43,12 +43,12 @@ class InputMedia(TelegramObject):
Base class for Telegram InputMedia Objects.
.. versionchanged:: 14.0:
Added arguments and attributes :attr:`media_type`, :attr:`media`, :attr:`caption`,
:attr:`caption_entities`, :attr:`parse_mode`.
Added arguments and attributes :attr:`type`, :attr:`media`, :attr:`caption`,
:attr:`caption_entities`, :paramref:`parse_mode`.
Args:
media_type (:obj:`str`) Type of media that the instance represents.
media (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
:class:`telegram.Animation` | :class:`telegram.Audio` | \
:class:`telegram.Document` | :class:`telegram.PhotoSize` | \
:class:`telegram.Video`):
@ -114,7 +114,7 @@ class InputMediaAnimation(InputMedia):
arguments.
Args:
media (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
:class:`telegram.Animation`): File to send. Pass a
file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP
URL for Telegram to get a file from the Internet. Lastly you can pass an existing
@ -127,7 +127,7 @@ class InputMediaAnimation(InputMedia):
:obj:`tempfile` module.
.. versionadded:: 13.1
thumb (`filelike object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail of
thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail of
the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be
in JPEG format and less than 200 kB in size. A thumbnail's width and height should
@ -195,7 +195,7 @@ class InputMediaPhoto(InputMedia):
"""Represents a photo to be sent.
Args:
media (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
:class:`telegram.PhotoSize`): File to send. Pass a
file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP
URL for Telegram to get a file from the Internet. Lastly you can pass an existing
@ -253,7 +253,7 @@ class InputMediaVideo(InputMedia):
by Telegram.
Args:
media (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
:class:`telegram.Video`): File to send. Pass a
file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP
URL for Telegram to get a file from the Internet. Lastly you can pass an existing
@ -279,7 +279,7 @@ class InputMediaVideo(InputMedia):
duration (:obj:`int`, optional): Video duration in seconds.
supports_streaming (:obj:`bool`, optional): Pass :obj:`True`, if the uploaded video is
suitable for streaming.
thumb (`filelike object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail of
thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail of
the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be
in JPEG format and less than 200 kB in size. A thumbnail's width and height should
@ -346,7 +346,7 @@ class InputMediaAudio(InputMedia):
optional arguments.
Args:
media (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
:class:`telegram.Audio`):
File to send. Pass a
file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP
@ -372,7 +372,7 @@ class InputMediaAudio(InputMedia):
performer (:obj:`str`, optional): Performer of the audio as defined by sender or by audio
tags.
title (:obj:`str`, optional): Title of the audio as defined by sender or by audio tags.
thumb (`filelike object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail of
thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail of
the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be
in JPEG format and less than 200 kB in size. A thumbnail's width and height should
@ -430,7 +430,7 @@ class InputMediaDocument(InputMedia):
"""Represents a general file to be sent.
Args:
media (:obj:`str` | `filelike object` | :obj:`bytes` | :class:`pathlib.Path` | \
media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
:class:`telegram.Document`): File to send. Pass a
file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP
URL for Telegram to get a file from the Internet. Lastly you can pass an existing
@ -451,7 +451,7 @@ class InputMediaDocument(InputMedia):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of parse_mode.
thumb (`filelike object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail of
thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail of
the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be
in JPEG format and less than 200 kB in size. A thumbnail's width and height should

2
telegram/_files/sticker.py
View file

@ -60,7 +60,7 @@ class Sticker(_BaseThumbedMedium):
position where the mask should be placed.
file_size (:obj:`int`, optional): File size in bytes.
bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
**kwargs (obj:`dict`): Arbitrary keyword arguments.
_kwargs (:obj:`dict`): Arbitrary keyword arguments.
Attributes:
file_id (:obj:`str`): Identifier for this file.

8
telegram/_inline/inlinekeyboardbutton.py
View file

@ -66,9 +66,9 @@ class InlineKeyboardButton(TelegramObject):
You can now mention a user using ``tg://user?id=<user_id>``.
login_url (:class:`telegram.LoginUrl`, optional): An HTTP URL used to automatically
authorize the user. Can be used as a replacement for the Telegram Login Widget.
callback_data (:obj:`str` | :obj:`Any`, optional): Data to be sent in a callback query to
the bot when button is pressed, UTF-8 1-64 bytes. If the bot instance allows arbitrary
callback data, anything can be passed.
callback_data (:obj:`str` | :obj:`object`, optional): Data to be sent in a callback query
to the bot when button is pressed, UTF-8 1-64 bytes. If the bot instance allows
arbitrary callback data, anything can be passed.
switch_inline_query (:obj:`str`, optional): If set, pressing the button will prompt the
user to select one of their chats, open that chat and insert the bot's username and the
specified inline query in the input field. Can be empty, in which case just the bot's
@ -170,7 +170,7 @@ class InlineKeyboardButton(TelegramObject):
.. versionadded:: 13.6
Args:
callback_data (:obj:`obj`): The new callback data.
callback_data (:class:`object`): The new callback data.
"""
self.callback_data = callback_data
self._set_id_attrs()

8
telegram/_inline/inlinequery.py
View file

@ -38,7 +38,7 @@ class InlineQuery(TelegramObject):
considered equal, if their :attr:`id` is equal.
Note:
In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
In Python :keyword:`from` is a reserved word, :paramref:`from_user`
Args:
id (:obj:`str`): Unique identifier for this query.
@ -142,11 +142,13 @@ class InlineQuery(TelegramObject):
Args:
auto_pagination (:obj:`bool`, optional): If set to :obj:`True`, :attr:`offset` will be
passed as :attr:`current_offset` to :meth:`telegram.Bot.answer_inline_query`.
passed as :paramref:`current_offset` to :meth:`telegram.Bot.answer_inline_query`.
Defaults to :obj:`False`.
Raises:
ValueError: If both :attr:`current_offset` and :attr:`auto_pagination` are supplied.
ValueError: If both
:paramref:`~telegram.Bot.answer_inline_query.current_offset` and
:paramref:`auto_pagination` are supplied.
"""
if current_offset and auto_pagination:
raise ValueError('current_offset and auto_pagination are mutually exclusive!')

4
telegram/_inline/inlinequeryresultaudio.py
View file

@ -49,7 +49,7 @@ class InlineQueryResultAudio(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@ -71,7 +71,7 @@ class InlineQueryResultAudio(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

4
telegram/_inline/inlinequeryresultcachedaudio.py
View file

@ -46,7 +46,7 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@ -65,7 +65,7 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

4
telegram/_inline/inlinequeryresultcacheddocument.py
View file

@ -49,7 +49,7 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@ -70,7 +70,7 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

4
telegram/_inline/inlinequeryresultcachedgif.py
View file

@ -48,7 +48,7 @@ class InlineQueryResultCachedGif(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@ -68,7 +68,7 @@ class InlineQueryResultCachedGif(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

4
telegram/_inline/inlinequeryresultcachedmpeg4gif.py
View file

@ -48,7 +48,7 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@ -68,7 +68,7 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

4
telegram/_inline/inlinequeryresultcachedphoto.py
View file

@ -50,7 +50,7 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@ -71,7 +71,7 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

4
telegram/_inline/inlinequeryresultcachedvideo.py
View file

@ -49,7 +49,7 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@ -70,7 +70,7 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

4
telegram/_inline/inlinequeryresultcachedvoice.py
View file

@ -47,7 +47,7 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@ -67,7 +67,7 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

4
telegram/_inline/inlinequeryresultdocument.py
View file

@ -47,7 +47,7 @@ class InlineQueryResultDocument(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
document_url (:obj:`str`): A valid URL for the file.
mime_type (:obj:`str`): Mime type of the content of the file, either "application/pdf"
or "application/zip".
@ -73,7 +73,7 @@ class InlineQueryResultDocument(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
document_url (:obj:`str`): A valid URL for the file.
mime_type (:obj:`str`): Mime type of the content of the file, either "application/pdf"
or "application/zip".

4
telegram/_inline/inlinequeryresultgif.py
View file

@ -55,7 +55,7 @@ class InlineQueryResultGif(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@ -81,7 +81,7 @@ class InlineQueryResultGif(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

4
telegram/_inline/inlinequeryresultmpeg4gif.py
View file

@ -54,7 +54,7 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@ -80,7 +80,7 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

4
telegram/_inline/inlinequeryresultphoto.py
View file

@ -52,7 +52,7 @@ class InlineQueryResultPhoto(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@ -77,7 +77,7 @@ class InlineQueryResultPhoto(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
to the message.
input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

4
telegram/_inline/inlinequeryresultvideo.py
View file

@ -54,7 +54,7 @@ class InlineQueryResultVideo(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
video_width (:obj:`int`, optional): Video width.
video_height (:obj:`int`, optional): Video height.
video_duration (:obj:`int`, optional): Video duration in seconds.
@ -82,7 +82,7 @@ class InlineQueryResultVideo(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
video_width (:obj:`int`): Optional. Video width.
video_height (:obj:`int`): Optional. Video height.
video_duration (:obj:`int`): Optional. Video duration in seconds.

4
telegram/_inline/inlinequeryresultvoice.py
View file

@ -48,7 +48,7 @@ class InlineQueryResultVoice(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
voice_duration (:obj:`int`, optional): Recording duration in seconds.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message.
@ -69,7 +69,7 @@ class InlineQueryResultVoice(InlineQueryResult):
in :class:`telegram.constants.ParseMode` for the available modes.
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
voice_duration (:obj:`int`): Optional. Recording duration in seconds.
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
to the message.

4
telegram/_inline/inputtextmessagecontent.py
View file

@ -41,7 +41,7 @@ class InputTextMessageContent(InputMessageContent):
in :class:`telegram.constants.ParseMode` for the available modes.
entities (List[:class:`telegram.MessageEntity`], optional): List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in the
sent message.
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
@ -55,7 +55,7 @@ class InputTextMessageContent(InputMessageContent):
in :class:`telegram.constants.ParseMode` for the available modes.
entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
entities that appear in the caption, which can be specified instead of
:attr:`parse_mode`.
:paramref:`parse_mode`.
disable_web_page_preview (:obj:`bool`): Optional. Disables link previews for links in the
sent message.

10
telegram/_message.py
View file

@ -81,7 +81,7 @@ class Message(TelegramObject):
considered equal, if their :attr:`message_id` and :attr:`chat` are equal.
Note:
In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
In Python :keyword:`from` is a reserved word, :paramref:`from_user`
Args:
message_id (:obj:`int`): Unique message identifier inside this chat.
@ -305,7 +305,7 @@ class Message(TelegramObject):
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.
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.
@ -1761,14 +1761,14 @@ class Message(TelegramObject):
For the documentation of the arguments, please see :meth:`telegram.Bot.send_invoice`.
Warning:
As of API 5.2 :attr:`start_parameter` is an optional argument and therefore the order
of the arguments had to be changed. Use keyword arguments to make sure that the
As of API 5.2 :paramref:`start_parameter` is an optional argument and therefore the
order of the arguments had to be changed. Use keyword arguments to make sure that the
arguments are passed correctly.
.. versionadded:: 13.2
.. versionchanged:: 13.5
As of Bot API 5.2, the parameter :attr:`start_parameter` is optional.
As of Bot API 5.2, the parameter :paramref:`start_parameter` is optional.
Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the invoice is sent as an actual

4
telegram/_passport/credentials.py
View file

@ -159,7 +159,7 @@ class EncryptedCredentials(TelegramObject):
:obj:`str`: Lazily decrypt and return secret.
Raises:
telegram.PassportDecryptionError: Decryption failed. Usually due to bad
telegram.error.PassportDecryptionError: Decryption failed. Usually due to bad
private/public key but can also suggest malformed/tampered data.
"""
if self._decrypted_secret is None:
@ -192,7 +192,7 @@ class EncryptedCredentials(TelegramObject):
`decrypted_data.nonce`.
Raises:
telegram.PassportDecryptionError: Decryption failed. Usually due to bad
telegram.error.PassportDecryptionError: Decryption failed. Usually due to bad
private/public key but can also suggest malformed/tampered data.
"""
if self._decrypted_data is None:

4
telegram/_passport/encryptedpassportelement.py
View file

@ -54,7 +54,7 @@ class EncryptedPassportElement(TelegramObject):
"email".
hash (:obj:`str`): Base64-encoded element hash for using in
:class:`telegram.PassportElementErrorUnspecified`.
data (:class:`telegram.PersonalDetails` | :class:`telegram.IdDocument` | \
data (:class:`telegram.PersonalDetails` | :class:`telegram.IdDocumentData` | \
:class:`telegram.ResidentialAddress` | :obj:`str`, optional):
Decrypted or encrypted data, available for "personal_details", "passport",
"driver_license", "identity_card", "identity_passport" and "address" types.
@ -89,7 +89,7 @@ class EncryptedPassportElement(TelegramObject):
"email".
hash (:obj:`str`): Base64-encoded element hash for using in
:class:`telegram.PassportElementErrorUnspecified`.
data (:class:`telegram.PersonalDetails` | :class:`telegram.IdDocument` | \
data (:class:`telegram.PersonalDetails` | :class:`telegram.IdDocumentData` | \
:class:`telegram.ResidentialAddress` | :obj:`str`):
Optional. Decrypted or encrypted data, available for "personal_details", "passport",
"driver_license", "identity_card", "identity_passport" and "address" types.

8
telegram/_passport/passportdata.py
View file

@ -32,9 +32,9 @@ class PassportData(TelegramObject):
Note:
To be able to decrypt this object, you must pass your ``private_key`` to either
:class:`telegram.Updater` or :class:`telegram.Bot`. Decrypted data is then found in
:class:`telegram.ext.Updater` or :class:`telegram.Bot`. Decrypted data is then found in
:attr:`decrypted_data` and the payload can be found in :attr:`decrypted_credentials`'s
attribute :attr:`telegram.Credentials.payload`.
attribute :attr:`telegram.Credentials.nonce`.
Args:
data (List[:class:`telegram.EncryptedPassportElement`]): Array with encrypted information
@ -95,7 +95,7 @@ class PassportData(TelegramObject):
about documents and other Telegram Passport elements which were shared with the bot.
Raises:
telegram.PassportDecryptionError: Decryption failed. Usually due to bad
telegram.error.PassportDecryptionError: Decryption failed. Usually due to bad
private/public key but can also suggest malformed/tampered data.
"""
if self._decrypted_data is None:
@ -115,7 +115,7 @@ class PassportData(TelegramObject):
`decrypted_data.payload`.
Raises:
telegram.PassportDecryptionError: Decryption failed. Usually due to bad
telegram.error.PassportDecryptionError: Decryption failed. Usually due to bad
private/public key but can also suggest malformed/tampered data.
"""
return self.credentials.decrypted_data

36
telegram/_passport/passportelementerrors.py
View file

@ -62,8 +62,8 @@ class PassportElementErrorDataField(PassportElementError):
considered resolved when the field's value changes.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`source`, :attr:`type`, :attr:`field_name`, :attr:`data_hash`
and :attr:`message` are equal.
considered equal, if their :attr:`~telegram.PassportElementError.source`, :attr:`type`,
:attr:`field_name`, :attr:`data_hash` and :attr:`message` are equal.
Args:
type (:obj:`str`): The section of the user's Telegram Passport which has the error, one of
@ -101,8 +101,8 @@ class PassportElementErrorFile(PassportElementError):
the document scan changes.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`source`, :attr:`type`, :attr:`file_hash`, and
:attr:`message` are equal.
considered equal, if their :attr:`~telegram.PassportElementError.source`, :attr:`type`,
:attr:`file_hash`, and :attr:`message` are equal.
Args:
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
@ -137,8 +137,8 @@ class PassportElementErrorFiles(PassportElementError):
files with the document scans changes.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`source`, :attr:`type`, :attr:`file_hashes`, and
:attr:`message` are equal.
considered equal, if their :attr:`~telegram.PassportElementError.source`, :attr:`type`,
:attr:`file_hashes`, and :attr:`message` are equal.
Args:
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
@ -173,8 +173,8 @@ class PassportElementErrorFrontSide(PassportElementError):
the file with the front side of the document changes.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`source`, :attr:`type`, :attr:`file_hash`, and
:attr:`message` are equal.
considered equal, if their :attr:`~telegram.PassportElementError.source`, :attr:`type`,
:attr:`file_hash`, and :attr:`message` are equal.
Args:
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
@ -209,8 +209,8 @@ class PassportElementErrorReverseSide(PassportElementError):
the file with the reverse side of the document changes.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`source`, :attr:`type`, :attr:`file_hash`, and
:attr:`message` are equal.
considered equal, if their :attr:`~telegram.PassportElementError.source`, :attr:`type`,
:attr:`file_hash`, and :attr:`message` are equal.
Args:
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
@ -245,8 +245,8 @@ class PassportElementErrorSelfie(PassportElementError):
the file with the selfie changes.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`source`, :attr:`type`, :attr:`file_hash`, and
:attr:`message` are equal.
considered equal, if their :attr:`~telegram.PassportElementError.source`, :attr:`type`,
:attr:`file_hash`, and :attr:`message` are equal.
Args:
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
@ -279,8 +279,8 @@ class PassportElementErrorTranslationFile(PassportElementError):
The error is considered resolved when the file changes.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`source`, :attr:`type`, :attr:`file_hash`, and
:attr:`message` are equal.
considered equal, if their :attr:`~telegram.PassportElementError.source`, :attr:`type`,
:attr:`file_hash`, and :attr:`message` are equal.
Args:
type (:obj:`str`): Type of element of the user's Telegram Passport which has the issue,
@ -317,8 +317,8 @@ class PassportElementErrorTranslationFiles(PassportElementError):
resolved when a file with the document translation changes.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`source`, :attr:`type`, :attr:`file_hashes`, and
:attr:`message` are equal.
considered equal, if their :attr:`~telegram.PassportElementError.source`, :attr:`type`,
:attr:`file_hashes`, and :attr:`message` are equal.
Args:
type (:obj:`str`): Type of element of the user's Telegram Passport which has the issue,
@ -355,8 +355,8 @@ class PassportElementErrorUnspecified(PassportElementError):
data is added.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`source`, :attr:`type`, :attr:`element_hash`,
and :attr:`message` are equal.
considered equal, if their :attr:`~telegram.PassportElementError.source`, :attr:`type`,
:attr:`element_hash`, and :attr:`message` are equal.
Args:
type (:obj:`str`): Type of element of the user's Telegram Passport which has the issue.

4
telegram/_payment/invoice.py
View file

@ -27,7 +27,7 @@ class Invoice(TelegramObject):
"""This object contains basic information about an invoice.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`title`, :attr:`description`, :attr:`start_parameter`,
considered equal, if their :attr:`title`, :attr:`description`, :paramref:`start_parameter`,
:attr:`currency` and :attr:`total_amount` are equal.
Args:
@ -38,7 +38,7 @@ class Invoice(TelegramObject):
currency (:obj:`str`): Three-letter ISO 4217 currency code.
total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not
float/double). For example, for a price of US$ 1.45 pass ``amount = 145``. See the
:obj:`exp` parameter in
``exp`` parameter in
`currencies.json <https://core.telegram.org/bots/payments/currencies.json>`_,
it shows the number of digits past the decimal point for each currency
(2 for the majority of currencies).

2
telegram/_payment/labeledprice.py
View file

@ -33,7 +33,7 @@ class LabeledPrice(TelegramObject):
label (:obj:`str`): Portion label.
amount (:obj:`int`): Price of the product in the smallest units of the currency (integer,
not float/double). For example, for a price of US$ 1.45 pass ``amount = 145``.
See the :obj:`exp` parameter in
See the ``exp`` parameter in
`currencies.json <https://core.telegram.org/bots/payments/currencies.json>`_,
it shows the number of digits past the decimal point for each currency
(2 for the majority of currencies).

4
telegram/_payment/precheckoutquery.py
View file

@ -35,7 +35,7 @@ class PreCheckoutQuery(TelegramObject):
considered equal, if their :attr:`id` is equal.
Note:
In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
In Python :keyword:`from` is a reserved word, :paramref:`from_user`
Args:
id (:obj:`str`): Unique query identifier.
@ -43,7 +43,7 @@ class PreCheckoutQuery(TelegramObject):
currency (:obj:`str`): Three-letter ISO 4217 currency code.
total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not
float/double). For example, for a price of US$ 1.45 pass ``amount = 145``.
See the :obj:`exp` parameter in
See the ``exp`` parameter in
`currencies.json <https://core.telegram.org/bots/payments/currencies.json>`_,
it shows the number of digits past the decimal point for each currency
(2 for the majority of currencies).

2
telegram/_payment/shippingaddress.py
View file

@ -28,7 +28,7 @@ class ShippingAddress(TelegramObject):
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`country_code`, :attr:`state`, :attr:`city`,
:attr:`street_line1`, :attr:`street_line2` and :attr:`post_cod` are equal.
:attr:`street_line1`, :attr:`street_line2` and :attr:`post_code` are equal.
Args:
country_code (:obj:`str`): ISO 3166-1 alpha-2 country code.

2
telegram/_payment/shippingquery.py
View file

@ -35,7 +35,7 @@ class ShippingQuery(TelegramObject):
considered equal, if their :attr:`id` is equal.
Note:
In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
In Python :keyword:`from` is a reserved word, :paramref:`from_user`
Args:
id (:obj:`str`): Unique query identifier.

2
telegram/_payment/successfulpayment.py
View file

@ -38,7 +38,7 @@ class SuccessfulPayment(TelegramObject):
currency (:obj:`str`): Three-letter ISO 4217 currency code.
total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not
float/double). For example, for a price of US$ 1.45 pass ``amount = 145``.
See the :obj:`exp` parameter in
See the ``exp`` parameter in
`currencies.json <https://core.telegram.org/bots/payments/currencies.json>`_,
it shows the number of digits past the decimal point for each currency
(2 for the majority of currencies).

2
telegram/_poll.py
View file

@ -65,7 +65,7 @@ class PollAnswer(TelegramObject):
This object represents an answer of a user in a non-anonymous poll.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`poll_id`, :attr:`user` and :attr:`options_ids` are equal.
considered equal, if their :attr:`poll_id`, :attr:`user` and :attr:`option_ids` are equal.
Args:
poll_id (:obj:`str`): Unique poll identifier.

6
telegram/_user.py
View file

@ -701,12 +701,12 @@ class User(TelegramObject):
For the documentation of the arguments, please see :meth:`telegram.Bot.send_invoice`.
Warning:
As of API 5.2 :attr:`start_parameter` is an optional argument and therefore the order
of the arguments had to be changed. Use keyword arguments to make sure that the
As of API 5.2 :paramref:`start_parameter` is an optional argument and therefore the
order of the arguments had to be changed. Use keyword arguments to make sure that the
arguments are passed correctly.
.. versionchanged:: 13.5
As of Bot API 5.2, the parameter :attr:`start_parameter` is optional.
As of Bot API 5.2, the parameter :paramref:`start_parameter` is optional.
Returns:
:class:`telegram.Message`: On success, instance representing the message posted.

4
telegram/_utils/defaultvalue.py
View file

@ -74,10 +74,10 @@ class DefaultValue(Generic[DVType]):
``f'DefaultValue({value})'``.
Args:
value (:obj:`obj`): The value of the default argument
value (:class:`object`): The value of the default argument
Attributes:
value (:obj:`obj`): The value of the default argument
value (:class:`object`): The value of the default argument
"""

2
telegram/_utils/files.py
View file

@ -72,7 +72,7 @@ def parse_file_input(
attribute.
Args:
file_input (:obj:`str` | :obj:`bytes` | `filelike object` | Telegram media object): The
file_input (:obj:`str` | :obj:`bytes` | :term:`file object` | Telegram media object): The
input to parse.
tg_type (:obj:`type`, optional): The Telegram media type the input can be. E.g.
:class:`telegram.Animation`.

122
telegram/constants.py
View file

@ -122,7 +122,7 @@ class CallbackQueryLimit(IntEnum):
ANSWER_CALLBACK_QUERY_TEXT_LENGTH = 200
""":obj:`int`: Maximum number of characters for the ``text`` parameter of
:meth:`Bot.answer_callback_query`."""
:meth:`telegram.Bot.answer_callback_query`."""
class ChatAction(_StringEnum):
@ -171,23 +171,23 @@ class ChatID(IntEnum):
""":obj:`int`: User ID in groups for messages sent by anonymous admins.
Note:
:attr:`Message.from_user` will contain this ID for backwards compatibility only. It's
recommended to use :attr:`Message.sender_chat` instead.
:attr:`telegram.Message.from_user` will contain this ID for backwards compatibility only.
It's recommended to use :attr:`telegram.Message.sender_chat` instead.
"""
SERVICE_CHAT = 777000
""":obj:`int`: Telegram service chat, that also acts as sender of channel posts forwarded to
discussion groups.
Note:
:attr:`Message.from_user` will contain this ID for backwards compatibility only. It's
recommended to use :attr:`Message.sender_chat` instead.
:attr:`telegram.Message.from_user` will contain this ID for backwards compatibility only.
It's recommended to use :attr:`telegram.Message.sender_chat` instead.
"""
FAKE_CHANNEL = 136817688
""":obj:`int`: User ID in groups when message is sent on behalf of a channel.
Note:
* :attr:`Message.from_user` will contain this ID for backwards compatibility only. It's
recommended to use :attr:`Message.sender_chat` instead.
* :attr:`telegram.Message.from_user` will contain this ID for backwards compatibility only.
It's recommended to use :attr:`telegram.Message.sender_chat` instead.
* This value is undocumented and might be changed by Telegram.
"""
@ -377,10 +377,10 @@ class InlineQueryLimit(IntEnum):
RESULTS = 50
""":obj:`int`: Maximum number of results that can be passed to
:meth:`Bot.answer_inline_query`."""
:meth:`telegram.Bot.answer_inline_query`."""
SWITCH_PM_TEXT_LENGTH = 64
""":obj:`int`: Maximum number of characters for the ``switch_pm_text`` parameter of
:meth:`Bot.answer_inline_query`."""
:meth:`telegram.Bot.answer_inline_query`."""
class InlineQueryResultType(_StringEnum):
@ -490,39 +490,39 @@ class MessageAttachmentType(_StringEnum):
# (Enums are not extendable)
ANIMATION = 'animation'
""":obj:`str`: Messages with :attr:`Message.animation`."""
""":obj:`str`: Messages with :attr:`telegram.Message.animation`."""
AUDIO = 'audio'
""":obj:`str`: Messages with :attr:`Message.audio`."""
""":obj:`str`: Messages with :attr:`telegram.Message.audio`."""
CONTACT = 'contact'
""":obj:`str`: Messages with :attr:`Message.contact`."""
""":obj:`str`: Messages with :attr:`telegram.Message.contact`."""
DICE = 'dice'
""":obj:`str`: Messages with :attr:`Message.dice`."""
""":obj:`str`: Messages with :attr:`telegram.Message.dice`."""
DOCUMENT = 'document'
""":obj:`str`: Messages with :attr:`Message.document`."""
""":obj:`str`: Messages with :attr:`telegram.Message.document`."""
GAME = 'game'
""":obj:`str`: Messages with :attr:`Message.game`."""
""":obj:`str`: Messages with :attr:`telegram.Message.game`."""
INVOICE = 'invoice'
""":obj:`str`: Messages with :attr:`Message.invoice`."""
""":obj:`str`: Messages with :attr:`telegram.Message.invoice`."""
LOCATION = 'location'
""":obj:`str`: Messages with :attr:`Message.location`."""
""":obj:`str`: Messages with :attr:`telegram.Message.location`."""
PASSPORT_DATA = 'passport_data'
""":obj:`str`: Messages with :attr:`Message.passport_data`."""
""":obj:`str`: Messages with :attr:`telegram.Message.passport_data`."""
PHOTO = 'photo'
""":obj:`str`: Messages with :attr:`Message.photo`."""
""":obj:`str`: Messages with :attr:`telegram.Message.photo`."""
POLL = 'poll'
""":obj:`str`: Messages with :attr:`Message.poll`."""
""":obj:`str`: Messages with :attr:`telegram.Message.poll`."""
STICKER = 'sticker'
""":obj:`str`: Messages with :attr:`Message.sticker`."""
""":obj:`str`: Messages with :attr:`telegram.Message.sticker`."""
SUCCESSFUL_PAYMENT = 'successful_payment'
""":obj:`str`: Messages with :attr:`Message.successful_payment`."""
""":obj:`str`: Messages with :attr:`telegram.Message.successful_payment`."""
VIDEO = 'video'
""":obj:`str`: Messages with :attr:`Message.video`."""
""":obj:`str`: Messages with :attr:`telegram.Message.video`."""
VIDEO_NOTE = 'video_note'
""":obj:`str`: Messages with :attr:`Message.video_note`."""
""":obj:`str`: Messages with :attr:`telegram.Message.video_note`."""
VOICE = 'voice'
""":obj:`str`: Messages with :attr:`Message.voice`."""
""":obj:`str`: Messages with :attr:`telegram.Message.voice`."""
VENUE = 'venue'
""":obj:`str`: Messages with :attr:`Message.venue`."""
""":obj:`str`: Messages with :attr:`telegram.Message.venue`."""
class MessageEntityType(_StringEnum):
@ -607,76 +607,76 @@ class MessageType(_StringEnum):
# -------------------------------------------------- Attachment types
ANIMATION = 'animation'
""":obj:`str`: Messages with :attr:`Message.animation`."""
""":obj:`str`: Messages with :attr:`telegram.Message.animation`."""
AUDIO = 'audio'
""":obj:`str`: Messages with :attr:`Message.audio`."""
""":obj:`str`: Messages with :attr:`telegram.Message.audio`."""
CONTACT = 'contact'
""":obj:`str`: Messages with :attr:`Message.contact`."""
""":obj:`str`: Messages with :attr:`telegram.Message.contact`."""
DICE = 'dice'
""":obj:`str`: Messages with :attr:`Message.dice`."""
""":obj:`str`: Messages with :attr:`telegram.Message.dice`."""
DOCUMENT = 'document'
""":obj:`str`: Messages with :attr:`Message.document`."""
""":obj:`str`: Messages with :attr:`telegram.Message.document`."""
GAME = 'game'
""":obj:`str`: Messages with :attr:`Message.game`."""
""":obj:`str`: Messages with :attr:`telegram.Message.game`."""
INVOICE = 'invoice'
""":obj:`str`: Messages with :attr:`Message.invoice`."""
""":obj:`str`: Messages with :attr:`telegram.Message.invoice`."""
LOCATION = 'location'
""":obj:`str`: Messages with :attr:`Message.location`."""
""":obj:`str`: Messages with :attr:`telegram.Message.location`."""
PASSPORT_DATA = 'passport_data'
""":obj:`str`: Messages with :attr:`Message.passport_data`."""
""":obj:`str`: Messages with :attr:`telegram.Message.passport_data`."""
PHOTO = 'photo'
""":obj:`str`: Messages with :attr:`Message.photo`."""
""":obj:`str`: Messages with :attr:`telegram.Message.photo`."""
POLL = 'poll'
""":obj:`str`: Messages with :attr:`Message.poll`."""
""":obj:`str`: Messages with :attr:`telegram.Message.poll`."""
STICKER = 'sticker'
""":obj:`str`: Messages with :attr:`Message.sticker`."""
""":obj:`str`: Messages with :attr:`telegram.Message.sticker`."""
SUCCESSFUL_PAYMENT = 'successful_payment'
""":obj:`str`: Messages with :attr:`Message.successful_payment`."""
""":obj:`str`: Messages with :attr:`telegram.Message.successful_payment`."""
VIDEO = 'video'
""":obj:`str`: Messages with :attr:`Message.video`."""
""":obj:`str`: Messages with :attr:`telegram.Message.video`."""
VIDEO_NOTE = 'video_note'
""":obj:`str`: Messages with :attr:`Message.video_note`."""
""":obj:`str`: Messages with :attr:`telegram.Message.video_note`."""
VOICE = 'voice'
""":obj:`str`: Messages with :attr:`Message.voice`."""
""":obj:`str`: Messages with :attr:`telegram.Message.voice`."""
VENUE = 'venue'
""":obj:`str`: Messages with :attr:`Message.venue`."""
""":obj:`str`: Messages with :attr:`telegram.Message.venue`."""
# -------------------------------------------------- Other types
TEXT = 'text'
""":obj:`str`: Messages with :attr:`Message.text`."""
""":obj:`str`: Messages with :attr:`telegram.Message.text`."""
NEW_CHAT_MEMBERS = 'new_chat_members'
""":obj:`str`: Messages with :attr:`Message.new_chat_members`."""
""":obj:`str`: Messages with :attr:`telegram.Message.new_chat_members`."""
LEFT_CHAT_MEMBER = 'left_chat_member'
""":obj:`str`: Messages with :attr:`Message.left_chat_member`."""
""":obj:`str`: Messages with :attr:`telegram.Message.left_chat_member`."""
NEW_CHAT_TITLE = 'new_chat_title'
""":obj:`str`: Messages with :attr:`Message.new_chat_title`."""
""":obj:`str`: Messages with :attr:`telegram.Message.new_chat_title`."""
NEW_CHAT_PHOTO = 'new_chat_photo'
""":obj:`str`: Messages with :attr:`Message.new_chat_photo`."""
""":obj:`str`: Messages with :attr:`telegram.Message.new_chat_photo`."""
DELETE_CHAT_PHOTO = 'delete_chat_photo'
""":obj:`str`: Messages with :attr:`Message.delete_chat_photo`."""
""":obj:`str`: Messages with :attr:`telegram.Message.delete_chat_photo`."""
GROUP_CHAT_CREATED = 'group_chat_created'
""":obj:`str`: Messages with :attr:`Message.group_chat_created`."""
""":obj:`str`: Messages with :attr:`telegram.Message.group_chat_created`."""
SUPERGROUP_CHAT_CREATED = 'supergroup_chat_created'
""":obj:`str`: Messages with :attr:`Message.supergroup_chat_created`."""
""":obj:`str`: Messages with :attr:`telegram.Message.supergroup_chat_created`."""
CHANNEL_CHAT_CREATED = 'channel_chat_created'
""":obj:`str`: Messages with :attr:`Message.channel_chat_created`."""
""":obj:`str`: Messages with :attr:`telegram.Message.channel_chat_created`."""
MESSAGE_AUTO_DELETE_TIMER_CHANGED = 'message_auto_delete_timer_changed'
""":obj:`str`: Messages with :attr:`Message.message_auto_delete_timer_changed`."""
""":obj:`str`: Messages with :attr:`telegram.Message.message_auto_delete_timer_changed`."""
MIGRATE_TO_CHAT_ID = 'migrate_to_chat_id'
""":obj:`str`: Messages with :attr:`Message.migrate_to_chat_id`."""
""":obj:`str`: Messages with :attr:`telegram.Message.migrate_to_chat_id`."""
MIGRATE_FROM_CHAT_ID = 'migrate_from_chat_id'
""":obj:`str`: Messages with :attr:`Message.migrate_from_chat_id`."""
""":obj:`str`: Messages with :attr:`telegram.Message.migrate_from_chat_id`."""
PINNED_MESSAGE = 'pinned_message'
""":obj:`str`: Messages with :attr:`Message.pinned_message`."""
""":obj:`str`: Messages with :attr:`telegram.Message.pinned_message`."""
PROXIMITY_ALERT_TRIGGERED = 'proximity_alert_triggered'
""":obj:`str`: Messages with :attr:`Message.proximity_alert_triggered`."""
""":obj:`str`: Messages with :attr:`telegram.Message.proximity_alert_triggered`."""
VOICE_CHAT_SCHEDULED = 'voice_chat_scheduled'
""":obj:`str`: Messages with :attr:`Message.voice_chat_scheduled`."""
""":obj:`str`: Messages with :attr:`telegram.Message.voice_chat_scheduled`."""
VOICE_CHAT_STARTED = 'voice_chat_started'
""":obj:`str`: Messages with :attr:`Message.voice_chat_started`."""
""":obj:`str`: Messages with :attr:`telegram.Message.voice_chat_started`."""
VOICE_CHAT_ENDED = 'voice_chat_ended'
""":obj:`str`: Messages with :attr:`Message.voice_chat_ended`."""
""":obj:`str`: Messages with :attr:`telegram.Message.voice_chat_ended`."""
VOICE_CHAT_PARTICIPANTS_INVITED = 'voice_chat_participants_invited'
""":obj:`str`: Messages with :attr:`Message.voice_chat_participants_invited`."""
""":obj:`str`: Messages with :attr:`telegram.Message.voice_chat_participants_invited`."""
class ParseMode(_StringEnum):

55
telegram/ext/_basepersistence.py
View file

@ -60,6 +60,11 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
"""Interface class for adding persistence to your bot.
Subclass this object for different implementations of a persistent bot.
Attention:
The interface provided by this class is intended to be accessed exclusively by
:class:`~telegram.ext.Dispatcher`. Calling any of the methods below manually might
interfere with the integration of persistence into :class:`~telegram.ext.Dispatcher`.
All relevant methods must be overwritten. This includes:
* :meth:`get_bot_data`
@ -90,7 +95,7 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
Note:
:meth:`replace_bot` and :meth:`insert_bot` are used *independently* of the implementation
of the :meth:`update/get_*` methods, i.e. you don't need to worry about it while
of the ``update/get_*`` methods, i.e. you don't need to worry about it while
implementing a custom persistence subclass.
.. versionchanged:: 14.0
@ -191,17 +196,18 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
def replace_bot(cls, obj: object) -> object:
"""
Replaces all instances of :class:`telegram.Bot` that occur within the passed object with
:attr:`REPLACED_BOT`. Currently, this handles objects of type ``list``, ``tuple``, ``set``,
``frozenset``, ``dict``, ``defaultdict`` and objects that have a ``__dict__`` or
``__slots__`` attribute, excluding classes and objects that can't be copied with
``copy.copy``. If the parsing of an object fails, the object will be returned unchanged and
the error will be logged.
:attr:`REPLACED_BOT`. Currently, this handles objects of type :class:`list`,
:class:`tuple`, :class:`set`, :class:`frozenset`, :class:`dict`,
:class:`collections.defaultdict` and objects that have a :attr:`~object.__dict__` or
:data:`~object.__slots__` attribute, excluding classes and objects that can't be copied
with :func:`copy.copy`. If the parsing of an object fails, the object will be returned
unchanged and the error will be logged.
Args:
obj (:obj:`object`): The object
Returns:
:obj:`obj`: Copy of the object with Bot instances replaced.
:class:`object`: Copy of the object with Bot instances replaced.
"""
return cls._replace_bot(obj, {})
@ -294,17 +300,18 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
def insert_bot(self, obj: object) -> object:
"""
Replaces all instances of :attr:`REPLACED_BOT` that occur within the passed object with
:attr:`bot`. Currently, this handles objects of type ``list``, ``tuple``, ``set``,
``frozenset``, ``dict``, ``defaultdict`` and objects that have a ``__dict__`` or
``__slots__`` attribute, excluding classes and objects that can't be copied with
``copy.copy``. If the parsing of an object fails, the object will be returned unchanged and
the error will be logged.
:paramref:`bot`. Currently, this handles objects of type :class:`list`,
:class:`tuple`, :class:`set`, :class:`frozenset`, :class:`dict`,
:class:`collections.defaultdict` and objects that have a :attr:`~object.__dict__` or
:data:`~object.__slots__` attribute, excluding classes and objects that can't be copied
with :func:`copy.copy`. If the parsing of an object fails, the object will be returned
unchanged and the error will be logged.
Args:
obj (:obj:`object`): The object
Returns:
:obj:`obj`: Copy of the object with Bot instances inserted.
:class:`object`: Copy of the object with Bot instances inserted.
"""
return self._insert_bot(obj, {})
@ -460,7 +467,7 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
Returns:
Optional[Tuple[List[Tuple[:obj:`str`, :obj:`float`, \
Dict[:obj:`str`, :obj:`Any`]]], Dict[:obj:`str`, :obj:`str`]]]:
Dict[:obj:`str`, :class:`object`]]], Dict[:obj:`str`, :obj:`str`]]]:
The restored meta data or :obj:`None`, if no data was stored.
"""
@ -488,7 +495,7 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
Args:
name (:obj:`str`): The handler's name.
key (:obj:`tuple`): The key the state is changed for.
new_state (:obj:`tuple` | :obj:`Any`): The new state for the given key.
new_state (:obj:`tuple` | :class:`object`): The new state for the given key.
"""
@abstractmethod
@ -564,8 +571,8 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
@abstractmethod
def refresh_user_data(self, user_id: int, user_data: UD) -> None:
"""Will be called by the :class:`telegram.ext.Dispatcher` before passing the
:attr:`user_data` to a callback. Can be used to update data stored in :attr:`user_data`
from an external source.
:attr:`~telegram.ext.Dispatcher.user_data` to a callback. Can be used to update data stored
in :attr:`~telegram.ext.Dispatcher.user_data` from an external source.
.. versionadded:: 13.6
@ -573,7 +580,8 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
Changed this method into an ``@abstractmethod``.
Args:
user_id (:obj:`int`): The user ID this :attr:`user_data` is associated with.
user_id (:obj:`int`): The user ID this :attr:`~telegram.ext.Dispatcher.user_data` is
associated with.
user_data (:obj:`dict` | :attr:`telegram.ext.ContextTypes.user_data`):
The ``user_data`` of a single user.
"""
@ -581,8 +589,8 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
@abstractmethod
def refresh_chat_data(self, chat_id: int, chat_data: CD) -> None:
"""Will be called by the :class:`telegram.ext.Dispatcher` before passing the
:attr:`chat_data` to a callback. Can be used to update data stored in :attr:`chat_data`
from an external source.
:attr:`~telegram.ext.Dispatcher.chat_data` to a callback. Can be used to update data stored
in :attr:`~telegram.ext.Dispatcher.chat_data` from an external source.
.. versionadded:: 13.6
@ -590,7 +598,8 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
Changed this method into an ``@abstractmethod``.
Args:
chat_id (:obj:`int`): The chat ID this :attr:`chat_data` is associated with.
chat_id (:obj:`int`): The chat ID this :attr:`~telegram.ext.Dispatcher.chat_data` is
associated with.
chat_data (:obj:`dict` | :attr:`telegram.ext.ContextTypes.chat_data`):
The ``chat_data`` of a single chat.
"""
@ -598,8 +607,8 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
@abstractmethod
def refresh_bot_data(self, bot_data: BD) -> None:
"""Will be called by the :class:`telegram.ext.Dispatcher` before passing the
:attr:`bot_data` to a callback. Can be used to update data stored in :attr:`bot_data`
from an external source.
:attr:`~telegram.ext.Dispatcher.bot_data` to a callback. Can be used to update data stored
in :attr:`~telegram.ext.Dispatcher.bot_data` from an external source.
.. versionadded:: 13.6

37
telegram/ext/_builders.py
View file

@ -560,7 +560,7 @@ class DispatcherBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
"""Sets the base URL to be used for :attr:`telegram.ext.Dispatcher.bot`. If not called,
will default to ``'https://api.telegram.org/bot'``.
.. seealso:: :attr:`telegram.Bot.base_url`, `Local Bot API Server <https://github.com/\
.. seealso:: :paramref:`telegram.Bot.base_url`, `Local Bot API Server <https://github.com/\
python-telegram-bot/python-telegram-bot/wiki/Local-Bot-API-Server>`_,
:meth:`base_url`
@ -576,8 +576,8 @@ class DispatcherBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
"""Sets the base file URL to be used for :attr:`telegram.ext.Dispatcher.bot`. If not
called, will default to ``'https://api.telegram.org/file/bot'``.
.. seealso:: :attr:`telegram.Bot.base_file_url`, `Local Bot API Server <https://github.com\
/python-telegram-bot/python-telegram-bot/wiki/Local-Bot-API-Server>`_,
.. seealso:: :paramref:`telegram.Bot.base_file_url`, `Local Bot API Server <https://\
github.com/python-telegram-bot/python-telegram-bot/wiki/Local-Bot-API-Server>`_,
:meth:`base_file_url`
Args:
@ -589,7 +589,8 @@ class DispatcherBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
return self._set_base_file_url(base_file_url)
def request_kwargs(self: BuilderType, request_kwargs: Dict[str, Any]) -> BuilderType:
"""Sets keyword arguments that will be passed to the :class:`telegram.utils.Request` object
"""Sets keyword arguments that will be passed to the
:class:`telegram.request.Request` object
that is created when :attr:`telegram.ext.Dispatcher.bot` is created. If not called, no
keyword arguments will be passed.
@ -604,13 +605,13 @@ class DispatcherBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
return self._set_request_kwargs(request_kwargs)
def request(self: BuilderType, request: Request) -> BuilderType:
"""Sets a :class:`telegram.utils.Request` object to be used for
"""Sets a :class:`telegram.request.Request` object to be used for
:attr:`telegram.ext.Dispatcher.bot`.
.. seealso:: :meth:`request_kwargs`
Args:
request (:class:`telegram.utils.Request`): The request object.
request (:class:`telegram.request.Request`): The request object.
Returns:
:class:`DispatcherBuilder`: The same builder with the updated argument.
@ -718,7 +719,7 @@ class DispatcherBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
:meth:`telegram.ext.Dispatcher.run_async`, i.e. the number of callbacks that can be run
asynchronously at the same time.
.. seealso:: :attr:`telegram.ext.Handler.run_sync`,
.. seealso:: :paramref:`telegram.ext.Handler.run_async`,
:attr:`telegram.ext.Defaults.run_async`
Args:
@ -927,7 +928,7 @@ class UpdaterBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
"""Sets the base URL to be used for :attr:`telegram.ext.Updater.bot`. If not called,
will default to ``'https://api.telegram.org/bot'``.
.. seealso:: :attr:`telegram.Bot.base_url`, `Local Bot API Server <https://github.com/\
.. seealso:: :paramref:`telegram.Bot.base_url`, `Local Bot API Server <https://github.com/\
python-telegram-bot/python-telegram-bot/wiki/Local-Bot-API-Server>`_,
:meth:`base_url`
@ -943,8 +944,8 @@ class UpdaterBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
"""Sets the base file URL to be used for :attr:`telegram.ext.Updater.bot`. If not
called, will default to ``'https://api.telegram.org/file/bot'``.
.. seealso:: :attr:`telegram.Bot.base_file_url`, `Local Bot API Server <https://github.com\
/python-telegram-bot/python-telegram-bot/wiki/Local-Bot-API-Server>`_,
.. seealso:: :paramref:`telegram.Bot.base_file_url`, `Local Bot API Server <https://
github.com/python-telegram-bot/python-telegram-bot/wiki/Local-Bot-API-Server>`_,
:meth:`base_file_url`
Args:
@ -956,8 +957,8 @@ class UpdaterBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
return self._set_base_file_url(base_file_url)
def request_kwargs(self: BuilderType, request_kwargs: Dict[str, Any]) -> BuilderType:
"""Sets keyword arguments that will be passed to the :class:`telegram.utils.Request` object
that is created when :attr:`telegram.ext.Updater.bot` is created. If not called, no
"""Sets keyword arguments that will be passed to the :class:`telegram.request.Request`
object that is created when :attr:`telegram.ext.Updater.bot` is created. If not called, no
keyword arguments will be passed.
.. seealso:: :meth:`request`
@ -971,13 +972,13 @@ class UpdaterBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
return self._set_request_kwargs(request_kwargs)
def request(self: BuilderType, request: Request) -> BuilderType:
"""Sets a :class:`telegram.utils.Request` object to be used for
"""Sets a :class:`telegram.request.Request` object to be used for
:attr:`telegram.ext.Updater.bot`.
.. seealso:: :meth:`request_kwargs`
Args:
request (:class:`telegram.utils.Request`): The request object.
request (:class:`telegram.request.Request`): The request object.
Returns:
:class:`UpdaterBuilder`: The same builder with the updated argument.
@ -1087,7 +1088,7 @@ class UpdaterBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
:meth:`telegram.ext.Dispatcher.run_async`, i.e. the number of callbacks that can be run
asynchronously at the same time.
.. seealso:: :attr:`telegram.ext.Handler.run_sync`,
.. seealso:: :paramref:`telegram.ext.Handler.run_async`,
:attr:`telegram.ext.Defaults.run_async`
Args:
@ -1229,9 +1230,9 @@ class UpdaterBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
self: BuilderType, user_signal_handler: Callable[[int, object], Any]
) -> BuilderType:
"""Sets a callback to be used for :attr:`telegram.ext.Updater.user_signal_handler`.
The callback will be called when :meth:`telegram.ext.Updater.idle()` receives a signal.
The callback will be called when :meth:`telegram.ext.Updater.idle` receives a signal.
It will be called with the two arguments ``signum, frame`` as for the
:meth:`signal.signal` of the standard library.
:func:`signal.signal` of the standard library.
Note:
Signal handlers are an advanced feature that come with some culprits and are not thread
@ -1241,7 +1242,7 @@ class UpdaterBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
be executed after the updater has shut down.
Args:
user_signal_handler (Callable[signum, frame]): The signal handler.
user_signal_handler (Callable[`signum, frame`]): The signal handler.
Returns:
:class:`UpdaterBuilder`: The same builder with the updated argument.

5
telegram/ext/_callbackcontext.py
View file

@ -64,7 +64,7 @@ class CallbackContext(Generic[BT, UD, CD, BD]):
Warning:
Do not combine custom attributes and ``@run_async``/
:meth:`telegram.ext.Disptacher.run_async`. Due to how ``run_async`` works, it will
:func:`telegram.ext.Dispatcher.run_async`. Due to how ``run_async`` works, it will
almost certainly execute the callbacks for an update out of order, and the attributes
that you think you added will not be present.
@ -72,7 +72,8 @@ class CallbackContext(Generic[BT, UD, CD, BD]):
dispatcher (:class:`telegram.ext.Dispatcher`): The dispatcher associated with this context.
Attributes:
matches (List[:obj:`re match object`]): Optional. If the associated update originated from
matches (List[:meth:`re.Match <re.Match.expand>`]): Optional. If the associated update
originated from
a :class:`filters.Regex`, this will contain a list of match objects for every pattern
where ``re.search(pattern, string)`` returned a match. Note that filters short circuit,
so combined regex filters will not always be evaluated.

12
telegram/ext/_callbackdatacache.py
View file

@ -109,7 +109,7 @@ class CallbackDataCache:
Defaults to 1024.
persistent_data (Tuple[List[Tuple[:obj:`str`, :obj:`float`, \
Dict[:obj:`str`, :obj:`Any`]]], Dict[:obj:`str`, :obj:`str`]], optional): \
Dict[:obj:`str`, :class:`object`]]], Dict[:obj:`str`, :obj:`str`]], optional): \
Data to initialize the cache with, as returned by \
:meth:`telegram.ext.BasePersistence.get_callback_data`.
@ -146,7 +146,7 @@ class CallbackDataCache:
@property
def persistence_data(self) -> CDCData:
"""Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :obj:`Any`]]],
"""Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :class:`object`]]],
Dict[:obj:`str`, :obj:`str`]]: The data that needs to be persisted to allow
caching callback data across bot reboots.
"""
@ -160,7 +160,8 @@ class CallbackDataCache:
def process_keyboard(self, reply_markup: InlineKeyboardMarkup) -> InlineKeyboardMarkup:
"""Registers the reply markup to the cache. If any of the buttons have
:attr:`callback_data`, stores that data and builds a new keyboard with the correspondingly
:attr:`~telegram.InlineKeyboardButton.callback_data`, stores that data and builds a new
keyboard with the correspondingly
replaced buttons. Otherwise does nothing and returns the original reply markup.
Args:
@ -307,8 +308,9 @@ class CallbackDataCache:
"""Replaces the data in the callback query and the attached messages keyboard with the
cached objects, if necessary. If the data could not be found,
:class:`telegram.ext.InvalidCallbackData` will be inserted.
If :attr:`callback_query.data` or :attr:`callback_query.message` is present, this also
saves the callback queries ID in order to be able to resolve it to the stored data.
If :attr:`telegram.CallbackQuery.data` or :attr:`telegram.CallbackQuery.message` is
present, this also saves the callback queries ID in order to be able to resolve it to the
stored data.
Note:
Also considers inserts data into the buttons of

18
telegram/ext/_callbackqueryhandler.py
View file

@ -44,20 +44,22 @@ RT = TypeVar('RT')
class CallbackQueryHandler(Handler[Update, CCT]):
"""Handler class to handle Telegram callback queries. Optionally based on a regex.
Read the documentation of the ``re`` module for more information.
Read the documentation of the :mod:`re` module for more information.
Note:
* If your bot allows arbitrary objects as ``callback_data``, it may happen that the
original ``callback_data`` for the incoming :class:`telegram.CallbackQuery`` can not be
found. This is the case when either a malicious client tempered with the
``callback_data`` or the data was simply dropped from cache or not persisted. In these
* If your bot allows arbitrary objects as
:paramref:`~telegram.InlineKeyboardButton.callback_data`, it may happen that the
original :attr:`~telegram.InlineKeyboardButton.callback_data` for the incoming
:class:`telegram.CallbackQuery` can not be found. This is the case when either a
malicious client tempered with the :attr:`telegram.CallbackQuery.data` or the data was
simply dropped from cache or not persisted. In these
cases, an instance of :class:`telegram.ext.InvalidCallbackData` will be set as
``callback_data``.
:attr:`telegram.CallbackQuery.data`.
.. versionadded:: 13.6
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:
@ -69,7 +71,7 @@ class CallbackQueryHandler(Handler[Update, CCT]):
:class:`telegram.ext.ConversationHandler`.
pattern (:obj:`str` | `Pattern` | :obj:`callable` | :obj:`type`, optional):
Pattern to test :attr:`telegram.CallbackQuery.data` against. If a string or a regex
pattern is passed, :meth:`re.match` is used on :attr:`telegram.CallbackQuery.data` to
pattern is passed, :func:`re.match` is used on :attr:`telegram.CallbackQuery.data` to
determine if an update should be handled by this handler. If your bot allows arbitrary
objects as ``callback_data``, non-strings will be accepted. To filter arbitrary
objects you may pass

2
telegram/ext/_chatjoinrequesthandler.py
View file

@ -29,7 +29,7 @@ class ChatJoinRequestHandler(Handler[Update, CCT]):
"""Handler class to handle Telegram updates that contain a chat join request.
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
.. versionadded:: 13.8

2
telegram/ext/_chatmemberhandler.py
View file

@ -33,7 +33,7 @@ class ChatMemberHandler(Handler[Update, CCT]):
.. versionadded:: 13.4
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:

5
telegram/ext/_choseninlineresulthandler.py
View file

@ -35,7 +35,7 @@ class ChosenInlineResultHandler(Handler[Update, CCT]):
"""Handler class to handle Telegram updates that contain a chosen inline result.
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:
@ -47,7 +47,8 @@ class ChosenInlineResultHandler(Handler[Update, CCT]):
:class:`telegram.ext.ConversationHandler`.
run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
Defaults to :obj:`False`.
pattern (:obj:`str` | `Pattern`, optional): Regex pattern. If not :obj:`None`, ``re.match``
pattern (:obj:`str` | :func:`re.Pattern <re.compile>`, optional): Regex pattern. If not
:obj:`None`, :func:`re.match`
is used on :attr:`telegram.ChosenInlineResult.result_id` to determine if an update
should be handled by this handler. This is accessible in the callback as
:attr:`telegram.ext.CallbackContext.matches`.

12
telegram/ext/_commandhandler.py
View file

@ -47,7 +47,7 @@ class CommandHandler(Handler[Update, CCT]):
* :class:`CommandHandler` does *not* handle (edited) channel posts.
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:
@ -60,7 +60,7 @@ class CommandHandler(Handler[Update, CCT]):
The return value of the callback is usually ignored except for the special case of
:class:`telegram.ext.ConversationHandler`.
filters (:class:`telegram.ext.BaseFilter`, optional): A filter inheriting from
filters (:class:`telegram.ext.filters.BaseFilter`, optional): A filter inheriting from
:class:`telegram.ext.filters.BaseFilter`. Standard filters can be found in
:mod:`telegram.ext.filters`. Filters can be combined using bitwise
operators (& for and, | for or, ~ for not).
@ -75,7 +75,7 @@ class CommandHandler(Handler[Update, CCT]):
The command or list of commands this handler should listen for.
Limitations are the same as described here https://core.telegram.org/bots#commands
callback (:obj:`callable`): The callback function for this handler.
filters (:class:`telegram.ext.BaseFilter`): Optional. Only allow updates with these
filters (:class:`telegram.ext.filters.BaseFilter`): Optional. Only allow updates with these
Filters.
run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
"""
@ -194,7 +194,7 @@ class PrefixHandler(CommandHandler):
* :class:`PrefixHandler` does *not* handle (edited) channel posts.
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:
@ -208,7 +208,7 @@ class PrefixHandler(CommandHandler):
The return value of the callback is usually ignored except for the special case of
:class:`telegram.ext.ConversationHandler`.
filters (:class:`telegram.ext.BaseFilter`, optional): A filter inheriting from
filters (:class:`telegram.ext.filters.BaseFilter`, optional): A filter inheriting from
:class:`telegram.ext.filters.BaseFilter`. Standard filters can be found in
:mod:`telegram.ext.filters`. Filters can be combined using bitwise
operators (& for and, | for or, ~ for not).
@ -217,7 +217,7 @@ class PrefixHandler(CommandHandler):
Attributes:
callback (:obj:`callable`): The callback function for this handler.
filters (:class:`telegram.ext.BaseFilter`): Optional. Only allow updates with these
filters (:class:`telegram.ext.filters.BaseFilter`): Optional. Only allow updates with these
Filters.
run_async (:obj:`bool`): Determines whether the callback will run asynchronously.

6
telegram/ext/_contexttypes.py
View file

@ -194,16 +194,22 @@ class ContextTypes(Generic[CCT, UD, CD, BD]):
@property
def context(self) -> Type[CCT]:
"""The type of the ``context`` argument of all (error-)handler callbacks and job
callbacks.
"""
return self._context
@property
def bot_data(self) -> Type[BD]:
"""The type of ``context.bot_data`` of all (error-)handler callbacks and job callbacks."""
return self._bot_data
@property
def chat_data(self) -> Type[CD]:
"""The type of ``context.chat_data`` of all (error-)handler callbacks and job callbacks."""
return self._chat_data
@property
def user_data(self) -> Type[UD]:
"""The type of ``context.user_data`` of all (error-)handler callbacks and job callbacks."""
return self._user_data

2
telegram/ext/_defaults.py
View file

@ -131,7 +131,7 @@ class Defaults:
@property
def explanation_parse_mode(self) -> Optional[str]:
""":obj:`str`: Optional. Alias for :attr:`parse_mode`, used for
""":obj:`str`: Optional. Alias for :paramref:`parse_mode`, used for
the corresponding parameter of :meth:`telegram.Bot.send_poll`.
"""
return self._parse_mode

15
telegram/ext/_dictpersistence.py
View file

@ -33,6 +33,11 @@ except ImportError:
class DictPersistence(BasePersistence):
"""Using Python's :obj:`dict` and ``json`` for making your bot persistent.
Attention:
The interface provided by this class is intended to be accessed exclusively by
:class:`~telegram.ext.Dispatcher`. Calling any of the methods below manually might
interfere with the integration of persistence into :class:`~telegram.ext.Dispatcher`.
Note:
This class does *not* implement a :meth:`flush` method, meaning that data managed by
``DictPersistence`` is in-memory only and will be lost when the bot shuts down. This is,
@ -41,7 +46,7 @@ class DictPersistence(BasePersistence):
Warning:
:class:`DictPersistence` will try to replace :class:`telegram.Bot` instances by
:attr:`REPLACED_BOT` and insert the bot set with
:attr:`~telegram.ext.BasePersistence.REPLACED_BOT` and insert the bot set with
:meth:`telegram.ext.BasePersistence.set_bot` upon loading of the data. This is to ensure
that changes to the bot apply to the saved objects, too. If you change the bots token, this
may lead to e.g. ``Chat not found`` errors. For the limitations on replacing bots see
@ -202,7 +207,7 @@ class DictPersistence(BasePersistence):
@property
def callback_data(self) -> Optional[CDCData]:
"""Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :obj:`Any`]]], \
"""Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :class:`object`]]], \
Dict[:obj:`str`, :obj:`str`]]: The metadata on the stored callback data.
.. versionadded:: 13.6
@ -267,7 +272,7 @@ class DictPersistence(BasePersistence):
.. versionadded:: 13.6
Returns:
Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :obj:`Any`]]], \
Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :class:`object`]]], \
Dict[:obj:`str`, :obj:`str`]]: The restored metadata or :obj:`None`, \
if no data was stored.
"""
@ -295,7 +300,7 @@ class DictPersistence(BasePersistence):
Args:
name (:obj:`str`): The handler's name.
key (:obj:`tuple`): The key the state is changed for.
new_state (:obj:`tuple` | :obj:`Any`): The new state for the given key.
new_state (:obj:`tuple` | :class:`object`): The new state for the given key.
"""
if not self._conversations:
self._conversations = {}
@ -349,7 +354,7 @@ class DictPersistence(BasePersistence):
.. versionadded:: 13.6
Args:
data (Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :obj:`Any`]]], \
data (Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :class:`object`]]], \
Dict[:obj:`str`, :obj:`str`]]): The relevant data to restore
:class:`telegram.ext.CallbackDataCache`.
"""

18
telegram/ext/_dispatcher.py
View file

@ -109,7 +109,7 @@ class Dispatcher(Generic[BT, CCT, UD, CD, BD, JQ, PT]):
Attributes:
bot (:class:`telegram.Bot`): The bot object that should be passed to the handlers.
update_queue (:obj:`Queue`): The synchronized queue that will contain the updates.
update_queue (:class:`queue.Queue`): The synchronized queue that will contain the updates.
job_queue (:class:`telegram.ext.JobQueue`): Optional. The :class:`telegram.ext.JobQueue`
instance to pass onto handler callbacks.
workers (:obj:`int`, optional): Number of maximum concurrent worker threads for the
@ -120,7 +120,7 @@ class Dispatcher(Generic[BT, CCT, UD, CD, BD, JQ, PT]):
.. versionchanged:: 14.0
:attr:`chat_data` is now read-only
.. tip::
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
@ -129,7 +129,7 @@ class Dispatcher(Generic[BT, CCT, UD, CD, BD, JQ, PT]):
.. versionchanged:: 14.0
:attr:`user_data` is now read-only
.. tip::
Tip:
Manually modifying :attr:`user_data` is almost never needed and unadvisable.
bot_data (:obj:`dict`): A dictionary handlers can use to store data for the bot.
@ -154,6 +154,8 @@ class Dispatcher(Generic[BT, CCT, UD, CD, BD, JQ, PT]):
.. seealso::
:meth:`start`, :meth:`stop`
context_types (:class:`telegram.ext.ContextTypes`): Specifies the types used by this
dispatcher for the ``context`` argument of handler and job callbacks.
"""
@ -373,11 +375,11 @@ class Dispatcher(Generic[BT, CCT, UD, CD, BD, JQ, PT]):
Args:
func (:obj:`callable`): The function to run in the thread.
*args (:obj:`tuple`, optional): Arguments to ``func``.
*args (:obj:`tuple`, optional): Arguments to :paramref:`func`.
update (:class:`telegram.Update` | :obj:`object`, optional): The update associated with
the functions call. If passed, it will be available in the error handlers, in case
an exception is raised by :attr:`func`.
**kwargs (:obj:`dict`, optional): Keyword arguments to ``func``.
an exception is raised by :paramref:`func`.
**kwargs (:obj:`dict`, optional): Keyword arguments to :paramref:`func`.
Returns:
Promise
@ -693,7 +695,7 @@ class Dispatcher(Generic[BT, CCT, UD, CD, BD, JQ, PT]):
* The key `old_chat_id` of :attr:`chat_data` will be deleted
Args:
message (:class:`Message`, optional): A message with either
message (:class:`telegram.Message`, optional): A message with either
:attr:`telegram.Message.migrate_from_chat_id` or
:attr:`telegram.Message.migrate_to_chat_id`.
Mutually exclusive with passing ``old_chat_id`` and ``new_chat_id``
@ -846,8 +848,6 @@ class Dispatcher(Generic[BT, CCT, UD, CD, BD, JQ, PT]):
Args:
update (:obj:`object` | :class:`telegram.Update`): The update that caused the error.
error (:obj:`Exception`): The error that was raised.
promise (:class:`telegram._utils.Promise`, optional): The promise whose pooled function
raised the error.
job (:class:`telegram.ext.Job`, optional): The job that caused the error.
.. versionadded:: 14.0

2
telegram/ext/_extbot.py
View file

@ -202,7 +202,7 @@ class ExtBot(Bot):
*In place*, i.e. the passed :class:`telegram.Message` will be changed!
Args:
update (:class`telegram.Update`): The update.
update (:class:`telegram.Update`): The update.
"""
# The only incoming updates that can directly contain a message sent by the bot itself are:

8
telegram/ext/_handler.py
View file

@ -36,7 +36,7 @@ class Handler(Generic[UT, CCT], ABC):
"""The base class for all update handlers. Create custom handlers by inheriting from it.
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:
@ -76,10 +76,10 @@ class Handler(Generic[UT, CCT], ABC):
Note:
Custom updates types can be handled by the dispatcher. Therefore, an implementation of
this method should always check the type of :attr:`update`.
this method should always check the type of :paramref:`update`.
Args:
update (:obj:`str` | :class:`telegram.Update`): The update to be tested.
update (:obj:`object` | :class:`telegram.Update`): The update to be tested.
Returns:
Either :obj:`None` or :obj:`False` if the update should not be handled. Otherwise an
@ -105,7 +105,7 @@ class Handler(Generic[UT, CCT], ABC):
Args:
update (:obj:`str` | :class:`telegram.Update`): The update to be handled.
dispatcher (:class:`telegram.ext.Dispatcher`): The calling dispatcher.
check_result (:obj:`obj`): The result from :attr:`check_update`.
check_result (:class:`object`): The result from :attr:`check_update`.
context (:class:`telegram.ext.CallbackContext`): The context as provided by
the dispatcher.

12
telegram/ext/_inlinequeryhandler.py
View file

@ -44,10 +44,10 @@ RT = TypeVar('RT')
class InlineQueryHandler(Handler[Update, CCT]):
"""
Handler class to handle Telegram inline queries. Optionally based on a regex. Read the
documentation of the ``re`` module for more information.
documentation of the :mod:`re` module for more information.
Warning:
* When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
* When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
* :attr:`telegram.InlineQuery.chat_type` will not be set for inline queries from secret
chats and may not be set for inline queries coming from third-party clients. These
@ -60,9 +60,9 @@ class InlineQueryHandler(Handler[Update, CCT]):
The return value of the callback is usually ignored except for the special case of
:class:`telegram.ext.ConversationHandler`.
pattern (:obj:`str` | :obj:`Pattern`, optional): Regex pattern. If not :obj:`None`,
``re.match`` is used on :attr:`telegram.InlineQuery.query` to determine if an update
should be handled by this handler.
pattern (:obj:`str` | :func:`re.Pattern <re.compile>`, optional): Regex pattern.
If not :obj:`None`, :func:`re.match` is used on :attr:`telegram.InlineQuery.query`
to determine if an update should be handled by this handler.
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`.
@ -72,7 +72,7 @@ class InlineQueryHandler(Handler[Update, CCT]):
Attributes:
callback (:obj:`callable`): The callback function for this handler.
pattern (:obj:`str` | :obj:`Pattern`): Optional. Regex pattern to test
pattern (:obj:`str` | :func:`re.Pattern <re.compile>`): Optional. Regex pattern to test
:attr:`telegram.InlineQuery.query` against.
chat_types (List[:obj:`str`], optional): List of allowed chat types.

13
telegram/ext/_jobqueue.py
View file

@ -182,7 +182,7 @@ class JobQueue:
job_kwargs: JSONDict = None,
) -> 'Job':
"""Creates a new :class:`Job` instance that runs at specified intervals and adds it to the
queue.
queue.
Note:
For a note about DST, please see the documentation of `APScheduler`_.
@ -277,10 +277,6 @@ class JobQueue:
) -> 'Job':
"""Creates a new :class:`Job` that runs on a monthly basis and adds it to the queue.
.. versionchanged:: 14.0
The ``day_is_strict`` argument was removed. Instead one can now pass -1 to the ``day``
parameter to have the job run on the last day of the month.
.. versionchanged:: 14.0
The ``day_is_strict`` argument was removed. Instead one can now pass -1 to the ``day``
parameter to have the job run on the last day of the month.
@ -349,7 +345,8 @@ class JobQueue:
callback (:obj:`callable`): The callback function that should be executed by the new
job. Callback signature: ``def callback(context: CallbackContext)``
time (:obj:`datetime.time`): Time of day at which the job should run. If the timezone
(:obj:`time.tzinfo`) is :obj:`None`, the default timezone of the bot will be used.
(:obj:`datetime.time.tzinfo`) is :obj:`None`, the default timezone of the bot will
be used.
days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should
run (where ``0-6`` correspond to monday - sunday). Defaults to ``EVERY_DAY``
context (:obj:`object`, optional): Additional data needed for the callback function.
@ -450,7 +447,7 @@ class Job:
instance.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`id` is equal.
considered equal, if their :class:`id <apscheduler.job.Job>` is equal.
Note:
* All attributes and instance methods of :attr:`job` are also directly available as
@ -461,7 +458,7 @@ class Job:
this :class:`telegram.ext.Job` to be useful.
.. versionchanged:: 14.0
Removed argument and attribute :attr:`job_queue`.
Removed argument and attribute ``job_queue``.
Args:
callback (:obj:`callable`): The callback function that should be executed by the new job.

8
telegram/ext/_messagehandler.py
View file

@ -35,16 +35,16 @@ class MessageHandler(Handler[Update, CCT]):
"""Handler class to handle telegram messages. They might contain text, media or status updates.
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:
filters (:class:`telegram.ext.BaseFilter`): A filter inheriting from
filters (:class:`telegram.ext.filters.BaseFilter`): A filter inheriting from
:class:`telegram.ext.filters.BaseFilter`. Standard filters can be found in
:mod:`telegram.ext.filters`. Filters can be combined using bitwise
operators (& for and, | for or, ~ for not). This defaults to all message updates
being: :attr:`Update.message`, :attr:`Update.edited_message`,
:attr:`Update.channel_post` and :attr:`Update.edited_channel_post`.
being: :attr:`telegram.Update.message`, :attr:`telegram.Update.edited_message`,
: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.
callback (:obj:`callable`): The callback function for this handler. Will be called when

17
telegram/ext/_picklepersistence.py
View file

@ -37,9 +37,14 @@ from telegram.ext._utils.types import UD, CD, BD, ConversationDict, CDCData
class PicklePersistence(BasePersistence[UD, CD, BD]):
"""Using python's builtin pickle for making your bot persistent.
Attention:
The interface provided by this class is intended to be accessed exclusively by
:class:`~telegram.ext.Dispatcher`. Calling any of the methods below manually might
interfere with the integration of persistence into :class:`~telegram.ext.Dispatcher`.
Warning:
:class:`PicklePersistence` will try to replace :class:`telegram.Bot` instances by
:attr:`REPLACED_BOT` and insert the bot set with
:attr:`~telegram.ext.BasePersistence.REPLACED_BOT` and insert the bot set with
:meth:`telegram.ext.BasePersistence.set_bot` upon loading of the data. This is to ensure
that changes to the bot apply to the saved objects, too. If you change the bots token, this
may lead to e.g. ``Chat not found`` errors. For the limitations on replacing bots see
@ -252,7 +257,7 @@ class PicklePersistence(BasePersistence[UD, CD, BD]):
Returns:
Optional[Tuple[List[Tuple[:obj:`str`, :obj:`float`, \
Dict[:obj:`str`, :obj:`Any`]]], Dict[:obj:`str`, :obj:`str`]]]:
Dict[:obj:`str`, :class:`object`]]], Dict[:obj:`str`, :obj:`str`]]]:
The restored metadata or :obj:`None`, if no data was stored.
"""
if self.callback_data:
@ -297,7 +302,7 @@ class PicklePersistence(BasePersistence[UD, CD, BD]):
Args:
name (:obj:`str`): The handler's name.
key (:obj:`tuple`): The key the state is changed for.
new_state (:obj:`tuple` | :obj:`Any`): The new state for the given key.
new_state (:obj:`tuple` | :class:`object`): The new state for the given key.
"""
if not self.conversations:
self.conversations = {}
@ -370,7 +375,7 @@ class PicklePersistence(BasePersistence[UD, CD, BD]):
Args:
data (Tuple[List[Tuple[:obj:`str`, :obj:`float`, \
Dict[:obj:`str`, :obj:`Any`]]], Dict[:obj:`str`, :obj:`str`]]):
Dict[:obj:`str`, :class:`object`]]], Dict[:obj:`str`, :obj:`str`]]):
The relevant data to restore :class:`telegram.ext.CallbackDataCache`.
"""
if self.callback_data == data:
@ -383,7 +388,7 @@ class PicklePersistence(BasePersistence[UD, CD, BD]):
self._dump_singlefile()
def drop_chat_data(self, chat_id: int) -> None:
"""Will delete the specified key from the :attr:`chat_data` and depending on
"""Will delete the specified key from the ``chat_data`` and depending on
:attr:`on_flush` save the pickle file.
.. versionadded:: 14.0
@ -402,7 +407,7 @@ class PicklePersistence(BasePersistence[UD, CD, BD]):
self._dump_singlefile()
def drop_user_data(self, user_id: int) -> None:
"""Will delete the specified key from the :attr:`user_data` and depending on
"""Will delete the specified key from the ``user_data`` and depending on
:attr:`on_flush` save the pickle file.
.. versionadded:: 14.0

2
telegram/ext/_pollanswerhandler.py
View file

@ -29,7 +29,7 @@ class PollAnswerHandler(Handler[Update, CCT]):
"""Handler class to handle Telegram updates that contain a poll answer.
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:

2
telegram/ext/_pollhandler.py
View file

@ -29,7 +29,7 @@ class PollHandler(Handler[Update, CCT]):
"""Handler class to handle Telegram updates that contain a poll.
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:

2
telegram/ext/_precheckoutqueryhandler.py
View file

@ -28,7 +28,7 @@ class PreCheckoutQueryHandler(Handler[Update, CCT]):
"""Handler class to handle Telegram PreCheckout callback queries.
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:

2
telegram/ext/_shippingqueryhandler.py
View file

@ -28,7 +28,7 @@ class ShippingQueryHandler(Handler[Update, CCT]):
"""Handler class to handle Telegram shipping callback queries.
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:

2
telegram/ext/_stringcommandhandler.py
View file

@ -41,7 +41,7 @@ class StringCommandHandler(Handler[str, CCT]):
put in the queue. For example to send messages with the bot using command line or API.
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:

10
telegram/ext/_stringregexhandler.py
View file

@ -34,19 +34,19 @@ RT = TypeVar('RT')
class StringRegexHandler(Handler[str, CCT]):
"""Handler class to handle string updates based on a regex which checks the update content.
Read the documentation of the ``re`` module for more information. The ``re.match`` function is
used to determine if an update should be handled by this handler.
Read the documentation of the :mod:`re` module for more information. The :func:`re.match`
function is used to determine if an update should be handled by this handler.
Note:
This handler is not used to handle Telegram :attr:`telegram.Update`, but strings manually
put in the queue. For example to send messages with the bot using command line or API.
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:
pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
pattern (:obj:`str` | :func:`re.Pattern <re.compile>`): The regex pattern.
callback (:obj:`callable`): The callback function for this handler. Will be called when
:attr:`check_update` has determined that an update should be processed by this handler.
Callback signature: ``def callback(update: Update, context: CallbackContext)``
@ -57,7 +57,7 @@ class StringRegexHandler(Handler[str, CCT]):
Defaults to :obj:`False`.
Attributes:
pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
pattern (:obj:`str` | :func:`re.Pattern <re.compile>`): The regex pattern.
callback (:obj:`callable`): The callback function for this handler.
run_async (:obj:`bool`): Determines whether the callback will run asynchronously.

2
telegram/ext/_typehandler.py
View file

@ -32,7 +32,7 @@ class TypeHandler(Handler[UT, CCT]):
"""Handler class to handle updates of custom types.
Warning:
When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
When setting :paramref:`run_async` to :obj:`True`, you cannot rely on adding custom
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
Args:

18
telegram/ext/_updater.py
View file

@ -76,12 +76,12 @@ class Updater(Generic[BT, DT]):
Attributes:
bot (:class:`telegram.Bot`): The bot used with this Updater.
user_signal_handler (:obj:`function`): Optional. Function to be called when a signal is
user_signal_handler (Callable): Optional. Function to be called when a signal is
received.
.. versionchanged:: 14.0
Renamed ``user_sig_handler`` to ``user_signal_handler``.
update_queue (:obj:`Queue`): Queue for the updates.
update_queue (:class:`queue.Queue`): Queue for the updates.
dispatcher (:class:`telegram.ext.Dispatcher`): Optional. Dispatcher that handles the
updates and dispatches them to the handlers.
running (:obj:`bool`): Indicates if the updater is running.
@ -188,7 +188,7 @@ class Updater(Generic[BT, DT]):
"""Starts polling updates from Telegram.
.. versionchanged:: 14.0
Removed the ``clean`` argument in favor of ``drop_pending_updates``.
Removed the ``clean`` argument in favor of :paramref:`drop_pending_updates`.
Args:
poll_interval (:obj:`float`, optional): Time to wait between polling updates from
@ -212,7 +212,7 @@ class Updater(Generic[BT, DT]):
timeout from server (Default: ``2``).
Returns:
:obj:`Queue`: The update queue that can be filled from the main thread.
:class:`queue.Queue`: The update queue that can be filled from the main thread.
"""
with self.__lock:
@ -262,8 +262,8 @@ class Updater(Generic[BT, DT]):
max_connections: int = 40,
) -> Optional[Queue]:
"""
Starts a small http server to listen for updates via webhook. If :attr:`cert`
and :attr:`key` are not provided, the webhook will be started directly on
Starts a small http server to listen for updates via webhook. If :paramref:`cert`
and :paramref:`key` are not provided, the webhook will be started directly on
http://listen:port/url_path, so SSL can be handled by another
application. Else, the webhook will be started on
https://listen:port/url_path. Also calls :meth:`telegram.Bot.set_webhook` as required.
@ -273,8 +273,8 @@ class Updater(Generic[BT, DT]):
``webhook_url`` instead of calling ``updater.bot.set_webhook(webhook_url)`` manually.
.. versionchanged:: 14.0
Removed the ``clean`` argument in favor of ``drop_pending_updates`` and removed the
deprecated argument ``force_event_loop``.
Removed the ``clean`` argument in favor of :paramref:`drop_pending_updates` and removed
the deprecated argument ``force_event_loop``.
Args:
listen (:obj:`str`, optional): IP-Address to listen on. Default ``127.0.0.1``.
@ -308,7 +308,7 @@ class Updater(Generic[BT, DT]):
.. versionadded:: 13.6
Returns:
:obj:`Queue`: The update queue that can be filled from the main thread.
:class:`queue.Queue`: The update queue that can be filled from the main thread.
"""
with self.__lock:

2
telegram/ext/_utils/types.py
View file

@ -40,7 +40,7 @@ ConversationDict = Dict[Tuple[int, ...], Optional[object]]
"""
CDCData = Tuple[List[Tuple[str, float, Dict[str, Any]]], Dict[str, str]]
"""Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :obj:`Any`]]], \
"""Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :class:`object`]]], \
Dict[:obj:`str`, :obj:`str`]]: Data returned by
:attr:`telegram.ext.CallbackDataCache.persistence_data`.

18
telegram/ext/filters.py
View file

@ -25,7 +25,7 @@ This module contains filters for use with :class:`telegram.ext.MessageHandler`,
#. Filters are no longer callable, if you're using a custom filter and are calling an existing
filter, then switch to the new syntax: ``filters.{filter}.check_update(update)``.
#. Removed the ``Filters`` class. The filters are now directly attributes/classes of the
:mod:`filters` module.
: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
@ -561,7 +561,7 @@ class CaptionRegex(MessageFilter):
This filter will not work on simple text messages, but only on media with caption.
Args:
pattern (:obj:`str` | :obj:`re.Pattern`): The regex pattern.
pattern (:obj:`str` | :func:`re.Pattern <re.compile>`): The regex pattern.
"""
__slots__ = ('pattern',)
@ -1320,8 +1320,8 @@ class ForwardedFrom(_ChatUserBaseFilter):
Note:
When a user has disallowed adding a link to their account while forwarding their
messages, this filter will *not* work since both
:attr:`telegram.Message.forwarded_from` and
:attr:`telegram.Message.forwarded_from_chat` are :obj:`None`. However, this behaviour
:attr:`telegram.Message.forward_from` and
:attr:`telegram.Message.forward_from_chat` are :obj:`None`. However, this behaviour
is undocumented and might be changed by Telegram.
Warning:
@ -1393,7 +1393,7 @@ class _HasProtectedContent(MessageFilter):
return bool(message.has_protected_content)
HAS_PROTECTED_CONTENT = _HasProtectedContent(name='Filters.has_protected_content')
HAS_PROTECTED_CONTENT = _HasProtectedContent(name='filters.HAS_PROTECTED_CONTENT')
"""Messages that contain :attr:`telegram.Message.has_protected_content`.
.. versionadded:: 13.9
@ -1418,7 +1418,7 @@ class _IsAutomaticForward(MessageFilter):
return bool(message.is_automatic_forward)
IS_AUTOMATIC_FORWARD = _IsAutomaticForward(name='Filters.is_automatic_forward')
IS_AUTOMATIC_FORWARD = _IsAutomaticForward(name='filters.IS_AUTOMATIC_FORWARD')
"""Messages that contain :attr:`telegram.Message.is_automatic_forward`.
.. versionadded:: 13.9
@ -1509,7 +1509,7 @@ POLL = _Poll(name="filters.POLL")
class Regex(MessageFilter):
"""
Filters updates by searching for an occurrence of ``pattern`` in the message text.
The :obj:`re.search()` function is used to determine whether an update should be filtered.
The :func:`re.search` function is used to determine whether an update should be filtered.
Refer to the documentation of the :obj:`re` module for more information.
@ -1532,7 +1532,7 @@ class Regex(MessageFilter):
first filter, since the second one is never evaluated.
Args:
pattern (:obj:`str` | :obj:`re.Pattern`): The regex pattern.
pattern (:obj:`str` | :func:`re.Pattern <re.compile>`): The regex pattern.
"""
__slots__ = ('pattern',)
@ -1593,7 +1593,7 @@ class SenderChat(_ChatUserBaseFilter):
group). Since v13.9, the field :attr:`telegram.Message.is_automatic_forward` will be
:obj:`True` for the discussion group message.
.. seealso:: :attr:`telegram.ext.filters.IS_AUTOMATIC_FORWARD`
.. seealso:: :attr:`telegram.ext.filters.IS_AUTOMATIC_FORWARD`
Warning:
:attr:`chat_ids` will return a *copy* of the saved chat ids as :obj:`frozenset`. This

2
telegram/request.py
View file

@ -107,7 +107,7 @@ class Request:
con_pool_size (:obj:`int`): Number of connections to keep in the connection pool.
proxy_url (:obj:`str`): The URL to the proxy server. For example: `http://127.0.0.1:3128`.
urllib3_proxy_kwargs (:obj:`dict`): Arbitrary arguments passed as-is to
:obj:`urllib3.ProxyManager`. This value will be ignored if :attr:`proxy_url` is not
``urllib3.ProxyManager``. This value will be ignored if :paramref:`proxy_url` is not
set.
connect_timeout (:obj:`int` | :obj:`float`): The maximum amount of time (in seconds) to
wait for a connection attempt to a server to succeed. :obj:`None` will set an